Referencia de complementos - Claude Code Docs

Para tutoriales prácticos y uso práctico, consulte Complementos. Para la gestión de complementos en equipos y comunidades, consulte Mercados de complementos.

Esta referencia proporciona especificaciones técnicas completas para el sistema de complementos de Claude Code, incluidos esquemas de componentes, comandos CLI y herramientas de desarrollo.

Referencia de componentes de complementos

Esta sección documenta los cinco tipos de componentes que los complementos pueden proporcionar.

Comandos

Los complementos agregan comandos de barra diagonal personalizados que se integran perfectamente con el sistema de comandos de Claude Code. Ubicación: directorio commands/ en la raíz del complemento Formato de archivo: Archivos Markdown con frontmatter Para obtener detalles completos sobre la estructura de comandos de complementos, patrones de invocación y características, consulte Comandos de complementos.

Agentes

Los complementos pueden proporcionar subagentes especializados para tareas específicas que Claude puede invocar automáticamente cuando sea apropiado. Ubicación: directorio agents/ en la raíz del complemento Formato de archivo: Archivos Markdown que describen las capacidades del agente Estructura del agente:

---
description: En qué se especializa este agente
capabilities: ["tarea1", "tarea2", "tarea3"]
---

# Nombre del Agente

Descripción detallada del rol del agente, experiencia y cuándo Claude debe invocarlo.

## Capacidades
- Tarea específica en la que el agente destaca
- Otra capacidad especializada
- Cuándo usar este agente frente a otros

## Contexto y ejemplos
Proporcione ejemplos de cuándo se debe usar este agente y qué tipos de problemas resuelve.

Puntos de integración:

Los agentes aparecen en la interfaz /agents
Claude puede invocar agentes automáticamente según el contexto de la tarea
Los agentes pueden ser invocados manualmente por los usuarios
Los agentes de complementos funcionan junto con los agentes Claude integrados

Habilidades

Los complementos pueden proporcionar Habilidades de Agente que amplían las capacidades de Claude. Las habilidades son invocadas por el modelo: Claude decide autónomamente cuándo usarlas según el contexto de la tarea. Ubicación: directorio skills/ en la raíz del complemento Formato de archivo: Directorios que contienen archivos SKILL.md con frontmatter Estructura de habilidad:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opcional)
│   └── scripts/ (opcional)
└── code-reviewer/
    └── SKILL.md

Comportamiento de integración:

Las Habilidades de complementos se descubren automáticamente cuando se instala el complemento
Claude invoca Habilidades autónomamente según el contexto de tarea coincidente
Las Habilidades pueden incluir archivos de apoyo junto con SKILL.md

Para el formato SKILL.md y la guía completa de autoría de Habilidades, consulte:

Hooks

Los complementos pueden proporcionar controladores de eventos que responden automáticamente a eventos de Claude Code. Ubicación: hooks/hooks.json en la raíz del complemento, o en línea en plugin.json Formato: Configuración JSON con coincidencias de eventos y acciones Configuración de hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Eventos disponibles:

PreToolUse: Antes de que Claude use cualquier herramienta
PostToolUse: Después de que Claude use cualquier herramienta
UserPromptSubmit: Cuando el usuario envía un mensaje
Notification: Cuando Claude Code envía notificaciones
Stop: Cuando Claude intenta detenerse
SubagentStop: Cuando un subagente intenta detenerse
SessionStart: Al comienzo de las sesiones
SessionEnd: Al final de las sesiones
PreCompact: Antes de que se compacte el historial de conversación

Tipos de hook:

command: Ejecutar comandos de shell o scripts
validation: Validar contenido de archivos o estado del proyecto
notification: Enviar alertas o actualizaciones de estado

Servidores MCP

Los complementos pueden agrupar servidores del Protocolo de Contexto de Modelo (MCP) para conectar Claude Code con herramientas y servicios externos. Ubicación: .mcp.json en la raíz del complemento, o en línea en plugin.json Formato: Configuración estándar del servidor MCP Configuración del servidor MCP:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Comportamiento de integración:

Los servidores MCP de complementos se inician automáticamente cuando se habilita el complemento
Los servidores aparecen como herramientas MCP estándar en el kit de herramientas de Claude
Las capacidades del servidor se integran perfectamente con las herramientas existentes de Claude
Los servidores de complementos se pueden configurar independientemente de los servidores MCP del usuario

Esquema de manifiesto de complemento

El archivo plugin.json define los metadatos y la configuración de su complemento. Esta sección documenta todos los campos y opciones admitidos.

Esquema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Campos requeridos

Campo	Tipo	Descripción	Ejemplo
`name`	string	Identificador único (kebab-case, sin espacios)	`"deployment-tools"`

Campos de metadatos

Campo	Tipo	Descripción	Ejemplo
`version`	string	Versión semántica	`"2.1.0"`
`description`	string	Breve explicación del propósito del complemento	`"Deployment automation tools"`
`author`	object	Información del autor	`{"name": "Dev Team", "email": "[email protected]"}`
`homepage`	string	URL de documentación	`"https://docs.example.com"`
`repository`	string	URL del código fuente	`"https://github.com/user/plugin"`
`license`	string	Identificador de licencia	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Etiquetas de descubrimiento	`["deployment", "ci-cd"]`

Campos de ruta de componente

