Referencia del manifiesto de plugins

Referencia completa de plugin.json: cada campo con su tipo y valor predeterminado, formas de ruta aceptadas, y los esquemas de userConfig y variables de entorno.

Un manifiesto de plugin es el archivo plugin.json en el directorio .claude-plugin/ de un plugin. Contiene los metadatos del plugin y los valores de userConfig que Claude Code solicita al usuario. También declara cualquier componente que defina en línea o que mantenga fuera de su ubicación predeterminada.

Esta referencia es para creadores de plugins y para propietarios de mercados que colocan campos de componentes en una entrada del mercado.

Comience en la sección que coincida con lo que está buscando:

• Un campo: la tabla de campos proporciona el tipo de cada campo, si es obligatorio, su valor predeterminado y qué acepta. Reglas de ruta cubre el prefijo ./ y la contención para cada ruta de componente
• Una opción userConfig o una entrada channels: los esquemas de Configuración del usuario y Canales
• ${CLAUDE_PLUGIN_ROOT} u otra variable que un plugin pueda referenciar: Variables de entorno
• Dónde van los archivos de cada componente: Diseño estándar
• Un mensaje de claude plugin validate: la página de solución de problemas enumera cada mensaje con su solución y enlaces a las secciones relevantes en esta página

Archivo de manifiesto

El manifiesto es opcional. Sin él, Claude Code carga los componentes que encuentra en el diseño estándar. El nombre del plugin proviene de la entrada del mercado o del nombre del directorio cuando carga el plugin con --plugin-dir.

Escriba un manifiesto cuando desee metadatos, un componente fuera de su directorio predeterminado, userConfig, o una definición de componente en línea.

Guarde el manifiesto en .claude-plugin/plugin.json bajo la raíz del plugin. Coloque todos los demás archivos del plugin en la raíz del plugin, no dentro de .claude-plugin/. Esto incluye skills/, commands/ y hooks/.

El siguiente ejemplo establece la mayoría de las claves en la tabla de campos. Pasa la validación en un directorio de plugin que contiene cada ruta referenciada.

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

Campos no reconocidos

Una clave de nivel superior no reconocida se elimina, y una clave no reconocida dentro de una opción userConfig, entrada channels, configuración lspServers o entrada monitors se rechaza:

• Campos de nivel superior: el campo se elimina y el plugin se carga. claude plugin validate reporta cada campo de nivel superior no reconocido como una advertencia
• Objetos estrictos: las opciones userConfig, entradas channels, configuraciones lspServers y entradas monitors son estrictas. Una clave desconocida dentro de una es un error, y el plugin no se carga

Validar el manifiesto

claude plugin validate es la verificación autorizada para un manifiesto. Ejecútelo desde su shell contra el directorio del plugin:

claude plugin validate ./my-plugin

El comando reporta uno de estos resultados:

• Validation passed: el manifiesto se carga
• Validation passed with warnings: el manifiesto se carga, pero el validador encontró algo que corregir, como un campo de nivel superior desconocido que Claude Code elimina, un name que no está en kebab-case, o un version, description o author faltante. Pase --strict para convertir advertencias en fallos en CI
• Validation failed: el manifiesto tiene una discrepancia de tipo, una ruta que falta o escapa de la raíz del plugin, o una clave desconocida dentro de una opción userConfig, entrada channels, configuración lspServers o entrada monitors. Claude Code reporta el mismo problema cuando carga el plugin

Campos

La tabla enumera las claves de nivel superior en plugin.json. name es la única clave obligatoria. Donde un nombre de campo es un enlace, la sección vinculada tiene sus reglas completas.

Para claves de componentes como commands y hooks, Formas de ruta de componente muestra cada forma aceptada con un ejemplo, y cada ruta sigue las reglas de ruta para el prefijo ./, extensiones y contención.

En la columna Tipo, una ruta es una cadena relativa a la raíz del plugin, como "./custom/commands".

