Tu primer plugin de Claude Code en 60 minutos, de la carpeta vacía al bundle instalable

Tienes un slash command que solo tú necesitas. Una skill que copias en tres repos. Un hook que comprueba algo en cada edit. En solitario funciona. En cuanto quieres pasar el setup a un compañero, se cae. Siete archivos en tres sitios, cada uno instala distinto, nadie sabe qué versión es la actual.

Para eso están exactamente los plugins. Un plugin es un contenedor que empaqueta slash commands, skills, hooks, sub-agentes, servidores MCP, servidores LSP y temas en una sola unidad. Lo instalas una vez, lo activas una vez, lo compartes como ZIP, como repo de Git o vía un marketplace. Anthropic ha convertido el sistema de plugins en la vía estándar para distribuir todo lo que antes se repartía con copy-paste.

Este playbook va de cero. Puedes hacer los 10 pasos en 60 minutos, y al final tienes un plugin instalable con un slash command, una skill y un hook. Quien quiera, enchufa luego servidores MCP.

Paso 1, carpeta vacía y el manifiesto

Un plugin es una carpeta con una estructura fija. Pon la carpeta donde quieras, el nombre es libre. Yo la tengo en ~/dev/plugins/tu-plugin-name. Lo importante es que dentro haya un directorio oculto .claude-plugin/ con el archivo plugin.json. Ese archivo es el manifiesto y la única entrada obligatoria.

~/dev/plugins/tu-plugin-name/
└── .claude-plugin/
    └── plugin.json

Contenido mínimo de plugin.json:

{
  "name": "tu-plugin-name",
  "version": "0.1.0",
  "description": "Qué hace tu plugin en una frase."
}

Más no necesitas al principio. Author, homepage, license y demás vienen después.

Paso 2, los directorios de componentes en la raíz del plugin

Trampa número uno para principiantes. Las carpetas de componentes NO van dentro de .claude-plugin/, sino directamente en la raíz del plugin, al lado. El directorio .claude-plugin/ es solo para el manifiesto y la config. Todo lo demás vive un nivel por encima.

Estas carpetas las reconoce Claude Code en la raíz del plugin:

• commands/ para slash commands
• skills/ para skills con SKILL.md
• agents/ para sub-agentes
• hooks/hooks.json para event hooks
• output-styles/ para estilos de respuesta propios
• themes/ para color themes
• monitors/ para watchers de la status line
• .mcp.json para configs de servidores MCP
• .lsp.json para language servers
• bin/ para ejecutables que entran automáticamente en el PATH de la herramienta Bash cuando el plugin está activo

No hace falta crearlas todas. Para la primera ronda bastan commands/, skills/ y hooks/.

Paso 3, primer slash command

Crea commands/hello.md. Los slash commands son archivos Markdown simples con frontmatter YAML. El nombre del archivo se convierte en el comando, así que esto se vuelve /hello en Claude Code.

---
description: "Saluda y muestra qué hace este slash command."
---

Escribe un saludo corto y explica qué ofrece la suite de plugins
`tu-plugin-name`. Lista los slash commands más importantes.

Eso es todo. Al invocar /hello, Claude Code renderiza el archivo como prompt del usuario y lo manda al modelo.

Paso 4, primera skill

Las skills son distintas. Claude decide solo cuándo usar una skill, basándose en la descripción del SKILL.md. Viven en una subcarpeta con el nombre de la skill.

skills/
└── code-review/
    └── SKILL.md

Contenido del SKILL.md:

---
name: code-review
description: "Se usa automáticamente cuando el usuario pide un code review, quiere revisar un pull request o pregunta qué destaca en un snippet de código. Comprueba siempre seguridad, legibilidad y tests."
---

# Code Review Skill

En cada review, comprueba por orden:

1. Seguridad: vectores de inyección, secretos hardcodeados, input sin validar.
2. Legibilidad: nombres de variables, longitud de funciones, complejidad.
3. Tests: cobertura para el happy path y al menos dos edge cases.

Escribe el review como Markdown con tres titulares.

El bloque description es lo más importante. Claude lo lee en el routing y decide si la skill encaja con la petición actual. Escríbelo de forma que quede claro cuándo debe ayudar la skill.

Paso 5, primer hook

Los hooks son pequeños scripts que se disparan en ciertos eventos. Muy útiles para lint checks, audit logs, memory updates. En el plugin viven en hooks/hooks.json o directamente en el manifiesto.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date +%H:%M:%S) edit by $CLAUDE_USER\" >> ~/.claude/edits.log"
          }
        ]
      }
    ]
  }
}

Eso registra cada file edit con timestamp en un archivo de log local. Pequeño, pero muestra el patrón. Hooks más complejos llaman a scripts de bash que viven en bin/.

Paso 6, servidor MCP como opción

Si tu plugin debe traer un servidor MCP, pon .mcp.json en la raíz del plugin. El formato es idéntico al .mcp.json local de proyecto que quizá ya conoces.

{
  "mcpServers": {
    "tu-herramienta": {
      "command": "node",
      "args": ["./bin/tu-mcp-server.js"]
    }
  }
}