Campo	Tipo	Descripción	Ejemplo
`commands`	string\|array	Archivos/directorios de comandos adicionales	`"./custom/cmd.md"` o `["./cmd1.md"]`
`agents`	string\|array	Archivos de agentes adicionales	`"./custom/agents/"`
`hooks`	string\|object	Ruta de configuración de hooks o configuración en línea	`"./hooks.json"`
`mcpServers`	string\|object	Ruta de configuración de MCP o configuración en línea	`"./mcp.json"`

Reglas de comportamiento de ruta

Importante: Las rutas personalizadas complementan los directorios predeterminados, no los reemplazan.

Si existe commands/, se carga además de las rutas de comandos personalizadas
Todas las rutas deben ser relativas a la raíz del complemento y comenzar con ./
Los comandos de rutas personalizadas utilizan las mismas reglas de nomenclatura y espacios de nombres
Se pueden especificar múltiples rutas como matrices para mayor flexibilidad

Ejemplos de ruta:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variables de entorno

${CLAUDE_PLUGIN_ROOT}: Contiene la ruta absoluta a su directorio de complemento. Úselo en hooks, servidores MCP y scripts para garantizar rutas correctas independientemente de la ubicación de instalación.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Estructura de directorio de complemento

Diseño estándar de complemento

Un complemento completo sigue esta estructura:

enterprise-plugin/
├── .claude-plugin/           # Directorio de metadatos
│   └── plugin.json          # Requerido: manifiesto de complemento
├── commands/                 # Ubicación de comando predeterminada
│   ├── status.md
│   └──  logs.md
├── agents/                   # Ubicación de agente predeterminada
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Habilidades de Agente
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Configuraciones de hook
│   ├── hooks.json           # Configuración de hook principal
│   └── security-hooks.json  # Hooks adicionales
├── .mcp.json                # Definiciones de servidor MCP
├── scripts/                 # Scripts de hook y utilidad
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Archivo de licencia
└── CHANGELOG.md             # Historial de versiones

El directorio .claude-plugin/ contiene el archivo plugin.json. Todos los demás directorios (commands/, agents/, skills/, hooks/) deben estar en la raíz del complemento, no dentro de .claude-plugin/.

Referencia de ubicaciones de archivo

Componente	Ubicación predeterminada	Propósito
Manifiesto	`.claude-plugin/plugin.json`	Archivo de metadatos requerido
Comandos	`commands/`	Archivos Markdown de comandos de barra diagonal
Agentes	`agents/`	Archivos Markdown de subagentes
Habilidades	`skills/`	Habilidades de Agente con archivos SKILL.md
Hooks	`hooks/hooks.json`	Configuración de hook
Servidores MCP	`.mcp.json`	Definiciones de servidor MCP

Herramientas de depuración y desarrollo

Comandos de depuración

Use claude --debug para ver detalles de carga de complementos:

claude --debug

Esto muestra:

Qué complementos se están cargando
Cualquier error en los manifiestos de complementos
Registro de comandos, agentes y hooks
Inicialización del servidor MCP

Problemas comunes

Problema	Causa	Solución
El complemento no se carga	`plugin.json` inválido	Validar sintaxis JSON
Los comandos no aparecen	Estructura de directorio incorrecta	Asegurar `commands/` en raíz, no en `.claude-plugin/`
Los hooks no se disparan	Script no ejecutable	Ejecutar `chmod +x script.sh`
El servidor MCP falla	Falta `${CLAUDE_PLUGIN_ROOT}`	Usar variable para todas las rutas de complemento
Errores de ruta	Se utilizan rutas absolutas	Todas las rutas deben ser relativas y comenzar con `./`

Referencia de distribución y versionamiento

Gestión de versiones

Siga el versionamiento semántico para las versiones de complementos:

## Ver también

- [Complementos](/es/plugins) - Tutoriales y uso práctico
- [Mercados de complementos](/es/plugin-marketplaces) - Crear y gestionar mercados
- [Comandos de barra diagonal](/es/slash-commands) - Detalles de desarrollo de comandos
- [Subagentes](/es/sub-agents) - Configuración y capacidades del agente
- [Habilidades de Agente](/es/skills) - Ampliar las capacidades de Claude
- [Hooks](/es/hooks) - Manejo de eventos y automatización
- [MCP](/es/mcp) - Integración de herramientas externas
- [Configuración](/es/settings) - Opciones de configuración para complementos

Referencia

​Referencia de componentes de complementos

​Comandos

​Agentes

​Habilidades

​Hooks

​Servidores MCP

​Esquema de manifiesto de complemento

​Esquema completo

​Campos requeridos

​Campos de metadatos

​Campos de ruta de componente

​Reglas de comportamiento de ruta

​Variables de entorno

​Estructura de directorio de complemento

​Diseño estándar de complemento

​Referencia de ubicaciones de archivo

​Herramientas de depuración y desarrollo

​Comandos de depuración

​Problemas comunes

​Referencia de distribución y versionamiento

​Gestión de versiones

Referencia de componentes de complementos

Comandos

Agentes

Habilidades

Hooks

Servidores MCP

Esquema de manifiesto de complemento

Esquema completo

Campos requeridos

Campos de metadatos

Campos de ruta de componente

Reglas de comportamiento de ruta

Variables de entorno

Estructura de directorio de complemento

Diseño estándar de complemento

Referencia de ubicaciones de archivo

Herramientas de depuración y desarrollo

Comandos de depuración

Problemas comunes

Referencia de distribución y versionamiento

Gestión de versiones