SpyBara
Go Premium

plugins/marketplace-reference.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 533 additions and 0 deletions.

2026
Fri 25 23:58

Referencia de Marketplace

Referencia completa de los campos marketplace.json, entradas de plugins y los objetos de origen de plugin y marketplace, con dónde es válido cada uno.

marketplace.json es el archivo que define un marketplace de plugins. Contiene el nombre del marketplace, su propietario y una entrada por cada plugin. La fuente de plugin de cada entrada indica dónde Claude Code obtiene ese plugin.

Una fuente de marketplace es un objeto separado que indica dónde Claude Code obtiene el archivo marketplace en sí. Usted escribe uno en la configuración, o Claude Code construye uno cuando ejecuta claude plugin marketplace add.

Esta referencia es para los mantenedores de marketplace que necesitan un nombre de campo o valor exacto, y para los administradores que necesitan saber qué valores de source son válidos en extraKnownMarketplaces, strictKnownMarketplaces y blockedMarketplaces.

Encuentre la sección para lo que está escribiendo o leyendo:

Archivo marketplace

Guarde el archivo marketplace en .claude-plugin/marketplace.json en el directorio de su marketplace. Si mantiene el archivo en otro lugar del repositorio, los usuarios tienen que declarar el marketplace en extraKnownMarketplaces con path establecido en su fuente, porque claude plugin marketplace add no tiene opción para ello.

El directorio que contiene .claude-plugin/ se llama raíz del marketplace, y cada fuente de plugin relativa se resuelve desde él, no desde .claude-plugin/.

Cada usuario registra un marketplace por name, por lo que un usuario no puede tener dos marketplaces con el mismo nombre registrados a la vez.

Claude Code ignora una clave de nivel superior desconocida o una clave de entrada de plugin en lugar de rechazarla, por lo que un error tipográfico se carga silenciosamente. claude plugin validate reporta cada clave desconocida como una advertencia.

Nombres reservados

No puede dar a su marketplace ninguno de los siguientes nombres:

  • Nombres de marketplace oficial: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, life-sciences, knowledge-work-plugins, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins y claude-tag-plugins. Reservado a menos que el marketplace provenga de una fuente de marketplace github o git bajo github.com/anthropics/.
  • Nombres de marketplace comunitario: claude-community, claude-plugins-community y healthcare. Reservado bajo la misma regla que los nombres oficiales.
  • Nombres de directorio de plugins: anthropic-plugin-directory y claude-plugin-directory. Reservado bajo la misma regla que los nombres oficiales.
  • Nombres que suplanten un marketplace oficial: nombres como official-claude-plugins o claude-plugins-v2, y cualquier nombre que contenga un carácter no ASCII. El error es Marketplace name impersonates an official Anthropic/Claude marketplace. Un carácter de control o de formato bidireccional en un nombre también reporta Marketplace name cannot contain control or bidirectional-formatting characters.
  • Otra ortografía de un nombre reservado: un nombre que difiere de un nombre reservado solo por un punto final, o por un símbolo distinto de un guión en lugar de un guión, por lo que claude.code.plugins cuenta como claude-code-plugins. claude plugin validate acepta tal nombre; agregar el marketplace falla con is another spelling of "<reserved>", a reserved marketplace name, y un marketplace ya registrado bajo uno deja de cargarse. Esta verificación requiere Claude Code v2.1.280 o posterior.
  • Nombres que Claude Code usa para plugins que no provienen de un marketplace: inline para plugins cargados con --plugin-dir, builtin para plugins integrados, skills-dir para plugins cargados automáticamente desde .claude/skills/ y synced para plugins sincronizados desde su cuenta claude.ai. claude-plugin-test también está reservado. skills-dir también aparece como {"source": "skills-dir"} en strictKnownMarketplaces y blockedMarketplaces, descrito bajo Valores de fuente válidos solo en listas de políticas.
  • npm, pip, uv, cargo, github y gh: reservado en cualquier mayúscula. Esta verificación requiere Claude Code v2.1.275 o posterior.
  • Nombres que comienzan con claudeai-: reservado para marketplaces alojados en claude.ai. claude plugin marketplace add rechaza cualquier otro marketplace que use uno con Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai.

