SpyBara
Go Premium

plugin-marketplaces.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 84 additions and 36 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Wed 23 23:57 Thu 24 22:57 Fri 25 23:58

Crear y distribuir un marketplace de plugins

Cree y aloje marketplaces de plugins para distribuir extensiones de Claude Code en equipos y comunidades.

Un marketplace de plugins es un catálogo que le permite distribuir plugins a otros. Los marketplaces proporcionan descubrimiento centralizado, seguimiento de versiones, actualizaciones automáticas y soporte para múltiples tipos de fuentes, incluyendo repositorios git y rutas locales. Esta guía le muestra cómo crear su propio marketplace para compartir plugins con su equipo o comunidad.

¿Busca instalar plugins desde un marketplace existente? Consulte Descubrir e instalar plugins precompilados.

Descripción general

Crear y distribuir un marketplace implica:

  1. Crear plugins: construya uno o más plugins con skills, agentes, hooks, servidores MCP o servidores LSP. Esta guía asume que ya tiene plugins para distribuir; consulte Crear plugins para obtener detalles sobre cómo crearlos.
  2. Crear el archivo de marketplace: defina un marketplace.json que enumere sus plugins y dónde encontrarlos. Consulte Crear el archivo de marketplace.
  3. Alojar el marketplace: envíe a GitHub, GitLab u otro host git. Consulte Alojar y distribuir marketplaces.
  4. Compartir con usuarios: los usuarios agregan su marketplace con /plugin marketplace add e instalan plugins individuales. Consulte Descubrir e instalar plugins.

Una vez que su marketplace esté activo, puede actualizarlo enviando cambios a su repositorio. Los usuarios actualizan su copia local con /plugin marketplace update.

Tutorial: crear un marketplace local

Este ejemplo crea un marketplace con un plugin: una skill quality-review para revisiones de código. Creará la estructura de directorios, agregará una skill, creará el manifiesto del plugin y el catálogo del marketplace, luego lo instalará y probará.

1

Crear la estructura de directorios

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review
2

Crear la skill

Cree un archivo SKILL.md que defina qué hace la skill quality-review.

---
description: Review code for bugs, security, and performance
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.
3

Crear el manifiesto del plugin

Cree un archivo plugin.json que describa el plugin. El manifiesto va en el directorio .claude-plugin/.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
4

Crear el archivo de marketplace

Cree el catálogo de marketplace que enumera su plugin.

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}
5

Agregar e instalar

Desde el directorio que contiene my-marketplace, inicie Claude Code y ejecute los siguientes comandos. El comando install abre una vista de detalles del plugin donde selecciona un alcance de instalación para confirmar la instalación. Verifique el resumen de instalación: si informa Run /reload-plugins to activate., consulte Aplicar cambios de plugin sin reiniciar.

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins
6

Pruébelo

Seleccione algo de código en su editor y ejecute su nueva skill. Las skills del plugin tienen un espacio de nombres con el nombre del plugin.

/quality-review-plugin:quality-review

Para obtener más información sobre lo que los plugins pueden hacer, incluidos hooks, agentes, servidores MCP y servidores LSP, consulte Plugins.

Crear el archivo de marketplace

Cree .claude-plugin/marketplace.json en la raíz de su repositorio. Este archivo define el nombre de su marketplace, información del propietario y una lista de plugins con sus fuentes.

Cada entrada de plugin necesita como mínimo un name y un source que le indique a Claude Code dónde obtenerlo. Consulte el esquema completo a continuación para todos los campos disponibles.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Esquema de marketplace

Campos requeridos

Campo Tipo Descripción Ejemplo
name string Identificador de marketplace en kebab-case, sin espacios, caracteres de control o caracteres de formato bidireccional. Esto es público: los usuarios lo ven al instalar plugins (por ejemplo, /plugin install my-tool@your-marketplace). Cada usuario puede registrar solo un marketplace por nombre: cuando agregan un segundo marketplace con el mismo nombre, Claude Code reemplaza el primero. Para publicar múltiples plugins bajo un nombre de marketplace, enumérelos todos en un único marketplace.json. "acme-tools"
owner object Información del mantenedor del marketplace. Consulte Campos del propietario
plugins array Lista de plugins disponibles Ver Entradas de plugins

Campos del propietario

Campo Tipo Requerido Descripción
name string Sí Nombre del mantenedor o equipo
email string No Correo electrónico de contacto del mantenedor
url string No Sitio web, perfil de GitHub u URL de organización

Campos opcionales

Campo Tipo Descripción
$schema string URL del esquema JSON para autocompletado y validación del editor. Claude Code ignora este campo al cargar.
description string Descripción breve del marketplace
version string Versión del manifiesto del marketplace
metadata.pluginRoot string Directorio que Claude Code resuelve bajo nombres de fuente de plugin sin ruta. Consulte Rutas relativas. Requiere Claude Code v2.1.239 o posterior.
allowCrossMarketplaceDependenciesOn array Otros marketplaces en los que los plugins en este marketplace pueden depender. Las dependencias de un marketplace no listado aquí se bloquean en la instalación. Consulte Depender de un plugin de otro marketplace.
renames object Mapa del anterior name de un plugin a su nombre actual, o a null si el plugin fue eliminado. Permite que los usuarios existentes migren automáticamente cuando cambia el nombre o elimina una entrada en plugins. Consulte Renombrar o eliminar un plugin. Requiere Claude Code v2.1.193 o posterior.

description y version también se aceptan bajo metadata para compatibilidad con versiones anteriores.

Entradas de plugins

Cada entrada de plugin en el array plugins describe un plugin y dónde encontrarlo. Puede incluir cualquier campo del esquema de manifiesto de plugin, como description, version, author, commands y hooks, más estos campos específicos del marketplace: source, category, tags, strict, relevance, headers y headersHelper.

Campos requeridos

Campo Tipo Descripción
name string Identificador de plugin en kebab-case, sin espacios, caracteres de control ni caracteres de formato bidireccional. Esto es público: los usuarios lo ven al instalar (por ejemplo, /plugin install my-plugin@marketplace).
source string|object Dónde obtener el plugin (consulte Fuentes de plugins a continuación)

Campos de plugin opcionales

Campos de metadatos estándar:

Campo Tipo Descripción
displayName string Nombre legible mostrado en superficies de interfaz de usuario. Cuando ni la entrada ni el plugin.json del plugin establece uno, los usuarios ven el name del plugin. Puede contener espacios y cualquier capitalización. No se utiliza para espacios de nombres o búsqueda.
description string Descripción breve del plugin
version string Versión del plugin. Si se establece (aquí o en plugin.json), el plugin se fija a esta cadena y los usuarios solo reciben actualizaciones cuando cambia. Un plugin con una fuente command no se fija por ninguno de los campos. Tampoco un plugin cargado en su lugar desde un marketplace agregado como directorio local. Si no se establece en ningún lugar, la versión proviene de la siguiente fuente en gestión de versiones.
author object Información del autor del plugin (name requerido; email y url opcionales)
homepage string URL de página de inicio o documentación del plugin
repository string URL del repositorio de código fuente
license string Identificador de licencia SPDX (por ejemplo, MIT, Apache-2.0)
keywords array Etiquetas para descubrimiento y categorización de plugins
metadata object Objeto de forma libre para sus propios campos, como datos de derechos o catálogo. Claude Code no lo lee. Antes de v2.1.222, claude plugin validate reportaba la clave como un campo no reconocido.
category string Categoría del plugin para organización
tags array Etiquetas para búsqueda
strict boolean Controla si plugin.json es la autoridad para definiciones de componentes (predeterminado: true). Consulte Modo estricto a continuación.
relevance object Señales que indican a Claude Code cuándo sugerir este plugin a los usuarios. Solo tiene efecto para marketplaces que un administrador incluye en la lista de permitidos en la configuración administrada. Consulte Recomendar plugins para su organización.
defaultEnabled boolean Si el plugin está habilitado después de la instalación (predeterminado: true). Establezca en false para instalar el plugin deshabilitado hasta que el usuario opte por participar. Tiene prioridad sobre el mismo campo en el plugin.json del plugin. Consulte Habilitación predeterminada.

Tanto la entrada como el plugin.json del plugin pueden establecer los campos de visualización displayName, description, author, homepage, repository, license y keywords. En listados y detalles de plugins, antes y después de la instalación:

  • Para un campo que establece en la entrada, los usuarios ven el valor de la entrada, incluso cuando plugin.json establece uno diferente.
  • Para un campo que la entrada deja sin establecer, los usuarios ven el valor de plugin.json.

Antes de la instalación, Claude Code solo puede leer plugin.json para entradas con una fuente de ruta relativa, cuyos archivos de plugin viven dentro del marketplace. Para una entrada con cualquier otro tipo de fuente, los usuarios ven solo los campos de la entrada hasta que instalen el plugin.

Campos de configuración de componentes:

Campo Tipo Descripción
skills string|array Rutas personalizadas a directorios de skills que contienen <name>/SKILL.md
commands string|array Rutas personalizadas a archivos de skills planos o directorios
agents string|array Rutas personalizadas a archivos de agentes
hooks string|object Configuración de hooks personalizada o ruta a archivo de hooks
mcpServers string|object Configuraciones de servidor MCP o ruta a configuración de MCP
lspServers string|object Configuraciones de servidor LSP o ruta a configuración de LSP

Campos de autenticación de archivo:

Establezca estos cuando la entrada tenga una fuente archive en un servidor que requiera credenciales.

Campo Tipo Descripción
headers object Encabezados HTTP que Claude Code envía cuando descarga el archivo de esta entrada. Anula los encabezados del marketplace con el mismo nombre. Requiere Claude Code v2.1.238 o posterior.
headersHelper string Comando que imprime los encabezados HTTP para la descarga del archivo de esta entrada como un objeto JSON, para una credencial que expira. Consulte Autenticar descargas de archivo. La entrada también debe establecer "strict": false. Requiere Claude Code v2.1.238 o posterior.

Fuentes de plugins

Las fuentes de plugins le indican a Claude Code dónde obtener cada plugin individual listado en su marketplace. Estos se establecen en el campo source de cada entrada de plugin en marketplace.json.

