Referencia de Marketplace

• El archivo marketplace: Campos de nivel superior y Entradas de plugins
• El source de una entrada: Fuentes de plugins
• Un objeto source en la configuración: Fuentes de marketplace
• Salida de claude plugin validate <path>: Mensajes de validación, que asigna cada mensaje al campo que nombra

​

Archivo marketplace

​

Nombres reservados

• 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. Un marketplace ya registrado bajo tal nombre deja de cargarse, junto con sus plugins.
• 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 guion bajo en lugar de un guion, por lo que claude.code.plugins cuenta como claude-code-plugins. 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 de miembros que tiene todo objeto de JavaScript: constructor, hasOwnProperty, isPrototypeOf, propertyIsEnumerable, toLocaleString, toString y valueOf. claude plugin marketplace add rechaza un marketplace que use uno con Claude Code reserves this name and cannot register a marketplace under it. Esta verificación requiere Claude Code v2.1.296 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.
• La carpeta de descarga de un marketplace de GitHub registrado, <owner>-<repo>: Claude Code descarga un marketplace agregado desde una fuente github como acme/x-tools a través de una carpeta llamada acme-x-tools, sea cual sea el name propio de ese marketplace. Mientras ese marketplace esté registrado con un nombre distinto de acme-x-tools, claude plugin marketplace add rechaza un marketplace diferente llamado acme-x-tools después de descargarlo, e informa Can't use the marketplace name "acme-x-tools". Esta verificación requiere Claude Code v2.1.290 o posterior.

​

Campos de nivel superior

​

Entradas de plugins

​

Cómo una entrada se combina con plugin.json

• Sin plugin.json: la entrada es el manifiesto independientemente de strict. Cada campo de manifiesto que acepta 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. Los campos mcpServers, lspServers, userConfig y channels de la entrada no se aplican. Decláralos en plugin.json.

​

Hooks en una entrada

​

Campos de visualización

• Para un campo que establezcas 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.

​

Modo estricto

​

Orígenes de plugins

• ref: una rama o etiqueta. De forma predeterminada es la rama predeterminada del repositorio.
• sha: un SHA de commit completo de 40 caracteres en minúsculas. Cuando estableces tanto ref como sha, Claude Code hace checkout de sha. En la mayoría de los hosts de git, incluidos GitHub, GitLab y Bitbucket, esto significa que la instalación tiene éxito aunque la rama o etiqueta nombrada por ref se haya eliminado desde entonces en el upstream, siempre que el commit siga siendo alcanzable desde el repositorio. Algunos servidores, como AWS CodeCommit, no admiten obtener commits por SHA. En esos servidores, la ref debe seguir existiendo y el commit fijado debe ser alcanzable desde ella.

​

Origen de plugin de ruta relativa

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

• 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. En su lugar, dale a cada plugin un origen de tipo objeto, como github o git-subdir.
• settings: las rutas relativas se rechazan directamente.

​

Submódulos de Git en el repositorio del marketplace

• El plugin está dentro del submódulo: el submódulo es el directorio del plugin o un directorio por encima de él
• El submódulo está dentro del plugin: el submódulo está en cualquier lugar bajo el directorio del plugin
• Un enlace simbólico apunta dentro del submódulo: un enlace con commit en el repositorio tiene su destino en el submódulo

• Un directorio de componentes: un directorio en la raíz que contiene componentes del plugin, como skills/, hooks/ o bin/
• Una ruta en la configuración del plugin: una ruta en la entrada del marketplace del plugin, en su plugin.json o en un archivo de configuración como .mcp.json o hooks/hooks.json
• Un enlace simbólico: un enlace con commit en el repositorio
• Texto en los archivos del plugin: la ruta de un submódulo, como vendor/tool, escrita en un archivo de configuración o en un archivo bajo un directorio de componentes

• Un SKILL.md en la raíz: en ese caso, todo el repositorio es el directorio de un skill
• Un archivo que Claude Code no puede leer: el archivo del marketplace, uno de los archivos de configuración del plugin o .gitmodules

​

Nombres simples bajo pluginRoot

• Debe ser en sí mismo una ruta relativa dentro del marketplace.
• No tiene efecto sobre un origen que ya comienza con ./.
• Un origen que contiene una /, como team-a/formatter, no es un nombre simple y sigue necesitando el prefijo ./, incluso cuando metadata.pluginRoot está establecido.

​

Origen de plugin github

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

​

Origen de plugin url

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

​

Origen de plugin git-subdir

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

​

Origen de plugin npm

• package: un nombre de paquete del registro como @your-org/formatter, un nombre con una versión añadida como @your-org/formatter@2.0.0, o un enlace https al archivo tarball del paquete
• version: una versión, un rango semver o una dist-tag, que se usa cuando package es un nombre de paquete sin versión añadida. Omítelo para obtener latest
• registry: una URL de registro para un paquete que no está en el registro predeterminado

