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
}

​
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")
La ruta debe apuntar al directorio raíz del plugin (el directorio que contiene .claude-plugin/plugin.json).

​
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);
  }
}
Si instalaste un plugin a través de la CLI (por ejemplo, /plugin install my-plugin@marketplace), aún puedes usarlo en el SDK proporcionando su ruta de instalación. Verifica ~/.claude/plugins/ para plugins instalados por CLI.

​
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:

​
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