Claude Code copia cada plugin instalado en el caché de plugins versionado local en ~/.claude/plugins/cache, a menos que el plugin se cargue en su lugar. Una fuente command en modo link se carga en su lugar, y también lo hace una fuente de ruta relativa en un marketplace agregado desde un directorio local. Claude Code también instala las dependencias de paquetes Node.js elegibles del plugin en la copia en caché. Consulte Plugin caching and file resolution para ver cómo un plugin cargado en su lugar desde un marketplace de directorio local recoge sus ediciones.

Fuente Tipo Campos Notas
Ruta relativa string (p. ej. "./my-plugin") ninguno Directorio local dentro del repositorio de marketplace. Debe comenzar con ./, a menos que escriba un nombre simple bajo metadata.pluginRoot. Claude Code resuelve la ruta relativa a la raíz del marketplace, no al directorio .claude-plugin/
github object repo, ref?, sha?
url object url, ref?, sha? Fuente de URL de Git
git-subdir object url, path, ref?, sha? Subdirectorio dentro de un repositorio git. Clona escasamente para minimizar el ancho de banda para monorepos
npm object package, version?, registry? Paquete npm, obtenido con su cliente npm y desempaquetado sin ejecutar scripts de instalación
archive object url, sha256? Archivo zip descargado sobre HTTPS. Funciona sin git o npm en la máquina del usuario. Requiere Claude Code v2.1.224 o posterior
command object command, timeout?, mode? Directorio de plugin producido al ejecutar un comando local, se vuelve a ejecutar una vez por sesión para recoger cambios. Requiere Claude Code v2.1.229 o posterior

Los tipos de fuente basados en git que se muestran a continuación son github, url y git-subdir. Cuando tanto ref como sha se establecen en cualquiera de ellos, sha es el pin efectivo. Claude Code obtiene y verifica el commit fijado directamente.

En la mayoría de los hosts de git, incluidos GitHub, GitLab y Bitbucket, esto significa que la instalación tiene éxito incluso si la rama o etiqueta nombrada por ref ha sido eliminada posteriormente, siempre que el commit aún sea alcanzable desde el repositorio. Algunos servidores, como AWS CodeCommit, no soportan la obtención de commits por SHA. En esos servidores, ref aún debe existir y el commit fijado debe ser alcanzable desde él.

Si distribuye plugins a través de Configuración de organización > Plugins, solo se permiten algunos tipos de fuente. Consulte Distribuir a través de la configuración de organización.

Rutas relativas

Para plugins en el mismo repositorio, use una ruta que comience con ./:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Las rutas se resuelven relativas a la raíz del marketplace, que es el directorio que contiene .claude-plugin/. La fuente ./plugins/my-plugin por lo tanto apunta a <repo>/plugins/my-plugin, aunque marketplace.json vive en <repo>/.claude-plugin/marketplace.json. No use ../ para hacer referencia a rutas fuera de la raíz del marketplace. En macOS y Linux, Claude Code rechaza una ruta de entrada con una barra invertida en cualquier lugar después del ./ inicial, así que escriba los separadores como / en todas las plataformas.

Un nombre simple es un nombre de directorio único sin /, como "formatter". Para escribir nombres simples en lugar de rutas ./, establezca metadata.pluginRoot en el directorio bajo el cual se resuelven. Con "pluginRoot": "./plugins", Claude Code resuelve "source": "formatter" a ./plugins/formatter. Requiere Claude Code v2.1.239 o posterior.

metadata.pluginRoot debe ser en sí mismo una ruta relativa dentro del marketplace. Claude Code lo ignora para una fuente que ya comienza con ./. Una fuente que contiene un /, como team-a/formatter, no es un nombre simple y aún necesita el prefijo ./, incluso cuando metadata.pluginRoot está establecido.

Repositorios de GitHub 

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Puede fijar a una rama, etiqueta o commit específico:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
Campo Tipo Descripción
repo string Requerido. Repositorio de GitHub en formato owner/repo
ref string Opcional. Rama o etiqueta de Git (por defecto es la rama predeterminada del repositorio)
sha string Opcional. SHA de commit de git completo de 40 caracteres para fijar a una versión exacta

Repositorios de Git 

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Puede fijar a una rama, etiqueta o commit específico:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
Campo Tipo Descripción
url string Requerido. URL completa del repositorio de git (https:// o git@). El sufijo .git es opcional, por lo que las URLs de Azure DevOps y AWS CodeCommit sin el sufijo funcionan
ref string Opcional. Rama o etiqueta de Git (por defecto es la rama predeterminada del repositorio)
sha string Opcional. SHA de commit de git completo de 40 caracteres para fijar a una versión exacta

Subdirectorios de Git

Use git-subdir para apuntar a un plugin que vive dentro de un subdirectorio de un repositorio de git. Claude Code usa un clon parcial y escaso para obtener solo el subdirectorio, minimizando el ancho de banda para monorepos grandes.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

Puede fijar a una rama, etiqueta o commit específico:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

El campo url también acepta una abreviatura de GitHub (owner/repo) o URLs SSH (git@github.com:owner/repo.git).

Campo Tipo Descripción
url string Requerido. URL del repositorio de Git, abreviatura de GitHub owner/repo o URL SSH
path string Requerido. Ruta del subdirectorio dentro del repositorio que contiene el plugin (por ejemplo, "tools/claude-plugin")
ref string Opcional. Rama o etiqueta de Git (por defecto es la rama predeterminada del repositorio)
sha string Opcional. SHA de commit de git completo de 40 caracteres para fijar a una versión exacta

Paquetes npm

Una fuente npm puede nombrar cualquier paquete en el registro npm público o en un registro privado que su equipo aloje. Claude Code resuelve el paquete con su cliente npm, descarga el tarball y lo desempaqueta en el caché de plugins.

Los scripts de instalación del paquete, como preinstall o postinstall, nunca se ejecutan, y sus dependencias no se instalan durante la obtención.

Si el paquete envía un archivo de bloqueo compatible junto a su package.json, Claude Code instala esas dependencias de paquetes Node.js en un paso separado, también con scripts deshabilitados. De lo contrario, publique el plugin con todo lo que necesita ya construido. Un servidor MCP que necesita otros paquetes puede lanzarse a través de npx, que los instala en la primera ejecución.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Para fijar a una versión específica, agregue el campo version:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

Para instalar desde un registro privado o interno, agregue el campo registry:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}
Campo Tipo Descripción
package string Requerido. Nombre del paquete o paquete con alcance (por ejemplo, @org/plugin)
version string Opcional. Versión o rango de versión (por ejemplo, 2.1.0, ^2.0.0, ~1.5.0)
registry string Opcional. URL de registro npm personalizado. Por defecto es el registro npm del sistema (típicamente npmjs.org)

Archivos zip

Use archive para distribuir un plugin como un archivo zip que Claude Code descarga sobre HTTPS, para que las instalaciones funcionen sin git o npm en la máquina del usuario. Aloje el archivo en cualquier servidor de archivos estático o repositorio de artefactos, como un bucket de S3, un repositorio genérico de Artifactory o nginx. Requiere Claude Code v2.1.224 o posterior. En las versiones v2.1.120 a v2.1.223, la instalación del plugin falla con This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.; en versiones más antiguas, un marketplace que contiene una entrada archive falla al cargar completamente.

Esta entrada instala el plugin desde un archivo zip en un servidor de artefactos:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

Cuando construye el zip, puede comprimir el contenido del plugin directamente o comprimir la carpeta del plugin en sí. Claude Code busca .claude-plugin/ en la parte superior del archivo, luego dentro de una única carpeta de nivel superior, por lo que ambos diseños se instalan:

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

Claude Code no busca más profundo que una carpeta, por lo que un plugin anidado más abajo falla al instalar. Claude Code rechaza archivos más grandes que 256 MiB.

Para fijar el archivo exacto, agregue un campo sha256 con el resumen del archivo:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Si el archivo descargado no coincide con el pin, Claude Code rechaza la instalación e informa Plugin archive integrity check failed.

Las fuentes de archivo aceptan estos campos:

Campo Tipo Descripción
url string Requerido. URL HTTPS del archivo zip. Claude Code rechaza URLs http://, junto con hosts de loopback, link-local y cloud-metadata. Cada salto de redirección debe satisfacer las mismas reglas, o Claude Code rechaza la descarga
sha256 string Opcional. Resumen SHA-256 del archivo como 64 caracteres hexadecimales, mayúsculas o minúsculas. Claude Code verifica cada descarga contra él y rechaza la instalación en caso de discrepancia

El resumen sha256 también sirve como la versión del plugin cuando ni plugin.json ni la entrada del marketplace declaran una. Consulte Gestión de versiones. Si declara una version, esa cadena de versión es la señal de actualización, por lo que después de cambiar el zip y su resumen, también aumente la versión, o los usuarios mantienen la copia en caché.

Autenticar descargas de archivos

Para autenticar una descarga de archivo, como una descarga de un registro privado, establezca los encabezados HTTP que Claude Code envía con ella. Establezca headers en la fuente url desde la que registró el marketplace, como una entrada extraKnownMarketplaces. En Claude Code v2.1.238 o posterior, puede establecerlo en la entrada del plugin en su lugar, junto a source.

Si el valor que pondría en headers es de corta duración, como un token que su registro acuña bajo demanda, establezca un comando headersHelper en el mismo lugar en su lugar. Claude Code ejecuta el comando y envía el objeto JSON que imprime como los encabezados de ese lugar. Requiere Claude Code v2.1.238 o posterior.

El lugar que elija decide qué descargas obtienen los encabezados y cuándo Claude Code ejecuta el comando:

Lugar Descargas que obtienen los encabezados Cuándo Claude Code ejecuta un headersHelper establecido allí
Fuente url del marketplace Descargas de archivo en el origen de la URL del marketplace, lo que significa el mismo esquema, host y puerto Antes de cada obtención del marketplace.json del marketplace y antes de cada descarga de archivo en ese origen. Claude Code reutiliza la salida de una ejecución durante hasta 60 segundos
Entrada de plugin Solo la descarga de esa entrada Solo cuando un usuario instala o actualiza ese único plugin por sí solo y acepta el comando

Donde ambos lugares establecen un encabezado del mismo nombre, Claude Code envía el valor de la entrada. Dentro de un lugar, un encabezado que el comando imprime anula un encabezado del mismo nombre listado en headers.

Agregar un headersHelper a una entrada de plugin