`name`

El identificador del plugin. Debe ser no vacío, sin espacios, @, :, separadores de ruta, caracteres de control o caracteres de formato bidireccional; use kebab-case.

Claude Code espacía cada componente bajo él, por lo que un agente reviewer en el plugin deploy-tools aparece como deploy-tools:reviewer.

`displayName`

El nombre mostrado en la UI en lugar de name. Puede contener espacios y cualquier mayúscula, y no se usa para espaciado o búsqueda.

Para un plugin instalado desde el mercado, un displayName en la entrada del mercado tiene precedencia sobre este valor.

`version`

Una cadena de versión, no se verifica contra semver. Configurarla fija el plugin a esa versión hasta que la cambie; consulte Versiones y actualizaciones. Un plugin con una command source, un plugin de un mercado alojado en claude.ai, y un plugin cargado en su lugar desde un mercado agregado como directorio local no se fijan por este campo.

`metadata`

Un objeto de forma libre para sus propios datos, como campos de catálogo o derechos. Claude Code no lo lee. Requiere Claude Code v2.1.222 o posterior.

`defaultEnabled`

Si el plugin comienza habilitado cuando el usuario no lo ha configurado en enabledPlugins. Por defecto es true. Un plugin del que depende un plugin habilitado comienza habilitado independientemente. El mismo campo en la entrada del mercado anula este.

Una vez que se escribe la entrada enabledPlugins de un usuario, persiste en las actualizaciones del plugin, por lo que cambiar defaultEnabled en una versión posterior no cambia la configuración para un usuario existente.

`dependencies`

Plugins que deben estar habilitados para que este funcione. Cada entrada es "name", "name@marketplace", o { "name": "...", "marketplace": "...", "version": "..." }. Los nombres simples se resuelven contra el propio mercado de este plugin. Consulte restricciones de dependencia.

`settings`

Configuración que Claude Code aplica mientras el plugin está habilitado. Solo agent y subagentStatusLine tienen efecto; otras claves se descartan en la carga. Un settings.json en la raíz del plugin tiene precedencia sobre esta clave. Consulte Configuración predeterminada.

Formas de ruta de componente

Cada clave de componente acepta una ruta relativa a la raíz del plugin. hooks, mcpServers, lspServers y experimental.monitors también aceptan configuración en línea, commands también acepta un objeto mapa, y mcpServers también acepta rutas de bundle MCP y URLs. Los ejemplos que siguen muestran cada forma aceptada una vez. Para qué hace cada componente en tiempo de ejecución, consulte Componentes de plugins.

Campos solo de ruta

agents, skills, outputStyles, workflows y experimental.themes toman una ruta o un array de rutas. Las entradas agents deben ser archivos .md, y las entradas skills deben ser directorios. Los otros tres aceptan un directorio o un archivo.

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

`commands`

commands toma una ruta, un array de rutas, u un objeto mapa. Una ruta nombra un archivo de comando .md plano o un directorio. En el objeto mapa, cada clave se convierte en el nombre del comando después del prefijo del plugin. Por ejemplo, "about" en el plugin deploy-tools se ejecuta como /deploy-tools:about.

Cada valor establece exactamente uno de source o content, y una entrada que establece ambos o ninguno falla la validación. Los otros campos en esta tabla son opcionales:

Este mapa declara un comando de un archivo y uno de contenido en línea:

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

`hooks`

hooks toma una ruta de archivo .json, un objeto hooks en línea en la misma forma que hooks en settings.json, o un array que mezcla ambos. Para eventos de hook y campos de controlador, consulte la referencia de hooks.

Claude Code fusiona lo que declare con hooks/hooks.json cuando ese archivo existe.

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

`mcpServers`

mcpServers toma una ruta de archivo .json, una ruta de bundle MCP o URL, un mapa en línea, o un array que mezcla ellos. Para campos de configuración del servidor, consulte servidores MCP proporcionados por plugin.

