Crear plugins

Los plugins te permiten extender Claude Code con funcionalidad personalizada que se puede compartir entre proyectos y equipos. Esta guía cubre la creación de tus propios plugins con skills, agentes, hooks y servidores MCP. ¿Buscas instalar plugins existentes? Consulta Descubrir e instalar plugins. Para especificaciones técnicas completas, consulta Referencia de plugins.

Cuándo usar plugins versus configuración independiente

Claude Code admite dos formas de agregar skills, agentes y hooks personalizados:

Enfoque	Nombres de skills	Mejor para
Independiente (directorio `.claude/`)	`/hello`	Flujos de trabajo personales, personalizaciones específicas del proyecto, experimentos rápidos
Plugins (directorios con `.claude-plugin/plugin.json`)	`/plugin-name:hello`	Compartir con compañeros de equipo, distribuir a la comunidad, lanzamientos versionados, reutilizable en múltiples proyectos

Usa configuración independiente cuando:

Estés personalizando Claude Code para un único proyecto
La configuración es personal y no necesita ser compartida
Estés experimentando con skills o hooks antes de empaquetarlos
Quieras nombres de skills cortos como /hello o /deploy

Usa plugins cuando:

Quieras compartir funcionalidad con tu equipo o comunidad
Necesites los mismos skills/agentes en múltiples proyectos
Quieras control de versiones y actualizaciones fáciles para tus extensiones
Estés distribuyendo a través de un marketplace
Estés de acuerdo con skills con espacios de nombres como /my-plugin:hello (los espacios de nombres previenen conflictos entre plugins)

Comienza con configuración independiente en .claude/ para iteración rápida, luego convierte a un plugin cuando estés listo para compartir.

Inicio rápido

Este inicio rápido te guía a través de la creación de un plugin con un skill personalizado. Crearás un manifiesto (el archivo de configuración que define tu plugin), agregarás un skill y lo probarás localmente usando la bandera --plugin-dir.

Requisitos previos

Claude Code instalado y autenticado
Claude Code versión 1.0.33 o posterior (ejecuta claude --version para verificar)

Si no ves el comando /plugin, actualiza Claude Code a la última versión. Consulta Troubleshooting para obtener instrucciones de actualización.

Crea tu primer plugin

Crea el directorio del plugin

Cada plugin vive en su propio directorio que contiene un manifiesto y tus skills, agentes o hooks. Crea uno ahora:

mkdir my-first-plugin

Crea el manifiesto del plugin

El archivo de manifiesto en .claude-plugin/plugin.json define la identidad de tu plugin: su nombre, descripción y versión. Claude Code usa estos metadatos para mostrar tu plugin en el administrador de plugins.Crea el directorio .claude-plugin dentro de tu carpeta de plugin:

mkdir my-first-plugin/.claude-plugin

Luego crea my-first-plugin/.claude-plugin/plugin.json con este contenido:

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"
}
}

Campo	Propósito
`name`	Identificador único y espacio de nombres de skill. Los skills tienen este prefijo (por ejemplo, `/my-first-plugin:hello`).
`description`	Se muestra en el administrador de plugins al examinar o instalar plugins.
`version`	Rastrear lanzamientos usando versionado semántico.
`author`	Opcional. Útil para atribución.

Para campos adicionales como homepage, repository y license, consulta el esquema de manifiesto completo.

Agrega un skill

Los skills viven en el directorio skills/. Cada skill es una carpeta que contiene un archivo SKILL.md. El nombre de la carpeta se convierte en el nombre del skill, con el prefijo del espacio de nombres del plugin (hello/ en un plugin llamado my-first-plugin crea /my-first-plugin:hello).Crea un directorio de skill en tu carpeta de plugin:

mkdir -p my-first-plugin/skills/hello

Luego crea my-first-plugin/skills/hello/SKILL.md con este contenido:

my-first-plugin/skills/hello/SKILL.md

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

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

Prueba tu plugin

Ejecuta Claude Code con la bandera --plugin-dir para cargar tu plugin:

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

Una vez que Claude Code se inicie, prueba tu nuevo skill:

/my-first-plugin:hello