Esta entrada establece headersHelper junto a source. También establece "strict": false, que Claude Code requiere de una entrada marketplace.json que establezca headersHelper. Con "strict": false, la entrada del marketplace es la definición completa del plugin, por lo que un usuario puede revisar qué contiene el plugin antes de aceptar el comando:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

Para verificar la entrada, ejecute claude plugin install my-plugin@your-marketplace. Claude Code le muestra el comando y la URL del archivo, y descarga el zip después de que acepte.

Antes de v2.1.238, Claude Code descargaba el archivo de una entrada sin sus headers o headersHelper, por lo que una instalación que dependía de ellos fallaba con HTTP 401 while downloading plugin archive from, seguido de la URL, con el código de estado del registro en lugar de 401.

Escribir el comando headersHelper

Ya sea que establezca headersHelper en una fuente url del marketplace o en una entrada de plugin, escriba el comando para cumplir con estos requisitos:

  • Texto del comando: como máximo 500 caracteres de ASCII imprimible, sin una ejecución de cuatro o más espacios.
  • Salida: imprima un objeto JSON de nombres de encabezados y valores de cadena en stdout, luego salga 0 dentro de 10 segundos.
  • Shell y directorio de trabajo: Claude Code ejecuta el comando a través de sh, o cmd.exe en Windows, desde el directorio de configuración, ~/.claude o CLAUDE_CONFIG_DIR. Proporcione una ruta absoluta o un comando en PATH, porque una ruta relativa se resuelve contra ese directorio, no el proyecto del usuario.
  • Variables que Claude Code elimina: del entorno de un comando establecido en una entrada marketplace.json o en .claude/settings.json o .claude/settings.local.json de un proyecto, Claude Code elimina cada variable cuyo nombre contiene una palabra como TOKEN, SECRET, KEY o AUTH, incluida ANTHROPIC_API_KEY. Claude Code no aplica esta eliminación a un comando establecido en la configuración del usuario, un archivo --settings o configuración administrada.
  • Variables que Claude Code establece: CLAUDE_CODE_MARKETPLACE_URL y CLAUDE_CODE_MARKETPLACE_NAME para el comando de una fuente url, y CLAUDE_CODE_PLUGIN_NAME y CLAUDE_CODE_PLUGIN_ARCHIVE_URL para el comando de una entrada. CLAUDE_CODE_MARKETPLACE_NAME no está establecido en la primera obtención después de que un usuario agregue un marketplace por URL, porque esa obtención es lo que proporciona el nombre.

Un comando que acuña un token de portador imprime un objeto como este:

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

Cuándo Claude Code omite un comando headersHelper o descarta su salida

Claude Code no ejecuta un comando headersHelper, o descarta encabezados que vinieron de headers o de la salida del comando, en estas situaciones:

  • El comando falla: si el comando sale con código distinto de cero, se ejecuta más de 10 segundos, o imprime algo que no sea un objeto JSON de valores de cadena, Claude Code no realiza la obtención o descarga para la que ejecutó el comando.
  • La URL del marketplace no comienza con https://: Claude Code no ejecuta el comando de esa fuente url y envía solo los encabezados listados en su campo headers.
  • La redirección deja el origen: cuando una descarga se redirige fuera del origen de la URL del archivo, Claude Code descarta los valores de headers y la salida del comando tanto de la fuente url del marketplace como de la entrada del plugin.
  • La entrada establece un encabezado de enrutamiento o identidad: Claude Code descarta nombres de enrutamiento de solicitud e identidad de cliente como Host, Cookie y X-Forwarded-* de los headers de una entrada y la salida del comando, y mantiene nombres de autenticación como Authorization. Claude Code filtra cada entrada marketplace.json de esta manera, y una entrada de configuración en línea dependiendo de qué archivo la declare.
  • El comando se establece en la configuración de un directorio --add-dir: Claude Code lo ignora, en una fuente url y en una entrada de plugin en línea por igual, y envía solo los headers de ese archivo.
  • La configuración administrada bloquea el comando: establecer disableCommandPluginSources en true bloquea comandos headersHelper, y allowManagedHooksOnly también los bloquea a menos que disableCommandPluginSources sea explícitamente false. Bajo cualquiera de estos bloqueos, Claude Code aún ejecuta el comando para un marketplace que la configuración administrada declara por sí misma.

Cómo los usuarios aceptan un comando headersHelper

Un usuario acepta el comando de una entrada de plugin cada vez que instala o actualiza ese único plugin por sí solo, desde la vista propia del plugin en /plugin o con claude plugin install o claude plugin update. Claude Code muestra el comando y la URL del archivo, y ejecuta el comando solo después de que el usuario acepta.

En un shell no interactivo, pase --yes para aceptar el comando que imprime. Para aceptar solo el comando que una ejecución anterior de --json mostró, pase --accept-command con el sha256 que la ejecución reportó.

Claude Code ejecuta solo el comando que mostró, para la URL del archivo que mostró. Si el comando o la URL del archivo de la entrada cambiaron en el medio, Claude Code rechaza la instalación o actualización. Un cambio solo en la cadena de consulta no cuenta.

Instalaciones y actualizaciones que rechazan el comando en lugar de preguntar

En cualquier operación que no sea una instalación o actualización de un único plugin, Claude Code ni ejecuta el comando de una entrada ni descarga su archivo, por lo que el plugin permanece en su versión instalada o permanece desinstalado. Lo que el usuario ve depende de la operación:

  • Instalar varios plugins a la vez, desde una sugerencia de plugin, o como dependencia de otro plugin: Claude Code rechaza el plugin que tiene el comando y señala al usuario la vista propia de ese plugin en /plugin. Los otros plugins en una instalación masiva aún se instalan. Un plugin que depende del plugin rechazado falla al instalar hasta que el usuario instale el plugin rechazado por sí solo.
  • Actualización automática en segundo plano, o inicio de sesión para un plugin cuyo archivo nunca fue descargado: Claude Code enumera el plugin en la pestaña /plugin Errores para que el usuario sepa instalarlo o actualizarlo manualmente. Una actualización automática que encuentra la entrada aún anuncia la versión instalada sin listar nada.
Cuándo se ejecuta el comando headersHelper de una fuente `url` del marketplace

Un headersHelper de fuente url del marketplace se declara en un archivo de configuración, como una entrada extraKnownMarketplaces, en lugar de en el catálogo que publica el marketplace, por lo que Claude Code no le pide al usuario que lo acepte en cada instalación o actualización. El archivo de configuración que lo declara decide cuándo Claude Code lo ejecuta:

Archivo de configuración Cuándo Claude Code ejecuta el comando
Configuración del usuario, un archivo --settings o un archivo de configuración administrada en la máquina Sin preguntar, incluida durante una actualización de marketplace en segundo plano
.claude/settings.json o .claude/settings.local.json de un proyecto Solo después de que el usuario acepte el diálogo de confianza del espacio de trabajo para esa carpeta en sí. Una sesión -p o SDK no cuenta como aceptarlo, ni tampoco la confianza otorgada a una carpeta padre
Configuración administrada por servidor Solo después de que el usuario apruebe la configuración entregada en el diálogo de aprobación de seguridad

En una sesión -p o SDK, Claude Code no puede mostrar el diálogo de aprobación de seguridad. Aplica la otra configuración entregada, pero la obtención del marketplace, y cualquier descarga de archivo que necesite el comando, falla hasta que un usuario haya aprobado en una sesión interactiva.

Para una entrada de plugin en línea en uno de estos archivos, Claude Code requiere la misma confianza de carpeta o aprobación de configuración que para un comando a nivel de marketplace en ese archivo, y el usuario también acepta el comando de la entrada en cada instalación o actualización.

Fuentes de comando

Use command cuando una herramienta instalada localmente produce el directorio del plugin, como un IDE que renderiza su plugin para la cadena de herramientas seleccionada actualmente. Claude Code ejecuta el comando cuando el usuario instala el plugin y lo vuelve a ejecutar en segundo plano una vez por sesión, por lo que sus usuarios recogen la salida cambiada de la herramienta sin reinstalar. Requiere Claude Code v2.1.229 o posterior. En v2.1.120 a v2.1.228, la instalación del plugin falla con This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again., y en versiones más antiguas el marketplace completo falla al cargar.

Esta entrada instala el plugin desde cualquier directorio que la herramienta imprime:

{
  "name": "my-plugin",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path"
  }
}

Claude Code ejecuta el comando a través del shell de la plataforma, sh en macOS y Linux o cmd.exe en Windows, desde el directorio de inicio del usuario. El comando debe imprimir exactamente una línea en stdout y salir con código 0. Esa línea es la ruta absoluta de un directorio que contiene el plugin completo en el momento en que el comando sale, y la ruta puede cambiar entre ejecuciones.

Claude Code detiene un comando que se ejecuta más de timeout segundos, y la instalación o actualización falla. Claude Code también rechaza la ruta impresa en estos casos, y la instalación o actualización falla de la misma manera:

  • El directorio no tiene contenido de plugin en su nivel superior, como un directorio .claude-plugin/ o un directorio skills/, commands/, agents/ o hooks/
  • El directorio es el en el que Claude Code fue iniciado, o uno de sus padres
  • En Windows, la ruta es una ruta UNC

Las fuentes de comando aceptan estos campos:

Campo Tipo Descripción
command string Requerido. Comando shell que imprime la ruta absoluta del directorio del plugin como una única línea en stdout y sale 0. Debe ser ASCII imprimible, como máximo 500 caracteres, sin ejecuciones de cuatro o más espacios, para que los usuarios puedan revisar el comando completo que se les pide que acepten
timeout number Opcional. Número entero de segundos para esperar el comando antes de rendirse (predeterminado: 60, máximo: 600)
mode string Opcional. "copy" (predeterminado) copia el directorio impreso en el caché de plugins. "link" usa el directorio impreso en su lugar. Consulte Modo de copia y modo de enlace

Con el "mode": "copy" predeterminado, Claude Code copia el directorio impreso en el caché de plugins versionado y deriva la versión del plugin de un hash del contenido del directorio. Su herramienta puede eliminar o reescribir el directorio después de que el comando sale, y una re-ejecución que produce contenido idéntico cuenta como actualizado. Claude Code rechaza instalar un directorio más grande que 256 MiB o que contenga más de 20,000 entradas.

