Referencia de plugins

Para tutoriales prácticos y uso práctico, consulta Plugins. Para la gestión de plugins en equipos y comunidades, consulta Mercados de plugins.

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

Referencia de componentes de plugins

Esta sección documenta los cuatro tipos de componentes que los plugins pueden proporcionar.

Comandos

Los plugins 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 plugin Formato de archivo: archivos Markdown con frontmatter Para detalles completos sobre la estructura de comandos de plugin, patrones de invocación y características, consulta Comandos de plugin.

Agentes

Los plugins 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 plugin 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 debería invocarlo.

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

## Contexto y ejemplos
Proporciona ejemplos de cuándo este agente debería ser usado y qué tipos de problemas resuelve.

Puntos de integración:

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

Hooks

Los plugins pueden proporcionar manejadores de eventos que responden a eventos de Claude Code automáticamente. Ubicación: hooks/hooks.json en la raíz del plugin, o inline 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 prompt
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 el historial de conversación sea compactado

Tipos de hook:

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

Servidores MCP

Los plugins pueden incluir 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 plugin, o inline en plugin.json Formato: configuración estándar de 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 del plugin se inician automáticamente cuando el plugin está habilitado
Los servidores aparecen como herramientas MCP estándar en el conjunto de herramientas de Claude
Las capacidades del servidor se integran perfectamente con las herramientas existentes de Claude
Los servidores de plugin pueden configurarse independientemente de los servidores MCP del usuario

Esquema del manifiesto del plugin

El archivo plugin.json define los metadatos y configuración de tu plugin. Esta sección documenta todos los campos y opciones soportados.

Esquema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Breve descripción del plugin",
  "author": {
    "name": "Nombre del Autor",
    "email": "[email protected]",
    "url": "https://github.com/autor"
  },
  "homepage": "https://docs.ejemplo.com/plugin",
  "repository": "https://github.com/autor/plugin",
  "license": "MIT",
  "keywords": ["palabra-clave1", "palabra-clave2"],
  "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 plugin	`"Herramientas de automatización de despliegue"`
`author`	object	Información del autor	`{"name": "Equipo Dev", "email": "[email protected]"}`
`homepage`	string	URL de documentación	`"https://docs.ejemplo.com"`
`repository`	string	URL del código fuente	`"https://github.com/usuario/plugin"`
`license`	string	Identificador de licencia	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Etiquetas de descubrimiento	`["despliegue", "ci-cd"]`

Campos de ruta de componentes

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 hook o configuración inline	`"./hooks.json"`
`mcpServers`	string\|object	Ruta de configuración MCP o configuración inline	`"./mcp.json"`

Reglas de comportamiento de rutas

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

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

Ejemplos de rutas:

{
  "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 al directorio de tu plugin. Usa esto en hooks, servidores MCP y scripts para asegurar 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 del plugin

Diseño estándar del plugin

Un plugin completo sigue esta estructura:

enterprise-plugin/
├── .claude-plugin/           # Directorio de metadatos
│   └── plugin.json          # Requerido: manifiesto del plugin
├── commands/                 # Ubicación predeterminada de comandos
│   ├── status.md
│   └──  logs.md
├── agents/                   # Ubicación predeterminada de agentes
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── hooks/                    # Configuraciones de hooks
│   ├── hooks.json           # Configuración principal de hooks
│   └── security-hooks.json  # Hooks adicionales
├── .mcp.json                # Definiciones de servidor MCP
├── scripts/                 # Scripts de hooks y utilidades
│   ├── 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 otros directorios (commands/, agents/, hooks/) deben estar en la raíz del plugin, no dentro de .claude-plugin/.

Referencia de ubicaciones de archivos

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
Hooks	`hooks/hooks.json`	Configuración de hooks
Servidores MCP	`.mcp.json`	Definiciones de servidor MCP

Herramientas de depuración y desarrollo

Comandos de depuración

Usa claude --debug para ver detalles de carga de plugins:

claude --debug

Esto muestra:

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

Problemas comunes

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

Referencia de distribución y versionado

Gestión de versiones

Sigue el versionado semántico para lanzamientos de plugins:


## Ver también

- [Plugins](/es/docs/claude-code/plugins) - Tutoriales y uso práctico
- [Mercados de plugins](/es/docs/claude-code/plugin-marketplaces) - Creación y gestión de mercados
- [Comandos de barra diagonal](/es/docs/claude-code/slash-commands) - Detalles de desarrollo de comandos
- [Subagentes](/es/docs/claude-code/sub-agents) - Configuración y capacidades de agentes
- [Hooks](/es/docs/claude-code/hooks) - Manejo de eventos y automatización
- [MCP](/es/docs/claude-code/mcp) - Integración de herramientas externas
- [Configuración](/es/docs/claude-code/settings) - Opciones de configuración para plugins

Primeros pasos

Construir con Claude Code

SDK de Código Claude

Implementación

Administración

Configuración

Referencia

Recursos

Referencia de plugins

Referencia de componentes de plugins

Comandos

Agentes

Hooks

Servidores MCP

Esquema del manifiesto del plugin

Esquema completo

Campos requeridos

Campos de metadatos

Campos de ruta de componentes

Reglas de comportamiento de rutas

Variables de entorno

Estructura de directorio del plugin

Diseño estándar del plugin

Referencia de ubicaciones de archivos

Herramientas de depuración y desarrollo

Comandos de depuración

Problemas comunes

Referencia de distribución y versionado

Gestión de versiones

Primeros pasos

Construir con Claude Code

SDK de Código Claude

Implementación

Administración

Configuración

Referencia

Recursos

​Referencia de componentes de plugins

​Comandos

​Agentes

​Hooks

​Servidores MCP

​Esquema del manifiesto del plugin

​Esquema completo

​Campos requeridos

​Campos de metadatos

​Campos de ruta de componentes

​Reglas de comportamiento de rutas

​Variables de entorno

​Estructura de directorio del plugin

​Diseño estándar del plugin

​Referencia de ubicaciones de archivos

​Herramientas de depuración y desarrollo

​Comandos de depuración

​Problemas comunes

​Referencia de distribución y versionado

​Gestión de versiones

Referencia de componentes de plugins

Comandos

Agentes

Hooks

Servidores MCP

Esquema del manifiesto del plugin

Esquema completo

Campos requeridos

Campos de metadatos

Campos de ruta de componentes

Reglas de comportamiento de rutas

Variables de entorno

Estructura de directorio del plugin

Diseño estándar del plugin

Referencia de ubicaciones de archivos

Herramientas de depuración y desarrollo

Comandos de depuración

Problemas comunes

Referencia de distribución y versionado

Gestión de versiones