Referencia de plugins

Referencia técnica completa para el sistema de plugins de Claude Code, incluyendo esquemas, comandos CLI y especificaciones de componentes.

Un plugin es un directorio independiente de componentes que extiende Claude Code con funcionalidad personalizada. Los componentes de plugins incluyen skills, agentes, hooks, servidores MCP, servidores LSP y monitores.

Referencia de componentes de plugins

Skills

Los plugins añaden skills a Claude Code, creando atajos /name que usted o Claude pueden invocar.

Ubicación: directorio skills/ o commands/ en la raíz del plugin, o un único archivo SKILL.md en la raíz del plugin

Formato de archivo: Los skills son directorios con SKILL.md; los commands son archivos markdown simples

Estructura de skill:

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

Los skills y commands se descubren automáticamente cuando se instala el plugin.

Si un plugin no tiene directorio skills/ y no tiene campo manifest skills, un SKILL.md en la raíz del plugin se carga como un único skill. Establezca el campo frontmatter name para controlar el nombre de invocación del skill. Sin él, Claude Code recurre al nombre del directorio de instalación, que para plugins instalados desde marketplace es una cadena de versión que cambia en cada actualización. Para plugins que incluyen más de un skill, use el diseño de directorio skills/ mostrado arriba.

En skills y commands de plugins, los campos frontmatter booleanos como disable-model-invocation aceptan yes, no, on, off, 1, y 0 en cualquier caso de letra, además de true y false. Antes de v2.1.218, Claude Code reconocía solo true y false.

Para detalles completos, consulte Skills.

Agents

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 de agente:

---
name: agent-name
description: En qué se especializa este agente y cuándo Claude debe invocarlo
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Prompt del sistema detallado para el agente describiendo su rol, experiencia y comportamiento.

Los agentes de plugins soportan campos frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, e isolation. El único valor válido de isolation es "worktree". Por razones de seguridad, hooks, mcpServers, y permissionMode no se soportan para agentes enviados por plugins.

Claude Code carga un agente de plugin incluso cuando su frontmatter no tiene name o no se analiza:

• Sin name: Claude Code nombra el agente según el archivo, así que agents/reviewer.md en un plugin llamado my-plugin se carga como my-plugin:reviewer
• Frontmatter que no se analiza: Claude Code nombra el agente según el archivo, usa Agent from my-plugin plugin como su descripción, e ignora cada campo en el archivo

En contraste, Claude Code omite un archivo de agente de proyecto, usuario o administrado cuyo frontmatter no tiene name o no se analiza.

Para encontrar archivos en el directorio agents/ predeterminado de un plugin cuyo frontmatter no se analiza, ejecute claude plugin validate. La ruta que pase depende de si el plugin tiene un manifest, y ambos ejemplos usan ./my-plugin como directorio del plugin:

• Un plugin con manifest: claude plugin validate ./my-plugin
• Un plugin sin manifest: claude plugin validate ./my-plugin/agents. Requiere Claude Code v2.1.233 o posterior.

Los agentes aparecen en la typeahead de @-mention bajo su nombre con alcance, como my-plugin:code-reviewer, una vez que el plugin está habilitado.

Para detalles completos, consulte Subagentes.

Hooks

Los plugins pueden proporcionar manejadores de eventos que responden automáticamente a eventos de Claude Code.

Ubicación: hooks/hooks.json en la raíz del plugin, 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"
          }
        ]
      }
    ]
  }
}

Los hooks de plugins responden a los mismos eventos del ciclo de vida que los hooks definidos por el usuario:

Tipos de hook:

• command: ejecutar comandos shell o scripts
• http: enviar el JSON del evento como una solicitud POST a una URL
• mcp_tool: llamar a una herramienta en un servidor MCP configurado
• prompt: evaluar un prompt con un LLM (usa el marcador de posición $ARGUMENTS para contexto)
• agent: ejecutar un verificador agente con herramientas para tareas de verificación complejas

Los hooks que apuntan al servidor MCP agrupado propio del plugin deben usar sus nombres con alcance. Los coincidentes de herramientas y campos if toman el nombre de herramienta con alcance mcp__plugin_<plugin-name>_<server-name>__<tool>, y el campo server de un hook mcp_tool toma plugin:<plugin-name>:<server-name>. Un coincidente escrito contra la clave del servidor desnuda nunca se dispara. Consulte Match MCP tools y Plugin-provided MCP servers.

MCP servers

Los plugins 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 plugin, o en línea en plugin.json

Formato: Configuración estándar de servidor MCP

Configuración de 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"]
    }
  }
}

Comportamiento de integración:

• Los servidores MCP de plugins se inician automáticamente cuando el plugin está habilitado
• Los servidores aparecen como herramientas MCP estándar en el kit de herramientas de Claude
• Los servidores de plugins se pueden configurar independientemente de los servidores MCP del usuario
• Si ejecuta /reload-plugins a mitad de sesión, Claude Code mantiene las conexiones activas de servidores cuya configuración no ha cambiado

LSP servers

Los plugins pueden proporcionar servidores del Protocolo de Servidor de Lenguaje (LSP) para dar a Claude inteligencia de código en tiempo real mientras trabaja en su base de código.

Ubicación: .lsp.json en la raíz del plugin, o en línea en plugin.json

Formato: Configuración JSON que asigna nombres de servidores de lenguaje a sus configuraciones

Formato de archivo .lsp.json:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

En línea en plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Campos requeridos:

Campos opcionales:

restartOnCrash y shutdownTimeout requieren Claude Code v2.1.205 o posterior. Antes de v2.1.205, el esquema de configuración aceptaba ambas opciones pero establecer cualquiera de ellas causaba que Claude Code omitiera ese servidor LSP completamente al inicio, con la razón visible solo en la salida de claude --debug.

Múltiples servidores para la misma extensión: cuando más de un servidor LSP habilitado declara la misma extensión de archivo en extensionToLanguage, ya sea que los servidores provengan de un plugin o de diferentes plugins, el primer servidor registrado maneja archivos con esa extensión y los otros nunca se inician. La interfaz /plugin muestra una advertencia nombrando el plugin cuyo servidor está activo.

Servidores que fallan al inicializarse: Claude Code omite un servidor cuya configuración es inválida, por ejemplo uno que falta command o extensionToLanguage, y los otros servidores configurados aún se inician. Ejecute claude --debug para ver por qué se omitió un servidor.

Un servidor omitido no reclama sus extensiones de archivo, por lo que otro servidor válido que declare la misma extensión, del mismo plugin o de un plugin diferente, aún maneja esos archivos.

