Plugins de Claude Code: crea, prueba y publica tu primer plugin

Los plugins de Claude Code parecen una pequeña función de empaquetado, pero resuelven un problema mayor. Antes de que existieran, la configuración de Claude Code vivía suelta dentro de la carpeta .claude/. Compartirla era incómodo, versionarla era un lío y auditarla era difícil. Un plugin reúne todo eso en una única unidad estándar.

Hay un detalle que explica todo el diseño. Todo lo que puede contener un plugin, es decir, skills, agentes, hooks y servidores MCP, ya existía por separado. Los plugins no añaden capacidades nuevas. Estandarizan cómo se empaquetan esas piezas y cómo se entregan a otras personas.

¿Configuración independiente o plugin?

Las dos opciones se diferencian en la forma de nombrar las cosas y en para quién son:

• Configuración independiente en la carpeta .claude/. Los comandos se invocan como /hello. Encaja con flujos personales, ajustes propios de un proyecto y experimentos rápidos.
• Plugin, un directorio autónomo con un manifiesto. Los comandos llevan un prefijo, como en /plugin-name:hello. Encaja para compartir con el equipo, distribuir en la comunidad, publicar versiones y reutilizar en varios proyectos.

Un camino sensato es iterar rápido con una configuración independiente y convertirla en plugin cuando esté lista para compartirse.

Un primer plugin en tres pasos

1. Crea la carpeta y el manifiesto.

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

El archivo de manifiesto plugin.json va en esa carpeta oculta y le da identidad al plugin:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

El valor de name es el identificador único y además se convierte en el espacio de nombres de todas las skills del plugin. El campo version es opcional. Si se define, los usuarios solo reciben actualizaciones cuando se sube el número.

2. Añade una skill. Las skills están en el directorio skills/, cada una en su propia carpeta con un archivo SKILL.md:

mkdir -p my-first-plugin/skills/hello---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

3. Pruébalo en local.

claude --plugin-dir ./my-first-plugin

Cuando Claude arranca, al escribir /my-first-plugin:hello se ejecuta la skill.

El espacio de nombres merece una mención. Todas las skills de un plugin siguen el patrón /plugin-name:skill-name, así que dos plugins pueden incluir skills con el mismo nombre sin chocar nunca.

Para que una skill reciba datos de entrada, pon el marcador $ARGUMENTS en su SKILL.md:

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

Después de editar, /reload-plugins aplica los cambios. Una rareza: el número de skills que aparece tras recargar solo cuenta el directorio commands/, así que puede marcar cero aunque la nueva skill esté cargada y funcione.

También hay un atajo. Ejecutar claude plugin init my-tool crea un plugin en ~/.claude/skills/, que se carga en todas las sesiones futuras como my-tool@skills-dir sin necesidad de --plugin-dir.

Qué puede contener un plugin

Cada ubicación en la raíz del plugin tiene una función fija:

• .claude-plugin/ contiene solo el manifiesto plugin.json
• skills/ contiene las skills, organizadas como <skill-name>/SKILL.md
• commands/ es el formato antiguo de skills con archivos Markdown planos, y los plugins nuevos deberían usar skills/
• agents/ contiene definiciones de agentes personalizados
• hooks/ contiene manejadores de eventos descritos en hooks.json
• .mcp.json configura servidores MCP
• .lsp.json configura servidores de lenguaje para el análisis de código
• monitors/ configura monitores en segundo plano
• bin/ contiene ejecutables que se añaden al PATH mientras el plugin está activo
• settings.json aporta ajustes predeterminados que se aplican al activar el plugin

El error clásico de principiante es meter commands/, agents/, skills/ u otras carpetas de contenido dentro de .claude-plugin/. Ahí solo va el manifiesto. Todo lo demás va directamente en la raíz del plugin.

En un plugin con una sola skill, SKILL.md puede estar en la raíz, y el name de su frontmatter pasa a ser el nombre de invocación. Los plugins con varias skills deberían usar la estructura de skills/.

Extras para plugins más avanzados

Servidores de lenguaje. Para dar soporte a un lenguaje que Claude Code no cubre de serie, añade un archivo .lsp.json:

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

Quien instale el plugin necesita el binario del servidor de lenguaje correspondiente en su máquina. Sin él, aparece un fallo de arranque en la pestaña Errors del gestor /plugin.

