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:

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.
Crear el archivo de marketplace: defina un marketplace.json que enumere sus plugins y dónde encontrarlos. Consulte Crear el archivo de marketplace.
Alojar el marketplace: envíe a GitHub, GitLab u otro host git. Consulte Alojar y distribuir marketplaces.
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á.

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

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.

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"
}
}

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"
}
]
}

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., ejecute ese comando.

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

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 los campos a continuación)
`plugins`	array	Lista de plugins disponibles	Ver a continuación

Note

Nombres reservados: Los siguientes nombres de marketplace están reservados para uso oficial de Anthropic y no pueden ser utilizados por marketplaces de terceros: claude-code-marketplace, claude-code-plugins, claude-plugins-official, claude-plugins-community, claude-community, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, knowledge-work-plugins, life-sciences, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins, healthcare. Los nombres que se hacen pasar por marketplaces oficiales, como official-claude-plugins o anthropic-plugins-v2, también están bloqueados. Reservar estos nombres evita que un marketplace de terceros se presente como una fuente publicada por Anthropic.

Claude Code vuelve a verificar los nombres reservados cada vez que carga un marketplace, no solo cuando agrega uno. Un marketplace que fue registrado bajo uno de estos nombres antes de que el nombre se reservara deja de cargar e informa que está registrado desde una fuente no confiable. Elimine ese marketplace y vuelva a agregarlo desde la fuente oficial de Anthropic. Un marketplace de terceros afectado por un nombre recién reservado se carga nuevamente tan pronto como lo vuelva a agregar bajo un nombre diferente. Antes de v2.1.205, first-party-plugins y healthcare no estaban reservados, y un marketplace ya registrado bajo un nombre reservado seguía cargándose.

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. Recurre a `name` cuando se omite. 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. 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.

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, excepto para una fuente command en modo link, que Claude Code usa en su lugar. Claude Code también instala las dependencias de paquetes Node.js elegibles del plugin en la copia en caché.

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?`	Instalado vía `npm install`
`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

Note

Fuentes de marketplace vs fuentes de plugins: Estos son conceptos diferentes que controlan cosas diferentes.

Fuente de marketplace: dónde obtener el catálogo marketplace.json en sí. Se establece cuando los usuarios ejecutan /plugin marketplace add o en la configuración extraKnownMarketplaces. Las fuentes de marketplace basadas en Git soportan ref (rama/etiqueta) pero no sha.
Fuente de plugin: dónde obtener un plugin individual listado en el marketplace. Se establece en el campo source de cada entrada de plugin dentro de marketplace.json. Las fuentes de plugin basadas en Git soportan tanto ref (rama/etiqueta) como sha (commit exacto).

Por ejemplo, un marketplace alojado en acme-corp/plugin-catalog (fuente de marketplace) puede listar un plugin obtenido de acme-corp/code-formatter (fuente de plugin). La fuente de marketplace y la fuente de plugin apuntan a diferentes repositorios y se fijan independientemente.

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/. En el ejemplo anterior, ./plugins/my-plugin 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.

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

Los plugins distribuidos como paquetes npm se instalan usando npm install. Esto funciona con cualquier paquete en el registro npm público o un registro privado que su equipo aloje.

{
  "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 aceptarlo.

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

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.
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

Alojar en GitHub (recomendado)

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

Crear un repositorio: configure un nuevo repositorio para su marketplace
Agregar archivo de marketplace: cree .claude-plugin/marketplace.json con sus definiciones de plugins
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 Aplicación GitHub de Claude o la Aplicación GitHub Enterprise de su organización, y una fuente de plugin que no puede autenticarse debe ser pública. Consulte Distribuir a través de la configuración de la organización para las reglas completas.

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 para su git pull, por lo que la extracció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 las extracciones en segundo plano de la misma manera que los comandos que ejecuta. Cuando la extracción en segundo plano falla, Claude Code vuelve a clonar el marketplace desde cero. 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 clon existente cuando la extracción en segundo plano falla, en lugar de eliminar y re-clonar. Sus plugins siguen funcionando desde el último estado sincronizado, y las actualizaciones manuales con /plugin marketplace update aún extraen con sus credenciales.
Configure un ayudante de credenciales de git, por ejemplo con gh auth setup-git para GitHub, para que la alternativa de 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 extracció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 extracción en segundo plano deshabilite los ayudantes de credenciales, y una extracción exitosa omite la alternativa de 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:

El repositorio del marketplace debe ser privado o interno. La sincronización de la organización lo lee a través de la Aplicación GitHub de Claude o la Aplicación GitHub Enterprise de su organización.
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 dos 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
La sincronización de la organización obtiene todas las otras fuentes sin credenciales, por lo que los repositorios github.com bajo un propietario diferente y los repositorios en otros hosts, como GitLab o Bitbucket, deben ser públicos.

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"
}

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: el directorio seed nunca se escribe. Las actualizaciones automáticas están deshabilitadas para marketplaces seed ya que git pull fallaría en un sistema de archivos de solo lectura.
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": []
}

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.

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.

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

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

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.

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 ".."`	La ruta de fuente contiene `..`	Use rutas relativas a la raíz del marketplace sin `..`. 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.

Check files behind symlinks

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:

Un plugin cuyo directorio skills vincula a los skills de un plugin hermano: nombre el directorio del plugin hermano.
Una entrada de skill vinculada en ~/.claude/skills o .claude/skills: Claude Code sigue la entrada en una sesión. Para verificarla, nombre un directorio llamado skills que contenga la carpeta real.

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 para la extracción, por lo que la extracción no puede autenticarse sobre HTTPS. Los remotos SSH con una clave cargada en ssh-agent aún se autentican. Una extracción fallida desencadena un re-clonado desde cero, que usa sus credenciales almacenadas pero puede agotar el tiempo de espera en repositorios grandes
Establezca CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para mantener el clon existente cuando la extracción en segundo plano falla
Configure un ayudante de credenciales de git, por ejemplo gh auth setup-git, para que el re-clonado fallback 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 extracció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: El git pull del marketplace falla en segundo plano y Claude Code intenta repetidamente un re-clonado que no puede tener éxito.

Causa: Por defecto, cuando un git pull falla, Claude Code intenta un re-clonado desde cero. En entornos sin conexión o aislados, el re-clonado falla de la misma manera, y la restauración del caché anterior después es de mejor esfuerzo. La actualización se ejecuta en segundo plano después del inicio, por lo que no retrasa el inicio, pero cada sesión repite los intentos fallidos 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 caché existente cuando la extracción falla:

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" o "Git pull timed out after 120s".

Causa: Claude Code usa un tiempo de espera de 120 segundos para todas las operaciones de git, incluida la clonación de repositorios de plugins y la extracción de actualizaciones de marketplace. 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 URL (como https://example.com/marketplace.json), pero los plugins con fuentes de ruta relativa como "./plugins/my-plugin" fallan al instalar con errores "path not found".

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: Los plugins se copian a un directorio de caché en lugar de usarse en el lugar, excepto para una command source in link mode. 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

Descubrir e instalar plugins precompilados - Instalación de plugins desde marketplaces existentes
Plugins - Creación de sus propios plugins
Referencia de plugins - Especificaciones técnicas completas y esquemas
Configuración de plugins - Opciones de configuración de plugins
Referencia de strictKnownMarketplaces - Restricciones de marketplace administrado

plugin-marketplaces.md +467 −76

63 {63 {

64 "name": "quality-review-plugin",64 "name": "quality-review-plugin",

65 "description": "Adds a quality-review skill for quick code reviews",65 "description": "Adds a quality-review skill for quick code reviews",

~~66 "version": "1.0.0"~~66 "version": "1.0.0",

67 "author": {

68 "name": "Your Name"

69 }

67 }70 }

68 ```71 ```

69 72

70 <Note>73 <Note>

71 Establecer `version` significa que los usuarios solo reciben actualizaciones cuando cambia este campo, así que incremente la versión en cada lanzamiento. Si omite `version` y aloja este marketplace en git, cada commit cuenta automáticamente como una nueva versión. Consulte [Resolución de versiones](#version-resolution-and-release-channels) para elegir el enfoque correcto.74 Establecer `version` significa que los usuarios solo reciben actualizaciones cuando cambia este campo, así que incremente la versión en cada lanzamiento. Un plugin con una [fuente `command`](#command-sources) no está fijado por este campo. Si omite `version`, la versión proviene de la siguiente fuente en [gestión de versiones](/docs/es/plugins-reference#version-management).

72 </Note>75 </Note>

73 </Step>76 </Step>

74 77

93 </Step>96 </Step>

94 97

95 <Step title="Agregar e instalar">98 <Step title="Agregar e instalar">

~~96 Agregue el marketplace e instale el plugin.~~99 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.`, ejecute ese comando.