Verás que Claude responde con un saludo. Ejecuta /help para ver tu skill listado bajo el espacio de nombres del plugin.

¿Por qué espacios de nombres? Los skills de plugin siempre tienen espacios de nombres (como /greet:hello) para prevenir conflictos cuando múltiples plugins tienen skills con el mismo nombre.Para cambiar el prefijo del espacio de nombres, actualiza el campo name en plugin.json.

Agrega argumentos de skill

Haz tu skill dinámico aceptando entrada del usuario. El marcador de posición $ARGUMENTS captura cualquier texto que el usuario proporcione después del nombre del skill.Actualiza tu archivo SKILL.md:

my-first-plugin/skills/hello/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.

Ejecuta /reload-plugins para recoger los cambios, luego prueba el skill con tu nombre:

/my-first-plugin:hello Alex

Claude te saludará por tu nombre. Para más información sobre pasar argumentos a skills, consulta Skills.

Has creado y probado exitosamente un plugin con estos componentes clave:

Manifiesto del plugin (.claude-plugin/plugin.json): describe los metadatos de tu plugin
Directorio de skills (skills/): contiene tus skills personalizados
Argumentos de skill ($ARGUMENTS): captura entrada del usuario para comportamiento dinámico

La bandera --plugin-dir es útil para desarrollo y pruebas. Cuando estés listo para compartir tu plugin con otros, consulta Crear y distribuir un marketplace de plugins.

Descripción general de la estructura del plugin

Has creado un plugin con un skill, pero los plugins pueden incluir mucho más: agentes personalizados, hooks, servidores MCP y servidores LSP.

Error común: No pongas commands/, agents/, skills/ o hooks/ dentro del directorio .claude-plugin/. Solo plugin.json va dentro de .claude-plugin/. Todos los otros directorios deben estar en el nivel raíz del plugin.

Directorio	Ubicación	Propósito
`.claude-plugin/`	Raíz del plugin	Contiene el manifiesto `plugin.json` (opcional si los componentes usan ubicaciones predeterminadas)
`commands/`	Raíz del plugin	Skills como archivos Markdown
`agents/`	Raíz del plugin	Definiciones de agentes personalizados
`skills/`	Raíz del plugin	Agent Skills con archivos `SKILL.md`
`hooks/`	Raíz del plugin	Manejadores de eventos en `hooks.json`
`.mcp.json`	Raíz del plugin	Configuraciones de servidor MCP
`.lsp.json`	Raíz del plugin	Configuraciones de servidor LSP para inteligencia de código
`settings.json`	Raíz del plugin	Configuraciones predeterminadas aplicadas cuando el plugin está habilitado

Próximos pasos: ¿Listo para agregar más características? Salta a Desarrollar plugins más complejos para agregar agentes, hooks, servidores MCP y servidores LSP. Para especificaciones técnicas completas de todos los componentes del plugin, consulta Referencia de plugins.

Desarrollar plugins más complejos

Una vez que te sientas cómodo con plugins básicos, puedes crear extensiones más sofisticadas.

Agrega Skills a tu plugin

Los plugins pueden incluir Agent Skills para extender las capacidades de Claude. Los skills son invocados por el modelo: Claude los usa automáticamente basándose en el contexto de la tarea. Agrega un directorio skills/ en la raíz de tu plugin con carpetas de Skill que contengan archivos SKILL.md:

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

Cada SKILL.md necesita frontmatter con campos name y description, seguido de instrucciones:

---
name: code-review
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

Después de instalar el plugin, ejecuta /reload-plugins para cargar los Skills. Para orientación completa sobre la autoría de Skills incluyendo divulgación progresiva y restricciones de herramientas, consulta Agent Skills.

Agrega servidores LSP a tu plugin

Para lenguajes comunes como TypeScript, Python y Rust, instala los plugins LSP precompilados desde el marketplace oficial. Crea plugins LSP personalizados solo cuando necesites soporte para lenguajes que aún no están cubiertos.

Los plugins LSP (Language Server Protocol) dan a Claude inteligencia de código en tiempo real. Si necesitas soportar un lenguaje que no tiene un plugin LSP oficial, puedes crear uno propio agregando un archivo .lsp.json a tu plugin:

.lsp.json

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

Los usuarios que instalen tu plugin deben tener el binario del servidor de lenguaje instalado en su máquina. Para opciones de configuración LSP completas, consulta Servidores LSP.

Envía configuraciones predeterminadas con tu plugin

Los plugins pueden incluir un archivo settings.json en la raíz del plugin para aplicar configuración predeterminada cuando el plugin está habilitado. Actualmente, solo se admite la clave agent. Establecer agent activa uno de los agentes personalizados del plugin como el hilo principal, aplicando su indicación del sistema, restricciones de herramientas y modelo. Esto permite que un plugin cambie cómo se comporta Claude Code por defecto cuando está habilitado.

settings.json

{
  "agent": "security-reviewer"
}

Este ejemplo activa el agente security-reviewer definido en el directorio agents/ del plugin. Las configuraciones de settings.json tienen prioridad sobre settings declarados en plugin.json. Las claves desconocidas se ignoran silenciosamente.

Organiza plugins complejos

Para plugins con muchos componentes, organiza tu estructura de directorios por funcionalidad. Para diseños de directorios completos y patrones de organización, consulta Estructura de directorios del plugin.

Prueba tus plugins localmente

Usa la bandera --plugin-dir para probar plugins durante el desarrollo. Esto carga tu plugin directamente sin requerir instalación.

claude --plugin-dir ./my-plugin

Cuando un plugin --plugin-dir tiene el mismo nombre que un plugin de marketplace instalado, la copia local tiene prioridad para esa sesión. Esto te permite probar cambios en un plugin que ya tienes instalado sin desinstalarlo primero. Los plugins de marketplace forzados a estar habilitados por configuraciones administradas son la única excepción y no pueden ser anulados. A medida que hagas cambios en tu plugin, ejecuta /reload-plugins para recoger las actualizaciones sin reiniciar. Esto recarga comandos, skills, agentes, hooks, servidores MCP de plugin y servidores LSP de plugin. Prueba los componentes de tu plugin:

Prueba tus skills con /plugin-name:skill-name
Verifica que los agentes aparezcan en /agents
Verifica que los hooks funcionen como se espera

Puedes cargar múltiples plugins a la vez especificando la bandera varias veces:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Depura problemas del plugin

Si tu plugin no funciona como se espera:

Verifica la estructura: Asegúrate de que tus directorios estén en la raíz del plugin, no dentro de .claude-plugin/
Prueba componentes individualmente: Verifica cada comando, agente y hook por separado
Usa herramientas de validación y depuración: Consulta Herramientas de depuración y desarrollo para comandos CLI y técnicas de solución de problemas

Comparte tus plugins

Cuando tu plugin esté listo para compartir:

Agrega documentación: Incluye un README.md con instrucciones de instalación y uso
Versiona tu plugin: Usa versionado semántico en tu plugin.json
Crea o usa un marketplace: Distribuye a través de marketplaces de plugins para instalación
Prueba con otros: Haz que los miembros del equipo prueben el plugin antes de una distribución más amplia

Una vez que tu plugin esté en un marketplace, otros pueden instalarlo usando las instrucciones en Descubrir e instalar plugins.

Envía tu plugin al marketplace oficial

Para enviar un plugin al marketplace oficial de Anthropic, usa uno de los formularios de envío en la aplicación:

Claude.ai: claude.ai/settings/plugins/submit
Console: platform.claude.com/plugins/submit

Para especificaciones técnicas completas, técnicas de depuración y estrategias de distribución, consulta Referencia de plugins.

Convierte configuraciones existentes en plugins

Si ya tienes skills o hooks en tu directorio .claude/, puedes convertirlos en un plugin para compartir y distribución más fácil.

Pasos de migración

Crea la estructura del plugin

Crea un nuevo directorio de plugin:

mkdir -p my-plugin/.claude-plugin

Crea el archivo de manifiesto en my-plugin/.claude-plugin/plugin.json:

my-plugin/.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

Copia tus archivos existentes

