\
CONTEXT/academy
Lección 02 · ≈ 13 min

Anatomía de un plugin

El manifest plugin.json y la estructura de directorios del plugin.

Anatomía de un plugin

Un plugin es un directorio con un manifest y tus componentes. Dos piezas: el plugin.json que lo identifica, y las carpetas (skills/, hooks/…) en la raíz del plugin.

El manifest: .claude-plugin/plugin.json

Vive en .claude-plugin/plugin.json dentro del plugin:

{
  "name": "dev-tools",
  "description": "Skills, hooks y revisor del equipo",
  "version": "1.0.0",
  "author": { "name": "Tu equipo" }
}
CampoPara qué
nameidentificador y namespace de las skills (/dev-tools:review-pr)
descriptionse muestra al navegar/instalar
versionopcional; si lo pones, los usuarios solo reciben updates al subirlo (si lo omites y distribuyes por git, cuenta cada commit)
authoropcional, para atribución

La estructura de directorios

Las carpetas de componentes van en la raíz del plugin, no dentro de .claude-plugin/:

dev-tools/
├── .claude-plugin/
│   └── plugin.json        # SOLO el manifest va aquí
├── skills/
│   └── review-pr/SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
├── .mcp.json              # servidores MCP del plugin
└── settings.json          # settings por defecto al activarlo
DirectorioQué lleva
skills/skills como <nombre>/SKILL.md
commands/comandos de un fichero (usa skills/ en plugins nuevos)
agents/subagentes
hooks/hooks.json con tus eventos
.mcp.jsonservidores MCP que arrancan al activar el plugin
.lsp.json, monitors/, bin/LSP, monitores en background, ejecutables al PATH

El error más común (lo avisa la propia doc): no metas skills/, agents/, hooks/… dentro de .claude-plugin/. Ahí va solo plugin.json; el resto, en la raíz del plugin.

Variables útiles dentro del plugin

Cuando un componente del plugin necesita referenciar sus propios ficheros (un script de un hook, el binario de un servidor MCP), usa ${CLAUDE_PLUGIN_ROOT}, que apunta a la raíz del plugin estés donde estés. Así el plugin funciona igual cuando se instala en cualquier máquina.

Qué llevas hasta aquí

  • El manifest .claude-plugin/plugin.json (name, description, version, author) identifica el plugin; name es el namespace.
  • Las carpetas de componentes van en la raíz del plugin, nunca dentro de .claude-plugin/.
  • Usa ${CLAUDE_PLUGIN_ROOT} para referenciar ficheros propios.

En la siguiente lección, lo construyes de verdad: convertir tu .claude/ en un plugin.

Fuente oficial: Create plugins · Plugins reference

¿Quieres llevar la cuenta de las lecciones que has terminado?

Entrar para guardar progreso