Envíe la salida de registro a stderr, no a stdout: Claude Code lee el stdout de un servidor solo como mensajes de protocolo, y acepta encabezados de mensaje de hasta 64 KiB y un cuerpo de mensaje de hasta 32 MiB. Claude Code desconecta un servidor que excede cualquiera de los límites o escribe salida que no es de protocolo a stdout, y cuenta la desconexión como un fallo para restartOnCrash y maxRestarts. Cuando ejecuta con --debug, Claude Code escribe un error nombrando la causa en el registro de depuración.

Plugins LSP disponibles:

Instale el servidor de lenguaje primero, luego instale el plugin desde el marketplace.

Monitors

Los plugins pueden declarar monitores de fondo que Claude Code inicia automáticamente cuando el plugin está activo. Cada monitor ejecuta un comando shell durante la vida útil de la sesión y entrega cada línea de stdout a Claude como una notificación, para que Claude pueda reaccionar a entradas de registro, cambios de estado, o eventos sondeados sin que se le pida que inicie la observación por sí mismo.

Los monitores de plugins usan el mismo mecanismo que la herramienta Monitor y comparten sus restricciones de disponibilidad. Se ejecutan solo en sesiones CLI interactivas, se ejecutan sin sandbox al mismo nivel de confianza que los hooks, y se omiten en hosts donde la herramienta Monitor no está disponible.

Ubicación: monitors/monitors.json en la raíz del plugin, o en línea en plugin.json

Formato: Matriz JSON de entradas de monitor

El siguiente monitors/monitors.json observa un punto final de estado de implementación y un registro de errores local:

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Cambios de estado de implementación"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Registro de errores de aplicación",
    "when": "on-skill-invoke:debug"
  }
]

Para declarar monitores en línea, establezca experimental.monitors en plugin.json en la misma matriz. Para cargar desde una ruta no predeterminada, establezca experimental.monitors en una cadena de ruta relativa como "./config/monitors.json". Los monitores son un componente experimental.

Campos requeridos:

Campos opcionales:

El valor command soporta las sustituciones de ruta ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, y ${CLAUDE_PROJECT_DIR}, más cualquier ${ENV_VAR} del entorno. Prefije el comando con cd "${CLAUDE_PLUGIN_ROOT}" && si el script necesita ejecutarse desde el directorio propio del plugin.

Un command de monitor no puede referenciar valores ${user_config.*}. El comando se ejecuta a través de un shell, por lo que Claude Code rechaza el monitor con un error en lugar de sustituir el valor. Los procesos de monitor no reciben variables de entorno CLAUDE_PLUGIN_OPTION_<KEY>, así que haga que el script de monitor lea el valor de un archivo de configuración que posee.

Si deshabilita un plugin a mitad de sesión, Claude Code no detiene los monitores que ya se están ejecutando; se detienen cuando termina la sesión.

Themes

Los plugins pueden enviar temas de color que aparecen en /theme junto a los presets integrados y los temas locales del usuario. Un tema es un archivo JSON en themes/ con un preset base y un mapa disperso overrides de tokens de color. Los temas son un componente experimental.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Cuando un usuario selecciona un tema de plugin, Claude Code guarda custom:<plugin-name>:<slug> en su configuración. Los temas de plugins son de solo lectura: cuando un usuario presiona Ctrl+E en uno en /theme, Claude Code lo copia en ~/.claude/themes/ para que puedan editar la copia.

Alcances de instalación de plugins

Cuando instala un plugin, elige un alcance que determina dónde está disponible el plugin y quién más puede usarlo:

Los plugins utilizan el mismo sistema de alcances que otras configuraciones de Claude Code. Para instrucciones de instalación y banderas de alcance, consulte Install plugins. Para una explicación completa de los alcances, consulte Configuration scopes.

Plugins de directorio de skills

Cualquier carpeta bajo un directorio de skills que contenga un manifiesto .claude-plugin/plugin.json se carga como un plugin llamado <name>@skills-dir en la siguiente sesión, sin marketplace ni paso de instalación. Cree uno con plugin init. A diferencia de una instalación de marketplace copiada, el plugin se descubre en su lugar en lugar de copiarse en la caché de plugins.

Un árbol de directorio de skills admite tres cosas distintas:

Elija de dónde se carga el plugin

Un plugin de alcance de proyecto se verifica en el repositorio y llega a cada colaborador que lo clona. Debido a que ese contenido proviene del repositorio en lugar de provenir de usted, se carga solo después de la misma puerta de confianza que rige las reglas de permiso de proyecto en .claude/settings.json, por lo que confiar en una carpeta principal o ejecutar con -p no es suficiente, y los componentes que ejecutan código están restringidos aún más:

• Los servidores MCP que declara pasan por la misma aprobación por servidor que un .mcp.json de proyecto
• Los servidores LSP se inician solo después de que confía en el espacio de trabajo
• Los monitores de fondo no se cargan

Los plugins de alcance personal no tienen ninguna de estas restricciones.

Edite, recargue y deshabilite un plugin de directorio de skills

Los cambios que realiza en el SKILL.md de un skill surten efecto inmediatamente en la sesión actual. Los cambios en otros componentes del plugin, como hooks/, .mcp.json, agents/ y output-styles/, no lo hacen. Ejecute /reload-plugins o reinicie Claude Code para aplicarlos. Consulte Detección de cambios en vivo.

Para dejar de cargar un plugin de directorio de skills, elimine su carpeta o deshabilítelo por nombre. No hay un paso uninstall porque nada se instaló desde un marketplace.

claude plugin disable my-tool@skills-dir

Plugins sincronizados desde claude.ai

En Cowork y sesiones en la nube, Claude Code descarga los plugins habilitados para su cuenta de claude.ai en ~/.claude/plugins/synced/ en el entorno propio de la sesión y carga cada uno como <name>@synced, sin marketplace ni registro de instalación. Claude Code no los carga en sesiones que inicia en su propia terminal. Dentro de ese entorno de Cowork o nube, claude plugin list muestra las copias descargadas bajo un encabezado Synced from claude.ai. Antes de v2.1.239, Claude Code cargaba estos plugins como <name>@inline, la identidad que usan los plugins de --plugin-dir.

Administre un plugin sincronizado por el ID <name>@synced que imprime claude plugin list:

