Plugins y marketplaces de Claude Code: cómo usarlos, crearlos y publicarlos

En Claude Code, un conjunto de skills, subagentes, hooks y configuración MCP constituye un plugin. Un catálogo que enumera los nombres de los plugins y dónde obtenerlos es un marketplace. Ambos permiten reutilizar procedimientos entre proyectos o compartir un conjunto de extensiones con el equipo.

Este artículo te guía desde instalar un plugin existente hasta crear una skill de saludo y distribuirla mediante un catálogo. Distingue tres cosas: (1) el plugin y su catálogo de distribución ocupan niveles distintos; (2) registrar un catálogo e instalar un plugin son operaciones separadas; (3) superar un comando de validación no garantiza el funcionamiento correcto ni la seguridad. Los pasos siguen la guía oficial de creación.

1. ¿Qué son los plugins de Claude Code?

Un plugin empaqueta extensiones de Claude Code en un directorio que puedes compartir y reutilizar. No necesita todos los componentes: puede contener una sola skill.

Para procedimientos que utilizas por tu cuenta, puede bastar el directorio .claude/skills/ del proyecto. Los plugins ayudan cuando quieres distribuir el mismo conjunto en varios lugares y gestionar sus actualizaciones. También existen extensiones como la compatibilidad LSP y la monitorización, con requisitos de entorno y vía de distribución. Es más sencillo empezar por una skill pequeña y verificarla.

2. Estructura de un plugin

Esta es la estructura estándar de un plugin individual. Si incluyes un manifiesto, va en .claude-plugin/plugin.json; skills/, agents/ y hooks/ pertenecen a la raíz del propio plugin. El catálogo de distribución, marketplace.json, es independiente. El ejemplo posterior lo coloca en .claude-plugin/marketplace.json del marketplace.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # metadatos de este plugin
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

Este es un ejemplo de plugin.json. Puedes omitir por completo el manifiesto si solo utilizas la estructura estándar de directorios. Si lo incluyes, name es obligatorio; la descripción y la versión son opcionales.

{
  "name": "my-first-plugin",
  "description": "Un plugin de saludo para aprender los fundamentos",
  "version": "1.0.0",
  "author": { "name": "Tu nombre" }
}

El name también define el espacio de nombres de la skill: en este ejemplo, invoca /my-first-plugin:hello. Para la distribución almacenada en caché mediante Git, tiene prioridad la versión de plugin.json, seguida de la versión del plugin en el catálogo. Si ninguna existe, se utiliza el SHA del commit resuelto del origen. Mantener una versión explícita sin cambios impide que una modificación del código por sí sola habilite la actualización del plugin. La carga directa desde un directorio local y los orígenes de tipo command siguen otras reglas. Consulta la documentación de gestión de versiones.

3. Usar /plugin y los marketplaces

Empieza con /plugin. Abre un gestor con las pestañas Discover, Installed, Marketplaces y Errors. Estos son los comandos básicos:

# Añadir un marketplace (catálogo de distribución)
/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add ./my-marketplace              # ruta local
/plugin marketplace add https://example.com/marketplace.json

# Elegir ámbito en la interfaz, instalar y comprobar si está habilitado
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# Instalados mediante marketplaces (filtrar con --enabled / --disabled)
/plugin list
/plugin list --enabled

# Recargar los cambios cuando sea necesario y comprobar el resultado
/reload-plugins

Añadir un catálogo no instala plugins por sí solo. Instálalos individualmente después de registrarlo. El comando interactivo /plugin install permite elegir el ámbito en la vista de detalles. El comando de shell claude plugin install usa user de forma predeterminada; indica --scope para cambiarlo.

Después de instalar, comprueba si el resultado indica activo, pendiente de recarga o error de carga. La recarga puede aplazarse por su efecto sobre la caché del prompt. En sesiones sin terminal, los cambios MCP de plugins pueden no surtir efecto hasta la siguiente sesión. /plugin list solo abarca instalaciones mediante marketplaces; no enumera todo lo recibido por sincronización o directorios de skills. Consulta las condiciones de instalación y recarga y, si MCP no conecta, la resolución de errores de conexión MCP.

