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

​

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

​

Campos de visualización

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

​

Modo estricto

​

Fuentes de plugins

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

​

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

• 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

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

​

Fuente de plugin url

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

​

Fuente de plugin git-subdir

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

​

Fuente de plugin npm

• 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

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

​

Fuente de plugin archive

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

​

Fuente de plugin command

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

​

Qué debe hacer el comando

• 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

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

​

Modo de copia y modo de enlace

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

• 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

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

​

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

• 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

​

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