• Desactivar uno: en la sesión sincronizada, ejecute claude plugin disable <name>@synced, o pida a Claude que lo ejecute. Claude Code guarda la opción como "<name>@synced": false en el enabledPlugins a nivel de usuario de ese entorno. Para volver a activar el plugin, ejecute claude plugin enable <name>@synced en la misma sesión. Para mantener un plugin fuera de todas las sesiones sincronizadas, desactívelo para su cuenta de claude.ai. Para mantenerlo fuera de las sesiones sincronizadas de un proyecto en todos los entornos, establezca "<name>@synced": false bajo enabledPlugins en el .claude/settings.json comprometido de ese proyecto.
• Administre el plugin en claude.ai: claude plugin install, update y uninstall no se aplican a un plugin sincronizado. Para eliminar uno, desactive el plugin para su cuenta de claude.ai; la siguiente sesión sincronizada comienza sin él.

Cuando un plugin habilitado de cualquier otra fuente, como una instalación de marketplace, un plugin del directorio de skills, o un plugin de --plugin-dir, coincide con el nombre de un plugin sincronizado, Claude Code carga ese plugin e informa que la copia sincronizada no se cargó. Para usar la copia de claude.ai en su lugar, desactive su propia copia. Antes de v2.1.239, Claude Code cargaba la copia sincronizada en lugar de una instalación de marketplace con el mismo nombre.

Esquema de manifiesto de plugins

El archivo .claude-plugin/plugin.json define los metadatos y la configuración de su plugin.

El manifiesto es opcional. Si se omite, Claude Code detecta automáticamente componentes en ubicaciones predeterminadas y deriva el nombre del plugin del nombre del directorio. Use un manifiesto cuando necesite proporcionar metadatos o rutas de componentes personalizadas.

Esquema completo

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Campos requeridos

Si incluye un manifiesto, name es el único campo requerido.

Este nombre se utiliza para espacios de nombres de componentes. Por ejemplo, en la interfaz de usuario, el agente agent-creator para el plugin con nombre plugin-dev aparecerá como plugin-dev:agent-creator.

Campos no reconocidos

Claude Code ignora los campos de nivel superior que no reconoce. Puede mantener metadatos de otro ecosistema en plugin.json y el plugin aún se carga. Esto hace que sea práctico mantener un manifiesto que funcione como manifiesto de extensión de VS Code o Cursor, un package.json de npm, o un manifiesto de paquete MCPB/DXT.

claude plugin validate reporta campos no reconocidos como advertencias, no como errores. Si un campo está a uno o dos caracteres de uno reconocido, la advertencia sugiere el nombre probable previsto. Un plugin con solo advertencias de campos no reconocidos aún pasa la validación y se carga en tiempo de ejecución.

La forma en que Claude Code maneja un campo reconocido cuyo valor tiene el tipo incorrecto depende del campo:

• La mayoría de campos: el plugin no se carga. Por ejemplo, un valor keywords que es una cadena en lugar de un array es un error de carga, y claude plugin validate lo reporta como tal.
• experimental y metadata: Claude Code ignora un valor que no es un objeto, y claude plugin validate reporta una advertencia.

Pase --strict para tratar las advertencias como errores. Úselo en CI para detectar un nombre de campo mal escrito o un campo dejado de otra herramienta de manifiesto antes de publicar, aunque el plugin se cargue en tiempo de ejecución.

claude plugin validate ./my-plugin --strict

Campos de metadatos

Habilitación predeterminada

Establezca defaultEnabled: false en plugin.json para enviar un plugin que se instale deshabilitado. El usuario lo activa con claude plugin enable <plugin> o la interfaz /plugin. Úselo para plugins que agregan costo o alcance en el que un usuario debe optar, como uno que se conecta a un servicio externo.

defaultEnabled es la alternativa cuando nada más ha decidido el estado del plugin. Dos cosas tienen prioridad sobre él:

• La configuración del usuario: una entrada para el plugin en enabledPlugins en cualquier ámbito de configuración. Una vez escrita, persiste en actualizaciones y reinstalaciones de plugins, por lo que cambiar defaultEnabled en una versión posterior no invierte un usuario existente.
• Un requisito de dependencia: cuando un plugin es requerido por otro que está activo, Claude Code escribe true para él en tiempo de instalación o habilitación. Eso le da una configuración explícita, por lo que su propio valor predeterminado ya no se aplica. Vea Habilitar o deshabilitar un plugin con dependencias.

El mismo campo puede aparecer en la entrada de marketplace de un plugin, donde tiene prioridad sobre el valor en plugin.json. Vea Campos de plugin opcionales.

Campos de ruta de componentes

Componentes experimentales

Los componentes bajo la clave experimental, themes y monitors, tienen un esquema de manifiesto que puede cambiar entre versiones mientras se estabilizan. Dónde los declara es una migración separada: el nivel superior aún funciona, claude plugin validate advierte, y una versión futura requerirá experimental.*.

Configuración del usuario

El campo userConfig declara valores que Claude Code solicita al usuario cuando el plugin está habilitado. Úselo en lugar de requerir que los usuarios editen manualmente settings.json.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Las claves deben ser identificadores válidos. Cada opción admite estos campos:

Cada valor está disponible para sustitución como ${user_config.KEY} en configuraciones de servidores MCP y LSP y comandos de hooks. Los valores no sensibles también pueden sustituirse en contenido de skills y agentes. Todos los valores se exportan a procesos de hooks como variables de entorno CLAUDE_PLUGIN_OPTION_<KEY>, donde <KEY> es la clave de opción en mayúsculas.

Los campos que se ejecutan en un shell rechazan ${user_config.*}: sustituir un valor configurado en un comando de shell permitiría que el shell ejecute lo que ese valor contiene, por lo que el componente falla con un error en su lugar. Cada campo rechazado tiene una forma alternativa de pasar el valor:

Antes de v2.1.207, estos campos sustituían valores ${user_config.KEY}; actualice plugins que dependían de esto.

Los valores no sensibles se almacenan bajo la clave pluginConfigs en su settings.json de usuario como pluginConfigs[<plugin-id>].options.

En macOS, Claude Code almacena valores sensibles en el Keychain de macOS, retrocediendo a ~/.claude/.credentials.json cuando el Keychain rechaza la escritura. En plataformas sin un keychain compatible, los almacena en ~/.claude/.credentials.json. El almacenamiento de Keychain se comparte con tokens OAuth y tiene un límite total aproximado de 2 KB, por lo que mantenga los valores sensibles pequeños.

Claude Code lee todos los valores pluginConfigs de solo tres fuentes de configuración:

• Configuración del usuario: ~/.claude/settings.json, el archivo que el aviso de tiempo de habilitación escribe
• --settings: la bandera CLI o configuración en línea de SDK
• Configuración administrada: política controlada por la organización

