Plugins en el SDK
Cargue plugins personalizados para extender Claude Code con skills, agentes, hooks y servidores MCP 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 capacidades a sus sesiones de agente. Un plugin puede incluir:
- Skills: capacidades que Claude invoca de forma autónoma cuando es relevante. También puede invocar directamente un skill de plugin con
/plugin-name: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. El SDK admite cargar múltiples plugins desde diferentes ubicaciones.
Para usar un plugin distribuido a través de un marketplace o repositorio remoto, descárguelo primero y proporcione la ruta del directorio local. Para el diseño del directorio que necesita un plugin, consulte la referencia de estructura de plugin a continuación.
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: "/absolute/path/to/my-plugin" }]
// Plugin skills appear with the plugin name as a prefix
console.log("Skills:", message.skills);
// Example: ["my-plugin:greet"]
// Plugin commands use the same prefix, and skills appear here too
console.log("Commands:", message.slash_commands);
// Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
}
}
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": "/absolute/path/to/my-plugin"}]
# Plugin skills appear with the plugin name as a prefix
print("Skills:", message.data.get("skills"))
# Example: ["my-plugin:greet"]
# Plugin commands use the same prefix, and skills appear here too
print("Commands:", message.data.get("slash_commands"))
# Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
Usando skills de plugins
Los skills de los plugins se espacian automáticamente con el nombre del plugin para evitar conflictos. Para invocar uno directamente, envíe /plugin-name:skill-name como el prompt.
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="/my-plugin:greet", # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./my-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 { fileURLToPath } from "node:url";
async function runWithPlugin() {
const pluginPath = fileURLToPath(new URL("./plugins/my-plugin", import.meta.url));
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 skills:", message.skills);
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."""
import asyncio
from pathlib import Path
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" / "my-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 skills: {message.data.get('skills')}")
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__":
asyncio.run(run_with_plugin())
Referencia de estructura de plugin
Un directorio de plugin típicamente contiene un archivo de manifiesto .claude-plugin/plugin.json. El manifiesto es opcional. Cuando se omite, Claude Code descubre automáticamente los componentes desde el diseño del directorio. El directorio puede incluir:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (optional, components auto-discovered without it)
├── skills/ # Agent Skills (invoked autonomously or via /plugin-name:skill-name)
│ └── my-skill/
│ └── SKILL.md
├── commands/ # Skills as flat .md files
│ └── custom-cmd.md
├── agents/ # Custom agents
│ └── specialist.md
├── hooks/ # Event handlers
│ └── hooks.json
└── .mcp.json # MCP server definitions
Múltiples fuentes de plugins
Combine plugins de diferentes ubicaciones:
import * as os from "node:os";
import * as path from "node:path";
plugins: [
{ type: "local", path: "./local-plugin" },
{
type: "local",
path: path.join(os.homedir(), ".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, el directorio padre de
skills/,agents/,hooks/,commands/, o.claude-plugin/ - Valide plugin.json: si su plugin incluye un manifiesto, asegúrese de que tenga una sintaxis JSON válida
- Verifique los permisos de archivo: asegúrese de que el directorio del plugin sea legible
- Confirme que el directorio existe: el SDK omite una ruta inexistente, y el plugin no aparece en la lista
pluginsdel mensaje de inicialización
Los skills no aparecen
Si los skills del plugin no funcionan:
- Use el espacio de nombres: invoque los skills del plugin como
/plugin-name:skill-name - Verifique el mensaje de inicialización: verifique que el skill aparezca en la lista
skillscon el espacio de nombres correcto - Valide los archivos de skill: asegúrese de que cada skill tenga un archivo
SKILL.mden su propio subdirectorio bajoskills/, por ejemploskills/my-skill/SKILL.md
Ver también
- Plugins - Guía completa de desarrollo de plugins
- Plugins reference - Especificaciones técnicas
- Commands - Despachando comandos en el SDK
- Subagents - Trabajando con agentes especializados
- Skills - Usando Agent Skills