Plugins en el SDK

Cargue plugins personalizados para extender Claude Code con comandos, agentes, skills y hooks a través del Agent SDK

Los plugins le permiten extender Claude Code con funcionalidad personalizada que se puede compartir entre proyectos. A través del Agent SDK, puede cargar programáticamente plugins desde directorios locales para agregar comandos slash personalizados, agentes, skills, hooks y servidores MCP a sus sesiones de agente.

¿Qué son los plugins?

Los plugins son paquetes de extensiones de Claude Code que pueden incluir:

Skills: Capacidades invocadas por el modelo que Claude utiliza de forma autónoma (también se pueden invocar con /skill-name)
Agents: Subagentes especializados para tareas específicas
Hooks: Controladores de eventos que responden al uso de herramientas y otros eventos
MCP servers: Integraciones de herramientas externas a través del Model Context Protocol

Para obtener información completa sobre la estructura de plugins y cómo crear plugins, consulte Plugins.

Cargando plugins

Cargue plugins proporcionando sus rutas del sistema de archivos local en su configuración de opciones. El campo type debe ser "local", el único valor que acepta el SDK. Para usar un plugin distribuido a través de un marketplace o repositorio remoto, descárguelo primero y proporcione la ruta del directorio local. El SDK admite cargar múltiples plugins desde diferentes ubicaciones.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Hello",
options: {
plugins: [
{ type: "local", path: "./my-plugin" },
{ type: "local", path: "/absolute/path/to/another-plugin" }
]
}
})) {
// Plugin commands, agents, and other features are now available
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[
{"type": "local", "path": "./my-plugin"},
{"type": "local", "path": "/absolute/path/to/another-plugin"},
]
),
):
# Plugin commands, agents, and other features are now available
pass


asyncio.run(main())

Especificaciones de ruta

Las rutas de plugins pueden ser:

Rutas relativas: Se resuelven en relación con su directorio de trabajo actual (por ejemplo, "./plugins/my-plugin")
Rutas absolutas: Rutas completas del sistema de archivos (por ejemplo, "/home/user/plugins/my-plugin")

Verificando la instalación del plugin

Cuando los plugins se cargan correctamente, aparecen en el mensaje de inicialización del sistema. Puede verificar que sus plugins estén disponibles:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Hello",
options: {
plugins: [{ type: "local", path: "./my-plugin" }]
}
})) {
if (message.type === "system" && message.subtype === "init") {
// Check loaded plugins
console.log("Plugins:", message.plugins);
// Example: [{ name: "my-plugin", path: "./my-plugin" }]

// Check available commands from plugins
console.log("Commands:", message.slash_commands);
// Example: ["/help", "/compact", "my-plugin:custom-command"]
}
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage


async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./my-plugin"}]
),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
# Check loaded plugins
print("Plugins:", message.data.get("plugins"))
# Example: [{"name": "my-plugin", "path": "./my-plugin"}]

# Check available commands from plugins
print("Commands:", message.data.get("slash_commands"))
# Example: ["/help", "/compact", "my-plugin:custom-command"]


asyncio.run(main())

Usando skills de plugins

Los skills de los plugins se espacian automáticamente con el nombre del plugin para evitar conflictos. Cuando se invocan como comandos slash, el formato es plugin-name:skill-name.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet skill
for await (const message of query({
prompt: "/my-plugin:greet", // Use plugin skill with namespace
options: {
plugins: [{ type: "local", path: "./my-plugin" }]
}
})) {
// Claude executes the custom greeting skill from the plugin
if (message.type === "assistant") {
console.log(message.message.content);
}
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock


async def main():
# Load a plugin with a custom /greet skill
async for message in query(
prompt="/demo-plugin:greet",  # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]
),
):
# Claude executes the custom greeting skill from the plugin
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")


asyncio.run(main())

Ejemplo completo

