Referencia de plugins

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

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

Un plugin es un directorio independiente de componentes que extiende Claude Code con funcionalidad personalizada. Los componentes del plugin incluyen skills, agents, 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

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

Estructura de skill:

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

Comportamiento de integración:

• Los skills y comandos se descubren automáticamente cuando se instala el plugin
• Claude puede invocarlos automáticamente según el contexto de la tarea
• Los skills pueden incluir archivos de apoyo junto a SKILL.md

Para obtener detalles completos, consulte Skills.

Agents

Los plugins pueden proporcionar subagents 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 agent

Estructura del agent:

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

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

Los agents del plugin 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 agents distribuidos con plugins.

Puntos de integración:

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

Para obtener detalles completos, consulte Subagents.

Hooks

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

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

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

Configuración de hook:

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

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

Tipos de hook:

• command: ejecutar comandos de 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 el contexto)
• agent: ejecutar un verificador agentic con herramientas para tareas de verificación complejas

MCP servers

Los plugins pueden agrupar servidores Model Context Protocol (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 del servidor MCP

Configuración del servidor MCP:

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

Comportamiento de integración:

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

LSP servers

Los plugins pueden proporcionar servidores Language Server Protocol (LSP) para dar a Claude inteligencia de código en tiempo real mientras trabaja en su base de código.

La integración de LSP proporciona:

• Diagnósticos instantáneos: Claude ve errores y advertencias inmediatamente después de cada edición
• Navegación de código: ir a definición, encontrar referencias e información al pasar el ratón
• Conciencia del lenguaje: información de tipo y documentación para símbolos 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 del archivo .lsp.json:

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

En línea en plugin.json:

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

Campos requeridos:

Campos opcionales:

Plugins LSP disponibles:

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

Monitors

Los plugins pueden declarar monitores de fondo que Claude Code inicia automáticamente cuando el plugin está activo. Cada monitor ejecuta un comando de 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 vigilancia por sí mismo.

Los monitores del plugin utilizan 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: Array JSON de entradas de monitor

El siguiente monitors/monitors.json vigila un endpoint de estado de implementación y un registro de errores local:

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

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

Campos requeridos:

Campos opcionales:

El valor command soporta las mismas sustituciones de variables que las configuraciones de servidores MCP y LSP: ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${user_config.*} y cualquier ${ENV_VAR} del entorno. Prefije el comando con cd "${CLAUDE_PLUGIN_ROOT}" && si el script necesita ejecutarse desde el directorio del plugin.

Deshabilitar un plugin a mitad de sesión no detiene los monitores que ya se están ejecutando. Se detienen cuando termina la sesión.

Themes

Los plugins pueden distribuir temas de color que aparecen en /theme junto con 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"
  }
}

Seleccionar un tema de plugin persiste custom:<plugin-name>:<slug> en la configuración del usuario. Los temas de plugin son de solo lectura; presionar Ctrl+E en uno en /theme lo copia en ~/.claude/themes/ para que el usuario pueda editar la copia.

Alcances de instalación de plugins

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

Los plugins utilizan el mismo sistema de alcance que otras configuraciones de Claude Code. Para instrucciones de instalación y banderas de alcance, consulta Instalar plugins. Para una explicación completa de los alcances, consulta Alcances de configuración.

Esquema del manifiesto del plugin

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

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

Esquema completo

{
  "name": "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"],
  "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"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Campos requeridos

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

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

Campos de metadatos

Campos de ruta de componentes

Componentes experimentales

Los componentes bajo la clave experimental, themes y monitors, tienen un esquema de manifiesto que puede cambiar entre versiones mientras se estabilizan. Dónde los declares 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 se habilita el plugin. Usa esto en lugar de requerir que los usuarios editen manualmente settings.json.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Tu endpoint de API del equipo"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token de autenticación de API",
      "sensitive": true
    }
  }
}

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

Cada valor está disponible para sustitución como ${user_config.KEY} en configuraciones de servidores MCP y LSP, comandos de hooks y comandos de monitores. Los valores no sensibles también pueden sustituirse en contenido de skills y agents. Todos los valores se exportan a subprocesos del plugin como variables de entorno CLAUDE_PLUGIN_OPTION_<KEY>.

Los valores no sensibles se almacenan en settings.json bajo pluginConfigs[<plugin-id>].options. Los valores sensibles van al llavero del sistema (o ~/.claude/.credentials.json donde el llavero no está disponible). El almacenamiento en llavero se comparte con tokens OAuth y tiene un límite total aproximado de 2 KB, así que mantén los valores sensibles pequeños.

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": "Token del bot de Telegram",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Tu ID de usuario de Telegram"
        }
      }
    }
  ]
}

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 se habilita el plugin.

