← Volver al listado de tecnologías ← Índice de Claude Code

Cap 15: Plugins

2 de marzo de 2026 Por: Artiko

claude-codepluginsmarketplacesdistribution

Qué son los Plugins

Los plugins extienden Claude Code con funcionalidad custom compartible entre proyectos y equipos. Pueden incluir skills, agents, hooks, MCP servers, LSP servers, monitors, settings y binarios.

Plugins vs configuración standalone

Approach	Skill names	Best para
Standalone (`.claude/`)	`/hello`	Workflows personales, customización por proyecto, experimentos
Plugins (con `.claude-plugin/plugin.json`)	`/plugin-name:hello`	Compartir con el equipo, distribuir a la comunidad, versionado, reusable

Usá standalone cuando customizás para un único proyecto y los nombres cortos importan.

Usá plugin cuando querés compartir, versionar, distribuir via marketplace, o reusar en múltiples proyectos. Los plugin skills tienen namespace para evitar conflictos.

Empezá con standalone para iterar rápido y convertí a plugin cuando estés listo para compartir.

Quickstart

1. Crear directorio del plugin

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

2. Crear el manifest

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 namespace de skills. Los skills llevan prefix (`/my-first-plugin:hello`)
`description`	Mostrado en el plugin manager
`version`	Opcional. Si se setea, los users reciben updates solo cuando bumpés. Sin esto, el commit SHA se usa como versión
`author`	Opcional. Atribución

Campos adicionales soportados: homepage, repository, license. Ver Plugin manifest schema.

3. Agregar un skill

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

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.

4. Testear el plugin

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

Y luego /my-first-plugin:hello. Run /help para ver el skill bajo el plugin namespace.

Plugin skills están siempre namespaced para evitar conflictos. Para cambiar el prefix, actualizá name en plugin.json.

5. Argumentos en skills

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

# Hello Skill

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

Run /reload-plugins para recargar, luego /my-first-plugin:hello Alex.

Estructura de un plugin

Error común: NO pongas commands/, agents/, skills/, ni hooks/ dentro de .claude-plugin/. Solo plugin.json va ahí. Las demás carpetas van en el plugin root.

Directorio	Location	Propósito
`.claude-plugin/`	Plugin root	Contiene `plugin.json` (opcional si componentes usan locations default)
`skills/`	Plugin root	Skills como `<name>/SKILL.md` directorios
`commands/`	Plugin root	Commands como archivos Markdown planos. Usá `skills/` para plugins nuevos
`agents/`	Plugin root	Agent definitions
`hooks/`	Plugin root	Event handlers en `hooks.json`
`.mcp.json`	Plugin root	MCP server configs
`.lsp.json`	Plugin root	LSP server configs para code intelligence
`monitors/`	Plugin root	Background monitor configs en `monitors.json`
`bin/`	Plugin root	Ejecutables agregados al `PATH` del Bash tool mientras el plugin esté enabled
`settings.json`	Plugin root	Default settings aplicados cuando el plugin está enabled

Componentes avanzados

Skills

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

Después de instalar el plugin, /reload-plugins para cargar. Ver Skills para frontmatter completo.

LSP servers

Plugins LSP dan a Claude code intelligence en tiempo real. Para lenguajes comunes (TS, Python, Rust) usá los plugins oficiales. Para custom:

.lsp.json:

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

Los users instalando deben tener el binario instalado en su máquina.

Background monitors

Observan logs, files, o status externo y notifican a Claude.

monitors/monitors.json:

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

Cada stdout line del command se entrega a Claude como notificación durante la sesión.

Default settings con `settings.json`

Plugins pueden incluir settings.json en el root con defaults aplicados al habilitarse. Actualmente solo agent y subagentStatusLine están soportados.

{
  "agent": "security-reviewer"
}

Esto activa el agente security-reviewer definido en agents/ como main thread cuando el plugin se habilita.

MCP servers

.mcp.json en el plugin root. Los inline servers se conectan al startup del plugin y se desconectan al deshabilitarlo.

Testing local

# Directorio
claude --plugin-dir ./my-plugin

# ZIP archive (v2.1.128+)
claude --plugin-dir ./my-plugin.zip

# Múltiples plugins
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

# Desde URL
claude --plugin-url https://example.com/plugin.zip

Cuando un plugin con --plugin-dir tiene el mismo nombre que uno instalado del marketplace, la versión local tiene precedencia para esa sesión. Excepción: plugins force-enabled/disabled por managed settings no pueden ser overridden con --plugin-dir.

/reload-plugins recarga sin reiniciar (incluye skills, agents, hooks, MCP servers, LSP servers del plugin).

Debugging

Verificá la estructura: directorios en el plugin root, no dentro de .claude-plugin/
Test componentes individualmente: cada skill, agent, hook separado
Ver Debugging tools para CLI commands

Distribución

Pasos para compartir:

README.md con instrucciones de instalación y uso
Versioning strategy: setear version explícito o usar commit SHA del git
Marketplace: distribuir via plugin marketplaces o repositorio privado para uso interno
Test con el equipo antes de publicar

Submit al marketplace oficial

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

Convertir standalone a plugin

mkdir -p my-plugin/.claude-plugin

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

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

Copiar configuraciones:

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

Migrar hooks: crear my-plugin/hooks/hooks.json copiando el objeto hooks desde .claude/settings.json.

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

Testear:

claude --plugin-dir ./my-plugin

Después de migrar podés borrar los archivos originales de .claude/ para evitar duplicados. La versión del plugin tendrá precedencia.

Diferencias estándar vs plugin

Standalone	Plugin
Solo en un proyecto	Compartible via marketplaces
Files en `.claude/commands/`	Files en `plugin-name/commands/`
Hooks en `settings.json`	Hooks en `hooks/hooks.json`
Copiar manualmente para compartir	Install con `/plugin install`

Instalación de plugins existentes

/plugin install code-review@claude-plugins-official

Marketplace de equipo: configurar plugin marketplaces en repos privados para distribución interna.

CLI commands

claude plugin install <plugin>@<marketplace>
claude plugin list
claude plugin remove <plugin>

Alias: claude plugins. Ver plugin reference CLI commands.

Recomendar tu plugin desde tu CLI

Una vez listado en el marketplace, podés tener tu propio CLI que prompts a usuarios de Claude Code a instalarlo. Ver /en/plugin-hints en la doc oficial.

Siguiente: Checkpointing y Sesiones