Aquí hay un ejemplo completo que demuestra la carga y el uso de plugins:

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as path from "path";

async function runWithPlugin() {
const pluginPath = path.join(__dirname, "plugins", "my-plugin");

console.log("Loading plugin from:", pluginPath);

for await (const message of query({
prompt: "What custom commands do you have available?",
options: {
plugins: [{ type: "local", path: pluginPath }],
maxTurns: 3
}
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Loaded plugins:", message.plugins);
console.log("Available commands:", message.slash_commands);
}

if (message.type === "assistant") {
console.log("Assistant:", message.message.content);
}
}
}

runWithPlugin().catch(console.error);

#!/usr/bin/env python3
"""Example demonstrating how to use plugins with the Agent SDK."""

from pathlib import Path
import anyio
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
SystemMessage,
TextBlock,
query,
)


async def run_with_plugin():
"""Example using a custom plugin."""
plugin_path = Path(__file__).parent / "plugins" / "demo-plugin"

print(f"Loading plugin from: {plugin_path}")

options = ClaudeAgentOptions(
plugins=[{"type": "local", "path": str(plugin_path)}],
max_turns=3,
)

async for message in query(
prompt="What custom commands do you have available?", options=options
):
if isinstance(message, SystemMessage) and message.subtype == "init":
print(f"Loaded plugins: {message.data.get('plugins')}")
print(f"Available commands: {message.data.get('slash_commands')}")

if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Assistant: {block.text}")


if __name__ == "__main__":
anyio.run(run_with_plugin)

Referencia de estructura de plugin

Un directorio de plugin debe contener un archivo de manifiesto .claude-plugin/plugin.json. Opcionalmente puede incluir:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (invoked autonomously or via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: use skills/ instead
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Para obtener información detallada sobre cómo crear plugins, consulte:

Plugins - Guía completa de desarrollo de plugins
Plugins reference - Especificaciones técnicas y esquemas

Casos de uso comunes

Desarrollo y pruebas

Cargue plugins durante el desarrollo sin instalarlos globalmente:

plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }];

Extensiones específicas del proyecto

Incluya plugins en su repositorio de proyecto para consistencia en todo el equipo:

plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];

Múltiples fuentes de plugins

Combine plugins de diferentes ubicaciones:

plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];

Troubleshooting

Plugin no se carga

Si su plugin no aparece en el mensaje de inicialización:

Verifique la ruta: Asegúrese de que la ruta apunte al directorio raíz del plugin (que contiene .claude-plugin/)
Valide plugin.json: Asegúrese de que su archivo de manifiesto tenga una sintaxis JSON válida
Verifique los permisos de archivo: Asegúrese de que el directorio del plugin sea legible

Los skills no aparecen

Si los skills del plugin no funcionan:

Use el espacio de nombres: Los skills del plugin requieren el formato plugin-name:skill-name cuando se invocan como comandos slash
Verifique el mensaje de inicialización: Verifique que el skill aparezca en slash_commands con el espacio de nombres correcto
Valide los archivos de skill: Asegúrese de que cada skill tenga un archivo SKILL.md en su propio subdirectorio bajo skills/ (por ejemplo, skills/my-skill/SKILL.md)

Problemas de resolución de ruta

Si las rutas relativas no funcionan:

Verifique el directorio de trabajo: Las rutas relativas se resuelven desde su directorio de trabajo actual
Use rutas absolutas: Para mayor confiabilidad, considere usar rutas absolutas
Normalice las rutas: Use utilidades de ruta para construir rutas correctamente

Ver también

Plugins - Guía completa de desarrollo de plugins
Plugins reference - Especificaciones técnicas
Slash Commands - Usando comandos slash en el SDK
Subagents - Trabajando con agentes especializados
Skills - Usando Agent Skills

agent-sdk/plugins.md +16 −10

46 46

47 ```python Python theme={null}47 ```python Python theme={null}

48 import asyncio48 import asyncio