Establezca "mode": "link" para directorios de plugins grandes que no deben copiarse, como una exportación de SDK renderizada. Claude Code llena la entrada de caché del plugin con un enlace a cada entrada de nivel superior del directorio impreso y usa los archivos en su lugar, por lo que nada se copia, los contenidos de los archivos no se codifican, y los límites de tamaño no se aplican. La instalación falla si una entrada de nivel superior es un enlace simbólico que apunta fuera del directorio impreso. Claude Code también omite la instalación de dependencias de paquetes Node.js para un plugin en modo de enlace, por lo que imprima un directorio que ya contenga cualquier node_modules que el plugin necesite.

Mantenga el directorio impreso en su lugar mientras el plugin permanezca instalado, porque Claude Code carga el plugin a través de esos enlaces en cada inicio. Claude Code deriva la versión del plugin de la ruta real del directorio impreso y sus entradas de nivel superior, no los archivos dentro, por lo que imprima una ruta diferente para señalar contenido nuevo. En una sesión iniciada en el directorio impreso o en cualquier lugar debajo de él, Claude Code no carga el plugin en absoluto.

Claude Code no soporta modo de enlace en Windows y rechaza instalar un plugin en modo de enlace allí. Declare "mode": "copy" en su lugar.

Cómo los usuarios aceptan el comando

Claude Code ejecuta su comando en la máquina del usuario, por lo que vincula cada ejecución a la aceptación explícita del usuario:

  • Cuando los usuarios instalan el plugin desde su pantalla de detalles en /plugin, o lo instalan o actualizan con claude plugin install o claude plugin update en un terminal interactivo, Claude Code les muestra la cadena de comando exacta primero y registra el comando aceptado para esa instalación. Una claude plugin update que puede proceder en la aceptación registrada del mismo comando no muestra nada.
  • En un shell no interactivo, como un script de aprovisionamiento, pase --yes a claude plugin install o claude plugin update para aceptar el comando que imprime. Para aceptar solo el comando que una ejecución anterior de --json mostró, pase --accept-command con el sha256 que la ejecución reportó.
  • Cada otra ruta ejecuta solo el comando que el usuario ya aceptó. Esto incluye actualizaciones iniciadas desde /plugin y las ejecuciones en segundo plano descritas en Cuándo Claude Code vuelve a ejecutar el comando. Cuando ninguno fue aceptado, Claude Code rechaza ejecutar el comando y le dice al usuario cómo revisarlo. Claude Code nunca instala un plugin de origen de comando como dependencia de otro plugin, por lo que los usuarios lo instalan por sí solos primero.
  • Si cambia el command de la entrada, o cambia su mode, los usuarios mantienen la versión que ya tienen y Claude Code deja de volver a ejecutar el comando. En sesiones interactivas, la pestaña /plugin Errores muestra el nuevo comando hasta que el usuario lo revise y acepte ejecutando claude plugin update <plugin>@<marketplace>.

Los administradores pueden bloquear fuentes de comando en toda una organización con la configuración administrada disableCommandPluginSources. Si una organización establece allowManagedHooksOnly, Claude Code bloquea fuentes de comando de forma predeterminada.

Cuándo Claude Code vuelve a ejecutar el comando

El directorio impreso refleja el estado de la herramienta en el momento en que se ejecutó el comando, por lo que Claude Code ejecuta el comando nuevamente en estos momentos:

  • Cada vez que el usuario instala o actualiza el plugin
  • Una vez por sesión para cada plugin de origen de comando habilitado, en segundo plano, poco después de que la sesión comience. Esta ejecución no pasa por la actualización automática del marketplace, por lo que no depende de la configuración de actualización automática del marketplace
  • Al inicio o en /reload-plugins, cuando la versión instalada de un plugin habilitado falta en el caché de plugins

Claude Code omite las dos ejecuciones en segundo plano cuando el usuario establece CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Las instalaciones y actualizaciones explícitas aún ejecutan el comando con esa variable establecida.

Cuando la salida codificada del comando ha cambiado, Claude Code instala el resultado como una nueva versión y lo recarga en la sesión interactiva en ejecución, cambiando los mismos componentes que /reload-plugins cambia. El usuario ve una notificación de que el plugin fue recargado. Si recargar en su lugar invalidaría el caché de solicitud de la sesión, Claude Code en su lugar le pide al usuario que ejecute /reload-plugins, que advierte sobre el costo del caché y se aplica cuando se vuelve a ejecutar con --force.

Entradas de plugins avanzadas

Este ejemplo muestra una entrada de plugin usando muchos de los campos opcionales, incluidas rutas personalizadas para commands, agents, hooks y MCP servers:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Cosas clave a notar:

  • commands y agents: puede especificar múltiples directorios o archivos individuales. Las rutas son relativas a la raíz del plugin y deben permanecer dentro de ella.
    • Claude Code rechaza una ruta que se resuelve fuera del directorio del plugin, como ./../shared.md, con un error path escapes plugin directory, y aún carga el plugin sin ese componente
  • ${CLAUDE_PLUGIN_ROOT}: use esta variable en comandos de hooks y configuraciones de MCP server para hacer referencia a archivos dentro del directorio de instalación del plugin.
    • Consulte la tabla de sustitución para ver qué campos de configuración la sustituyen por tipo de servidor
    • Para dependencias o estado que deben sobrevivir a las actualizaciones de plugins, use ${CLAUDE_PLUGIN_DATA} en su lugar
  • strict: false: dado que esto se establece en false, el plugin no necesita su propio plugin.json. La entrada del marketplace define todo. Consulte Modo estricto a continuación.

Por defecto, las skills de un plugin se cargan desde el directorio skills/ bajo su source. Las rutas listadas en el campo skills se agregan a ese escaneo:

"skills": ["./skills/", "./extra-skills/"]

Cuando varias entradas de plugin comparten una carpeta skills/ en la raíz del marketplace (source: "./"), liste subdirectorios específicos en su lugar para que cada entrada cargue solo sus propias skills:

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

Con una fuente de raíz de marketplace, las rutas listadas son el conjunto completo para esa entrada, y otros directorios en la carpeta skills/ compartida no se cargan. Listar ./skills/ en sí, o la raíz del plugin, mantiene el escaneo completo. Si ninguna de las rutas listadas existe, se ejecuta el escaneo predeterminado en su lugar.

Modo estricto

El campo strict controla si plugin.json es la autoridad para definiciones de componentes (skills, agents, hooks, MCP servers, estilos de salida).

Valor Comportamiento
true (predeterminado) plugin.json es la autoridad. La entrada del marketplace puede complementarla con componentes adicionales, y ambas fuentes se fusionan.
false La entrada del marketplace es la definición completa. Si el plugin también tiene un plugin.json que declara componentes, eso es un conflicto y el plugin falla al cargar.

Cuándo usar cada modo:

  • strict: true: el plugin tiene su propio plugin.json y gestiona sus propios componentes. La entrada del marketplace puede agregar skills o hooks adicionales encima. Este es el predeterminado y funciona para la mayoría de los plugins.
  • strict: false: el operador del marketplace quiere control total. El repositorio del plugin proporciona archivos sin procesar, y la entrada del marketplace define cuáles de esos archivos se exponen como skills, agents, hooks, etc. Útil cuando el marketplace reestructura o cura los componentes de un plugin de manera diferente a la que el autor del plugin pretendía.

Alojar y distribuir marketplaces

Cuando los usuarios agregan un marketplace alojado en un repositorio de git, o instalan un plugin basado en git que enumera, Claude Code clona ese repositorio de marketplace o plugin en su máquina. El clon nunca descarga contenido de Git LFS, por lo que los archivos rastreados por LFS llegan como archivos de puntero. Mantenga los archivos que sus plugins necesitan fuera de LFS.

GitHub es la forma recomendada para alojar y distribuir un marketplace:

  1. Crear un repositorio: configure un nuevo repositorio para su marketplace
  2. Agregar archivo de marketplace: cree .claude-plugin/marketplace.json con sus definiciones de plugins
  3. Compartir con equipos: los usuarios agregan su marketplace con /plugin marketplace add owner/repo

Beneficios: control de versiones integrado, seguimiento de problemas y características de colaboración en equipo.

Alojar en otros servicios de git

Cualquier servicio de alojamiento de git funciona, como GitLab, Bitbucket y servidores autohospedados. Los usuarios agregan con la URL completa del repositorio:

/plugin marketplace add https://gitlab.com/company/plugins.git

Repositorios privados

Claude Code soporta instalar plugins desde repositorios privados. Si distribuye su marketplace a través de Configuración de la organización > Plugins en su lugar, sus credenciales de git no están involucradas: la sincronización de la organización lee el repositorio del marketplace a través de la conexión GitHub o GitLab de su organización en claude.ai. Consulte Distribuir a través de la configuración de la organización para saber qué fuentes de plugins pueden ser privadas.

Comandos que ejecuta

Cuando ejecuta /plugin marketplace add, /plugin install, /plugin update o /plugin marketplace update, Claude Code usa sus ayudantes de credenciales de git existentes, por lo que el acceso HTTPS a través de gh auth login, Keychain de macOS o git-credential-store funciona igual que en su terminal. El acceso SSH funciona siempre que el host ya esté en su archivo known_hosts y la clave esté cargada en ssh-agent, ya que Claude Code suprime los mensajes interactivos de SSH para la huella digital del host y la contraseña de la clave. Los atajos de teclado de GitHub owner/repo clonan sobre SSH de forma predeterminada; establezca CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 para clonarlos sobre HTTPS en su lugar.

Actualizaciones automáticas en segundo plano

De forma predeterminada, la actualización en segundo plano deshabilita los ayudantes de credenciales de git cuando verifica el remoto del marketplace para nuevos commits, por lo que la verificación no puede autenticarse en repositorios privados sobre HTTPS incluso cuando un ayudante está configurado. Los remotos SSH no se ven afectados: una clave cargada en ssh-agent autentica la verificación en segundo plano de la misma manera que los comandos que ejecuta.

Cuando la verificación encuentra nuevos commits, o falla porque no puede alcanzar o autenticarse en el remoto, Claude Code clona el marketplace nuevamente e intercambia el nuevo clon. Si ese clon falla, el checkout existente permanece en su lugar. El re-clonado sí usa sus credenciales de git almacenadas, pero puede agotar el tiempo de espera en repositorios grandes, por lo que las actualizaciones automáticas de marketplace privado pueden fallar intermitentemente.