Cuando más de una fuente establece la misma clave, la configuración administrada tiene prioridad, luego --settings, luego la configuración del usuario. La única fuente que puede eliminar de esta lista es la configuración del usuario: pase --setting-sources sin user y Claude Code las omite. La configuración administrada y --settings permanecen como las pase. La opción settingSources del SDK establece la misma lista.

Las entradas en .claude/settings.json o .claude/settings.local.json de un proyecto se ignoran. Ambos archivos viven en el espacio de trabajo, por lo que un repositorio clonado podría suministrar valores allí, y esos valores fluirían hacia comandos de hooks de plugins, configuraciones de servidores MCP, comandos LSP y comandos de monitores. Antes de v2.1.207, estas entradas se leían. La restricción es específica de pluginConfigs: enabledPlugins aún honra la configuración del proyecto y local.

Canales

El campo channels permite que un plugin declare uno o más canales de mensajes que inyecten contenido en la conversación. Cada canal se vincula a un servidor MCP que proporciona el plugin.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

El campo server es requerido y debe coincidir con una clave en los mcpServers del plugin. El userConfig opcional por canal usa el mismo esquema que el campo de nivel superior, permitiendo que el plugin solicite tokens de bot o IDs de propietario cuando el plugin está habilitado.

Reglas de comportamiento de ruta

Si una ruta personalizada reemplaza o extiende el directorio predeterminado del plugin depende del campo:

• Reemplaza el predeterminado: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Por ejemplo, cuando el manifiesto especifica commands, el directorio predeterminado commands/ no se escanea. Para mantener el predeterminado y agregar más, enumérelo explícitamente: "commands": ["./commands/", "./extras/"]
• Se agrega al predeterminado: skills. El directorio predeterminado skills/ siempre se escanea, y los directorios enumerados en skills se cargan junto a él. Excepción: para una entrada de marketplace cuya source se resuelve a la raíz de marketplace, declarar subdirectorios específicos reemplaza el escaneo predeterminado skills/
• Reglas de fusión propias: hooks, servidores MCP, y servidores LSP. Vea cada sección para cómo se combinan múltiples fuentes

Cuando un plugin tiene tanto una carpeta predeterminada como la clave de manifiesto coincidente, Claude Code advierte sobre la carpeta ignorada en claude plugin list y la vista de detalles /plugin. El plugin aún se carga usando las rutas del manifiesto. Claude Code no advierte cuando la clave del manifiesto apunta dentro de la carpeta predeterminada, por ejemplo "commands": ["./commands/deploy.md"], porque esa ruta nombra la carpeta explícitamente.

Para todos los campos de ruta:

• Todas las rutas deben ser relativas a la raíz del plugin e iniciar con ./, excepto que el campo skills también acepta "."
  • Tanto "." como "./" denotan la raíz del plugin en sí
  • Antes de v2.1.221, "." falló en la validación del manifiesto y el plugin no se cargó, así que use "./" para soportar versiones anteriores
• Los componentes de rutas personalizadas usan las mismas reglas de nomenclatura y espacios de nombres
• Se pueden especificar múltiples rutas como arrays
• Una ruta de skill puede apuntar a un directorio que contiene un SKILL.md directamente, por ejemplo "skills": ["."] para la raíz del plugin
  • Claude Code toma el nombre de invocación del skill del campo name del frontmatter en SKILL.md, por lo que el nombre permanece estable sin importar cómo se nombre el directorio de instalación
  • Si name no está establecido en el frontmatter, Claude Code retrocede al nombre base del directorio

Un plugin que tiene un SKILL.md en su raíz, sin subdirectorio skills/, y sin campo de manifiesto skills se carga automáticamente como un plugin de skill único. No necesita establecer "skills": ["./"] en plugin.json para este diseño.

Ejemplos de ruta:

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

Variables de entorno

Claude Code proporciona tres variables para referenciar rutas:

Los tres se exportan como variables de entorno a procesos de hooks y a subprocesos de servidores MCP y LSP. Qué campos sustituyen en línea depende del componente del plugin:

En comandos de hooks, use forma exec con args para que cada ruta se pase como un argumento sin comillas. En hooks de forma shell y comandos de monitores, envuelva las variables entre comillas dobles, como en "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Este hook de forma shell ejecuta un script incluido con un plugin:

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

${CLAUDE_PLUGIN_ROOT} cambia cuando el plugin se actualiza. El directorio de la versión anterior permanece en el disco durante un período de gracia después de una actualización, pero trátelo como efímero y no escriba estado allí. Vea almacenamiento en caché de plugins para semántica de limpieza.

Cuando un plugin se actualiza a mitad de sesión, comandos de hooks, monitores, servidores MCP y servidores LSP continúan usando la ruta de la versión anterior. Ejecute /reload-plugins para cambiar hooks, servidores MCP y servidores LSP a la nueva ruta; los monitores requieren un reinicio de sesión. En una sesión sin una terminal interactiva, la recarga deja servidores MCP de plugins en la ruta anterior hasta la siguiente sesión.

Para un plugin con una command source, Claude Code puede recargar el plugin en sí.

Los servidores MCP también pueden llamar a la solicitud roots/list para leer los directorios de trabajo de la sesión en tiempo de ejecución. Vea qué devuelve roots/list y cuándo Claude Code notifica al servidor de cambios.

Directorio de datos persistente

El directorio ${CLAUDE_PLUGIN_DATA} se resuelve a ~/.claude/plugins/data/{id}/, donde {id} es el identificador del plugin con caracteres fuera de a-z, A-Z, 0-9, _, y - reemplazados por -. Para un plugin instalado como formatter@my-marketplace, el directorio es ~/.claude/plugins/data/formatter-my-marketplace/.

Un uso común es instalar dependencias de lenguaje una vez y reutilizarlas en sesiones y actualizaciones de plugins. Úselo para dependencias de Python, dependencias bloqueadas con Yarn o pnpm, y paquetes cuyos scripts de ciclo de vida deben ejecutarse. Para un plugin instalado en marketplace, es posible que no lo necesite en absoluto: Claude Code instala automáticamente dependencias de paquetes Node.js elegibles cuando almacena en caché el plugin.

Debido a que el directorio de datos sobrevive a cualquier versión única del plugin, una verificación de existencia de directorio por sí sola no puede detectar cuándo una actualización cambia el manifiesto de dependencia del plugin. El patrón recomendado compara el manifiesto incluido contra una copia en el directorio de datos y reinstala cuando difieren.

