Marketplaces: distribuir e instalar

Tienes un plugin que funciona. Un marketplace es el catálogo desde el que tu equipo lo instala y se mantiene actualizado. Aquí publicas el tuyo — el artefacto del curso: un plugin interno en tu propio marketplace.

El catálogo: .claude-plugin/marketplace.json

Un marketplace es un repo git con un marketplace.json que lista tus plugins y dónde están. En la raíz del repo, .claude-plugin/marketplace.json:

{
  "name": "acme-tools",
  "owner": { "name": "Equipo DevTools" },
  "plugins": [
    { "name": "dev-tools", "source": "./plugins/dev-tools" }
  ]
}

El source puede ser una ruta relativa (./plugins/dev-tools, monorepo de plugins), o un objeto apuntando a github, una url git, git-subdir o npm. Las rutas relativas resuelven desde la raíz del marketplace (donde está .claude-plugin/).

Publicarlo

Empuja el repo a GitHub/GitLab. Ya está vivo: para actualizarlo, haces push de los cambios y los usuarios refrescan con /plugin marketplace update.

Instalar desde él

Tu equipo añade el marketplace una vez y luego instala los plugins que quiera. Pero marketplace add acepta dos formatos distintos según dónde viva el catálogo — y mezclarlos es el error nº1:

Con un repo GitHub remoto:

/plugin marketplace add acme/acme-tools
/plugin install dev-tools@acme-tools

/plugin (sin más) abre el gestor con pestañas para navegar e instalar de forma interactiva: Discover (catálogo), Installed, Marketplaces y Errors.

Qué verás al instalar

En la pestaña Discover, al seleccionar un plugin con Enter, el panel de detalle te muestra qué añade antes de confirmar: comandos, agentes, skills, hooks y servidores MCP/LSP, más un coste estimado de contexto. Tras instalar, corre /reload-plugins para activarlo sin reiniciar: te imprime cuántas skills, agentes y hooks ha cargado. A partir de ahí las skills aparecen como /dev-tools:..., los subagentes en /agents, y los hooks empiezan a aplicarse.

Para probar en local antes de publicar, usa el formato ./ruta (o --plugin-dir ./dev-tools de la lección anterior). El marketplace es el paso de "me funciona a mí" a "lo instala el equipo".

Si falla

Esta es la parte que más se rompe. Casi todo se diagnostica desde la pestaña Errors de /plugin. Los fallos típicos y su causa real:

• marketplace add falla / "no encuentro el marketplace" → el repo necesita .claude-plugin/marketplace.json en la raíz. Si no está ahí (o el JSON tiene una coma de más), Claude no lo reconoce como marketplace. Valida con claude plugin validate . desde la raíz del repo antes de publicar.
• install no encuentra el plugin / "path not found" → el source de ese plugin apunta a una ruta que no existe. Recuerda: las rutas relativas resuelven desde la raíz del marketplace (donde está .claude-plugin/), no desde dentro de .claude-plugin/, y deben empezar por ./. Un source: "./plugins/dev-tools" busca <repo>/plugins/dev-tools.
• El equipo no ve tu última versión → publicar (push) no basta: cada uno tiene que correr /plugin marketplace update (o /plugin marketplace update acme-tools para uno solo) para refrescar su copia local. Además, si fijaste version en plugin.json, súbela en cada release: si no cambia el string, Claude considera que es la misma versión y no actualiza.
• Repo privado: errores de autenticación al instalar → Claude usa tus credenciales de git existentes. Verifica que estás autenticado (gh auth status para GitHub) y que puedes clonar el repo a mano. Para las auto-actualizaciones en arranque, exporta el token en el entorno (GITHUB_TOKEN/GH_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN).

Recuperarte de un error

Si te equivocaste de marketplace o quieres limpiar un plugin, hay comandos directos (también editables desde el gestor /plugin):

/plugin marketplace list                  # ver los marketplaces añadidos y sus fuentes
/plugin marketplace remove acme-tools      # quitar un marketplace (alias: rm)
/plugin uninstall dev-tools@acme-tools     # desinstalar un plugin
/plugin disable  dev-tools@acme-tools      # desactivarlo sin desinstalar
/plugin enable   dev-tools@acme-tools      # reactivarlo

Cuidado: quitar un marketplace desinstala todos los plugins que instalaste de él. Si solo quieres refrescar el catálogo sin perder nada, usa /plugin marketplace update, no remove. El nombre que pasas a remove/update es el name del marketplace.json, no la fuente (acme/acme-tools) que pasaste a add — lo ves con marketplace list.

Marketplace privado del equipo

Para algo interno, no hace falta nada público: aloja el marketplace.json en un repo privado de tu organización. Quien tenga acceso al repo puede añadirlo con /plugin marketplace add e instalar. Es la forma natural de distribuir tooling interno sin exponerlo.

(También existen marketplaces públicos de Anthropic —claude-plugins-official y claude-community— para descubrir e instalar plugins de terceros, pero el artefacto de este curso es el tuyo.)

Tu turno

Monta un marketplace mínimo con tu dev-tools: crea el repo, añade .claude-plugin/marketplace.json, mete el plugin, y pruébalo:

/plugin marketplace add ./mi-marketplace
/plugin install dev-tools@mi-marketplace

Aquí ./mi-marketplace es el formato local (la carpeta del repo en tu disco); cuando lo publiques en GitHub, el equipo usará el formato owner/repo. En install, el @mi-marketplace es el name que pusiste en marketplace.json, no la carpeta — si no coinciden, no lo encontrará.

Cuando instale y la skill responda con su namespace, tienes el artefacto del curso.

Qué llevas hasta aquí

• Un marketplace es un repo con .claude-plugin/marketplace.json en la raíz (name, owner, plugins[] con name+source).
• Se añade con /plugin marketplace add en dos modos: owner/repo (GitHub remoto) o ./ruta (local); se instala con /plugin install <plugin>@<marketplace>.
• Para recuperarte: marketplace list / marketplace remove y /plugin uninstall / disable. Refrescar es marketplace update (no remove).
• Para el equipo, un repo privado basta: tooling interno sin exponerlo.

En la última lección, mantenerlo en el tiempo: versionado y dependencias.

Fuente oficial: Create and distribute a plugin marketplace · Discover and install plugins