~~49 from claude_agent_sdk import query~~49 from claude_agent_sdk import query, ClaudeAgentOptions

50 50

51 51

52 async def main():52 async def main():

53 async for message in query(53 async for message in query(

54 prompt="Hello",54 prompt="Hello",

~~55 options={~~55 options=ClaudeAgentOptions(

~~56 "plugins": [~~56 plugins=[

57 {"type": "local", "path": "./my-plugin"},57 {"type": "local", "path": "./my-plugin"},

58 {"type": "local", "path": "/absolute/path/to/another-plugin"},58 {"type": "local", "path": "/absolute/path/to/another-plugin"},

59 ]59 ]

~~60 },~~60 ),

61 ):61 ):

62 # Plugin commands, agents, and other features are now available62 # Plugin commands, agents, and other features are now available

63 pass63 pass

106 106

107 ```python Python theme={null}107 ```python Python theme={null}

108 import asyncio108 import asyncio

109 from claude_agent_sdk import query109 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

110 110

111 111

112 async def main():112 async def main():

113 async for message in query(113 async for message in query(

114 prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]}114 prompt="Hello",

115 options=ClaudeAgentOptions(

116 plugins=[{"type": "local", "path": "./my-plugin"}]

117 ),

115 ):118 ):

116 if message.type == "system" and message.subtype == "init":119 if isinstance(message, SystemMessage) and message.subtype == "init":

117 # Check loaded plugins120 # Check loaded plugins

118 print("Plugins:", message.data.get("plugins"))121 print("Plugins:", message.data.get("plugins"))

119 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]122 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

151 154

152 ```python Python theme={null}155 ```python Python theme={null}

153 import asyncio156 import asyncio

154 from claude_agent_sdk import query, AssistantMessage, TextBlock157 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

155 158

156 159

157 async def main():160 async def main():

158 # Load a plugin with a custom /greet skill161 # Load a plugin with a custom /greet skill

159 async for message in query(162 async for message in query(

160 prompt="/demo-plugin:greet", # Use plugin skill with namespace163 prompt="/demo-plugin:greet", # Use plugin skill with namespace

161 options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]},164 options=ClaudeAgentOptions(

165 plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]

166 ),

162 ):167 ):

163 # Claude executes the custom greeting skill from the plugin168 # Claude executes the custom greeting skill from the plugin

164 if isinstance(message, AssistantMessage):169 if isinstance(message, AssistantMessage):

219 from claude_agent_sdk import (224 from claude_agent_sdk import (

220 AssistantMessage,225 AssistantMessage,

221 ClaudeAgentOptions,226 ClaudeAgentOptions,

227 SystemMessage,

222 TextBlock,228 TextBlock,

223 query,229 query,

224 )230 )

238 async for message in query(244 async for message in query(

239 prompt="What custom commands do you have available?", options=options245 prompt="What custom commands do you have available?", options=options

240 ):246 ):

241 if message.type == "system" and message.subtype == "init":247 if isinstance(message, SystemMessage) and message.subtype == "init":

242 print(f"Loaded plugins: {message.data.get('plugins')}")248 print(f"Loaded plugins: {message.data.get('plugins')}")

243 print(f"Available commands: {message.data.get('slash_commands')}")249 print(f"Available commands: {message.data.get('slash_commands')}")

244 250

agent-sdk/plugins.md 2026-05-14 17:02 UTC to 2026-05-15 22:58 UTC

Plugins en el SDK

¿Qué son los plugins?

Cargando plugins

Especificaciones de ruta

Verificando la instalación del plugin

Usando skills de plugins

Ejemplo completo

Referencia de estructura de plugin

Casos de uso comunes

Desarrollo y pruebas

Extensiones específicas del proyecto

Múltiples fuentes de plugins

Troubleshooting

Plugin no se carga

Los skills no aparecen

Problemas de resolución de ruta

Ver también