Plugins y marketplaces

Qué son los plugins

Los plugins son paquetes de extensiones que agrupan skills, agentes, hooks, servidores MCP y servidores LSP en una unidad distribuible. Mientras que las configuraciones standalone en .claude/ son específicas de un proyecto, los plugins están diseñados para compartirse entre proyectos, equipos y la comunidad.

La diferencia principal entre ambos enfoques:

| Aspecto | Standalone (.claude/) | Plugin | |---|---|---| | Nombres de skills | /hello | /mi-plugin:hello | | Distribución | Manual (copiar archivos) | Via marketplaces | | Versionado | Mediante Git del proyecto | Versionado semántico propio | | Ideal para | Workflows personales, experimentos | Compartir con equipo, distribución amplia |

Los plugins usan namespacing en las skills para evitar conflictos: una skill hello dentro de un plugin llamado my-tools se invoca como /my-tools:hello. Esto permite instalar múltiples plugins sin riesgo de colisiones de nombres.

Descubrir e instalar plugins

Claude Code incluye un marketplace oficial de Anthropic que está disponible automáticamente. El comando /plugin permite explorar, instalar y gestionar plugins.

Explorar plugins disponibles

/plugin

Este comando abre una interfaz con varias opciones. Seleccionar "Browse Plugins" (o la pestaña "Discover") muestra los plugins disponibles con sus descripciones.

Instalar un plugin

La forma directa de instalar un plugin desde un marketplace:

/plugin install plugin-name@marketplace-name

Por ejemplo, para instalar un plugin de inteligencia de código para Python desde el marketplace oficial:

/plugin install python@claude-plugins-official

El marketplace oficial incluye plugins de code intelligence para lenguajes como Python, TypeScript, Rust, Go, Java, C++, Kotlin y Swift. Estos plugins habilitan funcionalidades como salto a definición y detección de errores mediante servidores LSP.

Gestionar plugins instalados

Tras la instalación, los plugins se gestionan con subcomandos de /plugin:

• Habilitar: /plugin enable plugin-name@marketplace-name
• Deshabilitar: /plugin disable plugin-name@marketplace-name
• Desinstalar: /plugin uninstall plugin-name@marketplace-name
• Ver instalados: /plugin y seleccionar "Manage Plugins"

Marketplaces personalizados

Los equipos y organizaciones pueden crear sus propios marketplaces como repositorios de GitHub y añadirlos a Claude Code:

/plugin marketplace add owner/repository

Esto permite distribuir plugins internos del equipo sin publicarlos en el marketplace oficial.

Estructura de un plugin

Un plugin es un directorio con una estructura específica. El elemento central es el archivo manifest en .claude-plugin/plugin.json, que define la identidad del plugin:

mi-plugin/
  .claude-plugin/
    plugin.json        # Manifest (obligatorio)
  skills/              # Skills del plugin
    code-review/
      SKILL.md
  agents/              # Agentes custom
    reviewer.md
  hooks/               # Hooks del plugin
    hooks.json
  commands/            # Comandos (alternativa a skills)
  .mcp.json            # Servidores MCP incluidos
  .lsp.json            # Servidores LSP incluidos
  settings.json        # Configuración por defecto del plugin

Los directorios commands/, agents/, skills/, hooks/ y demás archivos se colocan en la raíz del plugin, no dentro de .claude-plugin/. Solo plugin.json va dentro de .claude-plugin/.

El manifest plugin.json

El manifest define los metadatos del plugin:

{
  "name": "my-tools",
  "description": "Herramientas de desarrollo para el equipo",
  "version": "1.0.0",
  "author": {
    "name": "Tu Nombre"
  }
}

| Campo | Propósito | |---|---| | name | Identificador único y namespace de las skills | | description | Descripción mostrada en el gestor de plugins | | version | Versionado semántico del plugin | | author | Atribución (opcional) |

Crear un plugin

El proceso de creación de un plugin sigue estos pasos:

1. Crear la estructura de directorios:

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills/hello

2. Crear el manifest:

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

{
  "name": "my-plugin",
  "description": "Plugin de ejemplo para aprender la estructura",
  "version": "1.0.0"
}

3. Añadir una skill:

Crear my-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. Probar localmente:

claude --plugin-dir ./my-plugin

Dentro de la sesión, la skill estará disponible como /my-plugin:hello.

Componentes de un plugin

Skills

Las skills del plugin funcionan exactamente igual que las skills standalone, con la diferencia de que están namespaced con el nombre del plugin. Se crean en el directorio skills/ del plugin, cada una en su propia carpeta con un archivo SKILL.md.

Agentes

Los agentes se definen como archivos markdown en el directorio agents/ del plugin, con la misma estructura de frontmatter YAML que los agentes custom de proyecto o usuario.

Hooks

Los hooks del plugin se configuran en hooks/hooks.json con el mismo formato que el bloque hooks de settings.json:

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

Servidores MCP

Los plugins pueden incluir servidores MCP en un archivo .mcp.json en la raíz del plugin. Estos servidores se inician automáticamente cuando el plugin está habilitado:

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

La variable ${CLAUDE_PLUGIN_ROOT} referencia rutas relativas al directorio del plugin.

Servidores LSP

Los plugins de code intelligence incluyen un archivo .lsp.json que configura servidores de Language Server Protocol para proporcionar funcionalidades como salto a definición, detección de errores y autocompletado:

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

Configuración por defecto

Un archivo settings.json en la raíz del plugin aplica configuración por defecto al habilitarlo. Por ejemplo, activar un agente custom del plugin como agente principal:

{
  "agent": "security-reviewer"
}

Migrar configuración standalone a plugin

Si ya tienes skills, agentes o hooks en .claude/, se pueden migrar a un plugin para facilitar su distribución:

1. Crear la estructura del plugin:

mkdir -p my-plugin/.claude-plugin

2. Copiar los componentes:

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

3. Migrar hooks:

Crear my-plugin/hooks/hooks.json copiando el bloque hooks del archivo settings.json.

4. Probar la migración:

claude --plugin-dir ./my-plugin

Tras migrar, se pueden eliminar los archivos originales de .claude/ para evitar duplicados. El plugin tiene prioridad sobre la configuración standalone cuando ambos definen elementos con el mismo nombre.

Publicar en un marketplace

Para distribuir un plugin a la comunidad, se puede publicar en un marketplace:

• Marketplace oficial de Anthropic: enviar mediante los formularios en claude.ai/settings/plugins/submit o en la configuración de claude.ai
• Marketplace propio: crear un repositorio de GitHub y configurarlo como marketplace con /plugin marketplace add owner/repo

Antes de publicar, se recomienda versionar con versionado semántico, incluir documentación con un README.md, y que otros miembros del equipo prueben el plugin en sus entornos.