4. ¿Qué es un marketplace?

Un marketplace es un catálogo con un .claude-plugin/marketplace.json que enumera plugins y sus orígenes, suministrado mediante un repositorio Git, una ruta local o un archivo alojado. Existen catálogos oficiales y comunitarios.

Si falta un catálogo, revisa su registro; si falta un plugin concreto, comprueba su nombre y origen. Con un catálogo interno, también importa que los usuarios puedan acceder tanto al repositorio como al propio plugin. Al distribuir un archivo JSON por URL, el contenido del plugin situado en rutas relativas no se obtiene desde esa URL.

5. Crear y publicar tu propio plugin

Este ejemplo crea una skill de saludo. Empieza con la siguiente estructura. El directorio .claude-plugin externo corresponde al catálogo; el interno, al plugin individual. Ejecuta los comandos desde el directorio padre que contiene my-marketplace.

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-first-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── hello/
                └── SKILL.md

(1) Guarda el JSON de la sección anterior en el archivo interno my-marketplace/plugins/my-first-plugin/.claude-plugin/plugin.json. (2) Guarda lo siguiente en my-marketplace/plugins/my-first-plugin/skills/hello/SKILL.md. El ejemplo utiliza disable-model-invocation: true para que la skill solo se use cuando se invoque explícitamente.

---
name: hello
description: Dar un saludo breve utilizando un nombre
disable-model-invocation: true
---
Saluda brevemente al usuario.
Si se proporcionan argumentos, incluye ese nombre en el saludo.
Argumentos: $ARGUMENTS

(3) Escribe el catálogo en el archivo externo my-marketplace/.claude-plugin/marketplace.json. Las rutas relativas de source se resuelven respecto a la raíz del marketplace, no al directorio que contiene marketplace.json.

{
  "name": "my-plugins",
  "owner": { "name": "Tu nombre" },
  "description": "Catálogo de práctica para distribuir una skill de saludo",
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "Una skill que da un saludo breve utilizando un nombre"
    }
  ]
}

(4) Valida el catálogo y el plugin por separado. El primero comprueba el esquema del catálogo y el plugin.json de las entradas locales, pero no lee cada archivo de skill o hook. El segundo también abarca los archivos de los directorios estándar del plugin individual. Ninguna de las dos comprobaciones garantiza la ejecución correcta ni la seguridad.

claude plugin validate ./my-marketplace
claude plugin validate ./my-marketplace/plugins/my-first-plugin

# Cargar el plugin individual en esta sesión para probarlo
claude --plugin-dir ./my-marketplace/plugins/my-first-plugin

En la sesión interactiva que se abre, ejecuta /my-first-plugin:hello Alex y comprueba que aparezca un saludo breve que incluya Alex. Una prueba funcional consiste en examinar la salida y buscar efectos secundarios no deseados, no solo confirmar que el comando sea visible. Si no se carga, revisa los nombres en ambos JSON, la ruta de origen y la ubicación y el frontmatter de SKILL.md.

(5) Para probar también la vía del catálogo, termina la sesión de prueba anterior e inicia Claude Code sin --plugin-dir. Los siguientes comandos registran entradas en tu configuración: pruébalos en un proyecto de práctica y elige el ámbito de instalación.

/plugin marketplace add ./my-marketplace
/plugin install my-first-plugin@my-plugins
/my-first-plugin:hello Alex

(6) Para distribuirlo, publica el contenido de my-marketplace como raíz de un repositorio Git que los usuarios puedan obtener. Incluye en el commit tanto el directorio plugins como el catálogo. Los usuarios añaden el owner/repo real e instalan el mismo my-first-plugin@my-plugins. Esta estructura con rutas relativas funciona al registrar mediante Git o un directorio local; no sirve sin modificaciones para una URL independiente de marketplace.json. Consulta cómo crear, distribuir y validar catálogos.