Campos de nivel superior

La tabla enumera cada clave que Claude Code lee de marketplace.json. name, owner y plugins son obligatorios.

Campo Tipo Descripción
name string Identificador de marketplace. Sin espacios, caracteres de control o caracteres de formato bidireccional, sin / o \, sin .. y no .. Consulte Nombres reservados. Los usuarios lo escriben después de @ cuando instalan un plugin
owner object Información del mantenedor. name es obligatorio; email y url son opcionales
plugins array Entradas de plugins. Cada entrada se valida por sí sola, por lo que una entrada inválida no falla el marketplace
$schema string URL de JSON Schema para autocompletado del editor. Se ignora en tiempo de carga
description string Descripción del marketplace mostrada a los usuarios. claude plugin validate advierte cuando falta
version string Versión del manifiesto del marketplace
metadata.description, metadata.version string Ubicación alternativa para description y version
metadata.pluginRoot string Directorio bajo el cual se resuelven los nombres de fuente de plugin desnudos. Consulte Fuente de plugin de ruta relativa. Requiere Claude Code v2.1.239 o posterior
forceRemoveDeletedPlugins boolean Cuando es true, un plugin que elimina de plugins se desinstala en las máquinas de los usuarios. Consulte Alojar y mantener un marketplace
allowCrossMarketplaceDependenciesOn array of strings Nombres de marketplace cuyos plugins pueden instalarse como dependencias de los plugins de este marketplace. Cuando instala un plugin, solo se aplica la lista en el propio marketplace del plugin, para toda su cadena de dependencias. Consulte Dependencias de plugins
renames object Mapa de un name de plugin anterior a su nombre actual, o a null para un plugin que eliminó. Requiere Claude Code v2.1.193 o posterior. Consulte Alojar y mantener un marketplace

Entradas de plugins

Cada objeto en el array plugins de nivel superior de marketplace.json nombra un plugin e indica dónde obtenerlo. name y source son obligatorios.

Una entrada también acepta cada campo de plugin.json, como description, version, author, commands y hooks. Para cuándo se aplican esos campos, consulte Cómo una entrada se combina con plugin.json.

La tabla enumera los campos propios de la entrada y los campos del manifiesto cuyo significado cambia en una entrada.

Campo Tipo Descripción
name string Identificador de plugin, sin espacios, caracteres de control o caracteres de formato bidireccional. Los usuarios lo escriben antes de @ cuando instalan, incluso cuando el propio plugin.json del plugin establece un name diferente
source string or object Dónde obtener el plugin. Consulte Fuentes de plugins
description string Se muestra en los listados y detalles de /plugin
version string Cadena de versión para el plugin. Cuando plugin.json también establece version, plugin.json tiene precedencia y claude plugin validate advierte. Consulte Referencia de carga de plugins
category string Categoría de forma libre para organizar el catálogo
tags array of strings Etiquetas de forma libre para búsqueda
strict boolean Por defecto true. Si plugin.json es la fuente definitiva para los componentes del plugin. Consulte Modo estricto
relevance object Señales que indican a Claude Code cuándo sugerir el plugin. Consulte Recomendar plugins para su organización
dependencies array Plugins que deben estar habilitados para que este funcione. Cada elemento es "name", "name@marketplace" u un objeto. Consulte Dependencias de plugins
defaultEnabled boolean Por defecto true. Si el plugin comienza habilitado cuando el usuario no lo ha establecido en enabledPlugins. El valor de la entrada tiene precedencia sobre plugin.json
displayName string Nombre legible por humanos mostrado en la interfaz de usuario. Cuando ni la entrada ni el plugin.json del plugin establece uno, los usuarios ven el name del plugin
metadata object Objeto de forma libre para sus propios campos. Claude Code no lo lee. Requiere Claude Code v2.1.222 o posterior
headers object Encabezados HTTP que Claude Code envía cuando descarga el archivo de esta entrada. Un encabezado establecido aquí reemplaza un encabezado del mismo nombre de los headers de la fuente del marketplace. Requiere Claude Code v2.1.238 o posterior
headersHelper string Comando que imprime los encabezados de descarga de archivo de esta entrada como un objeto JSON, para una credencial que expira. La entrada también debe establecer "strict": false. Requiere Claude Code v2.1.238 o posterior. Consulte Autenticar descargas de archivos