Claude Code carga .mcp.json en la raíz del plugin primero, luego cada forma declarada en orden. Un nombre de servidor declarado después reemplaza uno anterior.

Un valor mcpServers toma una de estas formas:

Una ruta de bundle o URL debe terminar en .mcpb o .dxt. Cualquier otra extensión falla la validación.

`lspServers`

lspServers toma una ruta de archivo .json, un mapa en línea de nombre de servidor a configuración, o un array de cualquiera.

Claude Code carga .lsp.json en la raíz del plugin primero, luego cada configuración declarada en orden. Un nombre de servidor declarado después reemplaza uno anterior.

Cada configuración de servidor es un objeto estricto con estos campos. Una clave desconocida falla la validación.

Esta configuración en línea ejecuta gopls para archivos .go:

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

Para los servidores de lenguaje que Anthropic publica como plugins y cómo se comportan los servidores en tiempo de ejecución, consulte Inteligencia de código.

`monitors`

experimental.monitors toma una ruta de archivo .json o el array en línea. Cuando omite la clave, Claude Code carga monitors/monitors.json si existe.

Cada entrada es un objeto estricto con estos campos.

Este array en línea declara un monitor que comienza la primera vez que se ejecuta la skill deploy:

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

Un command de monitor no puede referenciar ${user_config.*}. Consulte Campos que se ejecutan a través de un shell.

Reglas de ruta

Cada ruta de componente en un manifiesto es relativa a la raíz del plugin y debe comenzar con ./. Una ruta como commands/foo.md falla la validación. skills y mcpServers cada uno aceptan una forma fuera de esa regla:

• skills: también acepta ".". Tanto "." como "./" denotan la raíz del plugin. Antes de v2.1.221, "." fallaba la validación del manifiesto, así que use "./" cuando el plugin deba cargarse en versiones anteriores
• mcpServers: también acepta una URL de bundle https://

Contención y existencia

Cada ruta de componente debe resolverse dentro de la raíz del plugin y debe existir. claude plugin validate no verifica las rutas outputStyles, lspServers, monitors o themes, por lo que una ruta incorrecta en esos campos falla solo cuando el plugin se carga:

• Contención: una ruta que se resuelve fuera de la raíz del plugin no se carga, y la pestaña Errors de /plugin muestra <component> path escapes plugin directory: <path>. Una ruta que contiene .. es el caso usual, y claude plugin validate la reporta como Path contains ".." which could be a path traversal attempt
• Existencia: una ruta que no existe no se carga, y la pestaña Errors de /plugin muestra <component> path not found: <path>. claude plugin validate la reporta como Path not found

Cómo cada clave se combina con su ubicación predeterminada

Cada clave de componente reemplaza su ubicación predeterminada, se suma a ella, o se fusiona con ella:

• Reemplaza el predeterminado: commands, agents, outputStyles, workflows, experimental.themes, experimental.monitors. Cuando establece commands, el directorio predeterminado commands/ no se escanea. Para mantener el predeterminado y agregar más, enumérelo explícitamente: "commands": ["./commands/", "./extras/"]
• Se suma al predeterminado: skills. El directorio skills/ aún se escanea, y los directorios enumerados se cargan junto a él
• Se fusiona: hooks, mcpServers, lspServers. El archivo predeterminado se carga primero, y lo que declara el manifiesto se fusiona en él, como se describe en Formas de ruta de componente

Si un plugin tiene una carpeta predeterminada como commands/ y también establece la clave de manifiesto que la reemplaza, Claude Code carga las rutas del manifiesto y no la carpeta. claude plugin list y la interfaz /plugin entonces muestran la advertencia Default <folder>/ folder is ignored because the manifest sets "<key>".

Para evitar la advertencia, establezca la clave en una ruta dentro de esa carpeta: "commands": ["./commands/deploy.md"] nombra un archivo en la carpeta predeterminada y no produce advertencia.