Monitores en segundo plano. Defínelos en monitors/monitors.json y se iniciarán cuando se active el plugin. Cada línea que el comando imprime en stdout le llega a Claude como notificación:

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

Ajustes predeterminados. settings.json solo entiende por ahora dos claves, agent y subagentStatusLine, y las claves desconocidas se ignoran sin aviso. La clave agent puede convertir uno de los agentes del propio plugin en el hilo principal, lo que cambia el comportamiento predeterminado de Claude Code:

{
  "agent": "security-reviewer"
}

Pruebas

La principal herramienta de desarrollo es el flag --plugin-dir. Acepta un directorio y también un paquete comprimido:

claude --plugin-dir ./my-plugin.zip

Si un plugin local tiene el mismo nombre que un plugin del marketplace ya instalado, en esa sesión gana la copia local. Es útil para probar cambios sin desinstalar nada. No sirve para anular plugins activados o desactivados de forma forzada.

Para pruebas en remoto existe --plugin-url:

claude --plugin-url https://example.com/my-plugin.zip

Si la descarga falla o el archivo está dañado, Claude Code arranca igualmente y deja constancia del problema en la pestaña Errors de /plugin. Como con cualquier plugin, carga solo fuentes de confianza.

Durante el desarrollo, /reload-plugins aplica los cambios sin reiniciar. Cuando algo no funcione, revisa la estructura de directorios, prueba cada componente por separado y apóyate en las ayudas de depuración de la CLI documentadas en las páginas de referencia de Anthropic.

Cómo aparecer en un marketplace

Anthropic gestiona dos marketplaces públicos:

• claude-plugins-official lo cura Anthropic y se registra automáticamente en el primer arranque interactivo. Un plugin aceptado ahí se ofrece a los usuarios directamente en el producto.
• claude-community lo gestiona la comunidad, y los envíos de terceros se añaden tras una revisión. Se añade con /plugin marketplace add anthropics/claude-plugins-community.

Valida antes de enviarlo:

claude plugin validate ./your-plugin

Si pasa, se muestra el mensaje «Validation passed» y se listan las advertencias que haya. Al añadir --strict, las advertencias se convierten en errores.

El envío se hace mediante uno de dos formularios. Una vía es el formulario de claude.ai, abierto solo a organizaciones con plan Team o Enterprise. Quienes publican por su cuenta usan el formulario de la Console. Tras la aprobación, el plugin queda fijado a un SHA de commit concreto en el repositorio de la comunidad, y la CI mueve esa fijación con cada commit nuevo. Los directorios públicos se sincronizan cada noche, así que es normal que pase un tiempo entre la aprobación y la aparición en marketplace.json.

El marketplace oficial funciona de otra manera. Anthropic decide qué entra y no hay solicitud pública.

Migrar una configuración existente

Las configuraciones independientes se convierten con poco esfuerzo. Crea la carpeta del plugin y el manifiesto, y luego copia el contenido:

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

Los hooks requieren un trato aparte. Toma el objeto hooks del settings.json existente y colócalo en hooks/hooks.json.

Después, borra los originales de .claude/. Los agentes de .claude/agents/, a nivel de proyecto o de usuario, anulan a los agentes del plugin con el mismo nombre, así que los restos impedirían que la nueva versión tuviera efecto. Las skills no chocan de esta forma, porque las del plugin tienen espacio de nombres y ambas versiones pueden convivir.

Qué cambian los plugins

Los plugins no trajeron ninguna capacidad nueva. Las skills, los agentes, los hooks y los servidores MCP funcionaban bien como configuración suelta. Lo que aportan los plugins es estructura: versiones, nombres coherentes, descripciones y canales de distribución de verdad.

Eso hace que Claude Code pase de ser una herramienta a ser una plataforma. Una herramienta hace bien un trabajo, mientras que una plataforma permite que otros construyan encima. Es difícil prever qué crecerá en el marketplace, pero copiar carpetas .claude/ enteras de una máquina a otra tiene los días contados. Otros productos de programación con IA, Cursor entre ellos, también han lanzado marketplaces de plugins, así que en todo el ecosistema los componentes dispersos se están convirtiendo en unidades empaquetadas y fáciles de compartir.