Cómo una entrada se combina con plugin.json

Los campos de la entrada se aplican de manera diferente a un plugin obtenido que tiene su propio .claude-plugin/plugin.json y a uno que no:

  • Sin plugin.json: la entrada es el manifiesto independientemente de strict. Cada campo de manifiesto en la entrada se aplica, incluidos mcpServers, lspServers, userConfig y channels.
  • plugin.json presente: plugin.json es el manifiesto. Modo estricto decide si los seis campos de componente de la entrada, commands, agents, skills, hooks, outputStyles y themes, se combinan con él o se rechazan como un conflicto. La entrada mcpServers, lspServers, userConfig y channels no se aplican. Declárelos en plugin.json.

Hooks en una entrada

Escriba hooks de entrada como un objeto en línea que asigne nombres de eventos de hook a arrays de coincidencia. Si escribe una ruta de archivo o un array en su lugar, claude plugin validate lo aprueba. Esos hooks nunca se ejecutan, y Claude Code reporta un error not yet supported in a marketplace entry para el plugin. Coloque hooks basados en archivos en el propio hooks/hooks.json del plugin o plugin.json.

Campos de visualización

Tanto la entrada como el propio plugin.json del plugin pueden establecer los campos de visualización displayName, description, author, homepage, repository, license y keywords. Los usuarios ven estos valores en los listados y detalles de plugins, antes y después de instalar:

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

Antes de instalar, Claude Code solo puede leer plugin.json para entradas con una fuente de ruta relativa, cuyos archivos de plugin están dentro del marketplace en sí. Para una entrada con cualquier otro tipo de fuente, los usuarios ven solo los campos propios de la entrada hasta que instalen el plugin.

Modo estricto

strict decide qué sucede cuando el plugin obtenido tiene su propio plugin.json y la entrada también declara cualquiera de los campos de componente: commands, agents, skills, hooks, outputStyles o themes. Con strict: true, el predeterminado, Claude Code añade los campos de componente de la entrada a plugin.json, excepto hooks, cuyos coincidentes reemplazan los del manifiesto por evento. Con strict: false, una entrada que declara cualquier campo de componente es un conflicto, y el plugin falla al cargar. La tabla muestra cada combinación de strict, plugin.json y los campos de componente de la entrada.

strict plugin.json Campos de componente de entrada Resultado
any absent any La entrada es el manifiesto
true, el predeterminado present any plugin.json es la autoridad. Claude Code añade los campos de componente de la entrada a él, excepto hooks, cuyos coincidentes reemplazan los del manifiesto por evento
false present none plugin.json es el manifiesto, como con true
false present one or more Conflicto. El plugin falla al cargar con Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components

Fuentes de plugins

El source de una entrada de plugin indica dónde Claude Code obtiene ese plugin. Es una cadena de ruta relativa u un objeto cuya propia clave source nombra el tipo, por lo que una entrada se ve como "source": { "source": "github", "repo": "your-org/formatter" }.

La tabla enumera cada tipo de fuente de plugin y sus campos.