Dos configuraciones hacen que los marketplaces privados se comporten de manera predecible:

  • Establezca CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para mantener el checkout existente sin intentar el re-clonado cuando la verificación en segundo plano no puede alcanzar o autenticarse en el remoto. Sus plugins siguen funcionando desde el último estado sincronizado, y las actualizaciones manuales con /plugin marketplace update aún se autentican con sus credenciales.
  • Configure un ayudante de credenciales de git, por ejemplo con gh auth setup-git para GitHub, para que el re-clonado pueda autenticarse sin solicitar.

Establecer un token de proveedor como GITHUB_TOKEN en su entorno no habilita por sí solo la autenticación en segundo plano. Los tokens tienen efecto solo a través de un ayudante de credenciales configurado, por ejemplo el ayudante de CLI gh, que lee GH_TOKEN y GITHUB_TOKEN.

Para hacer que la verificación en segundo plano se autentique sobre HTTPS, configure una reescritura de URL de git global. La reescritura incrusta un token en la URL remota, por lo que tiene efecto aunque la verificación en segundo plano deshabilite los ayudantes de credenciales. Cuando la verificación encuentra el checkout actualizado, Claude Code omite el re-clonado. El siguiente ejemplo reescribe la URL del repositorio del marketplace para incluir un token de acceso:

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

Limite el alcance de la reescritura al repositorio del marketplace o ruta de la organización. Una reescritura cuya base es solo el host se aplica a cada extracción e inserción a ese host en la máquina e invalida sus credenciales normales, incluidas las inserciones a sus propios repositorios.

Cada proveedor espera un nombre de usuario diferente en la URL reescrita, y el mismo alcance de ruta se aplica a cada proveedor. Para servidores autohospedados, reemplace el nombre de host con el nombre de host de su servidor:

Proveedor Forma de URL reescrita
GitHub https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins
GitLab https://oauth2:YOUR_TOKEN@gitlab.com/acme-corp/plugins
Bitbucket https://x-token-auth:YOUR_TOKEN@bitbucket.org/acme-corp/plugins

La reescritura almacena el token en texto plano en su gitconfig, por lo que use un token con acceso de solo lectura al repositorio del marketplace.

Distribuir a través de la configuración de la organización

Si distribuye plugins a través de Configuración de la organización > Plugins en un plan de Equipo o Empresa, se aplican estas reglas de fuente:

  • En github.com y gitlab.com, el repositorio del marketplace debe ser privado o interno. La sincronización de la organización lo lee a través de la conexión que coincide con su host:
    • github.com: la Aplicación GitHub de Claude
    • Su host de GitHub Enterprise Server: su Aplicación GitHub Enterprise de la organización
    • gitlab.com o su instancia de GitLab autogestionada: el token de acceso en su configuración de GitLab de la organización para ese host
  • Cada fuente de plugin debe ser de tipo github, url o git-subdir, o una ruta relativa que comience con ./. Si enumera un plugin por nombre simple bajo metadata.pluginRoot, la sincronización de la organización lo rechaza como una fuente no soportada, así que escriba la ruta, como ./plugins/deploy-tools.
  • Una fuente de plugin puede ser privada en tres casos:
    • Una fuente github.com que comparta el propietario del repositorio del marketplace
    • Una fuente en el host GitHub Enterprise de su organización con la Aplicación GHE instalada en el repositorio
    • Una fuente url o git-subdir en el mismo host de GitLab que el repositorio del marketplace. En gitlab.com, la fuente también debe estar bajo el mismo grupo de nivel superior o espacio de nombres de usuario que el repositorio del marketplace.
  • Cualquier otra fuente de plugin debe ser un repositorio público en github.com, gitlab.com o bitbucket.org, que la sincronización de la organización obtiene sin credenciales. La sincronización de la organización rechaza fuentes de plugins en hosts que estas reglas no cubren.

Consulte Administrar plugins para su organización para el flujo de trabajo del administrador.

Para incluir plugins privados, coloque las carpetas de plugins dentro del repositorio del marketplace y haga referencia a ellas con una ruta relativa. La sincronización de la organización empaqueta cada plugin durante la distribución, por lo que los usuarios nunca necesitan acceso a un repositorio de fuente separado.

Por ejemplo, esta entrada de plugin marketplace.json hace referencia a un plugin que confirmó en plugins/deploy-tools en el repositorio del marketplace:

{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}

Sincronizar un marketplace alojado en GitLab

Para sincronizar un marketplace desde gitlab.com o una instancia de GitLab autogestionada, un Propietario primero agrega una configuración de GitLab para ese host en Configuración de la organización > Claude Code. Las configuraciones de GitLab están en beta pública y se aplican solo a la sincronización del marketplace de plugins. Agregar una no hace que los repositorios de GitLab estén disponibles en Claude Code en la web. Consulte Administrar plugins para su organización para los pasos de configuración.

Cuando agrega el marketplace, ingrese la URL HTTPS del proyecto, como https://gitlab.example.com/platform/claude-plugins. Los proyectos en subgrupos anidados funcionan. La sincronización de la organización lee la rama predeterminada del proyecto. Si activa Sincronizar automáticamente, solo los envíos a la rama predeterminada inician una sincronización.

Mantener ejecutables fuera del directorio bin de nivel superior

No incluya un directorio bin/ de nivel superior en ningún plugin que distribuya a través de la configuración de la organización. claude.ai rechaza un plugin que tenga uno, ya sea que el plugin llegue por sincronización del marketplace o por carga directa:

  • Sincronización del marketplace: la sincronización de la organización rechaza ese plugin y sincroniza el resto del marketplace. El mensaje de error comienza con Plugin contains a top-level bin/ directory.
  • Carga directa: si carga el plugin en Configuración de la organización > Plugins en su lugar, claude.ai rechaza la carga con el mismo mensaje.

Mantenga los ejecutables en otro directorio, como scripts/, y haga referencia a ellos como ${CLAUDE_PLUGIN_ROOT}/scripts/<name> desde su configuración de skills, hooks o servidor MCP.

Requerir marketplaces para su equipo

Puede configurar su repositorio para que Claude Code agregue su marketplace para los miembros del equipo una vez que confíen en la carpeta del proyecto, sin solicitud separada. Agregue su marketplace a .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

También puede especificar qué plugins deben estar habilitados de forma predeterminada:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Para opciones de configuración completas, consulte Configuración de plugins.

Precargar plugins para contenedores

Para imágenes de contenedor y entornos de CI, puede precargar un directorio de plugins en tiempo de compilación para que Claude Code comience con marketplaces y plugins ya disponibles, sin clonar nada en tiempo de ejecución. Establezca la variable de entorno CLAUDE_CODE_PLUGIN_SEED_DIR para apuntar a este directorio.

Para superponer múltiples directorios seed, separe las rutas con : en Unix o ; en Windows. Claude Code busca cada directorio en orden y usa el primer seed que contiene un marketplace o caché de plugin dado.

El directorio seed refleja la estructura de ~/.claude/plugins:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

Para construir un directorio seed, ejecute Claude Code una vez durante la compilación de la imagen, instale los plugins que necesita, luego copie el directorio ~/.claude/plugins resultante en su imagen y apunte CLAUDE_CODE_PLUGIN_SEED_DIR a él.

Para omitir el paso de copia, establezca CLAUDE_CODE_PLUGIN_CACHE_DIR en su ruta de seed de destino durante la compilación para que los plugins se instalen directamente allí:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Luego establezca CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed en el entorno de tiempo de ejecución de su contenedor para que Claude Code lea desde el seed al inicio.

Al inicio, Claude Code registra los marketplaces encontrados en el known_marketplaces.json del seed en la configuración principal, y usa cachés de plugins encontrados bajo cache/ en su lugar sin re-clonar. Esto funciona tanto en modo interactivo como en modo no interactivo con la bandera -p.

Detalles de comportamiento:

  • Solo lectura: Claude Code nunca escribe en el directorio seed.
  • Actualizaciones automáticas deshabilitadas: los marketplaces seed no se actualizan automáticamente.
  • Las entradas seed tienen precedencia: los marketplaces declarados en el seed sobrescriben cualquier entrada coincidente en la configuración del usuario en cada inicio. Para optar por no participar en un plugin seed, use /plugin disable en lugar de eliminar el marketplace.
  • Resolución de rutas: Claude Code localiza contenido de marketplace sondeando $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ en tiempo de ejecución, no confiando en rutas almacenadas dentro del JSON del seed. Esto significa que el seed funciona correctamente incluso cuando se monta en una ruta diferente a donde fue construido.
  • Se bloquea la mutación: ejecutar /plugin marketplace remove o /plugin marketplace update contra un marketplace administrado por seed falla con orientación para pedir a su administrador que actualice la imagen seed.
  • Se compone con configuración: si extraKnownMarketplaces o enabledPlugins declaran un marketplace que ya existe en el seed, Claude Code usa la copia del seed en lugar de clonar.

Restricciones de marketplace administrado

Para organizaciones que requieren control estricto sobre las fuentes de plugins, los administradores pueden restringir qué marketplaces de plugins se permite a los usuarios agregar usando la configuración strictKnownMarketplaces en configuración administrada. Para también rechazar las banderas de CLI que cargan plugins, agentes y servidores MCP para una única ejecución, emparéjelo con disableSideloadFlags. Para permitir qué plugins de marketplaces pueden aparecer como sugerencias de instalación contextual, establezca pluginSuggestionMarketplaces.

strictKnownMarketplaces coincide con el marketplace del que proviene un plugin, no con las entradas dentro de él, por lo que los usuarios aún pueden instalar un plugin con una fuente command desde un marketplace permitido. Para bloquear también las fuentes de comando, establezca disableCommandPluginSources.

Cuando strictKnownMarketplaces se configura en configuración administrada, el comportamiento de restricción depende del valor:

Valor Comportamiento
Indefinido (predeterminado) Sin restricciones. Los usuarios pueden agregar cualquier marketplace
Array vacío [] Bloqueo completo. Bloquea cada fuente de marketplace, incluido el marketplace oficial de Anthropic
Lista de fuentes Lista de permitidos aplicada. Los usuarios solo pueden agregar marketplaces que coincidan con una entrada

Configuraciones comunes