• Una dirección de git, una carpeta o ruta file:, o un alias npm:: usa un origen github, url o git-subdir para un repositorio git, una ruta relativa para una carpeta del marketplace y el propio nombre del paquete en lugar de un alias
• Un enlace a un tarball en github.com, gist.github.com, gitlab.com, bitbucket.org o git.sr.ht: se rechaza incluso cuando el enlace es una descarga de una release de GitHub, a menos que sea un enlace al registro npm de GitLab bajo gitlab.com/api/v4/
• Un enlace a un tarball a través de http: se rechaza a menos que apunte al registro npm predeterminado del propio usuario que instala

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

​

Origen de plugin archive

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

​

Origen de plugin command

• command: un comando de shell que imprime la ruta absoluta del directorio del plugin como una sola línea y termina con código 0. Claude Code muestra a los usuarios la cadena completa para que la revisen antes de ejecutarla. Escríbelo en ASCII imprimible, con un máximo de 500 caracteres y sin secuencias de cuatro o más espacios.
• timeout: un número entero de segundos entre 1 y 600. El valor predeterminado es 60.
• mode: copy, el predeterminado, o link. Consulta Modo copy y modo link.

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

​

Qué debe hacer el comando

• Shell y directorio de trabajo: Claude Code ejecuta el comando mediante sh, o mediante cmd.exe en Windows, desde el directorio home del usuario. Indica una ruta absoluta o un comando que esté en PATH.
• Salida: imprime exactamente una línea en stdout, la ruta absoluta del directorio del plugin, y termina con código 0 dentro de los timeout segundos.
• Contenido del directorio: el directorio contiene el plugin completo en el momento en que el comando termina. La ruta puede ser distinta de una ejecución a otra.

​

Salida que hace fallar la instalación o actualización

• 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 propio directorio de la sesión: el directorio impreso es aquel en el que se inició Claude Code, o uno de sus directorios superiores.
• Una ruta de red: en Windows, la ruta impresa es una ruta UNC.
• Demasiado grande para copiar: en modo copy, el directorio ocupa más de 256 MiB o tiene más de 20,000 entradas.

​

Modo copy y modo link

• copy: Claude Code copia el directorio en la caché de plugins y deriva la versión del plugin a partir de un hash de los archivos copiados. Tu herramienta puede eliminar o reescribir el directorio después de que el comando termine. Una nueva ejecución que produce archivos idénticos se considera actualizada.
• 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 ubicación. No se copia nada, no se calcula el hash del contenido de los archivos y los límites de tamaño no se aplican. Úsalo para un directorio demasiado grande para copiar, como una exportación de un SDK generada.

• Mantén 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 siga instalado.
• Imprime una ruta diferente para indicar contenido nuevo: la versión proviene de la ruta real del directorio impreso y de sus entradas de nivel superior, no de los archivos que contienen.
• Mantén 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.
• Incluye node_modules: Claude Code omite la instalación de dependencias de paquetes de Node.js para un plugin en modo link, así que imprime 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 se niega a instalar un plugin en modo link en Windows. Declara "mode": "copy" allí.

​

Fuentes de marketplace

• claude plugin marketplace add: Claude Code construye la fuente a partir de la cadena que pasa.
• extraKnownMarketplaces: usted escribe la fuente en sí como el objeto source.
• strictKnownMarketplaces y blockedMarketplaces: los administradores escriben fuentes en estas dos listas de políticas. strictKnownMarketplaces es la lista de permitidos y blockedMarketplaces es la lista de bloqueados.

​

Campos por tipo

​

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

• hostPattern y pathPattern: expresiones regulares que Claude Code prueba contra una fuente antes de obtener de ella.
• skills-dir: no es una fuente. Si estableces strictKnownMarketplaces sin una entrada {"source": "skills-dir"}, los plugins del directorio de skills dejan de cargarse. Si bloqueas cualquier tipo de personalización con strictPluginOnlyCustomization, dejan de cargarse independientemente de que la entrada esté presente o no.
• 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.

​

Objetos de fuente en la configuración

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

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

​

Mensajes de validación

​

Entrada inválida en una fuente

• 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

​

Próximos pasos

• Crear un marketplace: construya un marketplace a partir de estos campos e instale desde él localmente
• Alojar y mantener un marketplace: dónde poner el archivo y cómo los usuarios reciben cambios
• Referencia de manifiesto de plugin: los campos plugin.json que una entrada puede anular
• Administrar plugins para su organización: recetas de lista de permitidos y lista de bloqueados que usan estos valores de fuente