Copia tus configuraciones existentes al directorio del plugin:

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

Migra hooks

Si tienes hooks en tu configuración, crea un directorio de hooks:

mkdir my-plugin/hooks

Crea my-plugin/hooks/hooks.json con tu configuración de hooks. Copia el objeto hooks de tu .claude/settings.json o settings.local.json, ya que el formato es el mismo. El comando recibe entrada de hook como JSON en stdin, así que usa jq para extraer la ruta del archivo:

my-plugin/hooks/hooks.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}

Prueba tu plugin migrado

Carga tu plugin para verificar que todo funciona:

claude --plugin-dir ./my-plugin

Prueba cada componente: ejecuta tus comandos, verifica que los agentes aparezcan en /agents y verifica que los hooks se activen correctamente.

Qué cambia al migrar

Independiente (`.claude/`)	Plugin
Solo disponible en un proyecto	Se puede compartir a través de marketplaces
Archivos en `.claude/commands/`	Archivos en `plugin-name/commands/`
Hooks en `settings.json`	Hooks en `hooks/hooks.json`
Debe copiar manualmente para compartir	Instalar con `/plugin install`

Después de migrar, puedes eliminar los archivos originales de .claude/ para evitar duplicados. La versión del plugin tendrá prioridad cuando se cargue.

Próximos pasos

Ahora que entiendes el sistema de plugins de Claude Code, aquí hay caminos sugeridos para diferentes objetivos:

Para usuarios de plugins

Descubrir e instalar plugins: examina marketplaces e instala plugins
Configura marketplaces de equipo: configura plugins a nivel de repositorio para tu equipo

Para desarrolladores de plugins

Crear y distribuir un marketplace: empaqueta y comparte tus plugins
Referencia de plugins: especificaciones técnicas completas
Profundiza en componentes específicos del plugin:
- Skills: detalles de desarrollo de skills
- Subagents: configuración y capacidades del agente
- Hooks: manejo de eventos y automatización
- MCP: integración de herramientas externas

Agentes

Herramientas y plugins

Automatización

Solución de problemas

Cuándo usar plugins versus configuración independiente

Inicio rápido

Requisitos previos

Crea tu primer plugin

Descripción general de la estructura del plugin

Desarrollar plugins más complejos

Agrega Skills a tu plugin

Agrega servidores LSP a tu plugin

Envía configuraciones predeterminadas con tu plugin

Organiza plugins complejos

Prueba tus plugins localmente

Depura problemas del plugin

Comparte tus plugins

Envía tu plugin al marketplace oficial

Convierte configuraciones existentes en plugins

Pasos de migración

Qué cambia al migrar

Próximos pasos

Para usuarios de plugins

Para desarrolladores de plugins

Agentes

Herramientas y plugins

Automatización

Solución de problemas

​Cuándo usar plugins versus configuración independiente

​Inicio rápido

​Requisitos previos

​Crea tu primer plugin

​Descripción general de la estructura del plugin

​Desarrollar plugins más complejos

​Agrega Skills a tu plugin

​Agrega servidores LSP a tu plugin

​Envía configuraciones predeterminadas con tu plugin

​Organiza plugins complejos

​Prueba tus plugins localmente

​Depura problemas del plugin

​Comparte tus plugins

​Envía tu plugin al marketplace oficial

​Convierte configuraciones existentes en plugins

​Pasos de migración

​Qué cambia al migrar

​Próximos pasos

​Para usuarios de plugins

​Para desarrolladores de plugins

Cuándo usar plugins versus configuración independiente

Inicio rápido

Requisitos previos

Crea tu primer plugin

Descripción general de la estructura del plugin

Desarrollar plugins más complejos

Agrega Skills a tu plugin

Agrega servidores LSP a tu plugin

Envía configuraciones predeterminadas con tu plugin

Organiza plugins complejos

Prueba tus plugins localmente

Depura problemas del plugin

Comparte tus plugins

Envía tu plugin al marketplace oficial

Convierte configuraciones existentes en plugins

Pasos de migración

Qué cambia al migrar

Próximos pasos

Para usuarios de plugins

Para desarrolladores de plugins