Deshabilitar todas las adiciones de marketplace, incluido el marketplace oficial de Anthropic:

{
  "strictKnownMarketplaces": []
}

Claude Code descarga los plugins sincronizados desde claude.ai desde su cuenta en lugar de desde un marketplace, por lo que este bloqueo no los cubre. Para detener también esos, establezca syncClaudeAiPlugins en false en configuración administrada, o desactive Skills para su organización en claude.ai.

Permitir solo el marketplace oficial de Anthropic. La coincidencia para una entrada de repositorio único es exacta, por lo que esta entrada no cubre variantes ref o path del mismo repositorio:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

Con esta entrada, Claude Code mantiene un marketplace oficial ya registrado disponible y, en una máquina nueva, registra el marketplace automáticamente la primera vez que inicia Claude Code interactivamente.

El registro automático no cubre todas las máquinas. Más comúnmente falta:

  • Entornos no interactivos que se ejecutan antes del primer lanzamiento interactivo de la máquina.
  • Máquinas donde Claude Code ya se ejecutó interactivamente bajo una política que bloqueó el marketplace, como el bloqueo de array vacío. Claude Code registra el intento bloqueado y no reintenta después de que cambia la política.

En estas máquinas, agregue el marketplace a extraKnownMarketplaces en el mismo managed-settings.json para que Claude Code lo registre automáticamente, o ejecute claude plugin marketplace add anthropics/claude-plugins-official.

Permitir solo marketplaces específicos:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

Permitir cada repositorio de marketplace bajo una organización de GitHub con una entrada owner-wildcard. Los owner wildcards requieren Claude Code v2.1.223 o posterior.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

Permitir todos los marketplaces desde un servidor git interno usando coincidencia de patrón regex en el host. Este es el enfoque recomendado para GitHub Enterprise Server o instancias de GitLab autohospedadas:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Permitir marketplaces basados en sistema de archivos desde un directorio específico usando coincidencia de patrón regex en la ruta:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Use ".*" como pathPattern para permitir cualquier ruta del sistema de archivos mientras aún controla fuentes de red con hostPattern.

Cómo funcionan las restricciones

Las restricciones se validan antes de cualquier operación de red o del sistema de archivos. La verificación se ejecuta al agregar marketplace y al instalar, actualizar, actualizar y auto-actualizar plugins. Si un marketplace se agregó antes de que se configurara la política y su fuente ya no coincide con la lista de permitidos, Claude Code se niega a instalar o actualizar plugins desde él. La misma aplicación se aplica a blockedMarketplaces.

Para bloquear cada repositorio de marketplace bajo un propietario de GitHub, use la forma owner-wildcard en una entrada blockedMarketplaces: { "source": "github", "repo": "untrusted-org/*" }. Requiere Claude Code v2.1.223 o posterior. Para las reglas de coincidencia, que difieren entre la lista de bloqueo y la lista de permitidos, consulte Owner wildcards.

Cuando un usuario agrega una URL de repositorio https:// que Claude Code clona en lugar de obtener, como una URL de repositorio github.com o gitlab.com simple, Claude Code también la verifica contra las entradas url en blockedMarketplaces. Claude Code bloquea la adición si una entrada nombra la misma URL. En esa comparación, Claude Code ignora el sufijo .git y cualquier ref que el usuario agregue después de #. Requiere Claude Code v2.1.232 o posterior. Antes de v2.1.232, Claude Code coincidía una entrada url solo contra una URL que obtenía como un archivo marketplace.json alojado.