Este hook SessionStart instala node_modules en la primera ejecución y nuevamente cada vez que una actualización de plugin incluye un package.json cambiado:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

El diff sale con código distinto de cero cuando la copia almacenada falta o difiere de la incluida, cubriendo tanto la primera ejecución como actualizaciones que cambian dependencias. Si npm install falla, el rm final elimina el manifiesto copiado para que la siguiente sesión reintente.

Los scripts incluidos en ${CLAUDE_PLUGIN_ROOT} pueden ejecutarse contra el node_modules persistente:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

El directorio de datos se elimina automáticamente cuando desinstala el plugin del último ámbito donde está instalado. La interfaz /plugin muestra el tamaño del directorio y solicita confirmación antes de eliminar. El CLI elimina por defecto; pase --keep-data para preservarlo.

Almacenamiento en caché de plugins y resolución de archivos

Los plugins se especifican de una de dos formas:

• A través de claude --plugin-dir o claude --plugin-url, durante la duración de una sesión.
• A través de un marketplace, instalado para sesiones futuras.

Por razones de seguridad y verificación, Claude Code copia los plugins del marketplace en la caché de plugins local del usuario (~/.claude/plugins/cache) en lugar de usarlos en su lugar, excepto para fuentes command en modo de enlace, que Claude Code usa en su lugar a través de enlaces en la entrada de caché.

Para plugins copiados, cada versión instalada es un directorio separado en la caché, agrupado por marketplace y plugin y nombrado para la versión resuelta, con su propia copia de los archivos del plugin y dependencias de paquetes Node.js. Una dependencia resuelta desde una etiqueta de lanzamiento obtiene un nombre de directorio con un sufijo de SHA de confirmación.

Cuando actualiza o desinstala un plugin, Claude Code marca el directorio de versión anterior como huérfano y lo elimina en un barrido de fondo aproximadamente 14 días después. El período de gracia permite que las sesiones concurrentes de Claude Code que ya cargaron la versión anterior sigan ejecutándose sin errores. Claude Code ejecuta el barrido solo mientras al menos un plugin esté instalado; después de desinstalar su último plugin, los directorios huérfanos permanecen en el disco hasta que instale un plugin nuevamente.

Claude Code elimina una carpeta de plugin o marketplace de la caché solo cuando ya no contiene ningún directorio o enlace simbólico. Si vincula un checkout de desarrollo en la caché como entrada de versión de un plugin, Claude Code nunca marca el enlace como huérfano y nunca lo elimina ni las carpetas que lo contienen. Claude Code tampoco escribe nunca sus archivos de seguimiento de versiones dentro del checkout vinculado.

Las herramientas Glob y Grep de Claude omiten directorios de versión huérfanos durante búsquedas, por lo que los resultados de archivos no incluyen código de plugin obsoleto.

Dependencias de paquetes Node.js

Cuando Claude Code copia un plugin en la caché, también instala las dependencias de paquetes Node.js del plugin allí, para que los hooks y servidores MCP del plugin puedan cargarlas. Esta sección cubre los paquetes npm y Bun que un plugin declara en su propio package.json. Para plugins que dependen de otros plugins, consulte versiones de dependencias de plugins.

Claude Code ejecuta la instalación dentro del directorio de versión copiado cada vez que crea uno: cuando instala un plugin, cuando Claude Code actualiza un plugin a una nueva versión, y al inicio de la sesión cuando un plugin habilitado aún no está en caché, como en una máquina nueva. La instalación se ejecuta solo cuando el directorio raíz del plugin contiene tanto un package.json como un archivo de bloqueo compatible:

Si un plugin contiene más de uno de estos archivos de bloqueo, Claude Code usa la primera coincidencia, verificando en orden: bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json. Claude Code omite yarn.lock y pnpm-lock.yaml porque Yarn y pnpm admiten hooks de configuración en tiempo de resolución que omiten --ignore-scripts.

Envíe un archivo de bloqueo npm para el alcance más amplio. Claude Code ejecuta el gestor de paquetes del archivo de bloqueo coincidente desde el PATH del usuario y no recurre al otro archivo de bloqueo si falta. Para un plugin distribuido a través de una fuente npm, use npm-shrinkwrap.json; npm excluye package-lock.json de los paquetes publicados.

Claude Code restringe esta instalación de dependencias para que ningún código del plugin o sus paquetes se ejecute durante ella, y limita cuánto tiempo puede ejecutarse:

• Resolución congelada: Bun y npm instalan exactamente lo que el archivo de bloqueo fija, y fallan en lugar de re-resolver versiones cuando package.json y el archivo de bloqueo no coinciden.
• Sin scripts de ciclo de vida: --ignore-scripts evita que se ejecuten scripts preinstall, install y postinstall, por lo que las dependencias que construyen módulos nativos en esos scripts se descargan pero no se compilan durante esta instalación.
• Tiempo de espera de 60 segundos: Claude Code detiene una instalación que se ejecuta más tiempo y la trata como fallida.

Obtener un plugin de fuente npm en sí ejecuta npm install con scripts de ciclo de vida habilitados, antes de que se ejecute esta instalación de dependencias.

Una instalación fallida u omitida nunca bloquea el plugin. Cuando la instalación falla, o Claude Code omite un archivo de bloqueo yarn o pnpm, registra el motivo como una advertencia en salida de depuración. Un plugin con un package.json y sin archivo de bloqueo se omite sin una entrada de registro. Una instalación que agota el tiempo de espera puede dejar un árbol node_modules parcial en la copia en caché.

No puede desactivar la instalación automática; ninguna configuración o variable de entorno la desactiva. En redes restringidas, consulte los requisitos de acceso a la red para los hosts a permitir.

Para dependencias que la instalación automática no puede proporcionar, como paquetes que necesitan sus scripts de ciclo de vida para construir, dependencias de Python, o un plugin bloqueado con Yarn o pnpm, instálelas desde un hook en el directorio de datos persistentes.

Limitaciones de traversal de rutas

Claude Code no permite que un plugin haga referencia a archivos fuera de su propio directorio. Rechaza una ruta de componente que se resuelve fuera de la raíz del plugin, ya sea que la ruta se declare en plugin.json o en una entrada de marketplace. Eso cubre una ruta que apunta fuera del plugin tal como está escrito, como ../shared-utils, y un enlace simbólico que conduce fuera del plugin, que no sea enlaces dentro de un marketplace.

