Agregar componentes a un plugin

​

Explorar el directorio del plugin

• Una skill de revisión y un comando about
• Un subagente de revisión de seguridad
• Un hook que formatea archivos después de que Claude los edita, y la carpeta scripts/ que llama
• Un monitor de registro
• Un estilo de salida y un tema de color
• Un flujo de trabajo de auditoría de rutas
• Un ejecutable hello-plugin
• Configuración predeterminada
• Un servidor MCP local y un servidor de lenguaje Go

​

Agregar cada tipo de componente

​

Skills

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• Nombre del comando: /<plugin>:<directory>, así que skills/review/SKILL.md en my-plugin es /my-plugin:review. Si establece name en el frontmatter, reemplaza el último segmento y el prefijo del plugin permanece. Consulte cómo una skill obtiene su nombre de comando
• Quién la invoca: Claude, el usuario, o ambos, controlado por frontmatter. Consulte Controlar quién invoca una skill

• Directorios adicionales: enumérelos en la clave de manifiesto skills. Se suman al escaneo predeterminado de skills/ en lugar de reemplazarlo, a diferencia de commands y agents
• Una única skill en la raíz del plugin: sin directorio skills/ y sin clave de manifiesto skills, un SKILL.md en la raíz del plugin se carga como una skill. Establezca name en su frontmatter, porque de lo contrario una instalación de marketplace nombra la skill después de su directorio de caché en lugar de su plugin

​

Comandos

​

Definir comandos en el manifiesto

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Agentes

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

Organizar agentes en subcarpetas

• Frontmatter name: reemplaza solo el nombre del archivo, así que name: audit en agents/review/security.md se carga como my-plugin:review:audit
• Campo de manifiesto agents: un archivo que enumera allí se carga sin nombres de subcarpeta, así que "agents": "./custom/review/security.md" se carga como my-plugin:security

​

Campos de frontmatter en agentes de plugin

• Campos admitidos: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, y la clave cacheTtl de experimental. El único valor válido de isolation es "worktree". Consulte campos de frontmatter admitidos para ver qué hace cada uno
• Campos ignorados: permissionMode, hooks, mcpServers, e initialPrompt. Un archivo de agente no puede agregar hooks o servidores MCP por su cuenta, así que agregue esos como plugin hooks y servidores MCP en su lugar
• Frontmatter que no se analiza: el agente aún se carga con cada campo ignorado. Se nombra después del archivo, y su descripción dice Agent from my-plugin plugin. Ejecute claude plugin validate en su shell para encontrar estos archivos

​

Hooks

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

​

Cuándo se activan los hooks del plugin

​

Entorno, entrecomillado y coincidencia de herramientas MCP

• Entorno: cada proceso de hook recibe CLAUDE_PLUGIN_ROOT y CLAUDE_PLUGIN_DATA en su entorno, más CLAUDE_PLUGIN_OPTION_<KEY> para cada valor de configuración del usuario, para que su script pueda leerlos desde allí
• Entrecomillado: cuando command no tiene args, se ejecuta a través de un shell, así que envuelva la ruta ${CLAUDE_PLUGIN_ROOT} entre comillas dobles, como hace el ejemplo hooks/hooks.json bajo Hooks, para mantener la ruta expandida como una palabra de shell. Cuando pasa args en su lugar, cada elemento se pasa como un argumento sin shell y no necesita entrecomillado. Consulte forma exec y forma shell
• Coincidencia de las herramientas MCP propias del plugin: una herramienta de un servidor MCP que este plugin declara se llama mcp__plugin_<plugin>_<server>__<tool>, así que escriba ese nombre completo en el matcher. Un matcher solo en el nombre del servidor nunca se activa. Consulte Coincidir herramientas MCP

​

Servidores MCP

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

Alcanzar usuarios en claude.ai y Cowork

​

Nombres de servidor, nombres de herramientas y recargas

