Plugins en el SDK

Los plugins te permiten extender Claude Code con funcionalidad personalizada que puede compartirse entre proyectos. A través del Agent SDK, puedes cargar programáticamente plugins desde directorios locales para agregar comandos de barra diagonal personalizados, agentes, habilidades, hooks y servidores MCP a tus sesiones de agente.

¿Qué son los plugins?

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

• Comandos: Comandos de barra diagonal personalizados
• Agentes: Subagentes especializados para tareas específicas
• Habilidades: Capacidades invocadas por el modelo que Claude utiliza de forma autónoma
• Hooks: Manejadores de eventos que responden al uso de herramientas y otros eventos
• Servidores MCP: Integraciones de herramientas externas a través del Protocolo de Contexto de Modelo

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

Cargando plugins

Carga plugins proporcionando sus rutas del sistema de archivos local en tu configuración de opciones. 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

async def main():
    async for message in 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
        pass

asyncio.run(main())

Especificaciones de ruta

Las rutas de plugins pueden ser:

• Rutas relativas: Resueltas relativas a tu 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. Puedes verificar que tus 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"]
  }
}

Usando comandos de plugin

Los comandos de los plugins se espacian automáticamente con el nombre del plugin para evitar conflictos. El formato es plugin-name:command-name.

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

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

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.content);
    }
  }
}

runWithPlugin().catch(console.error);

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
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Para obtener información detallada sobre la creación de plugins, consulta:

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

Casos de uso comunes

Desarrollo y pruebas

Carga plugins durante el desarrollo sin instalarlos globalmente:

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

Extensiones específicas del proyecto

Incluye plugins en tu repositorio de proyecto para consistencia en todo el equipo:

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

Múltiples fuentes de plugins

Combina plugins de diferentes ubicaciones:

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

Solución de problemas

Plugin no se carga

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

1. Verifica la ruta: Asegúrate de que la ruta apunte al directorio raíz del plugin (que contiene .claude-plugin/)
2. Valida plugin.json: Asegúrate de que tu archivo de manifiesto tenga una sintaxis JSON válida
3. Verifica permisos de archivo: Asegúrate de que el directorio del plugin sea legible

Comandos no disponibles

Si los comandos del plugin no funcionan:

1. Usa el espacio de nombres: Los comandos del plugin requieren el formato plugin-name:command-name
2. Verifica el mensaje de inicialización: Verifica que el comando aparezca en slash_commands con el espacio de nombres correcto
3. Valida archivos de comando: Asegúrate de que los archivos de comando markdown estén en el directorio commands/

Problemas de resolución de ruta

Si las rutas relativas no funcionan:

1. Verifica el directorio de trabajo: Las rutas relativas se resuelven desde tu directorio de trabajo actual
2. Usa rutas absolutas: Para mayor confiabilidad, considera usar rutas absolutas
3. Normaliza rutas: Usa utilidades de ruta para construir rutas correctamente

Ver también

• Plugins - Guía completa de desarrollo de plugins
• Referencia de plugins - Especificaciones técnicas
• Comandos de barra diagonal - Usando comandos de barra diagonal en el SDK
• Subagentes - Trabajando con agentes especializados
• Habilidades - Usando Agent Skills