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 skills, agentes, 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") {
// Verificar plugins cargados
console.log("Plugins:", message.plugins);
// Ejemplo: [{ name: "my-plugin", path: "./my-plugin" }]
// Las skills del plugin aparecen con el nombre del plugin como prefijo
console.log("Skills:", message.skills);
// Ejemplo: ["my-plugin:greet"]
// Los comandos del plugin usan el mismo prefijo, y las skills también aparecen aquí
console.log("Commands:", message.slash_commands);
// Ejemplo: ["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":
# Verificar plugins cargados
print("Plugins:", message.data.get("plugins"))
# Ejemplo: [{"name": "my-plugin", "path": "./my-plugin"}]
# Las skills del plugin aparecen con el nombre del plugin como prefijo
print("Skills:", message.data.get("skills"))
# Ejemplo: ["my-plugin:greet"]
# Los comandos del plugin usan el mismo prefijo, y las skills también aparecen aquí
print("Commands:", message.data.get("slash_commands"))
# Ejemplo: ["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="/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 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."""
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 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__":
anyio.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 # Manifiesto de plugin (opcional, componentes descubiertos automáticamente sin él)
├── skills/ # Agent Skills (invocadas autónomamente o vía /skill-name)
│ └── my-skill/
│ └── SKILL.md
├── commands/ # Heredado: usar skills/ en su lugar
│ └── custom-cmd.md
├── agents/ # Agentes personalizados
│ └── specialist.md
├── hooks/ # Manejadores de eventos
│ └── hooks.json
└── .mcp.json # Definiciones de servidor MCP
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, el directorio padre de
skills/,agents/,hooks/,commands/(heredado), 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
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
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
- Commands - Usando comandos en el SDK
- Subagents - Trabajando con agentes especializados
- Skills - Usando Agent Skills