Cómo crear un plugin de Claude Code en 2026 (guía práctica)

Para crear un plugin de Claude Code, coloca tus skills, agentes, hooks o configuración de MCP en un único directorio con un manifiesto .claude-plugin/plugin.json, pruébalo con claude --plugin-dir ./my-plugin y distribúyelo a través de un marketplace para que tus compañeros de equipo puedan instalarlo. Ese es todo el ciclo, y puedes tener un plugin funcional en unos cinco minutos. El resto consiste en saber qué piezas incluir, cómo evitar el único error de directorio que arruina la mayoría de los primeros intentos, y cómo versionarlo y compartirlo una vez que funciona.

Ejecutamos el motor de contenidos de TechRiseUps sobre Claude Code, y la forma más rápida de sacar un flujo de trabajo de una sola máquina y llevarlo a todo el equipo es empaquetarlo como un plugin en lugar de andar copiando carpetas .claude/ de un lado a otro. Esta guía recorre exactamente cómo crear un plugin de Claude Code en 2026, según la documentación oficial de plugins actual.

¿Qué es un plugin de Claude Code?

Un plugin de Claude Code es un directorio autónomo que agrupa una o varias extensiones —skills, subagentes, hooks, servidores MCP, servidores LSP o monitores en segundo plano— tras un único archivo de manifiesto. El manifiesto, .claude-plugin/plugin.json, le da al plugin un nombre, una descripción y una versión. Una vez instalado, todo lo que incluye el plugin queda bajo el espacio de nombres de ese nombre: una skill llamada hello dentro de un plugin llamado my-first-plugin se invoca como /my-first-plugin:hello, lo que evita que dos plugins colisionen cuando ambos definen una skill con el mismo nombre. La razón de ser de un plugin, frente a tener configuración suelta en tu carpeta .claude/, es la portabilidad: se controla por versiones como una sola unidad, se actualiza de forma limpia y se instala en la máquina de otra persona con un único comando en lugar de con un ritual de copiar y pegar.

Plugin frente a configuración independiente: ¿cuál deberías usar?

Claude Code te permite añadir skills, agentes y hooks de dos maneras, y elegir la equivocada hace perder tiempo. La configuración independiente en un directorio .claude/ es la adecuada para ajustes personales, específicos de un proyecto, y para experimentos rápidos: obtienes nombres cortos como /deploy y cero sobrecarga de empaquetado. Un plugin es la opción correcta en el momento en que quieres compartir el flujo de trabajo, reutilizarlo entre proyectos o publicar actualizaciones versionadas. La señal es simple: si solo tú vas a ejecutarlo en un único repositorio, mantenlo independiente; si alguien más lo necesita, conviértelo en un plugin.

	Independiente (.claude/)	Plugin
Nombre de invocación	/hello	/my-plugin:hello
Alcance	Un proyecto	Cualquier proyecto, cualquier máquina
Compartir	Copia manual	/plugin install desde un marketplace
Versionado	Ninguno	version explícita o SHA de git
Ideal para	Experimentos personales	Distribución en equipo y comunidad

El camino recomendado es prototipar en .claude/ para iterar rápido y luego convertirlo en un plugin cuando merezca la pena compartirlo.

Paso a paso: crea tu primer plugin

Aquí tienes la construcción mínima de principio a fin. Crea un plugin con una sola skill y lo prueba en local, sin necesidad de marketplace.

1. Crea el directorio del plugin.

mkdir my-first-plugin

2. Añade el manifiesto en my-first-plugin/.claude-plugin/plugin.json:

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

Solo name es realmente obligatorio; version y author son opcionales, pero vale la pena definirlos (más sobre el versionado más abajo).

3. Añade una skill. Las skills viven en skills/<name>/SKILL.md. Crea my-first-plugin/skills/hello/SKILL.md:

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

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

4. Pruébala en local con el flag --plugin-dir —sin necesidad de un paso de instalación:

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

Luego ejecuta /my-first-plugin:hello dentro de la sesión. A medida que edites archivos, ejecuta /reload-plugins para recoger los cambios sin reiniciar Claude Code. Si prefieres no pasar el flag en cada arranque, claude plugin init my-tool genera la estructura de un plugin en tu directorio de skills que se carga automáticamente en la siguiente sesión.

Eso es un plugin real y funcional. Todo lo que viene a partir de aquí consiste en añadir más componentes y en distribuirlo.

Qué va dentro de un plugin

Un plugin puede contener mucho más que una sola skill. Cada tipo de componente vive en su propio directorio en la raíz del plugin (no dentro de .claude-plugin/), y Claude Code los descubre por convención:

Directorio / archivo	Contiene
.claude-plugin/plugin.json	El manifiesto (nombre, versión, metadatos)
skills/<name>/SKILL.md	Skills invocadas por el modelo
agents/	Definiciones de subagentes personalizados
hooks/hooks.json	Manejadores de eventos (p. ej. lint en cada edición)
.mcp.json	Configuraciones de servidores MCP para herramientas externas
.lsp.json	Servidores de lenguaje para inteligencia de código
monitors/monitors.json	Observadores en segundo plano que notifican a Claude
bin/	Ejecutables añadidos al PATH de Bash mientras está activado
settings.json	Ajustes por defecto aplicados cuando está activado

Por eso los plugins son el hogar natural de un flujo de trabajo completo: un único plugin puede añadir una skill, un hook de lint y un servidor MCP que se distribuyen y actualizan todos juntos.

El error que arruina la mayoría de los primeros plugins

Si tu skill o tu hook no se carga sin dar ningún aviso, la causa casi siempre es la misma: archivos colocados en el lugar equivocado. Solo plugin.json va dentro de .claude-plugin/. Todos los demás directorios —skills/, agents/, hooks/, commands/— deben estar en la raíz del plugin, un nivel más arriba. Anidar skills/ dentro de .claude-plugin/ es el error más común al crear un primer plugin, y Claude Code no lanza ninguna advertencia sonora; los componentes simplemente nunca aparecen.

La raíz del plugin es la carpeta propia de cada plugin individual —la que pasas a --plugin-dir—, nunca tu ~/.claude/ global. Cuando algo no funciona, depura en este orden: confirma que la estructura de directorios está en la raíz, prueba cada componente por separado, ejecuta /reload-plugins y comprueba que los agentes aparecen en /context bajo Custom Agents. Ejecuta claude plugin validate para detectar problemas de manifiesto y de estructura antes de que te cuesten una sesión de depuración.

Distribuir tu plugin: marketplaces y versionado

--plugin-dir es para ti; un marketplace es para todos los demás. Un marketplace no es más que un repositorio de git con un archivo .claude-plugin/marketplace.json en su raíz que lista tus plugins y desde dónde obtener cada uno. Lo subes a GitHub o a cualquier host de git, y los usuarios lo añaden con /plugin marketplace add <owner/repo> y luego instalan plugins individuales desde él. Para mantener un plugin interno, aloja el marketplace en un repositorio privado; para llegar a un público más amplio, Anthropic mantiene dos catálogos públicos: uno curado, claude-plugins-official, y el de la comunidad, claude-community, que acepta envíos de terceros tras una revisión.

El versionado es la parte que la gente se salta y luego lamenta. Si defines una version explícita en plugin.json, los usuarios solo reciben actualizaciones cuando la subes —algo predecible y recomendado para cualquier cosa que se comparta. Si la omites y distribuyes vía git, el SHA del commit se convierte en la versión, de modo que cada commit cuenta como una nueva publicación. Elige versiones explícitas para cualquier cosa de la que dependa un equipo. Antes de publicar o enviar, ejecuta siempre claude plugin validate, añade un README.md con notas de instalación y uso, y haz que otra persona lo instale desde cero —la misma disciplina que aplicarías al ejecutar Claude Code en automatización.

Preguntas frecuentes

¿Necesito un marketplace para usar un plugin?

No. claude --plugin-dir ./my-plugin carga un plugin directamente desde una carpeta local durante esa sesión, y claude plugin init puede generar la estructura de uno que se carga automáticamente desde tu directorio de skills. Los marketplaces solo importan cuando quieres distribuir un plugin a otras personas o máquinas.

¿Cuál es la diferencia entre un plugin y una skill?

Una skill es una única capacidad: un archivo SKILL.md con instrucciones. Un plugin es un paquete que puede agrupar muchas skills, además de agentes, hooks y servidores MCP, tras un único manifiesto versionado. Un plugin de una sola skill está bien; incluso puedes colocar SKILL.md en la raíz del plugin en lugar de en una carpeta skills/.

¿Por qué no se carga mi plugin?

El culpable habitual es la ubicación de los directorios: skills/, agents/ y hooks/ deben estar en la raíz del plugin, y solo plugin.json va dentro de .claude-plugin/. Ejecuta /reload-plugins y luego claude plugin validate para hacer aflorar errores de estructura y de manifiesto.

¿Cómo reciben los usuarios las actualizaciones de mi plugin?

Depende de tu manifiesto. Con una version explícita, las actualizaciones se publican solo cuando subes el número. Sin ella, un plugin distribuido vía git trata cada nuevo commit como una nueva versión. Define una version explícita para cualquier cosa de la que dependa un equipo, de modo que las actualizaciones sean deliberadas.

Fuentes

• Claude Code Docs — Create plugins: quickstart oficial, campos del manifiesto, estructura de directorios, --plugin-dir y /reload-plugins.
• Claude Code Docs — Create and distribute a plugin marketplace: marketplace.json, alojamiento y repositorios privados.
• DataCamp — How to Build Claude Code Plugins: tutorial paso a paso con los comandos claude plugin (Feb 2026).
• DEV Community — Building my first Claude Code Plugin: recorrido de un desarrollador creando su primer plugin (Dec 2025).