Configuración del usuario

userConfig declara valores que Claude Code solicita al usuario cuando el plugin está habilitado, por lo que los usuarios no editan settings.json ellos mismos.

Las claves son identificadores hechos de letras, dígitos y guiones bajos, y no pueden comenzar con un dígito.

Cada valor es un objeto estricto con estos campos. Una clave desconocida falla la validación.

Cada opción de cada plugin habilitado también aparece como una fila en el panel /config, excepto opciones sensitive y listas multiple. Las filas /config requieren Claude Code v2.1.269 o posterior.

Este userConfig declara un punto final y un token enmascarado:

{
  "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
    }
  }
}

Limitar un campo a opciones fijas

Establezca options en un campo userConfig para que los usuarios elijan su valor de una lista fija.

Para limitar un campo tone a tres opciones, enumérelas en options y establezca default en una de ellas:

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

Si declara options en cualquier campo, los usuarios en versiones de Claude Code anteriores a v2.1.271 no pueden cargar el plugin.

options se aplica a un campo string que no es multiple o sensitive. Establezca default en uno de los valores enumerados, o establezca required: true para que el usuario deba elegir uno. Cada opción es una etiqueta simple de 1 a 64 caracteres, y claude plugin validate, que ejecuta en su shell, reporta cualquier otra cosa que rechace. Un plugin cuyas options rompan estas reglas no se carga.

Dónde se almacenan los valores

Los valores no sensibles se guardan bajo pluginConfigs en el settings.json del usuario. Los valores sensibles van al almacén de credenciales seguro de la plataforma en su lugar. La página de configuración enumera qué archivos de configuración se leen desde pluginConfigs.

Referenciar un valor guardado

Referencie un valor guardado donde el plugin lo necesite, en una de dos formas:

• ${user_config.KEY}: sustituido en configuración de servidor MCP, configuración de servidor LSP, forma exec hook args, y contenido de skill y agente. En contenido de skill y agente, solo se sustituyen valores no sensibles, y un valor sensible allí se convierte en un marcador de posición
• CLAUDE_PLUGIN_OPTION_<KEY>: exportado a procesos de hook para cada opción, con <KEY> en mayúsculas. Un hook de forma shell lee $CLAUDE_PLUGIN_OPTION_API_TOKEN para api_token

Campos que se ejecutan a través de un shell

Los comandos de hook de forma shell, comandos de monitor y MCP headersHelper rechazan ${user_config.*}. Un componente que lo referencia en uno de estos campos falla con un error en lugar de ejecutarse, porque el valor del campo se pasa a un shell que volvería a analizar el valor sustituido.

La tabla muestra cómo el valor puede llegar a cada uno de estos campos en su lugar.

Canales

channels declara los canales de mensajes que proporciona un plugin, como un puente a una aplicación de chat. Cuando declara uno, Claude Code puede solicitar la configuración del canal cuando el plugin está habilitado. Para cómo el servidor inyecta mensajes, consulte la referencia de canales.

Cada entrada es un objeto estricto vinculado a uno de los servidores MCP del plugin, con estos campos:

Este manifiesto vincula un canal al servidor MCP telegram del plugin y solicita un token de bot que se sustituye en el env del servidor:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

Variables de entorno

Claude Code proporciona tres variables de ruta a componentes de plugin. Referenciarlas como ${NAME} en los campos enumerados en Dónde se resuelve cada variable, y léalas como variables de entorno en los procesos que las reciben.

${CLAUDE_PLUGIN_ROOT} cambia cuando el plugin se actualiza, así que no escriba estado allí. Para dónde se mueve la raíz y cuándo se limpia el directorio antiguo, consulte la página de carga.

Cuando desinstala el plugin del último lugar donde está instalado, el directorio ${CLAUDE_PLUGIN_DATA} se elimina a menos que pase --keep-data.

Dónde se resuelve cada variable

