Saltar al contenido principal
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
El directorio commands/ es un formato heredado. Use skills/ para nuevos plugins. Claude Code continúa admitiendo ambos formatos para compatibilidad hacia atrás.
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
}

​
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")
La ruta debe apuntar al directorio raíz del plugin: el directorio padre de skills/, agents/, hooks/, commands/ (heredado), o .claude-plugin/, no a un subdirectorio.

​
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"]
  }
}

​
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);
  }
}
Si instaló un plugin a través de la CLI (por ejemplo, /plugin install my-plugin@marketplace), aún puede usarlo en el SDK proporcionando su ruta de instalación. Verifique ~/.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 skills:", message.skills);
      console.log("Available commands:", message.slash_commands);
    }

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

runWithPlugin().catch(console.error);

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

​
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:
  1. 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/
  2. Valide plugin.json: Si su plugin incluye un manifiesto, asegúrese de que tenga una sintaxis JSON válida
  3. 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:
  1. Use el espacio de nombres: Invoque los skills del plugin como /plugin-name:skill-name
  2. Verifique el mensaje de inicialización: Verifique que el skill aparezca en la lista skills con el espacio de nombres correcto
  3. 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:
  1. Verifique el directorio de trabajo: Las rutas relativas se resuelven desde su directorio de trabajo actual
  2. Use rutas absolutas: Para mayor confiabilidad, considere usar rutas absolutas
  3. Normalice las rutas: Use utilidades de ruta para construir rutas correctamente

​
Ver también