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. Para un plugin copiado en la caché, ese nombre 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, omitClaudeMd, e isolation. El único valor válido de isolation es "worktree".

Por razones de seguridad, los agentes enviados por plugins no soportan hooks, mcpServers, o permissionMode.

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

hooks/hooks.json puede llevar una clave $schema de nivel superior que nombre una URL de JSON Schema para autocompletado y validación del editor. Claude Code ignora la clave al cargar.

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:

Evento	Cuándo se dispara
`SessionStart`	Cuando una sesión comienza o se reanuda
`Setup`	Cuando inicia Claude Code con `--init-only`, o con `--init` o `--maintenance` en modo `-p`. Para preparación única en CI o scripts
`UserPromptSubmit`	Cuando envía un prompt, antes de que Claude lo procese
`UserPromptExpansion`	Cuando un comando escrito por el usuario se expande en un prompt, antes de que llegue a Claude. Puede bloquear la expansión
`PreToolUse`	Antes de que se ejecute una llamada a herramienta. Puede bloquearlo
`PermissionRequest`	Cuando una llamada a herramienta necesita una decisión de permiso
`PermissionDenied`	Cuando el modo automático deniega una llamada a herramienta, incluidas las denegaciones sin un veredicto del clasificador. Use JSON `hookSpecificOutput.retry: true` para indicar al modelo que puede reintentar la llamada a herramienta denegada. Claude Code ignora `retry` cuando el clasificador no produjo veredicto
`PostToolUse`	Después de que una llamada a herramienta se ejecuta correctamente
`PostToolUseFailure`	Después de que una llamada a herramienta falla
`PostToolBatch`	Después de que se resuelve un lote completo de llamadas a herramientas paralelas, antes de la siguiente llamada al modelo
`Notification`	Cuando Claude Code envía una notificación
`MessageDisplay`	Mientras se muestra el texto del mensaje del asistente
`SubagentStart`	Cuando se genera un subagente
`SubagentStop`	Cuando un subagente finaliza
`TaskCreated`	Cuando se está creando una tarea a través de `TaskCreate`
`TaskCompleted`	Cuando se marca una tarea como completada
`Stop`	Cuando Claude termina de responder
`StopFailure`	Cuando el turno termina debido a un error de API
`TeammateIdle`	Cuando un compañero de equipo de agentes está a punto de quedarse inactivo
`InstructionsLoaded`	Cuando se carga un archivo CLAUDE.md o `.claude/rules/*.md` en el contexto. Se dispara al inicio de la sesión y cuando los archivos se cargan de forma diferida durante una sesión
`ConfigChange`	Cuando un archivo de configuración cambia durante una sesión
`CwdChanged`	Cuando el directorio de trabajo cambia, por ejemplo cuando Claude ejecuta un comando `cd`. Útil para la gestión reactiva del entorno con herramientas como direnv
`DirectoryAdded`	Cuando se agrega un directorio de trabajo a mitad de sesión a través de `/add-dir` o la solicitud de control `register_repo_root` del SDK
`FileChanged`	Cuando un archivo observado cambia en el disco. El campo `matcher` especifica qué nombres de archivo observar
`WorktreeCreate`	Cuando se está creando un worktree a través de `--worktree`, `isolation: "worktree"`, o para una sesión en segundo plano. Reemplaza el comportamiento predeterminado de git
`WorktreeRemove`	Cuando se está eliminando un worktree al salir de la sesión, cuando un subagente finaliza, o cuando elimina una sesión en segundo plano
`PreCompact`	Antes de la compactación de contexto
`PostCompact`	Después de que se completa la compactación de contexto
`PreModelSwitch`	Antes de que Claude Code aplique un cambio de modelo que usted o un cliente solicitó. Puede bloquear el cambio
`PostModelSwitch`	Después de que cambia el modelo de la sesión, incluidos los cambios que Claude Code realiza por su cuenta, como restaurar el modelo cuando reanuda una sesión
`Elicitation`	Cuando un servidor MCP solicita entrada del usuario durante una llamada a herramienta
`ElicitationResult`	Después de que un usuario responde a una solicitud de MCP, antes de que la respuesta se envíe de vuelta al servidor
`SessionEnd`	Cuando una sesión termina

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:

Campo	Descripción
`command`	El binario LSP a ejecutar (debe estar en PATH)
`extensionToLanguage`	Asigna extensiones de archivo a identificadores de lenguaje

Campos opcionales:

Campo	Descripción
`args`	Argumentos de línea de comandos para el servidor LSP
`transport`	Transporte de comunicación: `stdio` (predeterminado) o `socket`. Claude Code acepta `socket` pero ejecuta cada servidor sobre stdio, por lo que las reglas del protocolo stdout se aplican a todos los servidores
`env`	Variables de entorno a establecer al iniciar el servidor
`initializationOptions`	Opciones pasadas al servidor durante la inicialización
`settings`	Configuración pasada vía `workspace/didChangeConfiguration`
`workspaceFolder`	Ruta de carpeta de espacio de trabajo para el servidor
`startupTimeout`	Tiempo máximo para esperar el inicio del servidor (milisegundos)
`shutdownTimeout`	Tiempo máximo para esperar el apagado elegante (milisegundos). Cuando se agota el tiempo de espera, Claude Code termina el proceso del servidor. Cuando no se establece, no se aplica tiempo de espera
`restartOnCrash`	Si reiniciar el servidor después de que falle. Por defecto es `true`. Establezca en `false` para dejar un servidor fallido detenido en lugar de reiniciarlo
`maxRestarts`	Número máximo de intentos de reinicio antes de rendirse
`diagnostics`	Si insertar diagnósticos en el contexto de Claude después de ediciones (por defecto `true`). Establezca en `false` para mantener la navegación de código pero suprimir la inyección automática de diagnósticos.

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:

Plugin	Servidor de lenguaje	Comando de instalación
`pyright-lsp`	Pyright (Python)	`pip install pyright` o `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-analyzer-lsp`	rust-analyzer	Ver instalación de rust-analyzer

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:

Campo	Descripción
`name`	Identificador único dentro del plugin. Previene procesos duplicados cuando el plugin se recarga o se invoca una skill nuevamente
`command`	Comando shell ejecutado como un proceso de fondo persistente en el directorio de trabajo de la sesión
`description`	Resumen breve de lo que se está observando. Se muestra en el panel de tareas y en resúmenes de notificaciones

Campos opcionales:

Campo	Descripción
`when`	Controla cuándo se inicia el monitor. `"always"` lo inicia al inicio de la sesión y en la recarga del plugin, y es el predeterminado. `"on-skill-invoke:<skill-name>"` lo inicia la primera vez que se envía la skill nombrada en este plugin

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:

Alcance	Archivo de configuración	Caso de uso
`user`	`~/.claude/settings.json`	Plugins personales disponibles en todos los proyectos (predeterminado)
`project`	`.claude/settings.json`	Plugins de equipo compartidos a través del control de versiones
`local`	`.claude/settings.local.json`	Plugins específicos del proyecto, ignorados por git cuando Claude Code guarda una configuración en él
`managed`	Managed settings	Plugins administrados (solo lectura, solo actualizar)

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:

Lo que tiene	Qué es
`<skills-dir>/foo/SKILL.md` sin manifiesto	Un skill simple llamado `foo`
`<skills-dir>/foo/.claude-plugin/plugin.json`	Un plugin `foo@skills-dir`, que puede agrupar sus propios skills, agentes, hooks y más
`<plugin>/skills/bar/SKILL.md`	Un skill `bar` empaquetado dentro de un plugin

Elija de dónde se carga el plugin

Directorio de skills	Alcance	Se carga
`~/.claude/skills/`	personal	En cada proyecto, ya que la ubicación es solo suya
`<cwd>/.claude/skills/`	proyecto	Solo después de que acepte el diálogo de confianza del espacio de trabajo para esa carpeta

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

Claude Code carga los plugins habilitados para su cuenta de claude.ai, incluidos los plugins que su organización activa para sus miembros, junto con los plugins que instala desde marketplaces. Los descarga en ~/.claude/plugins/synced/ y los carga como <name>@synced, sin marketplace ni registro de instalación. Un plugin sincronizado se ejecuta con la misma confianza que un plugin de marketplace que instaló: sus skills, agentes, hooks, servidores MCP y servidores LSP se cargan todos.

Dónde Claude Code sincroniza estos plugins depende de la sesión:

En Cowork y sesiones en la nube, Claude Code los descarga en el entorno propio de la sesión cuando la sesión comienza. Antes de v2.1.239, Claude Code cargaba estos plugins como <name>@inline, la identidad que usan los plugins de --plugin-dir.
En sesiones de terminal donde inicia sesión con su cuenta de claude.ai, Claude Code verifica su cuenta una vez cada vez que comienza, luego descarga plugins nuevos y actualizados y elimina los que usted u su organización desactivaron, todo en segundo plano. La sincronización en sesiones de terminal requiere Claude Code v2.1.273 o posterior.

La verificación de inicio se ejecuta en segundo plano, por lo que puede terminar después de que su sesión haya comenzado. Cuando agrega, actualiza o elimina un plugin sincronizado en una sesión interactiva, Claude Code muestra Plugins changed. Run /reload-plugins to activate. Ejecute /reload-plugins para cargar el cambio en esa sesión, o déjelo para la próxima vez que inicie Claude Code. Si habilita un plugin en claude.ai mientras una sesión se está ejecutando, Claude Code lo descarga la próxima vez que comienza.

La sincronización de plugins en sesiones de terminal se ejecuta bajo las mismas condiciones de inicio de sesión que skills sincronizados desde claude.ai. También necesita un inicio de sesión que otorgue a Claude Code acceso a los plugins de su cuenta.

Un inicio de sesión de una versión anterior de Claude Code obtiene acceso a plugins la próxima vez que Claude Code renueva ese inicio de sesión en segundo plano, dentro de unas pocas horas, o de inmediato si ejecuta /login nuevamente. La sincronización de plugins comienza la próxima vez que inicia Claude Code después de eso.

claude plugin list muestra plugins sincronizados bajo un encabezado Synced from claude.ai, y la pestaña Installed de /plugin los enumera con synced como su fuente. Administre un plugin sincronizado por el ID <name>@synced que imprime claude plugin list:

Desactivar uno: ejecute claude plugin disable <name>@synced, o desactívelo desde la pestaña Installed de /plugin. Claude Code guarda la opción como "<name>@synced": false en su enabledPlugins a nivel de usuario. Para volver a activar el plugin, ejecute claude plugin enable <name>@synced.
Mantener uno fuera en todas partes: desactívelo para su cuenta de claude.ai. Para mantenerlo fuera 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. Claude Code descarga las actualizaciones del plugin en la próxima sincronización. Para eliminar uno, desactive el plugin para su cuenta de claude.ai, y Claude Code lo elimina en la próxima sincronización.
Deje de sincronizar en una máquina: establezca syncClaudeAiPlugins en false en su configuración de usuario. Claude Code deja de descargar, y la próxima vez que comienza mueve los plugins que ya sincronizó a ~/.claude/plugins/.trash/ y ya no los carga. Su organización puede establecer la misma clave en configuración administrada, o desactivar Skills en claude.ai, lo que también detiene la sincronización de plugins.

No puede desactivar un plugin que su organización marca como requerido en claude.ai. Claude Code lo carga incluso si lo desactivó anteriormente, y claude plugin disable rechaza con Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it. En claude plugin list, estos plugins están marcados como required by your org.

Cuando un plugin habilitado de cualquier otra fuente coincide con el nombre de un plugin sincronizado, Claude Code carga ese plugin e informa que la copia sincronizada no se cargó. Otras fuentes incluyen instalaciones de marketplace, plugins del directorio de skills, plugins de --plugin-dir y plugins integrados en Claude Code. 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.

Campo	Tipo	Descripción	Ejemplo
`name`	string	Identificador único en kebab-case, sin espacios, caracteres de control o caracteres de formato bidireccional. Cuando una entrada de marketplace lista el plugin bajo un nombre diferente, el nombre de la entrada de marketplace es lo que `enabledPlugins` y `/plugin` usan	`"deployment-tools"`

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

Campo	Tipo	Descripción	Ejemplo
`$schema`	string	URL de JSON Schema para autocompletado y validación del editor. Claude Code ignora este campo en tiempo de carga.	`"https://json.schemastore.org/claude-code-plugin-manifest.json"`
`displayName`	string	Nombre legible por humanos mostrado en el selector `/plugin` y otras superficies de interfaz de usuario. Para un plugin instalado desde marketplace, un `displayName` en la entrada de marketplace tiene prioridad sobre este valor. Cuando no se establece ningún nombre de visualización en ninguno de los dos lugares, los usuarios ven `name`. A diferencia de `name`, puede contener espacios y cualquier capitalización. No se utiliza para espacios de nombres o búsqueda.	`"Deployment Tools"`
`version`	string	Opcional. Versión semántica. Establecer esto fija el plugin a esa cadena de versión, por lo que los usuarios solo reciben actualizaciones cuando la incrementa, excepto para una `command` source o un plugin cargado en lugar; vea Gestión de versiones. Si también se establece en la entrada de marketplace, `plugin.json` gana. Si se omite, la versión proviene de la siguiente fuente en Gestión de versiones.	`"2.1.0"`
`description`	string	Breve explicación del propósito del plugin	`"Deployment automation tools"`
`author`	object	Información del autor	`{"name": "Dev Team", "email": "dev@company.com"}`
`homepage`	string	URL de documentación	`"https://docs.example.com"`
`repository`	string	URL del código fuente	`"https://github.com/user/plugin"`
`license`	string	Identificador de licencia	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Etiquetas de descubrimiento	`["deployment", "ci-cd"]`
`metadata`	object	Objeto de forma libre para sus propios datos, como campos de derechos o catálogo. Claude Code no lo lee, por lo que los valores nunca afectan el comportamiento del plugin. Claude Code ignora un valor que no es un objeto, y `claude plugin validate` lo reporta como una advertencia. Antes de v2.1.222, Claude Code trataba la clave como un campo no reconocido.	`{"catalogId": "cat-123"}`
`defaultEnabled`	boolean	Si el plugin comienza en un estado habilitado cuando el usuario no ha establecido uno. Por defecto es `true`. Vea Habilitación predeterminada.	`false`

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. El ajuste del usuario y un requisito de dependencia 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

Campo	Tipo	Descripción	Ejemplo
`skills`	string\|array	Directorios de skills personalizados que contienen `<name>/SKILL.md`. Se agrega al escaneo predeterminado `skills/`. Vea Reglas de comportamiento de ruta para la excepción de raíz de marketplace	`"./custom/skills/"`
`commands`	string\|array	Archivos de skills `.md` planos personalizados o directorios (reemplaza el `commands/` predeterminado)	`"./custom/cmd.md"` o `["./cmd1.md"]`
`agents`	string\|array	Archivos de agentes personalizados (reemplaza el `agents/` predeterminado)	`"./custom/agents/reviewer.md"`
`workflows`	string\|array	Archivos de scripts de workflow personalizados o directorios (reemplaza el `workflows/` predeterminado)	`"./custom/workflows/"`
`hooks`	string\|array\|object	Rutas de configuración de hooks o configuración en línea	`"./my-extra-hooks.json"`
`mcpServers`	string\|array\|object	Rutas de configuración de MCP o configuración en línea	`"./my-extra-mcp-config.json"`
`outputStyles`	string\|array	Archivos/directorios de estilo de salida personalizados (reemplaza el `output-styles/` predeterminado)	`"./styles/"`
`lspServers`	string\|array\|object	Configuraciones de Language Server Protocol para inteligencia de código (ir a definición, buscar referencias, etc.)	`"./.lsp.json"`
`experimental.themes`	string\|array	Archivos/directorios de tema de color (reemplaza el `themes/` predeterminado). Vea Temas	`"./themes/"`
`experimental.monitors`	string\|array	Configuraciones de Monitor de fondo que se inician automáticamente cuando el plugin está activo. Vea Monitores	`"./monitors.json"`
`experimental.evals`	string\|array	Directorio debajo de la raíz del plugin que contiene los casos de eval del plugin, cuando no es el `evals/` predeterminado. `claude plugin eval --eval-dir` lo anula	`"quality/evals"`
`userConfig`	object	Valores configurables por el usuario solicitados en tiempo de habilitación. Vea Configuración del usuario
`channels`	array	Declaraciones de canales para inyección de mensajes (estilo Telegram, Slack, Discord). Vea Canales
`dependencies`	array	Otros plugins que este plugin requiere, opcionalmente con restricciones de versión semántica. Vea Restringir versiones de dependencia de plugins	`[{ "name": "secrets-vault", "version": "~2.1.0" }]`

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:

Campo	Requerido	Descripción
`type`	Sí	Uno de `string`, `number`, `boolean`, `directory`, o `file`
`title`	Sí	Etiqueta mostrada en el diálogo de configuración
`description`	Sí	Texto de ayuda mostrado debajo del campo
`sensitive`	No	Si es `true`, enmascara la entrada y almacena el valor en almacenamiento seguro en lugar de `settings.json`
`required`	No	Si es `true`, la validación falla cuando el campo está vacío
`default`	No	Valor utilizado cuando el usuario no proporciona nada
`options`	No	Para tipo `string`, los valores que el campo acepta, mostrados en `/config` como un selector sobre ellos. Requiere Claude Code v2.1.271 o posterior
`multiple`	No	Para tipo `string`, permitir un array de cadenas
`min` / `max`	No	Límites para tipo `number`

Excepto campos sensitive y listas multiple, cada campo de cada plugin habilitado también aparece como una fila en el panel /config. Las filas requieren Claude Code v2.1.269 o posterior.

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:

Campo rechazado	Cómo pasar el valor
Comandos de hooks en forma de shell	Use forma exec con `args`, o lea `CLAUDE_PLUGIN_OPTION_<KEY>` del entorno del hook
Comandos de Monitor	Lea el valor de un archivo de configuración en el script
MCP `headersHelper`	Lea el valor de un archivo de configuración en el script

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:

Variable	Se resuelve a	Úsela para
`${CLAUDE_PLUGIN_ROOT}`	Ruta absoluta al directorio de instalación del plugin	Scripts, binarios y archivos de configuración incluidos con el plugin
`${CLAUDE_PLUGIN_DATA}`	Directorio persistente que sobrevive a actualizaciones de plugins, creado en primera referencia	Dependencias instaladas como `node_modules` o entornos virtuales de Python, código generado y cachés
`${CLAUDE_PROJECT_DIR}`	La raíz del proyecto	Scripts y archivos de configuración locales del proyecto

Los tres se exportan como variables de entorno a procesos de hooks y a subprocesos de servidores MCP y LSP. 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 plugins, escriba el marcador de posición en su lugar, y Claude Code sustituye la ruta en línea cuando carga el contenido. Qué campos sustituyen en línea depende del componente del plugin:

Componente del plugin	Campos donde se resuelven los placeholders
Contenido de skills y agentes	En cualquier lugar donde aparezca el placeholder
Comandos de hooks y monitores	En cualquier lugar donde aparezca el placeholder
Servidores MCP `stdio`	`command`, `args`, `env`
Servidores MCP `http`, `sse`, `ws`	`url`, `headers`, `headersHelper`
Servidores LSP	`command`, `args`, `env`, `workspaceFolder`

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

Para un plugin copiado, ${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í. Para ver qué plugins se copian y para semántica de limpieza, vea almacenamiento en caché de plugins.

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 tres 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.
A través de su cuenta de claude.ai, sincronizado en ~/.claude/plugins/synced/.

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), a menos que el plugin se cargue en su lugar. Una fuente command en modo de enlace se carga en su lugar a través de enlaces en la entrada de caché. Una fuente de ruta relativa en un marketplace agregado desde un directorio local se carga en su lugar desde la carpeta del marketplace.

Para un plugin cargado en su lugar desde un marketplace de directorio local, sus ediciones al directorio de origen surten efecto en el siguiente inicio de sesión o /reload-plugins. No necesita un aumento de versión. Los procesos de hook del plugin y los servidores MCP y LSP reciben un CLAUDE_PLUGIN_ROOT que apunta al directorio de origen. Claude Code no instala las dependencias de paquetes Node.js del plugin en el directorio de origen. Instálelas allí usted mismo, o desde un hook en el directorio de datos persistentes.

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:

Archivo de bloqueo	Comando
`bun.lock` o `bun.lockb`	`bun install --frozen-lockfile --ignore-scripts`
`npm-shrinkwrap.json` o `package-lock.json`	`npm ci --ignore-scripts`

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 la instalación en dos casos, cada uno con su propia solución:

Si su plugin solo incluye un yarn.lock o pnpm-lock.yaml, reemplácelo con un archivo de bloqueo npm.
Si un bunfig.toml se encuentra junto al archivo de bloqueo bun, elimine el bunfig.toml, o reemplace el archivo de bloqueo bun con un archivo de bloqueo npm.

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.

Claude Code obtiene un plugin de fuente npm antes de esta instalación de dependencias, y ninguno de los scripts de instalación propios del paquete se ejecuta durante la obtención. Consulte paquetes npm.

Una instalación fallida u omitida nunca bloquea el plugin. Cuando la instalación falla, o Claude Code omite porque hay un archivo de bloqueo yarn o pnpm o un bunfig.toml, 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.

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

Componente	Ubicación predeterminada	Propósito
Manifiesto	`.claude-plugin/plugin.json`	Metadatos y configuración del plugin (opcional)
Skills	`skills/`	Skills con estructura `<name>/SKILL.md`
Comandos	`commands/`	Skills como archivos Markdown planos. Use `skills/` para nuevos plugins
Agentes	`agents/`	Archivos Markdown de subagentes
Flujos de trabajo	`workflows/`	Archivos de script de flujo de trabajo
Estilos de salida	`output-styles/`	Definiciones de estilos de salida
Temas	`themes/`	Definiciones de temas de color
Hooks	`hooks/hooks.json`	Configuración de hooks
Servidores MCP	`.mcp.json`	Definiciones de servidores MCP
Servidores LSP	`.lsp.json`	Configuraciones de servidores de lenguaje
Monitores	`monitors/monitors.json`	Configuraciones de monitores de fondo
Ejecutables	`bin/`	Ejecutables agregados a `PATH` de la herramienta Bash e invocables como comandos desnudos mientras el plugin está habilitado. No puede incluir este directorio en un plugin que distribuya a través de la configuración de la organización claude.ai
Configuración	`settings.json`	Configuración predeterminada aplicada cuando el plugin está habilitado. Solo se admiten las claves `agent` y `subagentStatusLine`

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:

Opción	Descripción	Predeterminado
`--description <text>`	Descripción del manifiesto
`--author <name>`	Nombre del autor	`git config user.name`
`--author-email <email>`	Correo electrónico del autor	`git config user.email`
`--with <components...>`	También crea carpetas de componentes. Valores válidos: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel`
`-f, --force`	Sobrescribe un `.claude-plugin/` existente en el destino
`-h, --help`	Muestra la ayuda del comando

claude plugin new es un alias para este comando.

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

Componente	Lo que crea
`skills`	Una skill adicional con espacio de nombres `<name>:example` junto a la predeterminada
`agents`	Una definición de subagente en `agents/`
`hooks`	Un `hooks/hooks.json` con un controlador de eventos de ejemplo
`mcp`	Un `.mcp.json` con ejemplos de servidor HTTP y stdio
`lsp`	Un ejemplo de servidor de lenguaje `.lsp.json`
`output-style`	Un `output-styles/<name>.md` que se aplica automáticamente mientras el plugin está habilitado
`channel`	Un canal basado en MCP: un servidor stdio (`server.ts`), su `.mcp.json` y un `package.json`

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:

Opción	Descripción	Predeterminado
`-s, --scope <scope>`	Alcance de instalación: `user`, `project` o `local`	`user`
`--config <key=value>`	Establece una opción `userConfig` declarada en el manifiesto del plugin. Repita la bandera para establecer múltiples opciones
`-y, --yes`	Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una fuente `command`, o el `headersHelper` que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY, a menos que pase `--accept-command`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal
`--accept-command <sha256>`	Acepta el comando declarado por el marketplace cuyo `sha256` una ejecución anterior con `--json` reportó en `shownCommand`, en lugar de `-y`. La aceptación cuenta para exactamente ese comando, plugin y catálogo de marketplace. Si alguno de ellos cambió desde que se mostró el comando, incluyendo a través de la actualización de marketplace de la propia ejecución, Claude Code no acepta el resumen y muestra el comando nuevamente. No se puede combinar con `-y`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal. Requiere Claude Code v2.1.271 o posterior
`--json`	Imprime el resultado como un objeto JSON en la última línea de stdout en lugar del mensaje legible por humanos, para usar en scripts. Consulte formato de resultado JSON. Requiere Claude Code v2.1.268 o posterior
`-h, --help`	Muestra la ayuda del comando

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.

Cuando una ejecución muestra un comando declarado por el marketplace y no lo ejecuta, el resultado failed también lleva un objeto shownCommand cuyos campos incluyen el comando tal como se mostró, el plugin al que pertenece y el sha256 del comando. Para aceptar exactamente ese comando, vuelva a ejecutar con ese sha256 como --accept-command. Requiere Claude Code v2.1.271 o posterior.

Si shownCommand.acceptCommandMatched es false, el resumen que pasó no coincide con el comando ahora mostrado. Muestre ese comando a una persona antes de pasar su sha256.

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:

Opción	Descripción	Predeterminado
`-s, --scope <scope>`	Desinstala del alcance: `user`, `project` o `local`	`user`
`--keep-data`	Preserva el directorio de datos persistentes del plugin
`--prune`	También elimina las dependencias instaladas automáticamente que ningún otro plugin requiere. Consulte plugin prune
`-y, --yes`	Omite el mensaje de confirmación de `--prune`. Requerido cuando stdin o stdout no es una TTY
`--json`	Imprime el resultado como un objeto JSON en la última línea de stdout, en el mismo formato que `plugin install --json`. No se puede combinar con `--prune`. Requiere Claude Code v2.1.268 o posterior
`-h, --help`	Muestra la ayuda del comando

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:

Opción	Descripción	Predeterminado
`-s, --scope <scope>`	Limpia en alcance: `user`, `project` o `local`	`user`
`--dry-run`	Lista lo que se eliminaría sin eliminar nada
`-y, --yes`	Omite el mensaje de confirmación. Requerido cuando stdin o stdout no es una TTY
`-h, --help`	Muestra la ayuda del comando

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, plugin-name@marketplace-name o plugin-name@synced para un plugin sincronizado desde claude.ai

El comando acepta estas opciones:

Opción	Descripción	Predeterminado
`-s, --scope <scope>`	Alcance a habilitar: `user`, `project` o `local`. Cuando se omite, Claude Code detecta el alcance donde está instalado el plugin	Detección automática
`--json`	Imprime el resultado como un objeto JSON en la última línea de stdout, en el mismo formato que `plugin install --json`. Requiere Claude Code v2.1.268 o posterior
`-h, --help`	Muestra la ayuda del comando

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.

Para un plugin sincronizado que su organización requiere, el comando falla y no guarda nada.

claude plugin disable [plugin] [options]

El comando toma estos argumentos:

[plugin]: Nombre del plugin, plugin-name@marketplace-name o plugin-name@synced para un plugin sincronizado desde claude.ai. Opcional cuando se usa --all

El comando acepta estas opciones:

Opción	Descripción	Predeterminado
`-a, --all`	Deshabilita todos los plugins habilitados. No se puede combinar con `--scope`
`-s, --scope <scope>`	Alcance a deshabilitar: `user`, `project` o `local`. Cuando se omite, Claude Code detecta el alcance donde está instalado el plugin	Detección automática
`--json`	Imprime el resultado como un objeto JSON en la última línea de stdout, en el mismo formato que `plugin install --json`. Requiere Claude Code v2.1.268 o posterior
`-h, --help`	Muestra la ayuda del comando

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:

Opción	Descripción	Predeterminado
`-s, --scope <scope>`	Alcance a actualizar: `user`, `project`, `local` o `managed`	`user`
`-y, --yes`	Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una fuente `command`, o el `headersHelper` que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY, a menos que pase `--accept-command`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal
`--accept-command <sha256>`	Acepta el comando declarado por el marketplace cuyo `sha256` una ejecución anterior con `--json` reportó en `shownCommand`, en lugar de `-y`. La aceptación cuenta para exactamente ese comando, plugin y catálogo de marketplace. Si alguno de ellos cambió desde que se mostró el comando, incluyendo a través de la actualización de marketplace de la propia ejecución, Claude Code no acepta el resumen y muestra el comando nuevamente. No se puede combinar con `-y`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal. Requiere Claude Code v2.1.271 o posterior
`--json`	Imprime el resultado como un objeto JSON en la última línea de stdout, en el mismo formato que `plugin install --json`. Requiere Claude Code v2.1.268 o posterior
`-h, --help`	Muestra la ayuda del comando

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:

Opción	Descripción	Predeterminado
`--json`	Salida como JSON. Una fila de plugin con problemas de carga o advertencias de autoría lleva matrices de cadenas `errors` o `notes`. En Claude Code v2.1.268 o posterior, matrices paralelas `errorDetails` y `noteDetails` dan el `type` de diagnóstico de cada entrada y los nombres a los que se refiere, como el plugin, marketplace, servidor o archivo
`--available`	Incluye plugins disponibles desde marketplaces. Requiere `--json`
`-h, --help`	Muestra la ayuda del comando

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.
Los plugins sincronizados desde claude.ai aparecen en claude plugin list en Claude Code v2.1.239 o posterior y en la interfaz /plugin, pero no 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:

Opción	Descripción	Predeterminado
`-h, --help`	Muestra la ayuda del comando

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:

Opción	Descripción	Predeterminado
`--strict`	Trata las advertencias como errores y sale con 1 en ellas. Use en CI para detectar problemas que el tiempo de ejecución tolera, como campos no reconocidos
`--json`	Salida del informe de validación como un objeto JSON con los mismos códigos de salida. Requiere Claude Code v2.1.259 o posterior
`-h, --help`	Muestra la ayuda del comando

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.

Opción	Descripción	Predeterminado
`--runs <n>`	Ejecuciones por caso por rama	El `runs` de cada caso, si no 3
`-j, --concurrency <n>`	Sesiones de agent a ejecutar a la vez, 1 a 8. Comparten su límite de velocidad	`1`
`--model <model>`	Modelo para el agent bajo prueba	El `model` de cada caso, si no `ANTHROPIC_MODEL` si está establecido, si no el predeterminado de Claude Code
`--judge-model <model>`	Modelo para calificadores `llm` y `baseline`	Un modelo pequeño y rápido
`--ablation <mode>`	`none` o `with-without`. Consulte Comparar contra una línea de base sin plugin	`with-without` cuando un plugin se resuelve, si no `none`
`--threshold <0..1>`	Sale con 1 si algún caso puntúa por debajo de esto	`1.0`
`--max-cost-usd <usd>`	Detiene antes de la siguiente ejecución una vez que el gasto alcanza esto, sale con 2 e informa resultados parciales	Sin límite
`--allow-tools <tools...>`	Otorga herramientas más allá del conjunto de solo lectura, como `Bash`, `Write`, `Edit` o `"mcp__plugin_<plugin>_<server>__*"`. Consulte Otorgar herramientas
`--scaffold`	Ejecuta el `scaffold_script` de cada caso	Desactivado
`--trust-plugin`	Omite el primer mensaje de confianza, para CI. Consulte Qué puede acceder una ejecución	Desactivado
`--mocks <mode>`	`record` u `off`. Consulte Simular servidores MCP	`record`
`--eval-dir <dir>`	Directorio debajo del plugin que contiene los casos	El `experimental.evals` del manifiesto, si no `evals`
`--json [path]`	Imprime el documento de resultado a stdout, o escríbelo en una ruta `.json`
`--no-publish`	Mantiene el informe HTML local
`-h, --help`	Muestra la ayuda del comando

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:

Opción	Descripción	Predeterminado
`--bare`	Escribe un `prompt.md` en blanco y `graders/criteria.md` para `<name>` en lugar de ejecutar la entrevista
`-i, --interactive`	Requiere la entrevista. Falla sin una terminal en lugar de escribir una plantilla
`--eval-dir <dir>`	Directorio debajo del directorio actual para escribir casos en	El `experimental.evals` del manifiesto, si no `evals`
`-h, --help`	Muestra la ayuda del comando

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:

Opción	Descripción	Predeterminado
`--push`	Empuja la etiqueta al remoto después de crearla
`--dry-run`	Imprime lo que se etiquetaría sin crear la etiqueta
`-f, --force`	Crea la etiqueta incluso si el árbol de trabajo está sucio o la etiqueta ya existe
`-m, --message <msg>`	Mensaje de anotación de etiqueta. Use `%s` como marcador de posición para la versión
`--remote <name>`	Remoto al que empujar con `--push`	`origin`
`-h, --help`	Muestra la ayuda del comando

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

Problema	Causa	Solución
Plugin no se carga	`plugin.json` inválido	Ejecute `claude plugin validate ./my-plugin` o `/plugin validate ./my-plugin`, donde `./my-plugin` es su directorio de plugins, para verificar `plugin.json`, `hooks/hooks.json` y el frontmatter de los skills, agentes y comandos en los directorios predeterminados del plugin para errores de sintaxis y esquema. Consulte Validar un plugin o un directorio sin un manifiesto para ver qué cubre una ejecución
Skills no aparecen	Estructura de directorio incorrecta	Asegúrese de que `skills/` o `commands/` esté en la raíz del plugin, no dentro de `.claude-plugin/`
Hooks no se activan	Script no ejecutable	Ejecute `chmod +x script.sh`
El servidor MCP falla	Falta `${CLAUDE_PLUGIN_ROOT}`	Use la variable para todas las rutas de plugins
Errores de ruta	Se utilizaron rutas absolutas	Haga que las rutas sean relativas, comenzando con `./`; consulte Reglas de comportamiento de rutas, que cubren la excepción `"."` del campo `skills`
LSP `Executable not found in $PATH`	Servidor de lenguaje no instalado	Instale el binario (por ejemplo, `npm install -g typescript-language-server typescript`)

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:

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

El hook no se activa en los eventos esperados:

Verifique que el nombre del evento sea correcto (sensible a mayúsculas): PostToolUse, no postToolUse
Verifique que el patrón del matcher coincida con sus herramientas: "matcher": "Write|Edit" para operaciones de archivo
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:

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

Las herramientas del servidor no aparecen:

Asegúrese de que el servidor esté correctamente configurado en .mcp.json o plugin.json
Verifique que el servidor implemente correctamente el protocolo MCP
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:

Ejecute claude --debug y busque mensajes "loading plugin"
Verifique que cada directorio de componentes esté listado en la salida de depuración
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. Un plugin cargado en su lugar desde un marketplace de directorio local carga sus archivos de fuente actuales en cada inicio de sesión, sin importar lo que diga su cadena de versión.

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

El campo version en el plugin.json del plugin
El campo version en la entrada del plugin en el marketplace en marketplace.json
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
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
unknown, para fuentes npm o directorios locales cuando ni el directorio del plugin ni su marketplace es un repositorio de git. Claude Code no toma la versión de un repositorio que encierra la ruta de instalación, como un ~/.claude gestionado por 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:

Enfoque	Cómo	Comportamiento de actualización	Mejor para
Versión explícita	Establezca `"version": "2.1.0"` en `plugin.json`	Los usuarios obtienen actualizaciones solo cuando incrementa este campo. Insertar nuevos commits sin incrementarlo no tiene efecto, y `/plugin update` informa "already at the latest version". Para un plugin cargado en su lugar, el nuevo contenido se carga de todas formas.	Plugins publicados con ciclos de lanzamiento estables
Versión de SHA de commit	Omita `version` tanto de `plugin.json` como de la entrada del marketplace	Los usuarios obtienen actualizaciones cada vez que cambia el commit resuelto de la fuente	Plugins internos o de equipo en desarrollo activo
Versión de resumen	Utilice una fuente `archive` y omita `version` tanto de `plugin.json` como de la entrada del marketplace	Con un pin `sha256`, los usuarios obtienen actualizaciones cuando cambia el pin. Sin uno, los usuarios obtienen actualizaciones cada vez que cambian los bytes del archivo zip alojado	Plugins publicados como archivos zip en un servidor estático o repositorio de artefactos

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

plugins-reference.md +72 −32

40 40

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

42 42

43Si 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.43Si 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. Para un plugin [copiado en la caché](#plugin-caching-and-file-resolution), ese nombre 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.

44 44

45En 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`.45En 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`.

46 46

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

72```72```

73 73

74Los 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.74Los agentes de plugins soportan campos frontmatter `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, [`omitClaudeMd`](/docs/es/sub-agents#supported-frontmatter-fields), e `isolation`. El único valor válido de `isolation` es `"worktree"`.

76Por razones de seguridad, los agentes enviados por plugins no soportan `hooks`, `mcpServers`, o `permissionMode`.

75 77

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

77 79

99 101

100**Formato**: Configuración JSON con coincidencias de eventos y acciones102**Formato**: Configuración JSON con coincidencias de eventos y acciones

101 103

104`hooks/hooks.json` puede llevar una clave `$schema` de nivel superior que nombre una URL de JSON Schema para autocompletado y validación del editor. Claude Code ignora la clave al cargar.

105

102**Configuración de hook**:106**Configuración de hook**:

103 107

104```json theme={null}108```json theme={null}

440 Plugins sincronizados desde claude.ai444 Plugins sincronizados desde claude.ai

441</h2>445</h2>

442 446

443En [Cowork](https://claude.com/product/cowork) y [sesiones en la nube](/docs/es/cloud-environments#what-carries-over-from-your-setup), 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`.447Claude Code carga los plugins habilitados para su cuenta de claude.ai, incluidos los plugins que su organización activa para sus miembros, junto con los plugins que instala desde marketplaces. Los descarga en `~/.claude/plugins/synced/` y los carga como `<name>@synced`, sin marketplace ni registro de instalación. Un plugin sincronizado se ejecuta con la misma confianza que un plugin de marketplace que instaló: sus skills, agentes, hooks, servidores MCP y servidores LSP se cargan todos.

448

449Dónde Claude Code sincroniza estos plugins depende de la sesión:

450

451* En [Cowork](https://claude.com/product/cowork) y [sesiones en la nube](/docs/es/cloud-environments#what-carries-over-from-your-setup), Claude Code los descarga en el entorno propio de la sesión cuando la sesión comienza. Antes de v2.1.239, Claude Code cargaba estos plugins como `<name>@inline`, la identidad que usan los plugins de `--plugin-dir`.

452* En sesiones de terminal donde inicia sesión con su cuenta de claude.ai, Claude Code verifica su cuenta una vez cada vez que comienza, luego descarga plugins nuevos y actualizados y elimina los que usted u su organización desactivaron, todo en segundo plano. La sincronización en sesiones de terminal requiere Claude Code v2.1.273 o posterior.

453

454La verificación de inicio se ejecuta en segundo plano, por lo que puede terminar después de que su sesión haya comenzado. Cuando agrega, actualiza o elimina un plugin sincronizado en una sesión interactiva, Claude Code muestra `Plugins changed. Run /reload-plugins to activate.` Ejecute [`/reload-plugins`](/docs/es/discover-plugins#apply-plugin-changes-without-restarting) para cargar el cambio en esa sesión, o déjelo para la próxima vez que inicie Claude Code. Si habilita un plugin en claude.ai mientras una sesión se está ejecutando, Claude Code lo descarga la próxima vez que comienza.

444 455

445Administre un plugin sincronizado por el ID `<name>@synced` que imprime `claude plugin list`:456La sincronización de plugins en sesiones de terminal se ejecuta bajo las mismas condiciones de inicio de sesión que [skills sincronizados desde claude.ai](/docs/es/skills#where-synced-skills-load). También necesita un inicio de sesión que otorgue a Claude Code acceso a los plugins de su cuenta.

446 457

447* **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`](/docs/es/settings-reference#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](/docs/es/desktop#extend-claude-code). 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.458Un inicio de sesión de una versión anterior de Claude Code obtiene acceso a plugins la próxima vez que Claude Code renueva ese inicio de sesión en segundo plano, dentro de unas pocas horas, o de inmediato si ejecuta `/login` nuevamente. La sincronización de plugins comienza la próxima vez que inicia Claude Code después de eso.

448* **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.

449 459

450Cuando un plugin habilitado de cualquier otra fuente, como una instalación de marketplace, un [plugin del directorio de skills](#skills-directory-plugins), 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.460`claude plugin list` muestra plugins sincronizados bajo un encabezado `Synced from claude.ai`, y la pestaña **Installed** de `/plugin` los enumera con `synced` como su fuente. Administre un plugin sincronizado por el ID `<name>@synced` que imprime `claude plugin list`:

461

462* **Desactivar uno**: ejecute `claude plugin disable <name>@synced`, o desactívelo desde la pestaña **Installed** de `/plugin`. Claude Code guarda la opción como `"<name>@synced": false` en su [`enabledPlugins`](/docs/es/settings-reference#enabledplugins) a nivel de usuario. Para volver a activar el plugin, ejecute `claude plugin enable <name>@synced`.

463* **Mantener uno fuera en todas partes**: [desactívelo para su cuenta de claude.ai](/docs/es/desktop#extend-claude-code). Para mantenerlo fuera de un proyecto en todos los entornos, establezca `"<name>@synced": false` bajo `enabledPlugins` en el `.claude/settings.json` comprometido de ese proyecto.

464* **Administre el plugin en claude.ai**: `claude plugin install`, `update` y `uninstall` no se aplican a un plugin sincronizado. Claude Code descarga las actualizaciones del plugin en la próxima sincronización. Para eliminar uno, desactive el plugin para su cuenta de claude.ai, y Claude Code lo elimina en la próxima sincronización.

465* **Deje de sincronizar en una máquina**: establezca [`syncClaudeAiPlugins`](/docs/es/settings-reference#syncclaudeaiplugins) en `false` en su configuración de usuario. Claude Code deja de descargar, y la próxima vez que comienza mueve los plugins que ya sincronizó a `~/.claude/plugins/.trash/` y ya no los carga. Su organización puede establecer la misma clave en [configuración administrada](/docs/es/managed-settings), o desactivar Skills en claude.ai, lo que también detiene la sincronización de plugins.

466

467No puede desactivar un plugin que su organización marca como requerido en claude.ai. Claude Code lo carga incluso si lo desactivó anteriormente, y `claude plugin disable` rechaza con `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` En `claude plugin list`, estos plugins están marcados como `required by your org`.

468

469Cuando un plugin habilitado de cualquier otra fuente coincide con el nombre de un plugin sincronizado, Claude Code carga ese plugin e informa que la copia sincronizada no se cargó. Otras fuentes incluyen instalaciones de marketplace, [plugins del directorio de skills](#skills-directory-plugins), plugins de `--plugin-dir` y plugins integrados en Claude Code. 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.

451 470

452***471***

453 472

534</h3>553</h3>

535 554

537| :--------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |556| :--------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |

539| `displayName` | string | Nombre legible por humanos mostrado en el selector `/plugin` y otras superficies de interfaz de usuario. Para un plugin instalado desde marketplace, un `displayName` en la [entrada de marketplace](/docs/es/plugin-marketplaces#optional-plugin-fields) tiene prioridad sobre este valor. Cuando no se establece ningún nombre de visualización en ninguno de los dos lugares, los usuarios ven `name`. A diferencia de `name`, puede contener espacios y cualquier capitalización. No se utiliza para espacios de nombres o búsqueda. | `"Deployment Tools"` |558| `displayName` | string | Nombre legible por humanos mostrado en el selector `/plugin` y otras superficies de interfaz de usuario. Para un plugin instalado desde marketplace, un `displayName` en la [entrada de marketplace](/docs/es/plugin-marketplaces#optional-plugin-fields) tiene prioridad sobre este valor. Cuando no se establece ningún nombre de visualización en ninguno de los dos lugares, los usuarios ven `name`. A diferencia de `name`, puede contener espacios y cualquier capitalización. No se utiliza para espacios de nombres o búsqueda. | `"Deployment Tools"` |

540| `version` | string | Opcional. Versión semántica. Establecer esto fija el plugin a esa cadena de versión, por lo que los usuarios solo reciben actualizaciones cuando la incrementa, excepto para una [`command` source](/docs/es/plugin-marketplaces#command-sources); vea [Gestión de versiones](#version-management). Si también se establece en la entrada de marketplace, `plugin.json` gana. Si se omite, la versión proviene de la siguiente fuente en [Gestión de versiones](#version-management). | `"2.1.0"` |559| `version` | string | Opcional. Versión semántica. Establecer esto fija el plugin a esa cadena de versión, por lo que los usuarios solo reciben actualizaciones cuando la incrementa, excepto para una [`command` source](/docs/es/plugin-marketplaces#command-sources) o un plugin [cargado en lugar](#plugin-caching-and-file-resolution); vea [Gestión de versiones](#version-management). Si también se establece en la entrada de marketplace, `plugin.json` gana. Si se omite, la versión proviene de la siguiente fuente en [Gestión de versiones](#version-management). | `"2.1.0"` |

542| `author` | object | Información del autor | `{"name": "Dev Team", "email": "dev@company.com"}` |561| `author` | object | Información del autor | `{"name": "Dev Team", "email": "dev@company.com"}` |

553 572

554Establezca `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.573Establezca `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.

555 574

556`defaultEnabled` es la alternativa cuando nada más ha decidido el estado del plugin. Dos cosas tienen prioridad sobre él:575`defaultEnabled` es la alternativa cuando nada más ha decidido el estado del plugin. El ajuste del usuario y un requisito de dependencia tienen prioridad sobre él:

557 576

558* **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.577* **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.

559* **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](/docs/es/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).578* **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](/docs/es/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).

579| `experimental.evals` | string\|array | Directorio debajo de la raíz del plugin que contiene los [casos de eval](/docs/es/plugin-evals#use-a-different-eval-directory) del plugin, cuando no es el `evals/` predeterminado. `claude plugin eval --eval-dir` lo anula | `"quality/evals"` |598| `experimental.evals` | string\|array | Directorio debajo de la raíz del plugin que contiene los [casos de eval](/docs/es/plugin-evals#use-a-different-eval-directory) del plugin, cuando no es el `evals/` predeterminado. `claude plugin eval --eval-dir` lo anula | `"quality/evals"` |

582| `dependencies` | array | Otros plugins que este plugin requiere, opcionalmente con restricciones de versión semántica. Vea [Restringir versiones de dependencia de plugins](/docs/es/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |601| `dependencies` | array | Otros plugins que este plugin requiere, opcionalmente con restricciones de versión semántica. Vea [Restringir versiones de dependencia de plugins](/docs/es/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

583 602

584<h3 id="experimental-components">603<h3 id="experimental-components">

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

615 634

617| :------------ | :-------- | :---------------------------------------------------------------------------------------------------------- |636| :------------ | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |

618| `type` | Sí | Uno de `string`, `number`, `boolean`, `directory`, o `file` |637| `type` | Sí | Uno de `string`, `number`, `boolean`, `directory`, o `file` |

619| `title` | Sí | Etiqueta mostrada en el diálogo de configuración |638| `title` | Sí | Etiqueta mostrada en el diálogo de configuración |

620| `description` | Sí | Texto de ayuda mostrado debajo del campo |639| `description` | Sí | Texto de ayuda mostrado debajo del campo |

621| `sensitive` | No | Si es `true`, enmascara la entrada y almacena el valor en almacenamiento seguro en lugar de `settings.json` |640| `sensitive` | No | Si es `true`, enmascara la entrada y almacena el valor en almacenamiento seguro en lugar de `settings.json` |

622| `required` | No | Si es `true`, la validación falla cuando el campo está vacío |641| `required` | No | Si es `true`, la validación falla cuando el campo está vacío |

623| `default` | No | Valor utilizado cuando el usuario no proporciona nada |642| `default` | No | Valor utilizado cuando el usuario no proporciona nada |

643| `options` | No | Para tipo `string`, los valores que el campo acepta, mostrados en `/config` como un selector sobre ellos. Requiere Claude Code v2.1.271 o posterior |

624| `multiple` | No | Para tipo `string`, permitir un array de cadenas |644| `multiple` | No | Para tipo `string`, permitir un array de cadenas |

625| `min` / `max` | No | Límites para tipo `number` |645| `min` / `max` | No | Límites para tipo `number` |

626 646

647Excepto campos `sensitive` y listas `multiple`, cada campo de cada plugin habilitado también aparece como una fila en el panel `/config`. Las filas requieren Claude Code v2.1.269 o posterior.

648

627Cada 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.649Cada 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.

628 650

629Los 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](/docs/es/errors#plugin-command-references-user-config) en su lugar. Cada campo rechazado tiene una forma alternativa de pasar el valor:651Los 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](/docs/es/errors#plugin-command-references-user-config) en su lugar. Cada campo rechazado tiene una forma alternativa de pasar el valor:

733| `${CLAUDE_PLUGIN_DATA}` | [Directorio persistente](#persistent-data-directory) que sobrevive a actualizaciones de plugins, creado en primera referencia | Dependencias instaladas como `node_modules` o entornos virtuales de Python, código generado y cachés |755| `${CLAUDE_PLUGIN_DATA}` | [Directorio persistente](#persistent-data-directory) que sobrevive a actualizaciones de plugins, creado en primera referencia | Dependencias instaladas como `node_modules` o entornos virtuales de Python, código generado y cachés |

734| `${CLAUDE_PROJECT_DIR}` | La raíz del proyecto | Scripts y archivos de configuración locales del proyecto |756| `${CLAUDE_PROJECT_DIR}` | La raíz del proyecto | Scripts y archivos de configuración locales del proyecto |

735 757

736Los 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:758Los tres se exportan como variables de entorno a procesos de hooks y a subprocesos de servidores MCP y LSP. 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 plugins, escriba el marcador de posición en su lugar, y Claude Code sustituye la ruta en línea cuando carga el contenido. Qué campos sustituyen en línea depende del componente del plugin:

737 759

738| Componente del plugin | Campos donde se resuelven los placeholders |760| Componente del plugin | Campos donde se resuelven los placeholders |

739| :--------------------------------- | :----------------------------------------------- |761| :--------------------------------- | :----------------------------------------------- |

762}784}

763```785```

764 786

765`${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](#plugin-caching-and-file-resolution) para semántica de limpieza.787Para un plugin copiado, `${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í. Para ver qué plugins se copian y para semántica de limpieza, vea [almacenamiento en caché de plugins](#plugin-caching-and-file-resolution).

766 788

767Cuando 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.789Cuando 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.

768 790

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

826</h2>848</h2>

827 849

828Los plugins se especifican de una de dos formas:850Los plugins se especifican de una de tres formas:

829 851

830* A través de `claude --plugin-dir` o `claude --plugin-url`, durante la duración de una sesión.852* A través de `claude --plugin-dir` o `claude --plugin-url`, durante la duración de una sesión.

831* A través de un marketplace, instalado para sesiones futuras.853* A través de un marketplace, instalado para sesiones futuras.

854* A través de su cuenta de claude.ai, [sincronizado](#synced-plugins) en `~/.claude/plugins/synced/`.

832 855

833Por 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](/docs/es/plugin-marketplaces#copy-mode-and-link-mode), que Claude Code usa en su lugar a través de enlaces en la entrada de caché.856Por razones de seguridad y verificación, Claude Code copia los plugins del *marketplace* en la **caché de plugins** local del usuario (`~/.claude/plugins/cache`), a menos que el plugin se cargue en su lugar. Una [fuente `command` en modo de enlace](/docs/es/plugin-marketplaces#copy-mode-and-link-mode) se carga en su lugar a través de enlaces en la entrada de caché. Una [fuente de ruta relativa](/docs/es/plugin-marketplaces#relative-paths) en un marketplace agregado desde un directorio local se carga en su lugar desde la carpeta del marketplace.

857

858Para un plugin cargado en su lugar desde un marketplace de directorio local, sus ediciones al directorio de origen surten efecto en el siguiente inicio de sesión o `/reload-plugins`. No necesita un aumento de versión. Los procesos de hook del plugin y los servidores MCP y LSP reciben un `CLAUDE_PLUGIN_ROOT` que apunta al directorio de origen. Claude Code no instala las [dependencias de paquetes Node.js](#node-js-package-dependencies) del plugin en el directorio de origen. Instálelas allí usted mismo, o desde un hook en el [directorio de datos persistentes](#persistent-data-directory).

834 859

835Para 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](#node-js-package-dependencies). Una dependencia resuelta desde una [etiqueta de lanzamiento](/docs/es/plugin-dependencies#tag-plugin-releases-for-version-resolution) obtiene un nombre de directorio con un sufijo de SHA de confirmación.860Para 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](#node-js-package-dependencies). Una dependencia resuelta desde una [etiqueta de lanzamiento](/docs/es/plugin-dependencies#tag-plugin-releases-for-version-resolution) obtiene un nombre de directorio con un sufijo de SHA de confirmación.

836 861

855 880

856Si 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`.881Si 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`.

882

883Claude Code omite la instalación en dos casos, cada uno con su propia solución:

884

885* Si su plugin solo incluye un `yarn.lock` o `pnpm-lock.yaml`, reemplácelo con un archivo de bloqueo npm.

886* Si un `bunfig.toml` se encuentra junto al archivo de bloqueo bun, elimine el `bunfig.toml`, o reemplace el archivo de bloqueo bun con un archivo de bloqueo npm.

857 887

858Enví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.888Enví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.

859 889

863* **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.893* **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.

864* **Tiempo de espera de 60 segundos:** Claude Code detiene una instalación que se ejecuta más tiempo y la trata como fallida.894* **Tiempo de espera de 60 segundos:** Claude Code detiene una instalación que se ejecuta más tiempo y la trata como fallida.

865 895

866Obtener 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.896Claude Code obtiene un plugin de fuente npm antes de esta instalación de dependencias, y ninguno de los scripts de instalación propios del paquete se ejecuta durante la obtención. Consulte [paquetes npm](/docs/es/plugin-marketplaces#npm-packages).

867 897

868Una 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](#debugging-commands). 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é.898Una instalación fallida u omitida nunca bloquea el plugin. Cuando la instalación falla, o Claude Code omite porque hay un archivo de bloqueo yarn o pnpm o un `bunfig.toml`, registra el motivo como una advertencia en [salida de depuración](#debugging-commands). 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é.

869 899

870No 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](/docs/es/network-config#network-access-requirements) para los hosts a permitir.900No 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](/docs/es/network-config#network-access-requirements) para los hosts a permitir.

871 901

1061El comando acepta estas opciones:1091El comando acepta estas opciones:

1062 1092

1064| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |1094| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------- |

1066| `--config <key=value>` | Establece una opción [`userConfig`](#user-configuration) declarada en el manifiesto del plugin. Repita la bandera para establecer múltiples opciones | |1096| `--config <key=value>` | Establece una opción [`userConfig`](#user-configuration) declarada en el manifiesto del plugin. Repita la bandera para establecer múltiples opciones | |

1067| `-y, --yes` | Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), o el [`headersHelper`](/docs/es/plugin-marketplaces#authenticate-archive-downloads) que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal | |1097| `-y, --yes` | Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), o el [`headersHelper`](/docs/es/plugin-marketplaces#authenticate-archive-downloads) que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY, a menos que pase `--accept-command`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal | |

1098| `--accept-command <sha256>` | Acepta el comando declarado por el marketplace cuyo `sha256` una ejecución anterior con [`--json`](#plugin-json-result) reportó en `shownCommand`, en lugar de `-y`. La aceptación cuenta para exactamente ese comando, plugin y catálogo de marketplace. Si alguno de ellos cambió desde que se mostró el comando, incluyendo a través de la actualización de marketplace de la propia ejecución, Claude Code no acepta el resumen y muestra el comando nuevamente. No se puede combinar con `-y`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal. Requiere Claude Code v2.1.271 o posterior | |

1068| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout en lugar del mensaje legible por humanos, para usar en scripts. Consulte [formato de resultado JSON](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |1099| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout en lugar del mensaje legible por humanos, para usar en scripts. Consulte [formato de resultado JSON](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |

1070 1101

1078 1109

1079Otros 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.1110Otros 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.

1080 1111

1112Cuando una ejecución muestra un comando declarado por el marketplace y no lo ejecuta, el resultado `failed` también lleva un objeto `shownCommand` cuyos campos incluyen el comando tal como se mostró, el plugin al que pertenece y el `sha256` del comando. Para aceptar exactamente ese comando, vuelva a ejecutar con ese `sha256` como `--accept-command`. Requiere Claude Code v2.1.271 o posterior.

1113

1114Si `shownCommand.acceptCommandMatched` es `false`, el resumen que pasó no coincide con el comando ahora mostrado. Muestre ese comando a una persona antes de pasar su `sha256`.

1115

1081Estos ejemplos muestran invocaciones comunes:1116Estos ejemplos muestran invocaciones comunes:

1082 1117

1083```bash theme={null}1118```bash theme={null}

1159 1194

1160El comando toma estos argumentos:1195El comando toma estos argumentos:

1161 1196

1162* `<plugin>`: Nombre del plugin o `plugin-name@marketplace-name`1197* `<plugin>`: Nombre del plugin, `plugin-name@marketplace-name` o `plugin-name@synced` para un [plugin sincronizado desde claude.ai](#synced-plugins)

1163 1198

1164El comando acepta estas opciones:1199El comando acepta estas opciones:

1165 1200

1173 plugin disable1208 plugin disable

1174</h3>1209</h3>

1175 1210

1176Deshabilita un plugin sin desinstalarlo. Cuando el destino está instalado desde un marketplace, el comando falla si otro plugin habilitado [depende de](/docs/es/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) él. El mensaje de error incluye un comando encadenado que deshabilita primero cada dependiente.1211Deshabilita un plugin sin desinstalarlo.

1212

1213Cuando el destino está instalado desde un marketplace, el comando falla si otro plugin habilitado [depende de](/docs/es/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) él. El mensaje de error incluye un comando encadenado que deshabilita primero cada dependiente.

1214

1215Para un [plugin sincronizado](#synced-plugins) que su organización requiere, el comando falla y no guarda nada.

1177 1216

1178```bash theme={null}1217```bash theme={null}

1179claude plugin disable [plugin] [options]1218claude plugin disable [plugin] [options]

1181 1220

1182El comando toma estos argumentos:1221El comando toma estos argumentos:

1183 1222

1184* `[plugin]`: Nombre del plugin o `plugin-name@marketplace-name`. Opcional cuando se usa `--all`1223* `[plugin]`: Nombre del plugin, `plugin-name@marketplace-name` o `plugin-name@synced` para un [plugin sincronizado desde claude.ai](#synced-plugins). Opcional cuando se usa `--all`

1185 1224

1186El comando acepta estas opciones:1225El comando acepta estas opciones:

1187 1226

1209El comando acepta estas opciones:1248El comando acepta estas opciones:

1210 1249

1212| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |1251| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------- |

1214| `-y, --yes` | Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), o el [`headersHelper`](/docs/es/plugin-marketplaces#authenticate-archive-downloads) que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal | |1253| `-y, --yes` | Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), o el [`headersHelper`](/docs/es/plugin-marketplaces#authenticate-archive-downloads) que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY, a menos que pase `--accept-command`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal | |

1254| `--accept-command <sha256>` | Acepta el comando declarado por el marketplace cuyo `sha256` una ejecución anterior con [`--json`](#plugin-json-result) reportó en `shownCommand`, en lugar de `-y`. La aceptación cuenta para exactamente ese comando, plugin y catálogo de marketplace. Si alguno de ellos cambió desde que se mostró el comando, incluyendo a través de la actualización de marketplace de la propia ejecución, Claude Code no acepta el resumen y muestra el comando nuevamente. No se puede combinar con `-y`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal. Requiere Claude Code v2.1.271 o posterior | |

1215| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout, en el [mismo formato que `plugin install --json`](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |1255| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout, en el [mismo formato que `plugin install --json`](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |

1217 1257

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

1243 1283

1244* 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`.1284* 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`.

1245* En Claude Code v2.1.239 o posterior, los [plugins sincronizados desde claude.ai](#synced-plugins) 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`.1285* Los [plugins sincronizados desde claude.ai](#synced-plugins) aparecen en `claude plugin list` en Claude Code v2.1.239 o posterior y en la interfaz `/plugin`, pero no en la salida en línea de `/plugin list`.

1246* 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.1286* 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.

1247 1287

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

1520 Gestión de versiones1560 Gestión de versiones

1521</h3>1561</h3>

1522 1562

1523Claude 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.1563Claude 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. Un plugin [cargado en su lugar](#plugin-caching-and-file-resolution) desde un marketplace de directorio local carga sus archivos de fuente actuales en cada inicio de sesión, sin importar lo que diga su cadena de versión.

1524 1564

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

1526 1566

15282. El campo `version` en la entrada del plugin en el marketplace en `marketplace.json`15682. El campo `version` en la entrada del plugin en el marketplace en `marketplace.json`

15293. 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 git15693. 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

15304. El resumen SHA-256, para [fuentes `archive`](/docs/es/plugin-marketplaces#zip-archives): 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 caracteres15704. El resumen SHA-256, para [fuentes `archive`](/docs/es/plugin-marketplaces#zip-archives): 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

15315. `unknown`, para fuentes `npm` o directorios locales que no estén dentro de un repositorio de git15715. `unknown`, para fuentes `npm` o directorios locales cuando ni el directorio del plugin ni su marketplace es un repositorio de git. Claude Code no toma la versión de un repositorio que encierra la ruta de instalación, como un `~/.claude` gestionado por git

1532 1572

1533Para una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), 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](/docs/es/plugin-marketplaces#copy-mode-and-link-mode), el hash cubre la ruta real del directorio impreso y sus entradas de nivel superior en lugar del contenido del archivo.1573Para una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), 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](/docs/es/plugin-marketplaces#copy-mode-and-link-mode), el hash cubre la ruta real del directorio impreso y sus entradas de nivel superior en lugar del contenido del archivo.

1534 1574

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

1536 1576

1538| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |1578| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |

1539| **Versión explícita** | Establezca `"version": "2.1.0"` en `plugin.json` | Los usuarios obtienen actualizaciones solo cuando incrementa este campo. Insertar nuevos commits sin incrementarlo no tiene efecto, y `/plugin update` informa "already at the latest version". | Plugins publicados con ciclos de lanzamiento estables |1579| **Versión explícita** | Establezca `"version": "2.1.0"` en `plugin.json` | Los usuarios obtienen actualizaciones solo cuando incrementa este campo. Insertar nuevos commits sin incrementarlo no tiene efecto, y `/plugin update` informa "already at the latest version". Para un plugin [cargado en su lugar](#plugin-caching-and-file-resolution), el nuevo contenido se carga de todas formas. | Plugins publicados con ciclos de lanzamiento estables |

1540| **Versión de SHA de commit** | Omita `version` tanto de `plugin.json` como de la entrada del marketplace | Los usuarios obtienen actualizaciones cada vez que cambia el commit resuelto de la fuente | Plugins internos o de equipo en desarrollo activo |1580| **Versión de SHA de commit** | Omita `version` tanto de `plugin.json` como de la entrada del marketplace | Los usuarios obtienen actualizaciones cada vez que cambia el commit resuelto de la fuente | Plugins internos o de equipo en desarrollo activo |

1541| **Versión de resumen** | Utilice una [fuente `archive`](/docs/es/plugin-marketplaces#zip-archives) y omita `version` tanto de `plugin.json` como de la entrada del marketplace | Con un pin `sha256`, los usuarios obtienen actualizaciones cuando cambia el pin. Sin uno, los usuarios obtienen actualizaciones cada vez que cambian los bytes del archivo zip alojado | Plugins publicados como archivos zip en un servidor estático o repositorio de artefactos |1581| **Versión de resumen** | Utilice una [fuente `archive`](/docs/es/plugin-marketplaces#zip-archives) y omita `version` tanto de `plugin.json` como de la entrada del marketplace | Con un pin `sha256`, los usuarios obtienen actualizaciones cuando cambia el pin. Sin uno, los usuarios obtienen actualizaciones cada vez que cambian los bytes del archivo zip alojado | Plugins publicados como archivos zip en un servidor estático o repositorio de artefactos |

1542 1582

plugins-reference.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

Referencia de plugins

Referencia de componentes de plugins

Skills

Agents

Hooks

MCP servers

LSP servers

Monitors

Themes

Alcances de instalación de plugins

Plugins de directorio de skills

Elija de dónde se carga el plugin

Edite, recargue y deshabilite un plugin de directorio de skills

Plugins sincronizados desde claude.ai

Esquema de manifiesto de plugins

Esquema completo

Campos requeridos

Campos no reconocidos

Campos de metadatos

Habilitación predeterminada

Campos de ruta de componentes

Componentes experimentales

Configuración del usuario

Canales

Reglas de comportamiento de ruta

Variables de entorno

Directorio de datos persistente

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

Dependencias de paquetes Node.js

Limitaciones de traversal de rutas

Compartir archivos dentro de un marketplace con enlaces simbólicos

Estructura de directorios de plugins

Diseño estándar de plugins

Referencia de ubicaciones de archivos

Referencia de comandos CLI

plugin init

plugin install

plugin uninstall

plugin prune

plugin enable

plugin disable

plugin update

plugin list

plugin details

plugin validate

plugin eval

plugin eval init

plugin tag

Herramientas de depuración y desarrollo

Comandos de depuración

Problemas comunes

Ejemplos de mensajes de error

Solución de problemas de hooks

Solución de problemas del servidor MCP

Errores de estructura de directorio

Referencia de distribución y versionado

Gestión de versiones

Ver también