En macOS y Linux, Claude Code también rechaza una ruta de componente que contiene una barra invertida en cualquier lugar, incluso cuando la ruta permanece dentro del plugin. Los componentes declarados con rutas de barra invertida, por lo tanto, se cargan solo en Windows. Escriba rutas de componentes con barras diagonales, como ./commands/deploy.md.

Cuando Claude Code rechaza una ruta, reporta un error path escapes plugin directory y carga el plugin sin ese componente.

Claude Code tampoco copia archivos fuera del directorio del plugin en la caché cuando instala el plugin, por lo que cuando un script dentro de un plugin copiado lee una ruta por encima de la raíz del plugin, tampoco encuentra esos archivos.

Compartir archivos dentro de un marketplace con enlaces simbólicos

Si su plugin necesita compartir archivos con otras partes del mismo marketplace, puede crear enlaces simbólicos dentro de su directorio de plugin. Cómo se maneja un enlace simbólico cuando el plugin se copia en la caché depende de dónde se resuelve su destino:

• Dentro del propio directorio del plugin: el enlace simbólico se preserva como un enlace simbólico relativo en la caché, por lo que sigue resolviendo al destino copiado en tiempo de ejecución.
• En otro lugar dentro del mismo marketplace: el enlace simbólico se desreferencia. El contenido del destino se copia en la caché en su lugar. Esto permite que el directorio skills/ de un meta-plugin se vincule a skills definidas por otros plugins en el marketplace.
• Fuera del marketplace: el enlace simbólico se omite por seguridad. Esto evita que los plugins extraigan archivos de host arbitrarios como rutas del sistema en la caché.

Para plugins instalados con --plugin-dir, desde una ruta local, o desde una fuente command en modo de copia, solo se preservan los enlaces simbólicos que se resuelven dentro del propio directorio del plugin. Todos los demás se omiten.

El siguiente comando crea un enlace desde dentro de un plugin de marketplace a una skill compartida definida por un plugin hermano. En Windows, use mklink /D desde un símbolo del sistema elevado o habilite el Modo de desarrollador:

ln -s ../../shared-plugin/skills/foo ./skills/foo

Estructura de directorios de plugins

Diseño estándar de plugins

Un plugin completo sigue esta estructura:

enterprise-plugin/
├── .claude-plugin/           # Directorio de metadatos (opcional)
│   └── plugin.json             # manifiesto del plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills como archivos .md planos
│   ├── status.md
│   └── logs.md
├── agents/                   # Definiciones de subagentes
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Scripts de flujo de trabajo
│   └── release-audit.js
├── output-styles/            # Definiciones de estilos de salida
│   └── terse.md
├── themes/                   # Definiciones de temas de color
│   └── dracula.json
├── monitors/                 # Configuraciones de monitores de fondo
│   └── monitors.json
├── hooks/                    # Configuraciones de hooks
│   ├── hooks.json           # Configuración principal de hooks
│   └── security-hooks.json  # Hooks adicionales
├── bin/                      # Ejecutables de plugins agregados a PATH
│   └── my-tool               # Invocable como comando desnudo en la herramienta Bash
├── settings.json            # Configuración predeterminada para el plugin
├── .mcp.json                # Definiciones de servidores MCP
├── .lsp.json                # Configuraciones de servidores LSP
├── scripts/                 # Scripts de hooks y utilidades
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Archivo de licencia
└── CHANGELOG.md             # Historial de versiones

Un archivo CLAUDE.md en la raíz del plugin no se carga como contexto del proyecto. Los plugins contribuyen contexto a través de skills, agentes y hooks en lugar de CLAUDE.md. Para enviar instrucciones que se carguen en el contexto de Claude, colóquelas en un skill.

Referencia de ubicaciones de archivos

Referencia de comandos CLI

Claude Code proporciona comandos CLI para la gestión de plugins no interactiva, útil para scripting y automatización.

plugin init

Crea un nuevo plugin en ~/.claude/skills/<name>/. En la siguiente sesión de Claude Code se carga automáticamente como <name>@skills-dir y aparece en /plugin y claude plugin list sin necesidad de un paso de instalación.

Consulte Plugins de directorio de skills para conocer los requisitos de alcance y confianza.

claude plugin init <name> [options]

El comando toma estos argumentos:

• <name>: Nombre del plugin. Se convierte en el espacio de nombres de la skill y el nombre del directorio bajo ~/.claude/skills/, por lo que no puede contener espacios ni separadores de ruta.

El comando acepta estas opciones:

claude plugin new es un alias para este comando.

Cada valor --with añade un archivo de inicio para ese componente, listo para editar:

El plugin creado utiliza la fuente @skills-dir en lugar de un marketplace. Los administradores pueden bloquear esta fuente con strictKnownMarketplaces o añadiendo {"source": "skills-dir"} a blockedMarketplaces en configuración administrada. Cuando está bloqueado, plugin init falla antes de escribir.

Estos ejemplos muestran invocaciones comunes:

# Crea un plugin mínimo
claude plugin init my-helper

# Crea con carpetas de skill y hook
claude plugin init my-helper --with skills hooks

# Sobrescribe un scaffold existente
claude plugin init my-helper --force

plugin install

Instala un plugin desde los marketplaces disponibles.

claude plugin install <plugin> [options]

El comando toma estos argumentos:

• <plugin>: Nombre del plugin o plugin-name@marketplace-name para un marketplace específico

El comando acepta estas opciones:

El alcance determina qué archivo de configuración se añade al plugin instalado. Por ejemplo, --scope project escribe en enabledPlugins en .claude/settings.json, haciendo que el plugin esté disponible para todos los que clonan el repositorio del proyecto.

Con --json, la última línea de stdout es un objeto JSON. Analice solo esa línea, porque Claude Code imprime cualquier comando que el marketplace declara antes de ella. Tres campos siempre están presentes:

• command: el subcomando que se ejecutó, como install
• outcome: ok o failed
• message: una descripción legible por humanos del resultado

Otros campos, como pluginId, scope y failureCode, aparecen solo cuando aplican. La opción --json en plugin uninstall, plugin update, plugin enable y plugin disable imprime el mismo objeto con los propios campos de ese subcomando. Un error de uso, como un --scope inválido, no imprime ninguna línea de resultado y sale con 1 con la razón en stderr.

Estos ejemplos muestran invocaciones comunes:

# Instala en alcance de usuario (predeterminado)
claude plugin install formatter@my-marketplace

# Instala en alcance de proyecto (compartido con el equipo)
claude plugin install formatter@my-marketplace --scope project

# Instala en alcance local (no compartido con el equipo)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Elimina un plugin instalado.

claude plugin uninstall <plugin> [options]

El comando toma estos argumentos:

• <plugin>: Nombre del plugin o plugin-name@marketplace-name

El comando acepta estas opciones:

claude plugin remove y claude plugin rm son alias para este comando.

De forma predeterminada, desinstalar desde el último alcance restante también elimina el directorio ${CLAUDE_PLUGIN_DATA} del plugin. Use --keep-data para preservarlo, por ejemplo al reinstalar después de probar una nueva versión.

plugin prune

Elimina las dependencias de plugins instaladas automáticamente que ya no son requeridas por ningún plugin instalado. Las dependencias que Claude Code incluyó para satisfacer el campo dependencies de otro plugin se eliminan; los plugins que instaló directamente nunca se tocan.

claude plugin prune [options]

El comando acepta estas opciones:

claude plugin autoremove es un alias para este comando.

El comando lista las dependencias huérfanas y solicita confirmación antes de eliminarlas. Para eliminar un plugin y limpiar sus dependencias en un paso, ejecute claude plugin uninstall <plugin> --prune.

plugin enable

Habilita un plugin deshabilitado. Cuando el destino está instalado desde un marketplace y declara dependencias, Claude Code las habilita transitivamente en el mismo alcance. El comando falla bajo las condiciones que Habilitar o deshabilitar un plugin con dependencias lista.

claude plugin enable <plugin> [options]

El comando toma estos argumentos:

• <plugin>: Nombre del plugin o plugin-name@marketplace-name

El comando acepta estas opciones:

plugin disable

Deshabilita un plugin sin desinstalarlo. Cuando el destino está instalado desde un marketplace, el comando falla si otro plugin habilitado depende de él. El mensaje de error incluye un comando encadenado que deshabilita primero cada dependiente.

claude plugin disable [plugin] [options]

El comando toma estos argumentos:

• [plugin]: Nombre del plugin o plugin-name@marketplace-name. Opcional cuando se usa --all

El comando acepta estas opciones:

plugin update

Actualiza un plugin a la versión más reciente.

claude plugin update <plugin> [options]

El comando toma estos argumentos:

• <plugin>: Nombre del plugin o plugin-name@marketplace-name

El comando acepta estas opciones:

plugin list

Lista los plugins instalados con su versión, marketplace de origen y estado de habilitación.

claude plugin list [options]

El comando acepta estas opciones:

Dentro de una sesión interactiva, /plugin list imprime un listado similar en línea, pero solo cubre plugins instalados desde marketplace:

• Los plugins cargados desde directorios de skills aparecen en la interfaz /plugin y en claude plugin list, pero no en la salida en línea de /plugin list.
• En Claude Code v2.1.239 o posterior, los plugins sincronizados desde claude.ai aparecen en claude plugin list cuando lo ejecuta en el entorno donde una sesión sincronizada los descargó. No aparecen en la salida en línea de /plugin list.
• Los plugins cargados para la sesión con --plugin-dir o --plugin-url aparecen en la interfaz /plugin, y en claude plugin list solo cuando la misma bandera precede al subcomando, como en claude --plugin-dir <dir> plugin list. Solo el nombre de la bandera nombra su ubicación, así que un claude plugin list sin calificar no puede encontrarlos, a diferencia de los plugins sincronizados y los plugins del directorio de skills, cuyos directorios fijos escanea Claude Code.

El formulario interactivo acepta --enabled o --disabled para mostrar solo los plugins en ese estado, y ls como abreviatura de list.

plugin details

Muestra el inventario de componentes de un plugin y el costo de token proyectado. La salida lista todos los componentes que contribuye el plugin, agrupados como Skills, Agents, Hooks, servidores MCP y servidores LSP, junto con una estimación de cuántos tokens añade a cada sesión. El grupo Skills incluye entradas tanto de skills/ como de commands/.

claude plugin details <name>

El comando toma estos argumentos:

• <name>: Nombre del plugin o plugin-name@marketplace-name

El comando acepta estas opciones:

La salida muestra dos cifras de costo para cada componente:

• Siempre activo: tokens añadidos a cada sesión por el texto de listado del plugin, como descripciones de skills, descripciones de agents y nombres de comandos, independientemente de si algún componente se activa.
• Al invocar: tokens que cuesta un componente cuando se activa. Se muestra por componente, no como total del plugin, porque una sesión típica invoca solo un subconjunto de componentes.

Este ejemplo muestra cómo se ve la salida para un plugin con dos skills:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

El total siempre activo se calcula a través de la API count_tokens para su modelo activo. Los números por componente se escalan proporcionalmente desde ese total. Si la API es inaccesible, el comando recurre a una estimación basada en caracteres.

plugin validate

Verifica un plugin o un marketplace para detectar errores de sintaxis y esquema antes de publicar.

El comando sale con 0 cuando la validación pasa, 1 cuando falla, y 2 cuando la propia ejecución de validación falla, como cuando la ruta que pasa es ilegible.

claude plugin validate <path> [options]

El comando toma estos argumentos:

• <path>: Ruta a un directorio de plugin o un directorio de marketplace. Consulte Validar un plugin o un directorio sin manifiesto para saber qué archivos cubre una ejecución de plugin.

El comando acepta estas opciones:

Con --json, Claude Code escribe el informe en stdout como un objeto JSON con estos campos de nivel superior:

• success: el mismo veredicto que da el código de salida
• strict: si la ejecución trató las advertencias como errores
• target: la ruta resuelta que Claude Code validó
• manifest: el resultado del propio manifiesto, o null para una ejecución sin manifiesto
• contents: resultados por archivo, cada uno nombrando su file y llevando matrices errors, warnings y notes

En salida 2, el comando no escribe nada en stdout; el mensaje de error va a stderr.

Dentro de una sesión interactiva, /plugin validate <path> ejecuta las mismas verificaciones en línea.

plugin eval

Ejecuta los casos de eval de un plugin e informa resultados puntuados. Requiere Claude Code v2.1.269 o posterior. Cada caso es un prompt más calificadores; Claude Code lo ejecuta varias veces en una sesión aislada con solo el plugin de destino cargado, y por defecto también sin el plugin para que el informe muestre la diferencia. Consulte Probar plugins con evals para el formato de caso, calificadores, resultados y uso en CI.

claude plugin eval [target] [options]

El target opcional es un directorio de plugin, un archivo único prompt.md o case.yaml, un plugin instalado como name o name@marketplace, o name@skills-dir, y por defecto es el directorio actual. Colóquelo antes de --tag, --allow-tools y --json.