No necesitas solicitar aparecer en un catálogo oficial para distribuir mediante tu propio repositorio Git. Si también quieres aparecer en el comunitario, los autores individuales pueden usar el formulario de envío de Console. El formulario de claude.ai exige una organización Team/Enterprise y permisos administrativos. Enviar una propuesta a community es distinto de aparecer en el catálogo oficial seleccionado por Anthropic.

6. Ámbitos de instalación y seguridad

Los ámbitos de instalación son user (todos tus proyectos), project (ajustes compartidos del proyecto) y local (solo tú en este proyecto). Distingue la elección interactiva del ámbito de la opción predeterminada user de la CLI de shell. Los ajustes managed los controlan los administradores y restringen los cambios de configuración de los usuarios.

Los equipos pueden compartir orígenes y estado de habilitación mediante extraKnownMarketplaces y enabledPlugins en .claude/settings.json. Sin embargo, escribir ajustes compartidos no equivale a completar la instalación en el equipo de cada integrante. Cada miembro debe instalar los plugins de fuentes externas. Tras confiar en el proyecto, comprueba el registro del catálogo, los permisos de acceso y el resultado de la instalación en cada entorno.

Resumen

Un plugin es una unidad de distribución de extensiones; un marketplace es su catálogo. El usuario registra un catálogo → instala plugins individuales → comprueba su habilitación y comportamiento. El autor prepara el plugin y el catálogo → valida ambos → invoca la función → distribuye mediante un repositorio accesible. Comprobar ámbitos, permisos de acceso y la versión usada para actualizar facilita reproducir la configuración en otros entornos.

El registro automático del catálogo oficial tiene condiciones, y las propuestas revisadas no ofrecen una garantía incondicional de funcionamiento. Empieza por una función que necesites, verifica el resultado y amplía después. Otros mecanismos relacionados se explican en Hooks de Claude Code, Claude Agent Skills, MCP y Artifacts de Claude Code.

Preguntas frecuentes

P. ¿En qué se diferencia un plugin de una skill?
R. Una skill es un procedimiento que ejecutar; un plugin es una unidad de distribución que la agrupa con hooks, configuración MCP y otros componentes. Invoca explícitamente una skill del plugin con /plugin-name:skill-name. La selección automática depende de su descripción y configuración.

P. No encuentro el marketplace oficial.
R. El oficial, claude-plugins-official, se registra automáticamente en el primer inicio interactivo, pero el uso no interactivo previo, las restricciones de red o las políticas administradas pueden impedirlo. En un entorno donde esté permitido, prueba /plugin marketplace add anthropics/claude-plugins-official. Registrar el catálogo no instala los plugins individuales.

P. ¿Cualquiera puede distribuir un plugin que haya creado?
R. Una vía es colocar el plugin y el catálogo en un repositorio Git propio y accesible. Solicitar aparecer en community es otra operación; los autores individuales pueden usar el formulario de Console. La vía de claude.ai tiene requisitos de organización y permisos. Comprueba también que source del catálogo apunte a la ubicación real del plugin.

P. ¿Por qué no se actualiza mi plugin tras cambiar el código?
R. Para la distribución almacenada en caché mediante Git, tiene prioridad la versión de plugin.json. Cambiar solo la versión del catálogo, manteniendo aquella fija, no actualiza el plugin. Si ninguno proporciona una versión, se utiliza el SHA del commit Git resuelto, pero también importan las operaciones de actualización y la referencia de origen. La carga directa desde un directorio local, los orígenes de tipo archive y los de tipo command siguen otras reglas.

P. ¿Un plugin es seguro si validate termina correctamente?
R. No. Validar la estructura y la configuración es distinto de probar el comportamiento y la seguridad reales. Validar solo el catálogo no inspecciona el contenido de las skills ni archivos similares. Valida el plugin individual y prueba sus funciones y efectos secundarios. La revisión para aparecer en community tampoco sustituye la comprobación del editor y del código incluido.