En cada componente de plugin, las referencias ${...} se resuelven en línea en campos específicos, y algunos componentes también reciben las variables en su entorno de proceso:

Las variables no están presentes en el entorno de comandos que Claude ejecuta a través de la herramienta Bash, en la sesión principal o en un subagente. En contenido de skill, comando y agente, escriba la referencia ${...} en el cuerpo Markdown en su lugar, y Claude Code sustituye la ruta en línea cuando carga el contenido.

Entrecomillado y separadores de ruta

Mantenga cada ruta sustituida como un argumento único:

• Comandos de hook: use forma exec con args para que cada ruta sea un argumento sin entrecomillado
• Hooks de forma shell y comandos de monitor: envuelva la variable en comillas dobles para que una ruta con espacios permanezca como una palabra

Este hook de forma shell ejecuta un script incluido con el plugin:

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

En Windows, las rutas sustituidas usan barras diagonales para que un shell no lea barras invertidas como escapes.

Diseño estándar

Cada tipo de componente tiene una ubicación predeterminada bajo la raíz del plugin, usada cuando el manifiesto no apunta a otro lugar.

Un plugin que usa cada ubicación predeterminada, más una carpeta scripts/ que sus hooks llaman, se distribuye así:

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

Para hacer clic en este diseño y leer qué hace cada archivo, abra el explorador de plugins.

Un CLAUDE.md en la raíz del plugin no se carga como contexto, y claude plugin validate advierte cuando encuentra uno. Para incluir instrucciones que se carguen en el contexto de Claude, colóquelas en una skill.

Entradas del mercado y el manifiesto

Una entrada del mercado acepta cada campo en esta página junto con sus propios campos, incluido strict.

El campo strict decide si la entrada puede agregar componentes a un plugin que tiene su propio plugin.json. Por defecto es true.

Cómo se combinan los campos de entrada con `plugin.json`

La entrada sirve como manifiesto, agrega componentes a él, o entra en conflicto con él:

• Sin plugin.json: la entrada es el manifiesto, independientemente de strict. Los hooks de entrada se cargan solo en la forma de objeto en línea. Para una ruta de archivo o array allí, la pestaña Errors de /plugin muestra un error not yet supported in a marketplace entry
• plugin.json presente, strict sin establecer o true: Claude Code carga el manifiesto y agrega los commands, agents, skills, outputStyles y themes de la entrada a él. Para hooks, los matchers de la entrada para un evento reemplazan los matchers del manifiesto para ese mismo evento, y los eventos que solo declara el manifiesto mantienen los suyos
• plugin.json presente, strict: false: una entrada que declara cualquiera de commands, agents, skills, hooks, outputStyles o themes es un conflicto, y el plugin no se carga con Plugin <name> has conflicting manifests

Cuando una entrada del mercado cuya source es la raíz del mercado enumera subdirectorios skills específicos, solo se cargan esos subdirectorios, y el directorio predeterminado skills/ del plugin no se escanea. Una clave skills en el manifiesto en su lugar se suma al predeterminado.

Precedencia de metadatos

Algunos campos de metadatos tienen una precedencia fija independientemente de strict:

• defaultEnabled y campos de visualización: el defaultEnabled de la entrada y sus campos de visualización como displayName anulan los del manifiesto
• version: el version del manifiesto anula el de la entrada
• name: cuando la entrada enumera el plugin bajo un name diferente al del manifiesto, enabledPlugins usa el nombre de la entrada, y los componentes se espacían bajo el nombre del manifiesto

Para la tabla de precedencia completa, consulte Modo estricto.

Próximos pasos

• Agregar componentes a un plugin: qué hace cada componente en tiempo de ejecución, con un ejemplo que valida
• Referencia del mercado: los campos de entrada que un mercado puede establecer para su plugin
• Referencia de comandos de plugin: banderas de claude plugin validate y salida
• Solucionar problemas de plugins: cada mensaje de validación con su solución