Tipo Campos Notas
Ruta relativa la cadena en sí Un directorio dentro del marketplace, resuelto desde la raíz del marketplace. Debe comenzar con ./, a menos que escriba un nombre desnudo bajo metadata.pluginRoot. "." por sí solo significa la raíz en sí
github repo, ref, sha Repositorio de GitHub en forma owner/repo
url url, ref, sha Cualquier repositorio git por URL
git-subdir url, path, ref, sha Un subdirectorio de un repositorio git, obtenido con un clon parcial disperso
npm package, version, registry Paquete npm, obtenido con su cliente npm y desempaquetado sin ejecutar scripts de instalación
archive url, sha256 Archivo Zip sobre HTTPS. Requiere Claude Code v2.1.224 o posterior
command command, timeout, mode Directorio impreso por un comando que Claude Code ejecuta en la máquina del usuario. Requiere Claude Code v2.1.229 o posterior

Los nombres url y github también son tipos de fuente de marketplace, donde url significa un enlace directo a un archivo marketplace.json en lugar de un repositorio git. git existe solo como una fuente de marketplace, y npm existe como ambas. git-subdir, archive y command existen solo como fuentes de plugins.

Use una ruta relativa para un plugin en un subdirectorio del repositorio del marketplace en sí. Use git-subdir para un subdirectorio de algún otro repositorio.

Las fuentes github, url y git-subdir comparten los campos ref y sha:

  • ref: una rama o etiqueta. Por defecto es la rama predeterminada del repositorio.
  • sha: un SHA de commit completo de 40 caracteres en minúsculas. Cuando establece tanto ref como sha, Claude Code verifica sha. En la mayoría de hosts 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 admiten obtener commits por SHA. En esos servidores, el ref aún debe existir y el commit fijado debe ser alcanzable desde él.

Para cómo se obtiene, almacena en caché y versiona cada tipo, consulte Referencia de carga de plugins.

Fuente de plugin de ruta relativa

La ruta se resuelve desde la raíz del marketplace. ./plugins/formatter es <root>/plugins/formatter aunque el archivo marketplace esté en <root>/.claude-plugin/.

Una ruta que contiene .. falla la validación. En macOS y Linux, Claude Code rechaza una ruta de entrada que contiene una barra invertida en cualquier lugar después del ./ inicial, por lo que escriba la ruta con barras diagonales.

{ "name": "formatter", "source": "./plugins/formatter" }

Una ruta relativa se resuelve solo cuando Claude Code tiene los archivos del marketplace, así que verifique el tipo de fuente de marketplace:

  • github, git, file y directory: Claude Code tiene los archivos del marketplace.
  • url: Claude Code obtiene solo marketplace.json, por lo que las rutas relativas no pueden resolverse. Dé a cada plugin una fuente de objeto en su lugar, como github o git-subdir.
  • settings: las rutas relativas se rechazan directamente.

Nombres desnudos bajo pluginRoot

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

metadata.pluginRoot tiene estos límites:

  • Debe ser en sí una ruta relativa dentro del marketplace.
  • No tiene efecto en una fuente que ya comienza con ./.
  • Una fuente que contiene un /, como team-a/formatter, no es un nombre desnudo y aún necesita el prefijo ./, incluso cuando metadata.pluginRoot está establecido.

Fuente de plugin github

repo toma owner/repo. ref y sha son opcionales.

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Fuente de plugin url

url es una URL git completa: https://, http://, file:// o git@. Un sufijo .git no es obligatorio, por lo que las URL de Azure DevOps y AWS CodeCommit funcionan tal como están escritas. Este tipo no toma el atajo owner/repo.

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

Fuente de plugin git-subdir

url acepta una URL git completa o el atajo owner/repo de GitHub. path es el subdirectorio que contiene el plugin, y Claude Code descarga solo ese subdirectorio.

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

Fuente de plugin npm

Una fuente npm toma estos campos:

  • package: un nombre de paquete, o un nombre con alcance como @your-org/formatter
  • version: una versión o rango
  • registry: una URL de registro para un paquete que no está en el registro predeterminado