La lista de permitidos usa coincidencia exacta para la mayoría de tipos de fuente, aparte de entradas github con owner-wildcard. Para que un marketplace sea permitido, todos los campos especificados deben coincidir:

  • Para fuentes de GitHub: repo es requerido, ya sea nombrando un repositorio o usando la forma owner-wildcard owner/* para cubrir cada repositorio bajo ese propietario. Para cómo las entradas wildcard coinciden, incluido el caso de reglas, consulte Owner wildcards. Para entradas de repositorio único, ref debe coincidir exactamente o estar ausente tanto de la fuente del marketplace como de la entrada de la lista de permitidos, y la misma regla se aplica a path
  • Para fuentes de URL: la URL completa debe coincidir exactamente
  • Para fuentes hostPattern: el host del marketplace se compara contra el patrón regex
  • Para fuentes pathPattern: la ruta del sistema de archivos del marketplace se compara contra el patrón regex

La coincidencia exacta de la lista de permitidos trata URLs que difieren solo por una barra diagonal final, un sufijo .git o el esquema ssh:// versus https:// como valores diferentes. Si el marketplace de su organización se puede clonar por más de una forma de URL, prefiera una entrada hostPattern sobre una URL literal para que todas las formas https://, ssh:// y user@host:path coincidan.

Un marketplace alojado en claude.ai se compara por host: una entrada hostPattern que coincida con claude.ai lo rige, en strictKnownMarketplaces y en blockedMarketplaces. En la lista de permitidos, tal entrada no admite las cargas personales de claude.ai de un miembro. Requiere Claude Code v2.1.273 o posterior.

Debido a que strictKnownMarketplaces se establece en configuración administrada, los usuarios individuales y las configuraciones del proyecto no pueden anular estas restricciones.

Para detalles de configuración completos incluyendo todos los tipos de fuente soportados y comparación con extraKnownMarketplaces, consulte la referencia de strictKnownMarketplaces.

Resolución de versiones y canales de lanzamiento

Las versiones de plugins determinan rutas de caché y detección de actualizaciones: si la versión resuelta coincide con lo que un usuario ya tiene, /plugin update y auto-actualización omiten el plugin. Para fuentes basadas en git, si omite version, Claude Code usa el SHA del commit resuelto de la fuente, por lo que los usuarios obtienen una actualización cada vez que ese commit cambia; esta es la configuración más simple para plugins internos o en desarrollo activo. Consulte Gestión de versiones para el orden de resolución completo, incluidas fuentes archive.

Configurar canales de lanzamiento

Para soportar canales de lanzamiento "estable" y "último" para sus plugins, puede configurar dos marketplaces que apunten a diferentes refs o SHAs del mismo repositorio. Luego puede asignar cada grupo de usuarios su propio marketplace a través de configuración administrada de una de dos maneras:

  • Implemente configuración administrada gestionada por endpoint separada, como un archivo de configuración administrada o un perfil MDM, en los dispositivos de cada grupo. Cómo Claude Code combina fuentes administradas dice si el archivo o perfil por grupo se aplica en un dispositivo que también tiene una fuente de toda la organización.
  • Defina una política de puerta de enlace de aplicaciones Claude por grupo. La puerta de enlace aplica la primera política cuya regla de coincidencia se ajusta a un usuario, por lo que ordene las políticas para que cada usuario llegue a la política de su grupo. La extraKnownMarketplaces de una política de grupo reemplaza el mapa de política de captura general en lugar de fusionarse con él, por lo que enumere cada marketplace que el grupo necesita en la política del grupo, no solo su marketplace de canal.

La configuración administrada gestionada por servidor se aplica a cada usuario en su organización, por lo que no pueden llevar una asignación por grupo.

Ejemplo 
{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}
Asignar canales a grupos de usuarios

Asigne cada marketplace a su grupo de usuarios a través de la configuración administrada gestionada por endpoint o política de puerta de enlace descrita bajo Configurar canales de lanzamiento. Por ejemplo, el grupo estable recibe:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

El grupo de acceso temprano recibe latest-tools en su lugar:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

Fijar versiones de dependencias

Un plugin puede restringir sus dependencias a un rango semver para que las actualizaciones de una dependencia no rompan el plugin dependiente. Consulte Restringir versiones de dependencias de plugins para la convención de etiqueta de git {plugin-name}--v{version}, sintaxis de rango y cómo se combinan múltiples restricciones en la misma dependencia.

Renombrar o eliminar un plugin

El name de un plugin es su identificador estable. Los usuarios lo referencian en enabledPlugins, pluginConfigs y comandos /plugin install, por lo que cambiarlo rompe cada instalación existente. Para cambiar la etiqueta mostrada en la interfaz de usuario sin romper instalaciones, establezca displayName y mantenga name sin cambios.

Si debe cambiar el name de un plugin, o elimina un plugin del array plugins, agregue una entrada de nivel superior renames para que los usuarios existentes migren en lugar de ver un error plugin-not-found. La migración automática requiere Claude Code v2.1.193 o posterior. Asigne cada nombre anterior a su nombre actual, o a null si el plugin ya no existe. El siguiente ejemplo renombra formatter a code-formatter y registra que legacy-linter fue eliminado:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

Cuando un usuario inicia Claude Code con el nombre anterior aún en su configuración, Claude Code sigue el mapa renames:

  • Si la entrada apunta a un nuevo nombre, Claude Code carga el plugin bajo su nuevo nombre y muestra un aviso de una línea como Renamed to "code-formatter" in the "acme-tools" marketplace. Luego reescribe la clave anterior a la nueva clave en los ámbitos de configuración del usuario, proyecto y local para enabledPlugins y pluginConfigs, por lo que el aviso aparece una vez.
  • Para una entrada null, Claude Code elimina la clave anterior y el aviso reporta que el plugin fue eliminado del marketplace.
  • Si el plugin renombrado usa una fuente remota como github o npm, Claude Code reporta plugin-cache-miss después del renombramiento y el usuario debe ejecutar /plugin install una vez para obtenerlo bajo el nuevo nombre.

Trate renames como historial de solo anexión: mantenga las entradas antiguas en su lugar incluso después de que espere que cada usuario haya migrado. Claude Code sigue cadenas, por lo que si más tarde renombra code-formatter a formatter-pro, agregue una segunda entrada en lugar de editar la primera. Un usuario que aún tiene el formatter original habilitado luego se resuelve a través de ambas entradas a formatter-pro.

Ejecute claude plugin validate . después de editar el mapa; rechaza cualquier entrada cuya cadena forme un ciclo o no termine en null o un nombre listado en plugins.

Las versiones anteriores de Claude Code ignoran el campo renames y reportan plugin-not-found para el nombre anterior.

Validación y pruebas

Pruebe su marketplace antes de compartirlo. La validación verifica la estructura de archivos; para probar si un plugin cambia lo que Claude hace en indicaciones realistas, ejecute su suite de evaluación con claude plugin eval antes de publicar una nueva versión.

Desde su directorio de marketplace, valide la sintaxis JSON:

claude plugin validate .

O desde dentro de Claude Code:

/plugin validate .

Agregue el marketplace para pruebas:

/plugin marketplace add ./path/to/marketplace

Instale un plugin de prueba para verificar que todo funciona:

/plugin install test-plugin@marketplace-name

Para flujos de trabajo completos de prueba de plugins, consulte Pruebe sus plugins localmente. Para solución de problemas técnicos, consulte Referencia de plugins.

Administrar marketplaces desde la CLI

Claude Code proporciona subcomandos no interactivos claude plugin marketplace para scripting y automatización. Estos son equivalentes a los comandos /plugin marketplace disponibles dentro de una sesión interactiva.

Plugin marketplace add

Agregue un marketplace desde un repositorio de GitHub, URL de git, URL remota o ruta local.

claude plugin marketplace add <source> [options]

Argumentos:

  • <source>: Abreviatura de GitHub owner/repo, URL de git, URL remota a un archivo marketplace.json o ruta de directorio local. Para fijar a una rama o etiqueta, agregue @ref a la abreviatura de GitHub o #ref a una URL de git

Una URL debe incluir su esquema. A partir de Claude Code v2.1.196, un host escrito sin uno, como gitlab.example.com/team/plugins, se rechaza como una abreviatura owner/repo inválida y el error le indica que agregue https:// o use ./ para una ruta local. Las versiones anteriores lo malinterpretaban como una ruta de repositorio de GitHub y fallan en el momento del clon con un error de no encontrado de GitHub.

Opciones:

Opción Descripción Predeterminado
--scope <scope> Dónde declarar el marketplace: user, project o local. Consulte Plugin installation scopes user
--sparse <paths...> Limitar el checkout a directorios específicos a través de git sparse-checkout. Útil para monorepos
--claudeai Lea el argumento como el nombre de un marketplace alojado en claude.ai en lugar de una fuente. Requiere Claude Code v2.1.273 o posterior

Agregue un marketplace desde GitHub usando la abreviatura owner/repo:

claude plugin marketplace add acme-corp/claude-plugins

Fije a una rama o etiqueta específica con @ref:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

Agregue desde una URL de git en un host que no sea GitHub:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

Agregue desde una URL remota que sirva el archivo marketplace.json directamente:

claude plugin marketplace add https://example.com/marketplace.json

Agregue desde un directorio local para pruebas:

claude plugin marketplace add ./my-marketplace

Declare el marketplace en alcance de proyecto para que se comparta con su equipo a través de .claude/settings.json:

claude plugin marketplace add acme-corp/claude-plugins --scope project

Para un monorepo, limite el checkout a los directorios que contienen contenido de plugins:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Agregue un marketplace alojado en claude.ai por el nombre impreso en la sección From claude.ai: de claude plugin marketplace list:

claude plugin marketplace add --claudeai claudeai-organization-library

Con --claudeai, el comando rechaza --scope y --sparse. El marketplace se aloja para su cuenta, no se declara en un archivo de configuración, por lo que no puede compartirlo a través del .claude/settings.json de un proyecto.

Plugin marketplace list

Enumere todos los marketplaces configurados.

claude plugin marketplace list [options]

Opciones:

Opción Descripción
--json Salida como JSON

Con --json, cada entrada incluye name, source, un campo installLocation con la ruta de caché local donde se almacena el marketplace, y campos específicos de la fuente: repo para fuentes de GitHub, url para fuentes de git y URL, y path para fuentes locales. Las fuentes de GitHub y git también incluyen un campo ref cuando el marketplace se agregó con una rama o etiqueta fija.

Un marketplace de claude.ai agregado no tiene un clon local, por lo que su entrada lleva sus identificadores de claude.ai, marketplaceId y organizationUuid, en lugar de installLocation.

En sesiones de terminal donde los plugins se sincronizan desde su cuenta de claude.ai, el listado de texto termina con una sección From claude.ai: que nombra lo que claude.ai lista para su cuenta más allá de los marketplaces que ha agregado. Para agregar uno de ellos, consulte Agregar desde claude.ai. La salida --json cubre solo los marketplaces configurados y deja esa sección fuera. Requiere Claude Code v2.1.273 o posterior.

Plugin marketplace remove

Elimine un marketplace configurado. El alias rm también se acepta.

claude plugin marketplace remove <name> [options]

Argumentos:

  • <name>: nombre del marketplace a eliminar, como se muestra en claude plugin marketplace list. Este es el name de marketplace.json, no la fuente que pasó a add

Opciones:

Opción Descripción Predeterminado
--scope <scope> Restringir la eliminación a un único alcance de configuración: user, project o local. Consulte Plugin installation scopes. Cuando se omite, la declaración se elimina de cada alcance editable. Cuando se proporciona, solo se elimina la declaración de ese alcance; el estado compartido, la caché y los datos de plugins instalados se conservan cuando el marketplace aún se declara en otro alcance (todos los alcances)

Plugin marketplace update

Actualice marketplaces desde sus fuentes para recuperar nuevos plugins y cambios de versión. Un marketplace agregado con una rama o etiqueta ref se actualiza a la confirmación más reciente de esa ref, no a la rama predeterminada del repositorio.

claude plugin marketplace update [name]

Argumentos:

  • [name]: nombre del marketplace a actualizar, como se muestra en claude plugin marketplace list. Actualiza todos los marketplaces si se omite

Tanto remove como update fallan cuando se ejecutan contra un marketplace administrado por seed, que es de solo lectura. Al actualizar todos los marketplaces, las entradas administradas por seed se omiten y otros marketplaces aún se actualizan. Para cambiar plugins proporcionados por seed, pida a su administrador que actualice la imagen seed. Consulte Precargar plugins para contenedores.

Solución de problemas

Marketplace no se carga

Síntomas: No puede agregar marketplace o ver plugins de él

Soluciones:

  • Verifique que la URL del marketplace sea accesible
  • Compruebe que .claude-plugin/marketplace.json existe en la ruta especificada
  • Asegúrese de que la sintaxis JSON sea válida usando claude plugin validate . o /plugin validate . desde el directorio del marketplace. Para verificar el frontmatter de skill, agente y comando, consulte Validate a plugin or a directory without a manifest
  • Para repositorios privados, confirme que tiene permisos de acceso

Errores de validación de marketplace

Ejecute claude plugin validate . o /plugin validate . desde su directorio de marketplace para verificar problemas. Cuando se apunta a un directorio de marketplace, el validador verifica marketplace.json para errores de esquema, nombres de plugins duplicados y traversal de ruta de fuente. Para cada entrada cuya source es una ruta local, también valida el plugin.json de ese plugin y advierte cuando la version de la entrada no coincide con la de plugin.json. Los problemas encontrados en el plugin.json de un plugin tienen el prefijo del índice de entrada, en la forma plugins[2] plugin.json →.

A partir de Claude Code v2.1.196, el pase por entrada también:

  • incluye plugins cuya source es .
  • se ejecuta cuando marketplace.json está fuera de un directorio .claude-plugin, resolviendo fuentes contra el directorio del archivo en sí
  • reporta los problemas de cada entrada incluso cuando otra parte del archivo tiene errores de esquema

Las versiones anteriores omiten plugins en la raíz del marketplace y solo descienden desde un .claude-plugin/marketplace.json.

Desde un directorio de marketplace, Claude Code no abre los archivos de skill, agente, comando o hook de los plugins. Para encontrar errores en esos archivos, consulte Validate a plugin or a directory without a manifest. La tabla a continuación enumera los errores más comunes desde un directorio de marketplace, con la causa y solución para cada uno:

Error Causa Solución
No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json El directorio que nombró no tiene .claude-plugin/marketplace.json o plugin.json, y no tiene archivos de skill, agente o comando para verificar Ejecute desde la raíz del marketplace, o cree .claude-plugin/marketplace.json con los campos requeridos
Invalid JSON syntax: Unexpected token... Error de sintaxis JSON en marketplace.json Verifique comas faltantes, comas extra o cadenas sin comillas
Duplicate plugin name "x" found in marketplace Dos plugins comparten el mismo nombre Dé a cada plugin un valor name único
plugins[0].source: Path contains ".." Un segmento de la ruta de fuente es .. Use rutas relativas a la raíz del marketplace sin segmentos ... Consulte Rutas relativas
Marketplace name cannot contain control or bidirectional-formatting characters El name del marketplace contiene un carácter de formato bidireccional Unicode o un carácter de control, como un escape o una nueva línea Elimine el carácter del nombre. Antes de v2.1.247, estos caracteres producían el error Marketplace name impersonates an official Anthropic/Claude marketplace
Plugin name cannot contain control or bidirectional-formatting characters Un name de plugin contiene un carácter de formato bidireccional Unicode o un carácter de control, como un escape o una nueva línea Elimine el carácter del nombre. Antes de v2.1.247, Claude Code no ejecutaba esta verificación

Advertencias (no bloqueantes):

  • Marketplace has no plugins defined: agregue al menos un plugin al array plugins
  • No marketplace description provided: agregue una description de nivel superior para ayudar a los usuarios a entender su marketplace
  • Plugin name "x" is not kebab-case: renombre a letras minúsculas, dígitos y guiones solamente (por ejemplo, my-plugin). Claude Code acepta otras formas, pero la sincronización del marketplace de claude.ai las rechaza.
  • Marketplace name "x" is reserved in Claude Desktop: el marketplace se llama org, org-provisioned u unknown, en cualquier combinación de mayúsculas y minúsculas. Claude Code acepta estos nombres, pero la sincronización de marketplace administrada de Claude Desktop rechaza todo el marketplace. Renombre el marketplace. Antes de v2.1.221, claude plugin validate no ejecutaba esta verificación.
  • Marketplace name "x" is not accepted by Claude Desktop o Plugin name "x" is not accepted by Claude Desktop: Claude Desktop acepta nombres de hasta 128 caracteres compuestos de letras, dígitos, ., _ y -, comenzando con una letra o dígito. Claude Code acepta otras formas, pero la sincronización de marketplace administrada de Claude Desktop rechaza un marketplace cuyo nombre falla la verificación y silenciosamente descarta una entrada de plugin cuyo nombre lo hace. Renombre el marketplace o plugin. Antes de v2.1.221, claude plugin validate no ejecutaba estas verificaciones.

Validate a plugin or a directory without a manifest

Para encontrar archivos de skill, agente y comando cuyo frontmatter no se analiza, ejecute claude plugin validate y nombre el directorio que los contiene. Claude Code no busca fuera del directorio que nombra. Cada ejecución excepto una contra un plugin que tiene un plugin.json requiere Claude Code v2.1.233 o posterior.

Pick the directory to name

Claude Code verifica diferentes archivos dependiendo de qué directorio nombre. Encuentre lo que desea verificar en la primera columna y ejecute el comando de esa fila:

To check Run Claude Code checks
A plugin that has a plugin.json claude plugin validate ./plugins/my-plugin plugin.json, hooks/hooks.json, y los directorios skills, agents y commands en la raíz del plugin
One directory of skills, agents, or commands, such as a plugin that has no plugin.json yet claude plugin validate .claude/skills, ~/.claude/agents, o ./my-plugin/agents Cada archivo de skill, agente o comando en ese directorio
A folder whose skill is its root SKILL.md claude plugin validate ./skills, nombrando el directorio skills que contiene la carpeta El SKILL.md raíz de cada carpeta. El directorio contenedor debe llamarse skills; una carpeta bajo otro nombre, como plugins/, no tiene una ejecución que verifique su SKILL.md raíz
A project's three directories at once claude plugin validate .claude, o la raíz del proyecto cuando no tiene un manifiesto .claude-plugin/ .claude/skills, .claude/agents y .claude/commands
Your user-level directories claude plugin validate ~/.claude ~/.claude/skills, ~/.claude/agents y ~/.claude/commands
Check a plugin whose skill is its root `SKILL.md`

Cuando ejecuta claude plugin validate contra un directorio de plugin, Claude Code no verifica un SKILL.md en la raíz del plugin. Cuando el plugin se encuentra en un directorio llamado skills, ejecute el comando dos veces:

  • Nombre ese directorio skills para verificar el SKILL.md raíz del plugin.
  • Nombre el directorio del plugin para verificar el resto.

Cuando el plugin se encuentra bajo otro nombre, como plugins/, la ejecución del directorio skills no está disponible, y ninguna ejecución verifica su SKILL.md raíz.

Cuando ejecuta claude plugin validate, Claude Code no sigue enlaces simbólicos dentro del directorio que nombra. Lo que hace depende de dónde esté el enlace:

  • Un directorio skills, agents o commands vinculado bajo la raíz del plugin o .claude: Claude Code advierte que nada en él fue leído.
  • Una entrada vinculada dentro de un directorio skills, agents o commands: Claude Code la omite y advierte, por directorio, cuántas entradas omitió que una sesión cargaría.
  • El directorio skills, agents o commands que nombra es en sí mismo un enlace simbólico, o su directorio padre .claude es: Claude Code reporta un error y no verifica nada en él. Nombre el directorio real en su lugar.

En dos casos de skills, la ejecución pasa con advertencias. Para verificar los archivos vinculados, ejecute nuevamente y nombre un directorio que los contenga directamente:

Read the validation results

Una ejecución limpia termina con Validation passed.

No manifest found in directory significa que Claude Code no encontró plugin.json o marketplace.json allí, y ningún archivo de skill, agente o comando en los directorios que sondea bajo él. Nombre el directorio skills, agents o commands que contiene sus archivos en su lugar.

Dos de los errores que Claude Code reporta de estas ejecuciones, con la solución para cada uno:

  • YAML frontmatter failed to parse: ...: corrija el YAML en el bloque frontmatter del archivo de skill, agente o comando. Hasta que lo haga, una sesión no lee campos frontmatter del archivo
  • Invalid JSON syntax: ... en hooks/hooks.json: corrija la sintaxis JSON. Hasta que lo haga, una sesión carga el plugin sin los hooks en ese archivo. Claude Code reporta este error solo en una ejecución de plugin

En una ejecución de plugin, Claude Code también advierte sobre un CLAUDE.md en la raíz del plugin. Para rutas que establece a través de los component path fields en plugin.json, Claude Code verifica que cada ruta exista pero no lee los archivos allí.

Fallos de instalación de plugins

Síntomas: El marketplace aparece pero la instalación del plugin falla

Soluciones:

  • Verifique que las URLs de fuente del plugin sean accesibles
  • Compruebe que los directorios de plugins contengan archivos requeridos
  • Para fuentes de GitHub, asegúrese de que los repositorios sean públicos o tenga acceso
  • Pruebe las fuentes de plugins manualmente clonando/descargando
  • Si la fuente fija tanto ref como sha, una rama o etiqueta ascendente eliminada no bloquea la instalación en la mayoría de los hosts de git, incluyendo GitHub, GitLab y Bitbucket. En servidores que no soportan obtener commits por SHA, como AWS CodeCommit, el ref aún debe existir y el commit fijado debe ser alcanzable desde él. Si la instalación aún falla, confirme que el commit fijado aún existe en el repositorio

La autenticación del repositorio privado falla

Síntomas: Errores de autenticación al instalar plugins desde repositorios privados

Soluciones:

Para instalación manual y actualizaciones:

  • Verifique que esté autenticado con su proveedor de git (por ejemplo, ejecute gh auth status para GitHub)
  • Compruebe que su ayudante de credenciales esté configurado: git config --global credential.helper
  • Ejecute git ls-remote <marketplace-url> para probar si git puede autenticarse por sí solo. Si git solicita un nombre de usuario o contraseña, almacene la credencial primero: para GitHub sobre HTTPS, ejecute gh auth setup-git, y para remotos SSH, cargue su clave en ssh-agent

Para actualizaciones automáticas en segundo plano:

  • Por defecto, las actualizaciones en segundo plano desactivan los ayudantes de credenciales de git cuando verifican el remoto para nuevos commits, por lo que la verificación no puede autenticarse sobre HTTPS. Los remotos SSH con una clave cargada en ssh-agent aún se autentican
  • Cuando la verificación no puede autenticarse, Claude Code re-clona el marketplace con sus credenciales almacenadas, pero el re-clonado puede agotar el tiempo de espera en repositorios grandes
  • Establezca CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para mantener el clon existente sin intentar el re-clonado cuando la verificación en segundo plano no puede alcanzar o autenticarse al remoto
  • Configure un ayudante de credenciales de git, por ejemplo gh auth setup-git, para que el re-clonado pueda autenticarse
  • Si el re-clonado agota el tiempo de espera en un repositorio grande, aumente el límite con CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
  • Configure una reescritura de URL de git limitada al repositorio del marketplace para que la verificación en segundo plano se autentique directamente
  • O actualice marketplaces privados manualmente con /plugin marketplace update <name>, que usa sus credenciales

Las actualizaciones del marketplace fallan en entornos sin conexión

Síntomas: En un entorno sin conexión o aislado, la actualización de marketplace en segundo plano no puede alcanzar el remoto y Claude Code intenta repetidamente un re-clonado que no puede tener éxito.

Causa: La actualización en segundo plano verifica el remoto del marketplace para nuevos commits, y cuando la verificación no puede alcanzar el remoto, Claude Code intenta clonar el marketplace nuevamente. Sin conexión, el clonado falla de la misma manera y el clon existente permanece en su lugar. Antes de v2.1.274, la actualización ejecutaba git pull en el clon existente, movía el clon a un lado para re-clonar cuando el pull fallaba, y lo restauraba después en una base de mejor esfuerzo.

La actualización se ejecuta en segundo plano después del inicio, por lo que no retrasa el inicio. Cada sesión aún repite el intento fallido, y cada operación de git puede esperar el tiempo de espera de 120 segundos.

Solución: Establezca CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para omitir el intento de re-clonado y mantener el uso del clon existente cuando la verificación no puede alcanzar el remoto:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Para implementaciones completamente sin conexión donde el repositorio nunca será alcanzable, use CLAUDE_CODE_PLUGIN_SEED_DIR para precargar el directorio de plugins en tiempo de compilación en su lugar.

Las operaciones de Git agotan el tiempo de espera

Síntomas: La instalación del plugin o las actualizaciones del marketplace fallan con un error de tiempo de espera como Git clone timed out after 120s.

Causa: Claude Code usa un tiempo de espera de 120 segundos para todas las operaciones de git, incluyendo clonación de repositorios de plugins y re-clonación de un marketplace para actualizarlo. Los repositorios grandes o las conexiones de red lentas pueden exceder este límite.

Solución: Aumente el tiempo de espera usando la variable de entorno CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. El valor está en milisegundos:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutos

Los plugins con rutas relativas fallan en marketplaces basados en URL

Síntomas: Agregó un marketplace a través de una URL como https://example.com/marketplace.json, pero plugins con fuentes de ruta relativa como "./plugins/my-plugin" fallan al instalar con its marketplace entry path does not stay inside the marketplace directory. Los plugins ya instalados fallan al cargar con Plugin source path refused. Ambos mensajes tienen una entrada de referencia de error.

Causa: Agregar un marketplace basado en URL descarga solo el archivo marketplace.json en sí, y Claude Code no obtiene archivos de plugins por ruta relativa desde ese servidor. Las rutas relativas en la entrada del marketplace hacen referencia a archivos en el servidor remoto que no fueron descargados.

Soluciones:

  • Use fuentes externas: cambie las entradas de plugins a cualquier plugin source que no sea una ruta relativa: 
    { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  • Use un marketplace basado en Git: Aloje su marketplace en un repositorio de Git y agréguelo con la URL de git. Los marketplaces basados en Git clonan el repositorio completo, haciendo que las rutas relativas funcionen correctamente.

Archivos no encontrados después de la instalación

Síntomas: El plugin se instala pero las referencias a archivos fallan, especialmente archivos fuera del directorio del plugin

Causa: Claude Code copia plugins instalados a un directorio de caché, a menos que el plugin se cargue en el lugar. Una command source in link mode se carga en el lugar, y también lo hace una relative path source en un marketplace agregado desde un directorio local. Las rutas que hacen referencia a archivos fuera del directorio del plugin copiado (como ../shared-utils) no funcionarán porque esos archivos no se copian.

Soluciones: Consulte Plugin caching and file resolution para soluciones alternativas incluyendo enlaces simbólicos y reestructuración de directorios.

Para herramientas de depuración adicionales y problemas comunes, consulte Debugging and development tools.

Ver también