Reglas de comportamiento de rutas

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

• Reemplaza el predeterminado: commands, agents, outputStyles, experimental.themes, experimental.monitors. Por ejemplo, cuando el manifiesto especifica commands, el directorio predeterminado commands/ no se escanea. Para mantener el predeterminado y añadir más, enuméralo explícitamente: "commands": ["./commands/", "./extras/"]
• Se añade al predeterminado: skills. El directorio predeterminado skills/ siempre se escanea, y los directorios enumerados en skills se cargan junto a él
• Reglas de fusión propias: hooks, MCP servers y LSP servers. Consulta cada sección para ver cómo se combinan múltiples fuentes

Para todos los campos de ruta:

• Todas las rutas deben ser relativas a la raíz del plugin y comenzar con ./
• Los componentes de rutas personalizadas utilizan las mismas reglas de nomenclatura y espacios de nombres
• Se pueden especificar múltiples rutas como arrays
• Cuando una ruta de skill apunta a un directorio que contiene un SKILL.md directamente, por ejemplo "skills": ["./"] apuntando a la raíz del plugin, el campo frontmatter name en SKILL.md determina el nombre de invocación de la skill. Esto proporciona un nombre estable independientemente del directorio de instalación. Si name no se establece en el frontmatter, el nombre base del directorio se usa como alternativa.

Ejemplos de rutas:

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

Variables de entorno

Claude Code proporciona dos variables para hacer referencia a rutas de plugins. Ambas se sustituyen en línea en cualquier lugar donde aparezcan en contenido de skills, contenido de agents, comandos de hooks, comandos de monitores y configuraciones de servidores MCP o LSP. Ambas también se exportan como variables de entorno a procesos de hooks y subprocesos de servidores MCP o LSP.

${CLAUDE_PLUGIN_ROOT}: la ruta absoluta al directorio de instalación de tu plugin. Úsala para hacer referencia a scripts, binarios y archivos de configuración incluidos con el plugin. Esta ruta cambia cuando se actualiza el plugin. El directorio de la versión anterior permanece en el disco durante aproximadamente siete días después de una actualización antes de la limpieza, pero trátalo como efímero y no escribas estado aquí.

Cuando un plugin se actualiza a mitad de sesión, los comandos de hooks, monitores, servidores MCP y servidores LSP siguen usando la ruta de la versión anterior. Ejecuta /reload-plugins para cambiar hooks, servidores MCP y servidores LSP a la nueva ruta; los monitores requieren un reinicio de sesión.

${CLAUDE_PLUGIN_DATA}: un directorio persistente para el estado del plugin que sobrevive a las actualizaciones. Úsalo para dependencias instaladas como node_modules o entornos virtuales de Python, código generado, cachés y cualquier otro archivo que deba persistir entre versiones del plugin. El directorio se crea automáticamente la primera vez que se hace referencia a esta variable.

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

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. Porque el directorio de datos sobrevive a cualquier versión única del plugin, una verificación de existencia de directorio solo no puede detectar cuándo una actualización cambia el manifiesto de dependencias 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 siempre que una actualización del plugin incluya 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 las 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 los node_modules persistidos:

{
  "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 desinstales el plugin del último alcance donde está instalado. La interfaz /plugin muestra el tamaño del directorio y solicita confirmación antes de eliminar. La CLI elimina por defecto; pasa --keep-data para preservarlo.

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

Los plugins se especifican de una de dos formas:

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

Por razones de seguridad y verificación, Claude Code copia plugins del marketplace a la caché de plugins local del usuario (~/.claude/plugins/cache) en lugar de usarlos en su lugar. Entender este comportamiento es importante al desarrollar plugins que hacen referencia a archivos externos.

Cada versión instalada es un directorio separado en la caché. Cuando actualiza o desinstala un plugin, el directorio de versión anterior se marca como huérfano y se elimina automáticamente 7 días después. El período de gracia permite que las sesiones de Claude Code concurrentes que ya cargaron la versión anterior sigan ejecutándose sin errores.

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.

Limitaciones de traversal de rutas

Los plugins instalados no pueden hacer referencia a archivos fuera de su directorio. Las rutas que traversan fuera de la raíz del plugin (como ../shared-utils) no funcionarán después de la instalación porque esos archivos externos no se copian a la caché.

Trabajar con dependencias externas

Si su plugin necesita acceder a archivos fuera de su directorio, puede crear enlaces simbólicos a archivos externos dentro de su directorio de plugin. Los enlaces simbólicos se preservan en la caché en lugar de ser desreferenciados, y se resuelven a su destino en tiempo de ejecución. El siguiente comando crea un enlace desde dentro de su directorio de plugin a una ubicación de utilidades compartidas:

ln -s /path/to/shared-utils ./shared-utils

Esto proporciona flexibilidad mientras se mantienen los beneficios de seguridad del sistema de almacenamiento en caché.

Estructura del directorio del plugin

Diseño estándar del plugin

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 subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Definiciones de estilo de salida
│   └── terse.md
├── themes/                   # Definiciones de tema de color
│   └── dracula.json
├── monitors/                 # Configuraciones de monitor de fondo
│   └── monitors.json
├── hooks/                    # Configuraciones de hooks
│   ├── hooks.json           # Configuración principal de hooks
│   └── security-hooks.json  # Hooks adicionales
├── bin/                      # Ejecutables del plugin añadidos a PATH
│   └── my-tool               # Invocable como comando desnudo en herramienta Bash
├── settings.json            # Configuración predeterminada para el plugin
├── .mcp.json                # Definiciones del servidor MCP
├── .lsp.json                # Configuraciones del servidor 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, agents y hooks en lugar de CLAUDE.md. Para enviar instrucciones que se carguen en el contexto de Claude, colóquelas en un skill.

Referencia de ubicaciones de archivos

Referencia de comandos CLI

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

plugin install

Instala un plugin desde los marketplaces disponibles.

claude plugin install <plugin> [options]

Argumentos:

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

Opciones:

El alcance determina qué archivo de configuración se añade el 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.

Ejemplos:

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

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

# Instalar en alcance local (ignorado por git)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Elimina un plugin instalado.

claude plugin uninstall <plugin> [options]

Argumentos:

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

Opciones:

Alias: remove, rm

Por defecto, desinstalar del último alcance restante también elimina el directorio ${CLAUDE_PLUGIN_DATA} del plugin. Usa --keep-data para preservarlo, por ejemplo cuando reinstales 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 instalaste directamente nunca se tocan.

claude plugin prune [options]

Opciones:

Alias: autoremove

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, ejecuta claude plugin uninstall <plugin> --prune.

plugin enable

Habilita un plugin deshabilitado.

claude plugin enable <plugin> [options]

Argumentos:

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

Opciones:

plugin disable

Deshabilita un plugin sin desinstalarlo.

claude plugin disable <plugin> [options]

Argumentos:

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

Opciones:

plugin update

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

claude plugin update <plugin> [options]

Argumentos:

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

Opciones:

plugin list

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

claude plugin list [options]

Opciones:

plugin tag

Crea una etiqueta de lanzamiento de git para el plugin en el directorio actual. Ejecuta desde dentro de la carpeta del plugin. Consulta Etiquetar lanzamientos de plugins.

claude plugin tag [options]

Opciones:

Herramientas de depuración y desarrollo

Comandos de depuración

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

Esto muestra:

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

Problemas comunes

Mensajes de error de ejemplo

Errores de validación de manifiesto:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: busca comas faltantes, comas extra o cadenas sin comillas
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: falta un campo requerido
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: error de sintaxis JSON

Errores de carga de plugin:

• 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.: elimina definiciones de componentes duplicadas o elimina strict: false en la entrada del marketplace

Solución de problemas de hooks

El script del hook no se ejecuta:

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

El hook no se dispara en los eventos esperados:

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

Solución de problemas del servidor MCP

El servidor no se inicia:

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

Las herramientas del servidor no aparecen:

1. Asegúrate de que el servidor esté correctamente configurado en .mcp.json o plugin.json
2. Verifica que el servidor implemente correctamente el protocolo MCP
3. Busca 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, agents, 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/.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Solo el manifiesto aquí
├── commands/            ← A nivel de raíz
├── agents/              ← A nivel de raíz
└── hooks/               ← A nivel de raíz

Si tus componentes están dentro de .claude-plugin/, muévelos a la raíz del plugin.

Lista de verificación de depuración:

1. Ejecuta claude --debug y busca mensajes "loading plugin"
2. Verifica que cada directorio de componentes esté listado en la salida de depuración
3. Verifica 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.

La versión se resuelve a partir de la primera de estas que esté configurada:

1. El campo version en el plugin.json del plugin
2. El campo version en la entrada del marketplace del plugin en marketplace.json
3. El SHA del commit de git del origen del plugin, para fuentes github, url, git-subdir y relative-path en un marketplace alojado en git
4. unknown, para fuentes npm o directorios locales que no estén dentro de un repositorio de git

Esto le proporciona dos formas de versionar un plugin:

Si utiliza versiones explícitas, siga el versionado semántico (MAJOR.MINOR.PATCH): aumente MAJOR para cambios de ruptura, 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