• Nombre del servidor: plugin:<plugin>:<server>, así que el servidor db en my-plugin es plugin:my-plugin:db en /mcp. Use la misma forma para nombrar el servidor en un hook mcp_tool
• Nombres de herramientas: mcp__plugin_<plugin>_<server>__<tool>, así que una herramienta query en ese servidor db es mcp__plugin_my-plugin_db__query. Ese es el nombre a usar en reglas de permisos y matchers de hook
• Sustitución: ${CLAUDE_PLUGIN_ROOT} y las otras variables de ruta se sustituyen en command, args y env. No se necesita entrecomillado en args, porque cada elemento se pasa como un argumento
• Recarga: cuando el usuario ejecuta /reload-plugins y la recarga se aplica, un servidor cuya configuración no ha cambiado mantiene su conexión. Un servidor cuya configuración cambió se reconecta, y uno que eliminó se desconecta

​

Incluir un servidor MCPB empaquetado

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

​

Servidores LSP

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

• Binario faltante: Claude Code inicia command por nombre desde el PATH del usuario. Cuando el binario no está allí, el servidor falla al iniciarse y claude --debug registra LSP server <name> failed to start
• Conflictos de extensión: cuando dos servidores habilitados reclaman la misma extensión, el primero registrado maneja esos archivos y el otro no se usa para ellos, ya sea que los servidores provengan de un plugin o dos. La pestaña Errors de /plugin muestra la advertencia LSP server "<name>" is not used for <ext> files

​

Ejecutables

#!/bin/bash
echo "hello from my-plugin"

​

Configuración predeterminada

{
  "agent": "security-reviewer"
}

• Archivo sobre manifiesto: cuando ambos existen y settings.json establece al menos una clave admitida, settings.json se aplica y el settings del manifiesto se ignora
• Configuración del usuario sobre valores predeterminados del plugin: en todas las fuentes de configuración, los valores predeterminados del plugin son la capa más baja, así que un agent propio del usuario en ~/.claude/settings.json anula el suyo
• Dos plugins establecen la misma clave: el valor del plugin cargado último se aplica, y claude --debug registra overrides setting

​

Temas y estilos de salida

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

​

Canales

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

​

Monitores

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

• Solo sesiones interactivas: los monitores del plugin comienzan en una sesión interactiva y nunca en modo no interactivo con la bandera -p. También comienzan solo donde la herramienta Monitor está disponible
• Sin configuración del usuario: command obtiene las variables de ruta y ${ENV_VAR} del entorno, pero nunca ${user_config.*}. Un monitor que hace referencia a uno no comienza, y los procesos de monitor tampoco reciben CLAUDE_PLUGIN_OPTION_<KEY>
• Deshabilitación a mitad de sesión: 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

​

Pedir al usuario valores de configuración

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

Cuándo aparece el diálogo de configuración

• Instala el plugin en /plugin
• Ejecuta /plugin install <plugin>@<marketplace> dentro de una sesión
• Habilita el plugin desde la pestaña Installed en /plugin

​

Hacer referencia a rutas de plugin y almacenar datos

• ${CLAUDE_PLUGIN_ROOT}: el directorio de instalación del plugin. Cada versión tiene su propio directorio de caché, así que la ruta cambia cuando el plugin se actualiza. No escriba estado allí
• ${CLAUDE_PLUGIN_DATA}: un directorio que sobrevive a las actualizaciones, para node_modules, entornos virtuales y cachés. Se resuelve a ~/.claude/plugins/data/<id>/ y se crea cuando se hace referencia por primera vez
• ${CLAUDE_PROJECT_DIR}: la raíz del proyecto, el mismo valor que los hooks reciben

​

Instalar dependencias en el directorio de datos

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

​

Próximos pasos

• Referencia de manifiesto de plugin: campos plugin.json, reglas de ruta y el diseño estándar
• Probar plugins con evals: verifique que los componentes que agregó cambien el comportamiento de Claude de la manera que pretende
• Publicar y distribuir un plugin: versione el plugin y colóquelo en un marketplace
• Solucionar problemas de plugins: qué hacer cuando un componente no se carga o un hook no se activa