Claude Code obtiene el paquete con su cliente npm. Los scripts de instalación del paquete, como preinstall o postinstall, nunca se ejecutan, y sus dependencias no se instalan durante la obtención. Si el paquete tiene un archivo de bloqueo compatible junto a su package.json, Claude Code instala esas dependencias de paquetes Node.js en un paso separado, también con scripts deshabilitados.

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Fuente de plugin archive

url debe usar https:// y no puede apuntar a un host de loopback, link-local o cloud-metadata.

La raíz del plugin puede estar en la parte superior del zip o un directorio hacia abajo.

sha256 es el resumen del archivo como 64 caracteres hexadecimales, mayúsculas o minúsculas. Cuando lo establece, Claude Code rechaza una descarga que no coincida.

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Fuente de plugin command

Use una fuente command cuando una herramienta instalada en la máquina del usuario produce el directorio del plugin, como un IDE que renderiza su plugin para la cadena de herramientas que el usuario ha seleccionado. Claude Code ejecuta el comando cuando el usuario instala o actualiza el plugin, y nuevamente una vez por sesión, por lo que los usuarios obtienen la salida cambiada de la herramienta sin reinstalar.

Una fuente command toma estos campos:

  • command: un comando de shell que imprime la ruta absoluta del directorio del plugin como una línea y sale con 0. Claude Code muestra a los usuarios la cadena completa para revisión antes de ejecutarla. Escríbala como ASCII imprimible, como máximo 500 caracteres, sin una ejecución de cuatro o más espacios.
  • timeout: un número entero de segundos de 1 a 600. Por defecto es 60.
  • mode: copy, el predeterminado, o link. Consulte Modo de copia y modo de enlace.
{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

Para cómo los usuarios aceptan el comando, consulte Instalar desde su shell. Para lo que los usuarios ven después de que lo cambia, consulte Cambiar el comando de una fuente de comando. Los administradores desactivan las fuentes de comando con disableCommandPluginSources.

Qué debe hacer el comando

Escriba el comando para cumplir con estos requisitos:

  • Shell y directorio de trabajo: Claude Code ejecuta el comando a través de sh, o a través de cmd.exe en Windows, desde el directorio de inicio del usuario. Dé una ruta absoluta o un comando en PATH.
  • Salida: imprima exactamente una línea en stdout, la ruta absoluta del directorio del plugin, y salga con 0 dentro de timeout segundos.
  • Contenido del directorio: el directorio contiene el plugin completo en el momento en que el comando sale. La ruta puede diferir de una ejecución a la siguiente.

Salida que falla la instalación o actualización

La instalación o actualización falla cuando el comando sale con un código distinto de cero, se ejecuta más tiempo que timeout, o imprime algo que no sea una ruta absoluta. También falla cuando el directorio impreso es uno de estos:

  • Sin contenido de plugin: el directorio impreso no tiene contenido de plugin en su nivel superior, como un directorio .claude-plugin/ o un directorio skills/, commands/, agents/ o hooks/.
  • El directorio de la propia sesión: el directorio impreso es el en el que se inició Claude Code, o uno de sus padres.
  • Una ruta de red: en Windows, la ruta impresa es una ruta UNC.
  • Demasiado grande para copiar: en modo de copia, el directorio es más grande que 256 MiB o tiene más de 20,000 entradas.

mode decide si Claude Code copia el directorio impreso o lo usa en su lugar:

  • copy: Claude Code copia el directorio en el caché de plugins y deriva la versión del plugin de un hash de los archivos copiados. Su herramienta puede eliminar o reescribir el directorio después de que el comando salga. Una re-ejecución que produce archivos idénticos cuenta como actualizado.
  • link: Claude Code llena la entrada de caché del plugin con un enlace a cada entrada de nivel superior del directorio impreso y carga los archivos en su lugar. Nada se copia, los contenidos de los archivos no se hashean, y los límites de tamaño no se aplican. Úselo para un directorio demasiado grande para copiar, como una exportación de SDK renderizada.

Un plugin en modo de enlace tiene estos requisitos:

  • Mantenga el directorio en su lugar: Claude Code carga el plugin a través de los enlaces en cada inicio, por lo que el directorio impreso debe permanecer donde está mientras el plugin permanezca instalado.
  • Imprima una ruta diferente para señalar contenido nuevo: la versión proviene de la ruta real del directorio impreso y sus entradas de nivel superior, no de los archivos dentro de ellas.
  • Mantenga los enlaces simbólicos de nivel superior dentro del directorio: la instalación falla si una entrada de nivel superior es un enlace simbólico que apunta fuera del directorio impreso.
  • Incluya node_modules: Claude Code 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 los paquetes que el plugin necesita.
  • Sesiones iniciadas dentro del directorio: una sesión iniciada en el directorio impreso o en cualquier lugar debajo de él no carga el plugin.
  • No en Windows: Claude Code rechaza instalar un plugin en modo de enlace en Windows. Declare "mode": "copy" allí.

Fuentes de marketplace

Una fuente de marketplace indica dónde Claude Code obtiene un marketplace.json. La CLI construye uno para usted cuando agrega un marketplace, y usted escribe uno en la configuración:

Los nombres de tipo url, git y github significan algo diferente en una fuente de marketplace que en una fuente de plugin:

Nombre de tipo Como fuente de marketplace Como fuente de plugin
url Un enlace directo a un archivo marketplace.json, con campos url, headers y headersHelper Un repositorio git para clonar, con campos url, ref y sha
git Un repositorio git para clonar, con campos url, ref, path y sparsePaths No existe
github Un repositorio de GitHub, con campos repo, ref, path y sparsePaths Un repositorio de GitHub, con campos repo, ref y sha, y sin path

La tabla enumera cada tipo de fuente de marketplace con sus campos, la entrada de claude plugin marketplace add que lo produce, y qué hace en cada una de las tres claves de configuración.

Tipo Campos entrada marketplace add extraKnownMarketplaces strictKnownMarketplaces blockedMarketplaces
url url, headers, headersHelper Una URL http:// o https:// que no coincide con una forma git Se carga Permite la misma URL Bloquea la misma URL
github repo, ref, path, sparsePaths owner/repo, owner/repo@ref u owner/repo#ref Se carga Permite el mismo repo, ref y path. repo puede ser owner/* Bloquea lo mismo, y una URL git al mismo repositorio
git url, ref, path, sparsePaths Una URL user@host:path, o una URL https:// que termina en .git, contiene /_git/, o nombra un repositorio github.com o gitlab.com. #ref fija un ref Se carga Permite la misma URL, ref y path Bloquea lo mismo, y otras ortografías del mismo repositorio github.com
npm package No producido Falla al cargar: NPM marketplace sources not yet implemented Se analiza pero no coincide con nada, porque nada registra un marketplace npm Se analiza pero no coincide con nada
file path Una ruta a un archivo .json Se carga Permite la misma ruta Bloquea la misma ruta
directory path Una ruta a un directorio Se carga Permite la misma ruta Bloquea la misma ruta
settings name, plugins, owner No producido Se carga Permite una entrada con el mismo name y plugins idénticos Bloquea el mismo name
skills-dir none No producido Falla al cargar: Unsupported marketplace source type Mantiene los plugins del directorio de skills cargándose mientras se establece una lista de permitidos. Consulte Valores de fuente válidos solo en listas de políticas Detiene los plugins del directorio de skills de cargarse
hostPattern hostPattern No producido Falla al cargar: Unsupported marketplace source type Permite fuentes github, git y url cuyo host coincida Bloquea esas fuentes
pathPattern pathPattern No producido Falla al cargar: Unsupported marketplace source type Permite fuentes file y directory cuya path coincida Bloquea esas fuentes

Campos por tipo

La tabla enumera cada campo de fuente de marketplace que tiene un predeterminado, una restricción o un significado específico de su tipo.

Campo Tipos Descripción
url url Enlace al archivo marketplace.json. Claude Code descarga solo ese archivo, por lo que los plugins del marketplace no pueden usar fuentes de ruta relativa
url git El repositorio git para clonar
headers url Mapa de encabezados HTTP que Claude Code envía con la obtención, para hosts autenticados
headersHelper url Comando que imprime encabezados cuyos valores son demasiado efímeros para listar en headers. Requiere Claude Code v2.1.238 o posterior. Consulte Autenticar descargas de archivos
repo github En marketplace add y extraKnownMarketplaces, repo debe nombrar un repositorio. marketplace add rechaza owner/* como no un atajo owner/repo válido; en extraKnownMarketplaces Claude Code lo toma literalmente y el clon falla
ref github, git Rama o etiqueta. Por defecto es la rama predeterminada del repositorio
path github, git La ruta del archivo marketplace dentro del repositorio. Por defecto es .claude-plugin/marketplace.json
path file El archivo marketplace en sí. Claude Code lo lee en su lugar y toma el directorio dos niveles arriba como la raíz del marketplace, así que mantenga el archivo en <root>/.claude-plugin/marketplace.json
path directory La raíz del marketplace, el directorio que contiene .claude-plugin/marketplace.json
sparsePaths github, git Array de directorios para un checkout disperso, como [".claude-plugin", "plugins"]. claude plugin marketplace add --sparse lo establece
skipLfs github, git Aceptado y no tiene efecto. Consulte Mantener archivos de plugin fuera de Git LFS
name settings Debe ser igual a la clave extraKnownMarketplaces y no puede ser un nombre reservado
plugins settings El catálogo en línea, sin archivo alojado. Cada elemento toma name, source, description, version, strict, headers y headersHelper. Escriba el source de cada elemento como un tipo de objeto, porque una ruta relativa no tiene repositorio para resolver

Valores de fuente válidos solo en listas de políticas

hostPattern, pathPattern, skills-dir y la forma owner/* de repo son válidos solo en las dos listas de políticas, strictKnownMarketplaces y blockedMarketplaces:

  • hostPattern y pathPattern: expresiones regulares que Claude Code prueba contra una fuente antes de obtener de ella.
  • skills-dir: no es una fuente. Si establece strictKnownMarketplaces en absoluto, los plugins del directorio de skills dejan de cargarse hasta que agregue {"source": "skills-dir"} a esa lista.
  • owner/*: como un valor repo de github, coincide con cada repositorio bajo exactamente ese propietario de GitHub. Requiere Claude Code v2.1.223 o posterior.

Para el orden de coincidencia, la semántica exacta de ref y recetas, consulte Administrar plugins para su organización.

Objetos de fuente en la configuración

Un valor extraKnownMarketplaces es un mapa de nombre de marketplace a un objeto con source. Esta entrada registra un marketplace desde un repositorio git en su rama main:

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

strictKnownMarketplaces y blockedMarketplaces son arrays de objetos de fuente. Esta lista de permitidos admite un propietario de GitHub y un host interno:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

Mensajes de validación

claude plugin validate <path> toma la raíz del marketplace o el archivo marketplace en sí. Imprime errores y advertencias. Para códigos de salida y --strict, consulte plugin validate.

Un mensaje nombra una entrada de plugin por su índice, escrito como plugins.1.source o plugins[1].source.

Un mensaje prefijado con un índice de entrada y plugin.json →, como plugins[2] plugin.json →, es sobre los propios archivos de ese plugin. claude plugin validate reporta errores enumera esos mensajes con sus correcciones.

Las advertencias que mencionan nombres de banderas de Claude Desktop señalan nombres que Claude Code acepta pero Claude Desktop rechaza, porque las reglas de nombre de Claude Desktop son más estrictas.

La tabla asigna mensajes de nivel de marketplace al campo sobre el que trata cada uno.

Mensaje Nivel Campo
Marketplace must have a name Error name está vacío
Marketplace name cannot contain spaces. Use kebab-case (e.g., "my-marketplace") Error name
Marketplace name cannot contain path separators (/ or \), ".." sequences, or be "." Error name
Marketplace name impersonates an official Anthropic/Claude marketplace Error name. Consulte Nombres reservados
Marketplace name cannot contain control or bidirectional-formatting characters Error name contiene un carácter de control, como un escape o una nueva línea, o un carácter de formato bidireccional Unicode
Marketplace name "inline" is reserved for --plugin-dir session plugins, y las variantes builtin, skills-dir, synced, claude-plugin-test, npm, pip, uv, cargo, github y gh Error name
Author name cannot be empty Error owner.name
Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin") Error plugins[i].name
Plugin name cannot contain control or bidirectional-formatting characters Error plugins[i].name
Duplicate plugin name "x" found in marketplace Error Dos entradas comparten un name
plugins.i.source: Invalid input Error El source de la entrada no coincide con ningún tipo. Consulte Entrada inválida en una fuente
plugins[i].source: Path contains "..": <path> Error Un source relativo que escapa de la raíz del marketplace
source.source: 'unsupported' is a parse-time placeholder and cannot be authored Error plugins[i].source
Plugin "x" sets headersHelper but is not "strict": false Error plugins[i].headersHelper, en una entrada archive
chain does not resolve (<reason>) — target must be a name in plugins[], a key in renames, or null Error renames.<old>
target "x" is not a valid plugin name (PluginIdSchema) Error renames.<old>
Unknown field 'x'. Claude Code ignores it at load time. Advertencia La clave nombrada en el nivel superior, bajo metadata, en una entrada, o bajo el relevance de una entrada
Marketplace has no plugins defined Advertencia plugins está vacío
Plugin "x" sets headers/headersHelper, which only apply to "archive" sources; they have no effect on this entry. Advertencia plugins[i].headers o plugins[i].headersHelper, en una entrada cuyo source no es archive
Plugin "x" fetches its archive with a headersHelper but sets no sha256 pin Advertencia plugins[i].source.sha256
Header "x" is a request-routing/identity header that catalog entries may not set; Claude Code drops it at download time. Advertencia plugins[i].headers.<name>
Local source "x" is or traverses a symlink, so <path> was not read Advertencia plugins[i].source
No marketplace description provided. Adding a description helps users understand what this marketplace offers Advertencia description
Entry declares version "x" but <path>/plugin.json says "y". At install time, plugin.json wins Advertencia plugins[i].version, en una entrada de ruta relativa
'relevance' must be an object containing topic and signals; got <type>. It will be ignored at load time. Advertencia plugins[i].relevance
'metadata' must be a free-form object; got <type>. It will be ignored at load time. Advertencia plugins[i].metadata
'experimental' must be an object containing component declarations; got <type>. It will be ignored at load time. Advertencia plugins[i].experimental
Marketplace name "x" is reserved in Claude Desktop Advertencia name es org, org-provisioned u unknown. Claude Desktop rechaza el marketplace
Marketplace name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars) Advertencia name. Claude Desktop rechaza el marketplace
Plugin name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars) Advertencia plugins[i].name. Claude Desktop descarta la entrada

Entrada inválida en una fuente

Invalid input en un source significa que el objeto no coincidió con ningún tipo de fuente. Verifique estas causas:

  • Una ruta relativa que no comienza con ./, que no sea "." o un nombre desnudo bajo metadata.pluginRoot
  • Un package npm que contiene ..
  • Un tipo de source que no es uno de las fuentes de plugins
  • Un tipo conocido con un campo obligatorio faltante o de tipo incorrecto, como github sin repo

Fallos que la validación no detecta

claude plugin validate no reporta cada fallo. Un hooks de entrada escrito como una ruta de archivo o array aprueba la validación, y el error aparece solo cuando el plugin se carga, como describe Hooks en una entrada. Los errores al obtener un source también aparecen solo después de instalar, no en la validación.

claude plugin list muestra un plugin que falló al cargar con su error, y Solucionar problemas de plugins cubre las cadenas de tiempo de carga.

Próximos pasos