Esta tabla lista las opciones que la mayoría de ejecuciones usan. Ejecute claude plugin eval --help para el conjunto completo, incluyendo --case, --tag, --output-dir, --report, --allow-real-servers, --keep-temp y --verbose.

El comando sale con 0 cuando cada caso cumple el umbral, 1 en un caso fallido, un error de carga o un directorio de plugin no confiable, 2 en una ejecución parcial, 130 cuando se interrumpe y 143 cuando se termina. Consulte Ejecutar evals en CI.

plugin eval init

Crea un conjunto de eval para el plugin en el directorio actual. Requiere Claude Code v2.1.269 o posterior. En una terminal esto inicia una entrevista de autoría que lee el plugin, propone casos y calificadores, los prueba y escribe los archivos. Con --bare, o sin una terminal, escribe una plantilla de caso único en blanco en su lugar. Ejecutado desde dentro de una sesión interactiva de Claude Code, imprime las instrucciones de entrevista para que esa sesión siga en lugar de escribir una plantilla. Consulte Crear su primer conjunto de eval.

claude plugin eval init [name] [options]

El name opcional es un nombre de caso: la entrevista no necesita uno, mientras que --bare y la ruta de plantilla sin terminal lo requieren. Acepta estas opciones:

plugin tag

Crea una etiqueta git de lanzamiento para un plugin. De forma predeterminada, el comando etiqueta el plugin en el directorio actual; pase una ruta para etiquetar un plugin en otro lugar. Consulte Etiquetar lanzamientos de plugins.

claude plugin tag [path] [options]

El comando toma estos argumentos:

• [path]: Ruta al directorio del plugin. Por defecto es el directorio actual.

El comando acepta estas opciones:

Herramientas de depuración y desarrollo

Comandos de depuración

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

Esto muestra:

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

Problemas comunes

Ejemplos de mensajes de error

Errores de validación de manifiestos:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: verifique si hay comas faltantes, comas adicionales o cadenas sin comillas
• Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: falta un campo requerido
• Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: error de sintaxis JSON. Antes de v2.1.246, Claude Code también producía este error para un plugin.json guardado como UTF-8 con una marca de orden de bytes (BOM) inicial, incluso cuando el JSON era válido de otra manera.

Errores de carga de plugins:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: la ruta del comando existe pero no contiene archivos de comando válidos
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: la ruta source en marketplace.json apunta a un directorio inexistente
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: elimine definiciones de componentes duplicadas o elimine strict: false en la entrada del marketplace

Solución de problemas de hooks

El script del hook no se ejecuta:

1. Verifique que el script sea ejecutable: chmod +x ./scripts/your-script.sh
2. Verifique la línea shebang: La primera línea debe ser #!/bin/bash o #!/usr/bin/env bash
3. Verifique que la ruta use ${CLAUDE_PLUGIN_ROOT}: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Pruebe el script manualmente: ./scripts/your-script.sh

El hook no se activa en los eventos esperados:

1. Verifique que el nombre del evento sea correcto (sensible a mayúsculas): PostToolUse, no postToolUse
2. Verifique que el patrón del matcher coincida con sus herramientas: "matcher": "Write|Edit" para operaciones de archivo
3. Confirme que el tipo de hook sea válido: command, http, mcp_tool, prompt o agent

Solución de problemas del servidor MCP

El servidor no se inicia:

1. Verifique que el comando exista y sea ejecutable
2. Verifique que todas las rutas usen la variable ${CLAUDE_PLUGIN_ROOT}
3. Verifique los registros del servidor MCP: claude --debug muestra errores de inicialización
4. Pruebe el servidor manualmente fuera de Claude Code

Las herramientas del servidor no aparecen:

1. Asegúrese de que el servidor esté correctamente configurado en .mcp.json o plugin.json
2. Verifique que el servidor implemente correctamente el protocolo MCP
3. Verifique si hay tiempos de espera de conexión en la salida de depuración

Errores de estructura de directorio

Síntomas: El plugin se carga pero faltan componentes (skills, agentes, hooks).

Estructura correcta: Los componentes deben estar en la raíz del plugin, no dentro de .claude-plugin/. Solo plugin.json pertenece a .claude-plugin/.

Lista de verificación de depuración:

1. Ejecute claude --debug y busque mensajes "loading plugin"
2. Verifique que cada directorio de componentes esté listado en la salida de depuración
3. Verifique que los permisos de archivo permitan leer los archivos del plugin

Referencia de distribución y versionado

Gestión de versiones

Claude Code utiliza la versión del plugin como clave de caché que determina si hay una actualización disponible. Cuando ejecuta /plugin update o se activa la actualización automática, Claude Code calcula la versión actual y omite la actualización si coincide con la que ya está instalada.

Para cada tipo de fuente excepto command, Claude Code resuelve la versión a partir de la primera de estas que esté establecida:

1. El campo version en el plugin.json del plugin
2. El campo version en la entrada del plugin en el marketplace en marketplace.json
3. El SHA del commit de git de la fuente del plugin, para fuentes github, url, git-subdir y relative-path en un marketplace alojado en git
4. El resumen SHA-256, para fuentes archive: el pin sha256 en la entrada del marketplace, o el resumen del archivo descargado cuando no establece ningún pin. Claude Code lo acorta a los primeros 12 caracteres
5. unknown, para fuentes npm o directorios locales que no estén dentro de un repositorio de git

Para una fuente command, Claude Code siempre deriva la versión de lo que produjo el comando: un hash de contenido de 12 caracteres por sí solo, o anexado a la versión plugin.json como <version>-<hash> cuando se establece uno. Claude Code ignora el campo version de la entrada del marketplace para fuentes de comando. Un comando cuya salida con hash cambia, por lo tanto, produce una nueva versión, incluso cuando la cadena de versión creada permanece igual. En modo de enlace, el hash cubre la ruta real del directorio impreso y sus entradas de nivel superior en lugar del contenido del archivo.

Para esos tipos de fuente, esto le proporciona tres formas de versionar un plugin:

Si utiliza versiones explícitas, siga versionado semántico (MAJOR.MINOR.PATCH): incremente MAJOR para cambios que rompan la compatibilidad, MINOR para nuevas características, PATCH para correcciones de errores. Documente los cambios en un CHANGELOG.md.

Ver también

• Plugins - Tutoriales y uso práctico
• Marketplaces de plugins - Crear y gestionar marketplaces
• Skills - Detalles de desarrollo de skills
• Subagents - Configuración y capacidades del agent
• Hooks - Manejo de eventos y automatización
• MCP - Integración de herramientas externas
• Configuración - Opciones de configuración para plugins