La ruta es relativa a la raíz del plugin. El directorio bin/ se añade automáticamente al PATH en cuanto el plugin está activo, así que también funciona un nombre de comando pelado sin prefijo ./bin/.

Paso 7, activar y probar en local

Antes de pensar en distribución, prueba en local. En Claude Code se hace con el slash command /plugin. En la pestaña Discover puedes instalar plugins desde marketplaces activados. Para tu plugin todavía no publicado, vas a la pestaña Manage y lo añades como filesystem source.

Alternativamente vía CLI:

claude plugin install --source ~/dev/plugins/tu-plugin-name

Por dentro, Claude Code escribe tu activación en ~/.claude/settings.json bajo enabledPlugins. La entrada se ve así:

{
  "enabledPlugins": {
    "local/tu-plugin-name": true
  }
}

Reload, luego escribe /hello. Si aparece el slash command, el plugin está vivo.

Paso 8, montar un marketplace o distribución por URL

Dos vías para distribuir el plugin. Primera opción, te montas tu propio marketplace. Eso es un repo de Git con un .claude-plugin/marketplace.json que lista todos los plugins que ofrece ese marketplace.

Estructura mínima del marketplace:

mi-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── tu-plugin-name/
        ├── .claude-plugin/plugin.json
        ├── commands/
        ├── skills/
        └── hooks/

marketplace.json lista qué carpetas de plugin del repo están disponibles. Otros usuarios añaden tu marketplace luego con /plugin marketplace add github:tu-handle/mi-marketplace.

Segunda opción es --plugin-url. Empaquetas el plugin como ZIP, lo subes a algún sitio, y los colegas arrancan Claude Code con claude --plugin-url https://example.com/tu-plugin-0.1.0.zip. Eso carga para una sesión, sin setup permanente. Detalles en el playbook aparte plugin-bundle-via-url-distribution.

Para la mayoría de equipos, marketplace es la elección correcta. URL distribution está bien para tests puntuales o para gente que no quiere instalar nada de forma permanente.

Paso 9, entender los trust boundaries

Una cosa importante que mucha gente pasa por alto al principio. Los plugins pueden ejecutar hooks y llamar scripts de bash en bin/. Eso es poder y eso es riesgo. Anthropic ha metido dos mecanismos de protección.

El primero, los plugins NO pueden controlar el settings.json entero. Solo están permitidas las dos claves agent y subagentStatusLine. Todo lo demás se ignora cuando un plugin intenta ponerlo. Es decir, un plugin malicioso no puede registrarte servidores MCP sin avisar ni torcerte permissions.

El segundo, los trust prompts. Al primera activación, Claude Code pregunta si confías en el plugin. Los administradores de IT pueden bloquear esto fuerte vía strictKnownMarketplaces como managed setting. Con pluginTrustMessage se puede poner un trust prompt custom, por ejemplo para notas de compliance.

Para plugins propios que tú mismo construyes, todo esto es transparente. En cuanto instalas plugins de terceros, léete antes el código del plugin. Hooks que hacen curl | bash son red flags.

Paso 10, versionar y comitear

Último paso. Tu plugin ya vive. Antes de compartirlo, deja limpio el versionado. Sube version en plugin.json a 1.0.0 cuando la primera variante estable esté lista. Etiqueta el commit de Git con el mismo valor.

Qué debería comitearse: todo excepto logs específicos del usuario. Qué tiene que quedar fuera: claves API en comandos de hooks, rutas personales, outputs de test locales. Los plugins son exactamente como código, léelo una vez con ojo crítico antes de hacer push.

Recomendación para el versionado, semantic versioning es exagerado para plugins solitarios. Basta con que uses 0.1.0 para "primera variante", 0.2.0 para "skill nueva añadida", 1.0.0 para "lo llevo dos semanas usando a diario y nada se ha roto".

Qué viene después

Cuando tu plugin esté de pie y tres personas lo usen, viene el siguiente paso. Quien quiera distribuir el plugin como URL de ZIP salta a plugin-bundle-via-url-distribution. Quien quiera montar un marketplace completo con repo propio y selección de plugins, mira la doc oficial de Anthropic sobre plugin marketplaces (link abajo). Quien quiera integrar el plugin en una CI, lo combina con claude-code-headless-in-ci-cd.

Una cosa que aprendí tras mi tercer plugin propio: mantenlos pequeños. Un plugin por use case, no un mega plugin con todo dentro. Si un plugin tiene siete skills y doce slash commands, divídelo. Los compañeros prefieren instalar tres plugins pequeños con función clara que uno grande que apenas encaja.

Source

Fuentes de la doc oficial de Claude Code:

• Plugin manifest, directorios de componentes, formato de hooks, trust boundaries: https://code.claude.com/docs/en/plugins-reference
• Montaje del marketplace y comandos CLI (/plugin marketplace add etc): https://code.claude.com/docs/en/plugin-marketplaces

Fecha de verificación: 2026-05-08. Si buscas funciones de plugin que no salen aquí, comprueba ambas páginas antes de apoyarte en fuentes de terceros.