97 100

98 ```shell theme={null}101 ```shell theme={null}

99 /plugin marketplace add ./my-marketplace102 /plugin marketplace add ./my-marketplace

113Para obtener más información sobre lo que los plugins pueden hacer, incluidos hooks, agentes, servidores MCP y servidores LSP, consulte [Plugins](/docs/es/plugins).116Para obtener más información sobre lo que los plugins pueden hacer, incluidos hooks, agentes, servidores MCP y servidores LSP, consulte [Plugins](/docs/es/plugins).

114 117

115<Note>118<Note>

116 **Cómo se instalan los plugins**: Cuando los usuarios instalan un plugin, Claude Code copia el directorio del plugin a una ubicación de caché. Esto significa que los plugins no pueden hacer referencia a archivos fuera de su directorio usando rutas como `../shared-utils`, porque esos archivos no se copiarán.119 **Cómo se instalan los plugins**: cuando los usuarios instalan un plugin, Claude Code copia el directorio del plugin a una ubicación de caché, excepto para una [fuente `command` en modo de enlace](#copy-mode-and-link-mode), que se usa en su lugar. Los plugins copiados no pueden hacer referencia a archivos fuera de su directorio usando rutas como `../shared-utils`, porque esos archivos no se copiarán.

117 120

118 Si necesita compartir archivos entre plugins, use enlaces simbólicos. Consulte [Plugin caching and file resolution](/docs/es/plugins-reference#plugin-caching-and-file-resolution) para obtener detalles.121 Si necesita compartir archivos entre plugins, use enlaces simbólicos. Consulte [Plugin caching and file resolution](/docs/es/plugins-reference#plugin-caching-and-file-resolution) para obtener detalles.

119</Note>122</Note>

164</h3>167</h3>

165 168

167| :-------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------- |170| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------- |

168| `name` | string | Identificador de marketplace (kebab-case, sin espacios). 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: agregar un segundo marketplace con el mismo nombre reemplaza el primero. Para publicar múltiples plugins bajo un nombre de marketplace, enumérelos todos en un único [`marketplace.json`](#create-the-marketplace-file). | `"acme-tools"` |171| `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`](#create-the-marketplace-file). | `"acme-tools"` |

171 174

180</h3>183</h3>

181 184

183| :------ | :----- | :-------- | :-------------------------------------------- |186| :------ | :----- | :-------- | :------------------------------------------------ |

189| `url` | string | No | Sitio web, perfil de GitHub u URL de organización |

186 190

187<h3 id="optional-fields">191<h3 id="optional-fields">

188 Campos opcionales192 Campos opcionales

196| `metadata.pluginRoot` | string | Directorio base antepuesto a rutas de fuente de plugin relativas (por ejemplo, `"./plugins"` le permite escribir `"source": "formatter"` en lugar de `"source": "./plugins/formatter"`) |200| `metadata.pluginRoot` | string | Directorio que Claude Code resuelve bajo nombres de fuente de plugin sin ruta. Consulte [Rutas relativas](#relative-paths). Requiere Claude Code v2.1.239 o posterior. |

197| `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](/docs/es/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). |201| `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](/docs/es/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). |

198| `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](#rename-or-remove-a-plugin). Requiere Claude Code v2.1.193 o posterior. |202| `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](#rename-or-remove-a-plugin). Requiere Claude Code v2.1.193 o posterior. |

199 203

203 Entradas de plugins207 Entradas de plugins

204</h2>208</h2>

205 209

206Cada entrada de plugin en el array `plugins` describe un plugin y dónde encontrarlo. Puede incluir cualquier campo del [esquema de manifiesto de plugin](/docs/es/plugins-reference#plugin-manifest-schema), como `description`, `version`, `author`, `commands` y `hooks`, más estos campos específicos del marketplace: `source`, `category`, `tags`, `strict` y `relevance`.210Cada entrada de plugin en el array `plugins` describe un plugin y dónde encontrarlo. Puede incluir cualquier campo del [esquema de manifiesto de plugin](/docs/es/plugins-reference#plugin-manifest-schema), como `description`, `version`, `author`, `commands` y `hooks`, más estos campos específicos del marketplace: `source`, `category`, `tags`, `strict`, `relevance`, `headers` y `headersHelper`.

207 211

208<h3 id="required-fields-2">212<h3 id="required-fields-2">

209 Campos requeridos213 Campos requeridos

210</h3>214</h3>

211 215

213| :------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |217| :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

214| `name` | string | Identificador de plugin (kebab-case, sin espacios). Esto es público: los usuarios lo ven al instalar (por ejemplo, `/plugin install my-plugin@marketplace`). |218| `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`). |

216 220

217<h3 id="optional-plugin-fields">221<h3 id="optional-plugin-fields">

221**Campos de metadatos estándar:**225**Campos de metadatos estándar:**

222 226

224| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |228| :--------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

225| `displayName` | string | Nombre legible mostrado en superficies de interfaz de usuario. Recurre a `name` cuando se omite. Puede contener espacios y cualquier capitalización. No se utiliza para espacios de nombres o búsqueda. Requiere Claude Code v2.1.143 o posterior. |229| `displayName` | string | Nombre legible mostrado en superficies de interfaz de usuario. Recurre a `name` cuando se omite. Puede contener espacios y cualquier capitalización. No se utiliza para espacios de nombres o búsqueda. |

227| `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. Omita para recurrir al SHA del commit de git. Consulte [Resolución de versiones](#version-resolution-and-release-channels). |231| `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`](#command-sources) no se fija por ninguno de los campos. Si no se establece en ningún lugar, la versión proviene de la siguiente fuente en [gestión de versiones](/docs/es/plugins-reference#version-management). |

237| `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. |

235| `strict` | boolean | Controla si `plugin.json` es la autoridad para definiciones de componentes (predeterminado: true). Consulte [Modo estricto](#strict-mode) a continuación. |240| `strict` | boolean | Controla si `plugin.json` es la autoridad para definiciones de componentes (predeterminado: true). Consulte [Modo estricto](#strict-mode) a continuación. |

236| `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](/docs/es/plugin-relevance). Requiere Claude Code v2.1.152 o posterior. |241| `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](/docs/es/plugin-relevance). |

237| `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](/docs/es/plugins-reference#default-enablement). Requiere Claude Code v2.1.154 o posterior. |242| `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](/docs/es/plugins-reference#default-enablement). |

238 243

239**Campos de configuración de componentes:**244**Campos de configuración de componentes:**

240 245

249 254

255**Campos de autenticación de archivo:**

256

257Establezca estos cuando la entrada tenga una fuente [`archive`](#zip-archives) en un servidor que requiera credenciales.

258

259| Campo | Tipo | Descripción |

260| :-------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

261| `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. |

262| `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](#authenticate-archive-downloads). La entrada también debe establecer [`"strict": false`](#strict-mode). Requiere Claude Code v2.1.238 o posterior. |

263

250<h2 id="plugin-sources">264<h2 id="plugin-sources">

251 Fuentes de plugins265 Fuentes de plugins

252</h2>266</h2>

253 267

254Las 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`.268Las 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`.

255 269

256Después de que Claude Code clona o descarga un plugin en la máquina local, lo copia en el caché de plugins versionado local en `~/.claude/plugins/cache`.270Claude Code copia cada plugin instalado en el caché de plugins versionado local en `~/.claude/plugins/cache`, excepto para una [fuente `command` en modo link](#copy-mode-and-link-mode), que Claude Code usa en su lugar. Claude Code también [instala las dependencias de paquetes Node.js elegibles del plugin](/docs/es/plugins-reference#node-js-package-dependencies) en la copia en caché.

257 271

259| ------------- | --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |273| ------------- | --------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

260| Ruta relativa | `string` (p. ej. `"./my-plugin"`) | ninguno | Directorio local dentro del repositorio de marketplace. Debe comenzar con `./`. Se resuelve relativo a la raíz del marketplace, no al directorio `.claude-plugin/` |274| 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`](#relative-paths). Claude Code resuelve la ruta relativa a la raíz del marketplace, no al directorio `.claude-plugin/` |

280| `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 |

265 281

266<Note>282<Note>

267 **Fuentes de marketplace vs fuentes de plugins**: Estos son conceptos diferentes que controlan cosas diferentes.283 **Fuentes de marketplace vs fuentes de plugins**: Estos son conceptos diferentes que controlan cosas diferentes.

268 284

269 * **Fuente de marketplace**: dónde obtener el catálogo `marketplace.json` en sí. Se establece cuando los usuarios ejecutan `/plugin marketplace add` o en la configuración `extraKnownMarketplaces`. Soporta `ref` (rama/etiqueta) pero no `sha`.285 * **Fuente de marketplace**: dónde obtener el catálogo `marketplace.json` en sí. Se establece cuando los usuarios ejecutan `/plugin marketplace add` o en la configuración `extraKnownMarketplaces`. Las fuentes de marketplace basadas en Git soportan `ref` (rama/etiqueta) pero no `sha`.

270 * **Fuente de plugin**: dónde obtener un plugin individual listado en el marketplace. Se establece en el campo `source` de cada entrada de plugin dentro de `marketplace.json`. Soporta tanto `ref` (rama/etiqueta) como `sha` (commit exacto).286 * **Fuente de plugin**: dónde obtener un plugin individual listado en el marketplace. Se establece en el campo `source` de cada entrada de plugin dentro de `marketplace.json`. Las fuentes de plugin basadas en Git soportan tanto `ref` (rama/etiqueta) como `sha` (commit exacto).

271 287

272 Por ejemplo, un marketplace alojado en `acme-corp/plugin-catalog` (fuente de marketplace) puede listar un plugin obtenido de `acme-corp/code-formatter` (fuente de plugin). La fuente de marketplace y la fuente de plugin apuntan a diferentes repositorios y se fijan independientemente.288 Por ejemplo, un marketplace alojado en `acme-corp/plugin-catalog` (fuente de marketplace) puede listar un plugin obtenido de `acme-corp/code-formatter` (fuente de plugin). La fuente de marketplace y la fuente de plugin apuntan a diferentes repositorios y se fijan independientemente.

273</Note>289</Note>

276 292

277En 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.293En 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.

278 294

295Si 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](#distribute-through-organization-settings).

296

279<h3 id="relative-paths">297<h3 id="relative-paths">

280 Rutas relativas298 Rutas relativas

281</h3>299</h3>

291 309

292Las rutas se resuelven relativas a la raíz del marketplace, que es el directorio que contiene `.claude-plugin/`. En el ejemplo anterior, `./plugins/my-plugin` 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.310Las rutas se resuelven relativas a la raíz del marketplace, que es el directorio que contiene `.claude-plugin/`. En el ejemplo anterior, `./plugins/my-plugin` 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.

293 311

312Un nombre simple es un nombre de directorio único sin `/`, como `"formatter"`. Para escribir nombres simples en lugar de rutas `./`, establezca [`metadata.pluginRoot`](#optional-fields) 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.

313

314`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.

315

294<Note>316<Note>

295 Las rutas relativas se resuelven contra una copia local del marketplace, por lo que funcionan cuando los usuarios agregan su marketplace desde una fuente de git o un directorio local. Si los usuarios agregan su marketplace a través de una URL directa al archivo `marketplace.json`, las rutas relativas no se resolverán, porque solo se descarga ese archivo. Para distribución basada en URL, use fuentes de GitHub, npm o URL de git en su lugar. Consulte [Solución de problemas](#plugins-with-relative-paths-fail-in-url-based-marketplaces) para obtener detalles.317 Claude Code resuelve rutas relativas contra una copia local del marketplace, por lo que funcionan cuando los usuarios agregan su marketplace desde una fuente de git o un directorio local. Si los usuarios agregan su marketplace a través de una URL directa al archivo `marketplace.json`, las rutas relativas no se resolverán, porque Claude Code descarga solo ese archivo. Para distribución basada en URL, use cualquier otra [fuente de plugin](#plugin-sources) en su lugar. Consulte [Solución de problemas](#plugins-with-relative-paths-fail-in-url-based-marketplaces) para obtener detalles.

296</Note>318</Note>

297 319

298<h3 id="github-repositories">320<h3 id="github-repositories">

455 477

478<h3 id="zip-archives">

479 Archivos zip

480</h3>

481

482Use `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.

483

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

485

486```json theme={null}

487{

488 "name": "my-plugin",

489 "source": {

490 "source": "archive",

491 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"

492 }

493}

494```

495

496Cuando 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:

497

498```text theme={null}

499my-plugin.zip my-plugin.zip

500├── .claude-plugin/ └── my-plugin/

501│ └── plugin.json ├── .claude-plugin/

502└── commands/ │ └── plugin.json

503 └── commands/

504```

505

506Claude 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.

507

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

509

510```json theme={null}

511{

512 "name": "my-plugin",

513 "source": {

514 "source": "archive",

515 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",

516 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"

517 }

518}

519```

520

521Si el archivo descargado no coincide con el pin, Claude Code rechaza la instalación e informa [`Plugin archive integrity check failed`](/docs/es/errors#plugin-archive-integrity-check-failed).

522

523Las fuentes de archivo aceptan estos campos:

524

525| Campo | Tipo | Descripción |

526| :------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

527| `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 |

528| `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 |

529

530El 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](/docs/es/plugins-reference#version-management). 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é.

531

532<h4 id="authenticate-archive-downloads">

533 Autenticar descargas de archivos

534</h4>

535

536Para 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`](/docs/es/settings-reference#extraknownmarketplaces). En Claude Code v2.1.238 o posterior, puede establecerlo en la entrada del plugin en su lugar, junto a `source`.

537

538Si 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.

539

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

541

542| Lugar | Descargas que obtienen los encabezados | Cuándo Claude Code ejecuta un `headersHelper` establecido allí |

543| :--------------------------- | :------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

544| 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 |

545| 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](#how-users-accept-a-headershelper-command) |

546

547Donde 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`.

548

549<h5 id="add-a-headershelper-to-a-plugin-entry">

550 Agregar un headersHelper a una entrada de plugin

551</h5>

552

553Esta 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`](#strict-mode), 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:

554

555```json theme={null}

556{

557 "name": "my-plugin",

558 "description": "Formatting commands for internal services",

559 "strict": false,

560 "commands": "./commands",

561 "source": {

562 "source": "archive",

563 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"

564 },

565 "headersHelper": "/opt/bin/mint-registry-token.sh"

566}

567```

568

569Para 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.

570

571Antes 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.

572

573<h4 id="write-the-headershelper-command">

574 Escribir el comando headersHelper

575</h4>

576

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

578

579* **Texto del comando**: como máximo 500 caracteres de ASCII imprimible, sin una ejecución de cuatro o más espacios.

580* **Salida**: imprima un objeto JSON de nombres de encabezados y valores de cadena en stdout, luego salga 0 dentro de 10 segundos.

581* **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`](/docs/es/env-vars#variables). Proporcione una ruta absoluta o un comando en `PATH`, porque una ruta relativa se resuelve contra ese directorio, no el proyecto del usuario.

582* **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.

583* **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.

584

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

586

587```json theme={null}

588{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

589```

590

591<h4 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">

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

593</h4>

594

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

596

597* **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.

598* **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`.

599* **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.

600* **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](/docs/es/settings-reference#extraknownmarketplaces) dependiendo de qué archivo la declare.

601* **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](/docs/es/settings-reference#extraknownmarketplaces) por igual, y envía solo los `headers` de ese archivo.

602* **La configuración administrada bloquea el comando**: establecer [`disableCommandPluginSources`](/docs/es/settings-reference#disablecommandpluginsources) en `true` bloquea comandos `headersHelper`, y [`allowManagedHooksOnly`](/docs/es/settings-reference#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.

603

604<h4 id="how-users-accept-a-headershelper-command">

605 Cómo los usuarios aceptan un comando headersHelper

606</h4>

607

608Un 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`](/docs/es/plugins-reference#plugin-install) para aceptarlo.

609

610Claude 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.

611

612<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

613 Instalaciones y actualizaciones que rechazan el comando en lugar de preguntar

614</h5>

615

616En 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:

617

618* **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.

619* **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.

620

621<h5 id="when-a-marketplace-url-source’s-command-runs">

622 Cuándo se ejecuta el comando headersHelper de una fuente `url` del marketplace

623</h5>

624

625Un `headersHelper` de fuente `url` del marketplace se declara en un archivo de configuración, como una entrada [`extraKnownMarketplaces`](/docs/es/settings-reference#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:

626

627| Archivo de configuración | Cuándo Claude Code ejecuta el comando |

628| :---------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

629| 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 |

630| `.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](/docs/es/permissions#what-runs-before-you-trust-a-folder) para esa carpeta en sí. Una sesión `-p` o SDK no cuenta como aceptarlo, ni tampoco la confianza otorgada a una carpeta padre |

631| 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](/docs/es/server-managed-settings#security-approval-dialogs) |

632

633En 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.

634

635Para una [entrada de plugin en línea](/docs/es/settings-reference#extraknownmarketplaces) 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.

636

637<h3 id="command-sources">

638 Fuentes de comando

639</h3>

640

641Use `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.

642

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

644

645```json theme={null}

646{

647 "name": "my-plugin",

648 "source": {

649 "source": "command",

650 "command": "my-tool claude-plugin-path"

651 }

652}

653```

654

655Claude 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.

656

657Claude 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:

658

659* El directorio no tiene contenido de plugin en su nivel superior, como un directorio `.claude-plugin/` o un directorio `skills/`, `commands/`, `agents/` o `hooks/`

660* El directorio es el en el que Claude Code fue iniciado, o uno de sus padres

661* En Windows, la ruta es una ruta UNC

662

663Las fuentes de comando aceptan estos campos:

664

665| Campo | Tipo | Descripción |

666| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

667| `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 |

668| `timeout` | number | Opcional. Número entero de segundos para esperar el comando antes de rendirse (predeterminado: 60, máximo: 600) |

669| `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](#copy-mode-and-link-mode) |

670

671<h4 id="copy-mode-and-link-mode">

672 Modo de copia y modo de enlace

673</h4>

674

675Con el `"mode": "copy"` predeterminado, Claude Code copia el directorio impreso en el caché de plugins versionado y deriva la [versión del plugin](/docs/es/plugins-reference#version-management) 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.

676

677Establezca `"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](/docs/es/plugins-reference#node-js-package-dependencies) para un plugin en modo de enlace, por lo que imprima un directorio que ya contenga cualquier `node_modules` que el plugin necesite.

678

679Mantenga 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](/docs/es/plugins-reference#version-management) 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.

680

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

682

683<h4 id="how-users-accept-the-command">

684 Cómo los usuarios aceptan el comando

685</h4>

686

687Claude 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:

688

689* 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.

690* 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](#when-claude-code-re-runs-the-command). 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.

691* 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>`.

692

693Los administradores pueden bloquear fuentes de comando en toda una organización con la configuración administrada [`disableCommandPluginSources`](/docs/es/settings-reference#disablecommandpluginsources). Si una organización establece [`allowManagedHooksOnly`](/docs/es/settings-reference#allowmanagedhooksonly), Claude Code bloquea fuentes de comando de forma predeterminada.

694

695<h4 id="when-claude-code-re-runs-the-command">

696 Cuándo Claude Code vuelve a ejecutar el comando

697</h4>

698

699El 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:

700

701* Cada vez que el usuario instala o actualiza el plugin

702* 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](/docs/es/discover-plugins#configure-auto-updates) del marketplace

703* Al inicio o en `/reload-plugins`, cuando la versión instalada de un plugin habilitado falta en el caché de plugins

704

705Claude Code omite las dos ejecuciones en segundo plano cuando el usuario establece [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/es/env-vars). Las instalaciones y actualizaciones explícitas aún ejecutan el comando con esa variable establecida.

706

707Cuando 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](/docs/es/plugins-reference#environment-variables). 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`](/docs/es/prompt-caching#enabling-or-disabling-a-plugin).

708

456<h3 id="advanced-plugin-entries">709<h3 id="advanced-plugin-entries">

457 Entradas de plugins avanzadas710 Entradas de plugins avanzadas

458</h3>711</h3>

508 761

509Cosas clave a notar:762Cosas clave a notar:

510 763

511* **`commands` y `agents`**: puede especificar múltiples directorios o archivos individuales. Las rutas son relativas a la raíz del plugin.764* **`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.

512* **`${CLAUDE_PLUGIN_ROOT}`**: Use esta variable en hooks y configuraciones de MCP server para hacer referencia a archivos dentro del directorio de instalación del plugin. Esto es necesario porque los plugins se copian a una ubicación de caché cuando se instalan.765 * Claude Code rechaza una ruta que se resuelve fuera del directorio del plugin, como `./../shared.md`, con un error [`path escapes plugin directory`](/docs/es/errors#path-escapes-plugin-directory), y aún carga el plugin sin ese componente

766* **`${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.

513 * Consulte la [tabla de sustitución](/docs/es/plugins-reference#environment-variables) para ver qué campos de configuración la sustituyen por tipo de servidor767 * Consulte la [tabla de sustitución](/docs/es/plugins-reference#environment-variables) para ver qué campos de configuración la sustituyen por tipo de servidor

514 * Para dependencias o estado que deben sobrevivir a las actualizaciones de plugins, use [`${CLAUDE_PLUGIN_DATA}`](/docs/es/plugins-reference#persistent-data-directory) en su lugar768 * Para dependencias o estado que deben sobrevivir a las actualizaciones de plugins, use [`${CLAUDE_PLUGIN_DATA}`](/docs/es/plugins-reference#persistent-data-directory) en su lugar

515* **`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](#strict-mode) a continuación.769* **`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](#strict-mode) a continuación.

575 Repositorios privados829 Repositorios privados

576</h3>830</h3>

577 831

578Claude Code soporta instalar plugins desde repositorios privados. Para instalación manual y actualizaciones, 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`](/docs/es/env-vars#variables) para clonarlos sobre HTTPS en su lugar.832Claude Code soporta instalar plugins desde repositorios privados. Si distribuye su marketplace a través de [**Configuración de la organización > Plugins**](https://claude.ai/admin-settings/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 Aplicación GitHub de Claude o la Aplicación GitHub Enterprise de su organización, y una fuente de plugin que no puede autenticarse debe ser pública. Consulte [Distribuir a través de la configuración de la organización](#distribute-through-organization-settings) para las reglas completas.

833

834<h4 id="commands-you-run">

835 Comandos que ejecuta

836</h4>

837

838Cuando 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`](/docs/es/env-vars#variables) para clonarlos sobre HTTPS en su lugar.

579 839

580Las actualizaciones automáticas en segundo plano funcionan de manera diferente. De forma predeterminada, la actualización en segundo plano deshabilita los ayudantes de credenciales de git para su `git pull`, por lo que la extracció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 las extracciones en segundo plano de la misma manera que las operaciones manuales. Cuando la extracción en segundo plano falla, Claude Code vuelve a clonar el marketplace desde cero. El re-clonado sí usa sus credenciales de git almacenadas, pero puede [agotar el tiempo de espera en repositorios grandes](#git-operations-time-out), por lo que las actualizaciones automáticas de marketplace privado pueden fallar intermitentemente.840<h4 id="background-auto-updates">

841 Actualizaciones automáticas en segundo plano

842</h4>

843

844De forma predeterminada, la actualización en segundo plano deshabilita los ayudantes de credenciales de git para su `git pull`, por lo que la extracció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 las extracciones en segundo plano de la misma manera que los comandos que ejecuta. Cuando la extracción en segundo plano falla, Claude Code vuelve a clonar el marketplace desde cero. El re-clonado sí usa sus credenciales de git almacenadas, pero puede [agotar el tiempo de espera en repositorios grandes](#git-operations-time-out), por lo que las actualizaciones automáticas de marketplace privado pueden fallar intermitentemente.

581 845

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

583 847

608 En entornos de CI/CD, configure un ayudante de credenciales de git antes de instalar plugins desde repositorios privados. En GitHub Actions, exporte un token con acceso de lectura al repositorio del marketplace como `GH_TOKEN`, luego ejecute `gh auth setup-git`. El token de flujo de trabajo predeterminado solo puede acceder al repositorio del flujo de trabajo, por lo que un marketplace privado en otro repositorio necesita un token de acceso personal o token de aplicación. Una reescritura de URL global configurada en la canalización también autentica la extracción en segundo plano directamente.872 En entornos de CI/CD, configure un ayudante de credenciales de git antes de instalar plugins desde repositorios privados. En GitHub Actions, exporte un token con acceso de lectura al repositorio del marketplace como `GH_TOKEN`, luego ejecute `gh auth setup-git`. El token de flujo de trabajo predeterminado solo puede acceder al repositorio del flujo de trabajo, por lo que un marketplace privado en otro repositorio necesita un token de acceso personal o token de aplicación. Una reescritura de URL global configurada en la canalización también autentica la extracción en segundo plano directamente.

609</Note>873</Note>

610 874

611<h3 id="test-locally-before-distribution">875<h3 id="distribute-through-organization-settings">

612 Probar localmente antes de la distribución876 Distribuir a través de la configuración de la organización

613</h3>877</h3>

614 878

615Pruebe su marketplace localmente antes de compartirlo:879Si distribuye plugins a través de [**Configuración de la organización > Plugins**](https://claude.ai/admin-settings/plugins) en un plan de Equipo o Empresa, se aplican estas reglas de fuente:

616 880

617```shell theme={null}881* El repositorio del marketplace debe ser privado o interno. La sincronización de la organización lo lee a través de la Aplicación GitHub de Claude o la Aplicación GitHub Enterprise de su organización.

618/plugin marketplace add ./my-marketplace882* Cada fuente de plugin debe ser de tipo `github`, `url` o `git-subdir`, o una [ruta relativa](#relative-paths) 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`.

619/plugin install quality-review-plugin@my-plugins883* Una fuente de plugin puede ser privada en dos casos:

884 * Una fuente github.com que comparta el propietario del repositorio del marketplace

885 * Una fuente en el host GitHub Enterprise de su organización con la Aplicación GHE instalada en el repositorio

886* La sincronización de la organización obtiene todas las otras fuentes sin credenciales, por lo que los repositorios github.com bajo un propietario diferente y los repositorios en otros hosts, como GitLab o Bitbucket, deben ser públicos.

887

888Consulte [Administrar plugins para su organización](https://support.claude.com/en/articles/13837433) para el flujo de trabajo del administrador.

889

890Para incluir plugins privados, coloque las carpetas de plugins dentro del repositorio del marketplace y haga referencia a ellas con una [ruta relativa](#relative-paths). 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.

891

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

893

894```json theme={null}

895{

896 "name": "deploy-tools",

897 "source": "./plugins/deploy-tools"

898}

620```899```

621 900

622Para el rango completo de comandos add (GitHub, URLs de Git, rutas locales, URLs remotas), consulte [Agregar marketplaces](/docs/es/discover-plugins#add-marketplaces).901<h4 id="keep-executables-out-of-the-top-level-bin-directory">

902 Mantener ejecutables fuera del directorio bin de nivel superior

903</h4>

904

905No 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:

906

907* **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`.

908* **Carga directa**: si carga el plugin en [**Configuración de la organización > Plugins**](https://claude.ai/admin-settings/plugins) en su lugar, claude.ai rechaza la carga con el mismo mensaje.

909

910Mantenga 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](/docs/es/plugins-reference#environment-variables).

623 911

624<h3 id="require-marketplaces-for-your-team">912<h3 id="require-marketplaces-for-your-team">

625 Requerir marketplaces para su equipo913 Requerir marketplaces para su equipo

626</h3>914</h3>

627 915

628Puede configurar su repositorio para que los miembros del equipo sean automáticamente solicitados para instalar su marketplace cuando confíen en la carpeta del proyecto. Agregue su marketplace a `.claude/settings.json`:916Puede 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](/docs/es/permissions#what-runs-before-you-trust-a-folder), sin solicitud separada. Agregue su marketplace a `.claude/settings.json`:

629 917

630```json theme={null}918```json theme={null}

631{919{

651}939}

652```940```

653 941

654Para opciones de configuración completas, consulte [Configuración de plugins](/docs/es/settings#plugin-settings).942Para opciones de configuración completas, consulte [Configuración de plugins](/docs/es/settings-reference#plugin-settings).

655 943

656<Note>944<Note>

657 Si usa una fuente local `directory` o `file` con una ruta relativa, la ruta se resuelve contra el checkout principal de su repositorio. Cuando ejecuta Claude Code desde un git worktree, la ruta aún apunta al checkout principal, por lo que todos los worktrees comparten la misma ubicación de marketplace. El estado del marketplace se almacena una vez por usuario en `~/.claude/plugins/known_marketplaces.json`, no por proyecto.945 Si usa una fuente local `directory` o `file` con una ruta relativa, la ruta se resuelve contra el checkout principal de su repositorio. Cuando ejecuta Claude Code desde un git worktree, la ruta aún apunta al checkout principal, por lo que todos los worktrees comparten la misma ubicación de marketplace. El estado del marketplace se almacena una vez por usuario en `~/.claude/plugins/known_marketplaces.json`, no por proyecto.

699 Restricciones de marketplace administrado987 Restricciones de marketplace administrado

700</h3>988</h3>

701 989

702Para 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`](/docs/es/settings#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`](/docs/es/settings#available-settings). Para permitir qué plugins de marketplaces pueden aparecer como sugerencias de instalación contextual, establezca [`pluginSuggestionMarketplaces`](/docs/es/settings#available-settings).990Para 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`](/docs/es/settings-reference#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`](/docs/es/settings-reference#disablesideloadflags). Para permitir qué plugins de marketplaces pueden aparecer como sugerencias de instalación contextual, establezca [`pluginSuggestionMarketplaces`](/docs/es/settings-reference#pluginsuggestionmarketplaces).

991

992`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`](#command-sources) desde un marketplace permitido. Para bloquear también las fuentes de comando, establezca [`disableCommandPluginSources`](/docs/es/settings-reference#disablecommandpluginsources).

703 993

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

705 995

706| Valor | Comportamiento |996| Valor | Comportamiento |

707| --------------------------- | -------------------------------------------------------------------------------------------------- |997| --------------------------- | --------------------------------------------------------------------------------------------------------- |

708| Indefinido (predeterminado) | Sin restricciones. Los usuarios pueden agregar cualquier marketplace |998| Indefinido (predeterminado) | Sin restricciones. Los usuarios pueden agregar cualquier marketplace |

710| Lista de fuentes | Los usuarios solo pueden agregar marketplaces que coincidan exactamente con la lista de permitidos |1000| Lista de fuentes | Lista de permitidos aplicada. Los usuarios solo pueden agregar marketplaces que coincidan con una entrada |

711 1001

712<h4 id="common-configurations">1002<h4 id="common-configurations">

713 Configuraciones comunes1003 Configuraciones comunes

714</h4>1004</h4>

715 1005

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

717 1007

718```json theme={null}1008```json theme={null}

719{1009{

721}1011}

722```1012```

723 1013

1014Permitir 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:

1015

1016```json theme={null}

1017{

1018 "strictKnownMarketplaces": [

1019 {

1020 "source": "github",

1021 "repo": "anthropics/claude-plugins-official"

1022 }

1023 ]

1024}

1025```

1026

1027Con 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.

1028

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

1030

1031* Entornos no interactivos que se ejecutan antes del primer lanzamiento interactivo de la máquina.

1032* 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.

1033

1034En estas máquinas, agregue el marketplace a [`extraKnownMarketplaces`](/docs/es/settings-reference#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`.

1035

724Permitir solo marketplaces específicos:1036Permitir solo marketplaces específicos:

725 1037

726```json theme={null}1038```json theme={null}

743}1055}

744```1056```

745 1057

1058Permitir cada repositorio de marketplace bajo una organización de GitHub con una entrada [owner-wildcard](/docs/es/settings-reference#owner-wildcards). Los owner wildcards requieren Claude Code v2.1.223 o posterior.

1059

1060```json theme={null}

1061{

1062 "strictKnownMarketplaces": [

1063 {

1064 "source": "github",

1065 "repo": "acme-corp/*"

1066 }

1067 ]

1068}

1069```

1070

746Permitir 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](/docs/es/github-enterprise-server#plugin-marketplaces-on-ghes) o instancias de GitLab autohospedadas:1071Permitir 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](/docs/es/github-enterprise-server#plugin-marketplaces-on-ghes) o instancias de GitLab autohospedadas:

747 1072

748```json theme={null}1073```json theme={null}

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

773 1098

774<Note>1099<Note>

775 `strictKnownMarketplaces` restringe lo que los usuarios pueden agregar, pero no registra marketplaces por sí solo. Para hacer que los marketplaces permitidos estén disponibles automáticamente sin que los usuarios ejecuten `/plugin marketplace add`, emparéjelo con [`extraKnownMarketplaces`](/docs/es/settings#extraknownmarketplaces) en el mismo `managed-settings.json`. Consulte [Usar ambos juntos](/docs/es/settings#strictknownmarketplaces).1100 `strictKnownMarketplaces` restringe lo que los usuarios pueden agregar, pero no registra marketplaces por sí solo. Para registrar un marketplace permitido para los usuarios automáticamente, agréguelo a [`extraKnownMarketplaces`](/docs/es/settings-reference#extraknownmarketplaces) en el mismo `managed-settings.json`.

1101

1102 El marketplace oficial de Anthropic es el único que Claude Code registra por sí solo, y solo cuando la lista de permitidos lo permite. El registro automático también falta en algunas máquinas, como entornos no interactivos y máquinas donde una política anterior lo bloqueó. Para cubrir esas máquinas, agregue también el marketplace oficial a `extraKnownMarketplaces`. Para los dos ajustes lado a lado, consulte la [referencia de `strictKnownMarketplaces`](/docs/es/settings-reference#strictknownmarketplaces).

776</Note>1103</Note>

777 1104

778<h4 id="how-restrictions-work">1105<h4 id="how-restrictions-work">

781 1108

782Las 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`.1109Las 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`.

783 1110

784La lista de permitidos usa coincidencia exacta para la mayoría de tipos de fuente. Para que un marketplace sea permitido, todos los campos especificados deben coincidir exactamente:1111Para 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](/docs/es/settings-reference#owner-wildcards).

1112

1113Cuando un usuario agrega una URL de repositorio `https://` que Claude Code [clona en lugar de obtener](/docs/es/discover-plugins#add-from-other-git-hosts), 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.

1114

1115La 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:

785 1116

786* Para fuentes de GitHub: `repo` es requerido, y `ref` o `path` también deben coincidir si se especifican en la lista de permitidos1117* 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](/docs/es/settings-reference#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`

787* Para fuentes de URL: la URL completa debe coincidir exactamente1118* Para fuentes de URL: la URL completa debe coincidir exactamente

788* Para fuentes `hostPattern`: el host del marketplace se compara contra el patrón regex1119* Para fuentes `hostPattern`: el host del marketplace se compara contra el patrón regex

789* Para fuentes `pathPattern`: la ruta del sistema de archivos del marketplace se compara contra el patrón regex1120* Para fuentes `pathPattern`: la ruta del sistema de archivos del marketplace se compara contra el patrón regex

790 1121

791La coincidencia exacta no normaliza URLs: una barra diagonal final, sufijo `.git` o forma `ssh://` versus `https://` se tratan 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 coincidan.1122La 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.

792 1123

793Debido a que `strictKnownMarketplaces` se establece en [configuración administrada](/docs/es/settings#settings-files), los usuarios individuales y las configuraciones del proyecto no pueden anular estas restricciones.1124Debido a que `strictKnownMarketplaces` se establece en [configuración administrada](/docs/es/managed-settings), los usuarios individuales y las configuraciones del proyecto no pueden anular estas restricciones.

794 1125

795Para detalles de configuración completos incluyendo todos los tipos de fuente soportados y comparación con `extraKnownMarketplaces`, consulte la [referencia de strictKnownMarketplaces](/docs/es/settings#strictknownmarketplaces).1126Para detalles de configuración completos incluyendo todos los tipos de fuente soportados y comparación con `extraKnownMarketplaces`, consulte la [referencia de strictKnownMarketplaces](/docs/es/settings-reference#strictknownmarketplaces).

796 1127

797<h3 id="version-resolution-and-release-channels">1128<h3 id="version-resolution-and-release-channels">

798 Resolución de versiones y canales de lanzamiento1129 Resolución de versiones y canales de lanzamiento

799</h3>1130</h3>

800 1131

801Las 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.1132Las 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](/docs/es/plugins-reference#version-management) para el orden de resolución completo, incluidas fuentes `archive`.

~~802~~

803Claude Code resuelve la versión de un plugin desde el primero de estos que esté establecido:

~~804~~

8051. `version` en el `plugin.json` del plugin

8062. `version` en la entrada del marketplace del plugin

8073. El SHA del commit de git de la fuente del plugin

~~808~~

809Para los tipos de fuente basados en git `github`, `url`, `git-subdir` y rutas relativas dentro de un marketplace alojado en git, puede omitir `version` completamente y cada nuevo commit se trata como una nueva versión. Esta es la configuración más simple para plugins internos o en desarrollo activo.

810 1133

811<Warning>1134<Warning>

812 Establecer `version` fija el plugin. Si `plugin.json` declara `"version": "1.0.0"`, empujar nuevos commits sin cambiar esa cadena no hace nada para usuarios existentes, porque Claude Code ve la misma versión y mantiene la copia en caché. Aumente el campo en cada lanzamiento, u omítalo para usar el SHA del commit.1135 Establecer `version` fija el plugin para cada tipo de fuente excepto [`command`](#command-sources), cuya versión siempre incluye un hash de lo que el comando produjo. Si declara `"version": "1.0.0"` en `plugin.json` e inserta nuevos commits sin cambiar esa cadena, los usuarios existentes de esas fuentes mantienen la copia en caché, porque Claude Code ve la misma versión. Aumente el campo en cada lanzamiento, u omítalo para recurrir a la versión resuelta.

813 1136

814 Evite establecer `version` en ambos `plugin.json` y la entrada del marketplace. El valor de `plugin.json` siempre gana silenciosamente, por lo que una versión de manifiesto obsoleta puede enmascarar una versión que estableció en `marketplace.json`.1137 Evite establecer `version` en ambos `plugin.json` y la entrada del marketplace. El valor de `plugin.json` siempre gana silenciosamente, por lo que una versión de manifiesto obsoleta puede enmascarar una versión que estableció en `marketplace.json`.

815</Warning>1138</Warning>

818 Configurar canales de lanzamiento1141 Configurar canales de lanzamiento

819</h4>1142</h4>

820 1143

821Para 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 los dos marketplaces a diferentes grupos de usuarios a través de [configuración administrada](/docs/es/settings#settings-files).1144Para 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:

1145

1146* Implemente [configuración administrada gestionada por endpoint](/docs/es/managed-settings#delivery-mechanisms) 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](/docs/es/managed-settings#precedence-within-the-managed-tier) dice si el archivo o perfil por grupo se aplica en un dispositivo que también tiene una fuente de toda la organización.

1147* Defina una [política de puerta de enlace de aplicaciones Claude](/docs/es/claude-apps-gateway-config#managed) 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.

1148

1149La configuración administrada gestionada por servidor [se aplica a cada usuario en su organización](/docs/es/server-managed-settings#current-limitations), por lo que no pueden llevar una asignación por grupo.

822 1150

823<Warning>1151<Warning>

824 Cada canal debe resolver a una versión diferente. Si usa versiones explícitas, `plugin.json` debe declarar una `version` diferente en cada ref fijado. Si omite `version`, los SHAs de commit distintos ya distinguen los canales. Si dos refs resuelven a la misma cadena de versión, Claude Code los trata como idénticos y omite la actualización.1152 Cada canal debe resolver a una versión diferente. Si usa versiones explícitas, `plugin.json` debe declarar una `version` diferente en cada ref fijado. Si omite `version`, los SHAs de commit distintos ya distinguen los canales. Si dos refs resuelven a la misma cadena de versión, Claude Code los trata como idénticos y omite la actualización.

864 Asignar canales a grupos de usuarios1192 Asignar canales a grupos de usuarios

865</h5>1193</h5>

866 1194

867Asigne cada marketplace al grupo de usuarios apropiado a través de configuración administrada. Por ejemplo, el grupo estable recibe:1195Asigne 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](#set-up-release-channels). Por ejemplo, el grupo estable recibe:

868 1196

869```json theme={null}1197```json theme={null}

870{1198{

944 1272

945Pruebe su marketplace antes de compartirlo.1273Pruebe su marketplace antes de compartirlo.

946 1274

947Valide la sintaxis JSON de su marketplace:1275Desde su directorio de marketplace, valide la sintaxis JSON:

948 1276

949```bash theme={null}1277```bash theme={null}

950claude plugin validate .1278claude plugin validate .

1057| :------- | :--------------- |1385| :------- | :--------------- |

1059 1387

1060Con `--json`, cada entrada incluye `name`, `source` 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.1388Con `--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.

1061 1389

1062<h3 id="plugin-marketplace-remove">1390<h3 id="plugin-marketplace-remove">

1063 Plugin marketplace remove1391 Plugin marketplace remove

1113 1441

1114* Verifique que la URL del marketplace sea accesible1442* Verifique que la URL del marketplace sea accesible

1115* Compruebe que `.claude-plugin/marketplace.json` existe en la ruta especificada1443* Compruebe que `.claude-plugin/marketplace.json` existe en la ruta especificada

1116* Asegúrese de que la sintaxis JSON sea válida usando `claude plugin validate` o `/plugin validate`. Para verificar el frontmatter de skill, agente y comando, ejecute el comando contra cada directorio de plugin1444* 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](#validate-a-plugin-or-a-directory-without-a-manifest)

1117* Para repositorios privados, confirme que tiene permisos de acceso1445* Para repositorios privados, confirme que tiene permisos de acceso

1118 1446

1119<h3 id="marketplace-validation-errors">1447<h3 id="marketplace-validation-errors">

1130 1458

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

1132 1460

1133Para validar el `plugin.json` de un plugin individual y sus archivos de skill, agente, comando y hook, ejecute el comando contra el directorio del plugin en sí, por ejemplo `claude plugin validate ./plugins/my-plugin`. Errores comunes:1461Desde 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](#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:

1134 1462

1136| :------------------------------------------------ | :----------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1464| :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1137| `File not found: .claude-plugin/marketplace.json` | Manifiesto faltante | Cree `.claude-plugin/marketplace.json` con campos requeridos |1465| `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 |

1140| `plugins[0].source: Path contains ".."` | La ruta de fuente contiene `..` | Use rutas relativas a la raíz del marketplace sin `..`. Consulte [Rutas relativas](#relative-paths) |1468| `plugins[0].source: Path contains ".."` | La ruta de fuente contiene `..` | Use rutas relativas a la raíz del marketplace sin `..`. Consulte [Rutas relativas](#relative-paths) |

1141| `YAML frontmatter failed to parse: ...` | YAML inválido en un archivo de skill, agente o comando | Corrija la sintaxis YAML en el bloque frontmatter. En tiempo de ejecución este archivo se carga sin metadatos. Se reporta solo cuando se valida un directorio de plugin |1469| `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` |

1142| `Invalid JSON syntax: ...` (hooks.json) | `hooks/hooks.json` malformado | Corrija la sintaxis JSON. Un `hooks/hooks.json` malformado previene que todo el plugin se cargue. Se reporta solo cuando se valida un directorio de plugin |1470| `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 |

1143 1471

1144**Advertencias** (no bloqueantes):1472**Advertencias** (no bloqueantes):

1145 1473

1146* `Marketplace has no plugins defined`: agregue al menos un plugin al array `plugins`1474* `Marketplace has no plugins defined`: agregue al menos un plugin al array `plugins`

1147* `No marketplace description provided`: agregue una `description` de nivel superior para ayudar a los usuarios a entender su marketplace1475* `No marketplace description provided`: agregue una `description` de nivel superior para ayudar a los usuarios a entender su marketplace

1148* `Plugin name "x" is not kebab-case`: el nombre del plugin contiene letras mayúsculas, espacios o caracteres especiales. 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.1476* `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.

1477* `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.

1478* `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.

1479

1480<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">

1481 Validate a plugin or a directory without a manifest

1482</h4>

1483

1484Para 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.

1485

1486<h5 id="pick-the-directory-to-name">

1487 Pick the directory to name

1488</h5>

1489

1490Claude 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:

1491

1492| To check | Run | Claude Code checks |

1493| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1494| 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 |

1495| 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 |

1496| 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 |

1497| 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` |

1498| Your user-level directories | `claude plugin validate ~/.claude` | `~/.claude/skills`, `~/.claude/agents` y `~/.claude/commands` |

1499

1500<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">

1501 Check a plugin whose skill is its root `SKILL.md`

1502</h5>

1503

1504Cuando 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:

1505

1506* Nombre ese directorio `skills` para verificar el `SKILL.md` raíz del plugin.

1507* Nombre el directorio del plugin para verificar el resto.

1508

1509Cuando 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.

1510

1511<h5 id="check-files-behind-symlinks">

1512 Check files behind symlinks

1513</h5>

1514

1515Cuando 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:

1516

1517* **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.

1518* **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.

1519* **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.

1520

1521En 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:

1522

1523* **Un plugin cuyo directorio `skills` [vincula a los skills de un plugin hermano](/docs/es/plugins-reference#share-files-within-a-marketplace-with-symlinks)**: nombre el directorio del plugin hermano.

1524* **Una [entrada de skill vinculada](/docs/es/skills#where-skills-live) en `~/.claude/skills` o `.claude/skills`**: Claude Code sigue la entrada en una sesión. Para verificarla, nombre un directorio llamado `skills` que contenga la carpeta real.

1525

1526<h5 id="read-the-validation-results">

1527 Read the validation results

1528</h5>

1529

1530Una ejecución limpia termina con `Validation passed`.

1531

1532`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.

1533

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

1535

1536* `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

1537* `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

1538

1539En 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](/docs/es/plugins-reference#component-path-fields) en `plugin.json`, Claude Code verifica que cada ruta exista pero no lee los archivos allí.

1149 1540

1150<h3 id="plugin-installation-failures">1541<h3 id="plugin-installation-failures">

1151 Fallos de instalación de plugins1542 Fallos de instalación de plugins

1172Para instalación manual y actualizaciones:1563Para instalación manual y actualizaciones:

1173 1564

1174* Verifique que esté autenticado con su proveedor de git (por ejemplo, ejecute `gh auth status` para GitHub)1565* Verifique que esté autenticado con su proveedor de git (por ejemplo, ejecute `gh auth status` para GitHub)

1175* Compruebe que su ayudante de credenciales esté configurado correctamente: `git config --global credential.helper`1566* Compruebe que su ayudante de credenciales esté configurado: `git config --global credential.helper`

1176* Intente clonar el repositorio manualmente para verificar que sus credenciales funcionan1567* 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`

1177 1568

1178Para actualizaciones automáticas en segundo plano:1569Para actualizaciones automáticas en segundo plano:

1179 1570

1198export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11589export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1199```1590```

1200 1591

1201Con esta variable establecida, Claude Code retiene el clon obsoleto del marketplace en fallo de `git pull` y continúa usando el último estado conocido bueno. Para implementaciones completamente sin conexión donde el repositorio nunca será alcanzable, use [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) para precargar el directorio de plugins en tiempo de compilación en su lugar.1592Para implementaciones completamente sin conexión donde el repositorio nunca será alcanzable, use [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) para precargar el directorio de plugins en tiempo de compilación en su lugar.

1202 1593

1203<h3 id="git-operations-time-out">1594<h3 id="git-operations-time-out">

1204 Las operaciones de Git agotan el tiempo de espera1595 Las operaciones de Git agotan el tiempo de espera

1220 1611

1221**Síntomas**: Agregó un marketplace a través de URL (como `https://example.com/marketplace.json`), pero los plugins con fuentes de ruta relativa como `"./plugins/my-plugin"` fallan al instalar con errores "path not found".1612**Síntomas**: Agregó un marketplace a través de URL (como `https://example.com/marketplace.json`), pero los plugins con fuentes de ruta relativa como `"./plugins/my-plugin"` fallan al instalar con errores "path not found".

1222 1613

1223**Causa**: Los marketplaces basados en URL solo descargan el archivo `marketplace.json` en sí. No descargan archivos de plugins del servidor. Las rutas relativas en la entrada del marketplace hacen referencia a archivos en el servidor remoto que no fueron descargados.1614**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.

1224 1615

1225**Soluciones**:1616**Soluciones**:

1226 1617

1227* **Use fuentes externas**: Cambie las entradas de plugins para usar fuentes de GitHub, npm o URL de git en lugar de rutas relativas:1618* **Use fuentes externas**: cambie las entradas de plugins a cualquier [plugin source](#plugin-sources) que no sea una ruta relativa:

1228 ```json theme={null}1619 ```json theme={null}

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

1230 ```1621 ```

1236 1627

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

1238 1629

1239**Causa**: Los plugins se copian a un directorio de caché en lugar de usarse en el lugar. Las rutas que hacen referencia a archivos fuera del directorio del plugin (como `../shared-utils`) no funcionarán porque esos archivos no se copian.1630**Causa**: Los plugins se copian a un directorio de caché en lugar de usarse en el lugar, excepto para una [`command` source in link mode](#copy-mode-and-link-mode). 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.

1240 1631

1241**Soluciones**: Consulte [Plugin caching and file resolution](/docs/es/plugins-reference#plugin-caching-and-file-resolution) para soluciones alternativas incluyendo enlaces simbólicos y reestructuración de directorios.1632**Soluciones**: Consulte [Plugin caching and file resolution](/docs/es/plugins-reference#plugin-caching-and-file-resolution) para soluciones alternativas incluyendo enlaces simbólicos y reestructuración de directorios.

1242 1633

1249* [Descubrir e instalar plugins precompilados](/docs/es/discover-plugins) - Instalación de plugins desde marketplaces existentes1640* [Descubrir e instalar plugins precompilados](/docs/es/discover-plugins) - Instalación de plugins desde marketplaces existentes

1250* [Plugins](/docs/es/plugins) - Creación de sus propios plugins1641* [Plugins](/docs/es/plugins) - Creación de sus propios plugins

1251* [Referencia de plugins](/docs/es/plugins-reference) - Especificaciones técnicas completas y esquemas1642* [Referencia de plugins](/docs/es/plugins-reference) - Especificaciones técnicas completas y esquemas

1252* [Configuración de plugins](/docs/es/settings#plugin-settings) - Opciones de configuración de plugins1643* [Configuración de plugins](/docs/es/settings-reference#plugin-settings) - Opciones de configuración de plugins

1253* [Referencia de strictKnownMarketplaces](/docs/es/settings#strictknownmarketplaces) - Restricciones de marketplace administrado1644* [Referencia de strictKnownMarketplaces](/docs/es/settings-reference#strictknownmarketplaces) - Restricciones de marketplace administrado

plugin-marketplaces.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

Crear y distribuir un marketplace de plugins

Descripción general

Tutorial: crear un marketplace local

Crear la estructura de directorios

Crear la skill

Crear el manifiesto del plugin

Crear el archivo de marketplace

Agregar e instalar

Pruébelo

Crear el archivo de marketplace

Esquema de marketplace

Campos requeridos

Campos del propietario

Campos opcionales

Entradas de plugins

Campos requeridos

Campos de plugin opcionales

Fuentes de plugins

Rutas relativas

Repositorios de GitHub

Repositorios de Git

Subdirectorios de Git

Paquetes npm

Archivos zip

Autenticar descargas de archivos

Agregar un headersHelper a una entrada de plugin

Escribir el comando headersHelper

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

Cómo los usuarios aceptan un comando headersHelper

Instalaciones y actualizaciones que rechazan el comando en lugar de preguntar

Cuándo se ejecuta el comando headersHelper de una fuente `url` del marketplace

Fuentes de comando

Modo de copia y modo de enlace

Cómo los usuarios aceptan el comando

Cuándo Claude Code vuelve a ejecutar el comando

Entradas de plugins avanzadas

Modo estricto

Alojar y distribuir marketplaces

Alojar en GitHub (recomendado)

Alojar en otros servicios de git

Repositorios privados

Comandos que ejecuta

Actualizaciones automáticas en segundo plano

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

Mantener ejecutables fuera del directorio bin de nivel superior

Requerir marketplaces para su equipo

Precargar plugins para contenedores

Restricciones de marketplace administrado

Configuraciones comunes

Cómo funcionan las restricciones

Resolución de versiones y canales de lanzamiento

Configurar canales de lanzamiento

Ejemplo

Asignar canales a grupos de usuarios

Fijar versiones de dependencias

Renombrar o eliminar un plugin

Validación y pruebas

Administrar marketplaces desde la CLI

Plugin marketplace add

Plugin marketplace list

Plugin marketplace remove

Plugin marketplace update

Solución de problemas

Marketplace no se carga

Errores de validación de marketplace

Validate a plugin or a directory without a manifest

Pick the directory to name

Check a plugin whose skill is its root `SKILL.md`

Check files behind symlinks

Read the validation results

Fallos de instalación de plugins

La autenticación del repositorio privado falla

Las actualizaciones del marketplace fallan en entornos sin conexión

Las operaciones de Git agotan el tiempo de espera

Los plugins con rutas relativas fallan en marketplaces basados en URL

Archivos no encontrados después de la instalación

Ver también