plugin-marketplaces.md +0 −1688 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Crear y distribuir un marketplace de plugins
6
7> Cree y aloje marketplaces de plugins para distribuir extensiones de Claude Code en equipos y comunidades.
8
9Un **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.
10
11¿Busca instalar plugins desde un marketplace existente? Consulte [Descubrir e instalar plugins precompilados](/docs/es/discover-plugins).
12
13<h2 id="overview">
14 Descripción general
15</h2>
16
17Crear y distribuir un marketplace implica:
18
191. **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](/docs/es/plugins) para obtener detalles sobre cómo crearlos.
202. **Crear el archivo de marketplace**: defina un `marketplace.json` que enumere sus plugins y dónde encontrarlos. Consulte [Crear el archivo de marketplace](#create-the-marketplace-file).
213. **Alojar el marketplace**: envíe a GitHub, GitLab u otro host git. Consulte [Alojar y distribuir marketplaces](#host-and-distribute-marketplaces).
224. **Compartir con usuarios**: los usuarios agregan su marketplace con `/plugin marketplace add` e instalan plugins individuales. Consulte [Descubrir e instalar plugins](/docs/es/discover-plugins).
23
24Una vez que su marketplace esté activo, puede actualizarlo enviando cambios a su repositorio. Los usuarios actualizan su copia local con `/plugin marketplace update`.
25
26<h2 id="walkthrough-create-a-local-marketplace">
27 Tutorial: crear un marketplace local
28</h2>
29
30Este 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á.
31
32<Steps>
33 <Step title="Crear la estructura de directorios">
34 ```bash theme={null}
35 mkdir -p my-marketplace/.claude-plugin
36 mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
37 mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review
38 ```
39 </Step>
40
41 <Step title="Crear la skill">
42 Cree un archivo `SKILL.md` que defina qué hace la skill `quality-review`.
43
44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}
45 ---
46 description: Review code for bugs, security, and performance
47 ---
48
49 Review the code I've selected or the recent changes for:
50 - Potential bugs or edge cases
51 - Security concerns
52 - Performance issues
53 - Readability improvements
54
55 Be concise and actionable.
56 ```
57 </Step>
58
59 <Step title="Crear el manifiesto del plugin">
60 Cree un archivo `plugin.json` que describa el plugin. El manifiesto va en el directorio `.claude-plugin/`.
61
62 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}
63 {
64 "name": "quality-review-plugin",
65 "description": "Adds a quality-review skill for quick code reviews",
66 "version": "1.0.0",
67 "author": {
68 "name": "Your Name"
69 }
70 }
71 ```
72
73 <Note>
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. Tampoco lo está un plugin [cargado en su lugar](/docs/es/plugins-reference#plugin-caching-and-file-resolution) desde un marketplace agregado como directorio local. Si omite `version`, la versión proviene de la siguiente fuente en [gestión de versiones](/docs/es/plugins-reference#version-management).
75 </Note>
76 </Step>
77
78 <Step title="Crear el archivo de marketplace">
79 Cree el catálogo de marketplace que enumera su plugin.
80
81 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}
82 {
83 "name": "my-plugins",
84 "owner": {
85 "name": "Your Name"
86 },
87 "plugins": [
88 {
89 "name": "quality-review-plugin",
90 "source": "./plugins/quality-review-plugin",
91 "description": "Adds a quality-review skill for quick code reviews"
92 }
93 ]
94 }
95 ```
96 </Step>
97
98 <Step title="Agregar e instalar">
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.`, consulte [Aplicar cambios de plugin sin reiniciar](/docs/es/discover-plugins#apply-plugin-changes-without-restarting).
100
101 ```shell theme={null}
102 /plugin marketplace add ./my-marketplace
103 /plugin install quality-review-plugin@my-plugins
104 ```
105 </Step>
106
107 <Step title="Pruébelo">
108 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.
109
110 ```shell theme={null}
111 /quality-review-plugin:quality-review
112 ```
113 </Step>
114</Steps>
115
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).
117
118<Note>
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é, a menos que el plugin se cargue en su lugar. Una [fuente `command` en modo de enlace](#copy-mode-and-link-mode) se carga en su lugar, y también lo hace una [fuente de ruta relativa](#relative-paths) en un marketplace agregado desde un directorio local. 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.
120
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.
122</Note>
123
124<h2 id="create-the-marketplace-file">
125 Crear el archivo de marketplace
126</h2>
127
128Cree `.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.
129
130Cada 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](#marketplace-schema) a continuación para todos los campos disponibles.
131
132```json theme={null}
133{
134 "name": "company-tools",
135 "owner": {
136 "name": "DevTools Team",
137 "email": "devtools@example.com"
138 },
139 "plugins": [
140 {
141 "name": "code-formatter",
142 "source": "./plugins/formatter",
143 "description": "Automatic code formatting on save",
144 "version": "2.1.0",
145 "author": {
146 "name": "DevTools Team"
147 }
148 },
149 {
150 "name": "deployment-tools",
151 "source": {
152 "source": "github",
153 "repo": "company/deploy-plugin"
154 },
155 "description": "Deployment automation tools"
156 }
157 ]
158}
159```
160
161<h2 id="marketplace-schema">
162 Esquema de marketplace
163</h2>
164
165<h3 id="required-fields">
166 Campos requeridos
167</h3>
168
169| Campo | Tipo | Descripción | Ejemplo |
170| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- |
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"` |
172| `owner` | object | Información del mantenedor del marketplace. Consulte [Campos del propietario](#owner-fields) | |
173| `plugins` | array | Lista de plugins disponibles | Ver [Entradas de plugins](#plugin-entries) |
174
175<Note>
176 **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`, `claude-tag-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.
177
178 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](/docs/es/errors#marketplace-is-registered-from-an-untrusted-source). 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. Antes de v2.1.265, `claude-tag-plugins` no estaba reservado.
179
180 Tampoco puede nombrar un marketplace `npm`, `pip`, `uv`, `cargo`, `github`, o `gh`, en cualquier combinación de mayúsculas y minúsculas. Esta verificación requiere Claude Code v2.1.275 o posterior.
181</Note>
182
183<h3 id="owner-fields">
184 Campos del propietario
185</h3>
186
187| Campo | Tipo | Requerido | Descripción |
188| :------ | :----- | :-------- | :------------------------------------------------ |
189| `name` | string | Sí | Nombre del mantenedor o equipo |
190| `email` | string | No | Correo electrónico de contacto del mantenedor |
191| `url` | string | No | Sitio web, perfil de GitHub u URL de organización |
192
193<h3 id="optional-fields">
194 Campos opcionales
195</h3>
196
197| Campo | Tipo | Descripción |
198| :------------------------------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
199| `$schema` | string | URL del esquema JSON para autocompletado y validación del editor. Claude Code ignora este campo al cargar. |
200| `description` | string | Descripción breve del marketplace |
201| `version` | string | Versión del manifiesto del marketplace |
202| `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. |
203| `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). |
204| `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. |
205
206`description` y `version` también se aceptan bajo `metadata` para compatibilidad con versiones anteriores.
207
208<h2 id="plugin-entries">
209 Entradas de plugins
210</h2>
211
212Cada 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`.
213
214<h3 id="required-fields-2">
215 Campos requeridos
216</h3>
217
218| Campo | Tipo | Descripción |
219| :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220| `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`). |
221| `source` | string\|object | Dónde obtener el plugin (consulte [Fuentes de plugins](#plugin-sources) a continuación) |
222
223<h3 id="optional-plugin-fields">
224 Campos de plugin opcionales
225</h3>
226
227**Campos de metadatos estándar:**
228
229| Campo | Tipo | Descripción |
230| :--------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
231| `displayName` | string | Nombre legible mostrado en superficies de interfaz de usuario. Cuando ni la entrada ni el `plugin.json` del plugin establece uno, los usuarios ven el `name` del plugin. Puede contener espacios y cualquier capitalización. No se utiliza para espacios de nombres o búsqueda. |
232| `description` | string | Descripción breve del plugin |
233| `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. Tampoco un plugin [cargado en su lugar](/docs/es/plugins-reference#plugin-caching-and-file-resolution) desde un marketplace agregado como directorio local. Si no se establece en ningún lugar, la versión proviene de la siguiente fuente en [gestión de versiones](/docs/es/plugins-reference#version-management). |
234| `author` | object | Información del autor del plugin (`name` requerido; `email` y `url` opcionales) |
235| `homepage` | string | URL de página de inicio o documentación del plugin |
236| `repository` | string | URL del repositorio de código fuente |
237| `license` | string | Identificador de licencia SPDX (por ejemplo, MIT, Apache-2.0) |
238| `keywords` | array | Etiquetas para descubrimiento y categorización de plugins |
239| `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. |
240| `category` | string | Categoría del plugin para organización |
241| `tags` | array | Etiquetas para búsqueda |
242| `strict` | boolean | Controla si `plugin.json` es la autoridad para definiciones de componentes (predeterminado: true). Consulte [Modo estricto](#strict-mode) a continuación. |
243| `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). |
244| `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). |
245
246Tanto la entrada como el `plugin.json` del plugin pueden establecer los campos de visualización `displayName`, `description`, `author`, `homepage`, `repository`, `license` y `keywords`. En listados y detalles de plugins, antes y después de la instalación:
247
248* Para un campo que establece en la entrada, los usuarios ven el valor de la entrada, incluso cuando `plugin.json` establece uno diferente.
249* Para un campo que la entrada deja sin establecer, los usuarios ven el valor de `plugin.json`.
250
251Antes de la instalación, Claude Code solo puede leer `plugin.json` para entradas con una [fuente de ruta relativa](#relative-paths), cuyos archivos de plugin viven dentro del marketplace. Para una entrada con cualquier otro tipo de fuente, los usuarios ven solo los campos de la entrada hasta que instalen el plugin.
252
253**Campos de configuración de componentes:**
254
255| Campo | Tipo | Descripción |
256| :----------- | :------------- | :--------------------------------------------------------------------------- |
257| `skills` | string\|array | Rutas personalizadas a directorios de skills que contienen `<name>/SKILL.md` |
258| `commands` | string\|array | Rutas personalizadas a archivos de skills planos o directorios |
259| `agents` | string\|array | Rutas personalizadas a archivos de agentes |
260| `hooks` | string\|object | Configuración de hooks personalizada o ruta a archivo de hooks |
261| `mcpServers` | string\|object | Configuraciones de servidor MCP o ruta a configuración de MCP |
262| `lspServers` | string\|object | Configuraciones de servidor LSP o ruta a configuración de LSP |
263
264**Campos de autenticación de archivo:**
265
266Establezca estos cuando la entrada tenga una fuente [`archive`](#zip-archives) en un servidor que requiera credenciales.
267
268| Campo | Tipo | Descripción |
269| :-------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
270| `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. |
271| `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. |
272
273<h2 id="plugin-sources">
274 Fuentes de plugins
275</h2>
276
277Las 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`.
278
279Claude Code copia cada plugin instalado en el caché de plugins versionado local en `~/.claude/plugins/cache`, a menos que el plugin se cargue en su lugar. Una [fuente `command` en modo link](#copy-mode-and-link-mode) se carga en su lugar, y también lo hace una [fuente de ruta relativa](#relative-paths) en un marketplace agregado desde un directorio local. 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é. Consulte [Plugin caching and file resolution](/docs/es/plugins-reference#plugin-caching-and-file-resolution) para ver cómo un plugin cargado en su lugar desde un marketplace de directorio local recoge sus ediciones.
280
281| Fuente | Tipo | Campos | Notas |
282| ------------- | --------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
283| 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/` |
284| `github` | object | `repo`, `ref?`, `sha?` | |
285| `url` | object | `url`, `ref?`, `sha?` | Fuente de URL de Git |
286| `git-subdir` | object | `url`, `path`, `ref?`, `sha?` | Subdirectorio dentro de un repositorio git. Clona escasamente para minimizar el ancho de banda para monorepos |
287| `npm` | object | `package`, `version?`, `registry?` | Paquete npm, obtenido con su cliente npm y desempaquetado sin ejecutar scripts de instalación |
288| `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 |
289| `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 |
290
291<Note>
292 **Fuentes de marketplace vs fuentes de plugins**: Estos son conceptos diferentes que controlan cosas diferentes.
293
294 * **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`.
295 * **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).
296
297 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.
298</Note>
299
300Los 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.
301
302En 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.
303
304Si 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).
305
306<h3 id="relative-paths">
307 Rutas relativas
308</h3>
309
310Para plugins en el mismo repositorio, use una ruta que comience con `./`:
311
312```json theme={null}
313{
314 "name": "my-plugin",
315 "source": "./plugins/my-plugin"
316}
317```
318
319Las rutas se resuelven relativas a la raíz del marketplace, que es el directorio que contiene `.claude-plugin/`. La fuente `./plugins/my-plugin` por lo tanto apunta a `<repo>/plugins/my-plugin`, aunque `marketplace.json` vive en `<repo>/.claude-plugin/marketplace.json`. No use `../` para hacer referencia a rutas fuera de la raíz del marketplace. En macOS y Linux, Claude Code rechaza una ruta de entrada con una barra invertida en cualquier lugar después del `./` inicial, así que escriba los separadores como `/` en todas las plataformas.
320
321Un 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.
322
323`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.
324
325<Note>
326 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.
327</Note>
328
329<h3 id="github-repositories">
330 Repositorios de GitHub
331</h3>
332
333```json theme={null}
334{
335 "name": "github-plugin",
336 "source": {
337 "source": "github",
338 "repo": "owner/plugin-repo"
339 }
340}
341```
342
343Puede fijar a una rama, etiqueta o commit específico:
344
345```json theme={null}
346{
347 "name": "github-plugin",
348 "source": {
349 "source": "github",
350 "repo": "owner/plugin-repo",
351 "ref": "v2.0.0",
352 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
353 }
354}
355```
356
357| Campo | Tipo | Descripción |
358| :----- | :----- | :--------------------------------------------------------------------------------------- |
359| `repo` | string | Requerido. Repositorio de GitHub en formato `owner/repo` |
360| `ref` | string | Opcional. Rama o etiqueta de Git (por defecto es la rama predeterminada del repositorio) |
361| `sha` | string | Opcional. SHA de commit de git completo de 40 caracteres para fijar a una versión exacta |
362
363<h3 id="git-repositories">
364 Repositorios de Git
365</h3>
366
367```json theme={null}
368{
369 "name": "git-plugin",
370 "source": {
371 "source": "url",
372 "url": "https://gitlab.com/team/plugin.git"
373 }
374}
375```
376
377Puede fijar a una rama, etiqueta o commit específico:
378
379```json theme={null}
380{
381 "name": "git-plugin",
382 "source": {
383 "source": "url",
384 "url": "https://gitlab.com/team/plugin.git",
385 "ref": "main",
386 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
387 }
388}
389```
390
391| Campo | Tipo | Descripción |
392| :---- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
393| `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 |
394| `ref` | string | Opcional. Rama o etiqueta de Git (por defecto es la rama predeterminada del repositorio) |
395| `sha` | string | Opcional. SHA de commit de git completo de 40 caracteres para fijar a una versión exacta |
396
397<h3 id="git-subdirectories">
398 Subdirectorios de Git
399</h3>
400
401Use `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.
402
403```json theme={null}
404{
405 "name": "my-plugin",
406 "source": {
407 "source": "git-subdir",
408 "url": "https://github.com/acme-corp/monorepo.git",
409 "path": "tools/claude-plugin"
410 }
411}
412```
413
414Puede fijar a una rama, etiqueta o commit específico:
415
416```json theme={null}
417{
418 "name": "my-plugin",
419 "source": {
420 "source": "git-subdir",
421 "url": "https://github.com/acme-corp/monorepo.git",
422 "path": "tools/claude-plugin",
423 "ref": "v2.0.0",
424 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
425 }
426}
427```
428
429El campo `url` también acepta una abreviatura de GitHub (`owner/repo`) o URLs SSH (`git@github.com:owner/repo.git`).
430
431| Campo | Tipo | Descripción |
432| :----- | :----- | :--------------------------------------------------------------------------------------------------------------------- |
433| `url` | string | Requerido. URL del repositorio de Git, abreviatura de GitHub `owner/repo` o URL SSH |
434| `path` | string | Requerido. Ruta del subdirectorio dentro del repositorio que contiene el plugin (por ejemplo, `"tools/claude-plugin"`) |
435| `ref` | string | Opcional. Rama o etiqueta de Git (por defecto es la rama predeterminada del repositorio) |
436| `sha` | string | Opcional. SHA de commit de git completo de 40 caracteres para fijar a una versión exacta |
437
438<h3 id="npm-packages">
439 Paquetes npm
440</h3>
441
442Una fuente npm puede nombrar cualquier paquete en el registro npm público o en un registro privado que su equipo aloje. Claude Code resuelve el paquete con su cliente npm, descarga el tarball y lo desempaqueta en el caché de plugins.
443
444Los scripts de instalación del paquete, como `preinstall` o `postinstall`, nunca se ejecutan, y sus dependencias no se instalan durante la obtención.
445
446Si el paquete envía un archivo de bloqueo compatible junto a su `package.json`, Claude Code instala esas [dependencias de paquetes Node.js](/docs/es/plugins-reference#node-js-package-dependencies) en un paso separado, también con scripts deshabilitados. De lo contrario, publique el plugin con todo lo que necesita ya construido. Un servidor MCP que necesita otros paquetes puede lanzarse a través de `npx`, que los instala en la primera ejecución.
447
448```json theme={null}
449{
450 "name": "my-npm-plugin",
451 "source": {
452 "source": "npm",
453 "package": "@acme/claude-plugin"
454 }
455}
456```
457
458Para fijar a una versión específica, agregue el campo `version`:
459
460```json theme={null}
461{
462 "name": "my-npm-plugin",
463 "source": {
464 "source": "npm",
465 "package": "@acme/claude-plugin",
466 "version": "2.1.0"
467 }
468}
469```
470
471Para instalar desde un registro privado o interno, agregue el campo `registry`:
472
473```json theme={null}
474{
475 "name": "my-npm-plugin",
476 "source": {
477 "source": "npm",
478 "package": "@acme/claude-plugin",
479 "version": "^2.0.0",
480 "registry": "https://npm.example.com"
481 }
482}
483```
484
485| Campo | Tipo | Descripción |
486| :--------- | :----- | :-------------------------------------------------------------------------------------------------------------- |
487| `package` | string | Requerido. Nombre del paquete o paquete con alcance (por ejemplo, `@org/plugin`) |
488| `version` | string | Opcional. Versión o rango de versión (por ejemplo, `2.1.0`, `^2.0.0`, `~1.5.0`) |
489| `registry` | string | Opcional. URL de registro npm personalizado. Por defecto es el registro npm del sistema (típicamente npmjs.org) |
490
491<h3 id="zip-archives">
492 Archivos zip
493</h3>
494
495Use `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.
496
497Esta entrada instala el plugin desde un archivo zip en un servidor de artefactos:
498
499```json theme={null}
500{
501 "name": "my-plugin",
502 "source": {
503 "source": "archive",
504 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
505 }
506}
507```
508
509Cuando 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:
510
511```text theme={null}
512my-plugin.zip my-plugin.zip
513├── .claude-plugin/ └── my-plugin/
514│ └── plugin.json ├── .claude-plugin/
515└── commands/ │ └── plugin.json
516 └── commands/
517```
518
519Claude 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.
520
521Para fijar el archivo exacto, agregue un campo `sha256` con el resumen del archivo:
522
523```json theme={null}
524{
525 "name": "my-plugin",
526 "source": {
527 "source": "archive",
528 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
529 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
530 }
531}
532```
533
534Si 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).
535
536Las fuentes de archivo aceptan estos campos:
537
538| Campo | Tipo | Descripción |
539| :------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
540| `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 |
541| `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 |
542
543El 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é.
544
545<h4 id="authenticate-archive-downloads">
546 Autenticar descargas de archivos
547</h4>
548
549Para 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`.
550
551Si 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.
552
553El lugar que elija decide qué descargas obtienen los encabezados y cuándo Claude Code ejecuta el comando:
554
555| Lugar | Descargas que obtienen los encabezados | Cuándo Claude Code ejecuta un `headersHelper` establecido allí |
556| :--------------------------- | :------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
557| 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 |
558| 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) |
559
560Donde 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`.
561
562<h5 id="add-a-headershelper-to-a-plugin-entry">
563 Agregar un headersHelper a una entrada de plugin
564</h5>
565
566Esta 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:
567
568```json theme={null}
569{
570 "name": "my-plugin",
571 "description": "Formatting commands for internal services",
572 "strict": false,
573 "commands": "./commands",
574 "source": {
575 "source": "archive",
576 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
577 },
578 "headersHelper": "/opt/bin/mint-registry-token.sh"
579}
580```
581
582Para 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.
583
584Antes 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.
585
586<h4 id="write-the-headershelper-command">
587 Escribir el comando headersHelper
588</h4>
589
590Ya sea que establezca `headersHelper` en una fuente `url` del marketplace o en una entrada de plugin, escriba el comando para cumplir con estos requisitos:
591
592* **Texto del comando**: como máximo 500 caracteres de ASCII imprimible, sin una ejecución de cuatro o más espacios.
593* **Salida**: imprima un objeto JSON de nombres de encabezados y valores de cadena en stdout, luego salga 0 dentro de 10 segundos.
594* **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.
595* **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.
596* **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.
597
598Un comando que acuña un token de portador imprime un objeto como este:
599
600```json theme={null}
601{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}
602```
603
604<h4 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">
605 Cuándo Claude Code omite un comando headersHelper o descarta su salida
606</h4>
607
608Claude Code no ejecuta un comando `headersHelper`, o descarta encabezados que vinieron de `headers` o de la salida del comando, en estas situaciones:
609
610* **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.
611* **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`.
612* **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.
613* **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.
614* **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.
615* **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.
616
617<h4 id="how-users-accept-a-headershelper-command">
618 Cómo los usuarios aceptan un comando headersHelper
619</h4>
620
621Un 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.
622
623En un shell no interactivo, pase [`--yes`](/docs/es/plugins-reference#plugin-install) para aceptar el comando que imprime. Para aceptar solo el comando que una ejecución anterior de `--json` mostró, pase [`--accept-command`](/docs/es/plugins-reference#plugin-install) con el `sha256` que la ejecución reportó.
624
625Claude 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.
626
627<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">
628 Instalaciones y actualizaciones que rechazan el comando en lugar de preguntar
629</h5>
630
631En 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:
632
633* **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.
634* **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.
635
636<h5 id="when-a-marketplace-url-source’s-command-runs">
637 Cuándo se ejecuta el comando headersHelper de una fuente `url` del marketplace
638</h5>
639
640Un `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:
641
642| Archivo de configuración | Cuándo Claude Code ejecuta el comando |
643| :---------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
644| 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 |
645| `.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 |
646| 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) |
647
648En 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.
649
650Para 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.
651
652<h3 id="command-sources">
653 Fuentes de comando
654</h3>
655
656Use `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.
657
658Esta entrada instala el plugin desde cualquier directorio que la herramienta imprime:
659
660```json theme={null}
661{
662 "name": "my-plugin",
663 "source": {
664 "source": "command",
665 "command": "my-tool claude-plugin-path"
666 }
667}
668```
669
670Claude 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.
671
672Claude 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:
673
674* El directorio no tiene contenido de plugin en su nivel superior, como un directorio `.claude-plugin/` o un directorio `skills/`, `commands/`, `agents/` o `hooks/`
675* El directorio es el en el que Claude Code fue iniciado, o uno de sus padres
676* En Windows, la ruta es una ruta UNC
677
678Las fuentes de comando aceptan estos campos:
679
680| Campo | Tipo | Descripción |
681| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
682| `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 |
683| `timeout` | number | Opcional. Número entero de segundos para esperar el comando antes de rendirse (predeterminado: 60, máximo: 600) |
684| `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) |
685
686<h4 id="copy-mode-and-link-mode">
687 Modo de copia y modo de enlace
688</h4>
689
690Con 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.
691
692Establezca `"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.
693
694Mantenga 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.
695
696Claude Code no soporta modo de enlace en Windows y rechaza instalar un plugin en modo de enlace allí. Declare `"mode": "copy"` en su lugar.
697
698<h4 id="how-users-accept-the-command">
699 Cómo los usuarios aceptan el comando
700</h4>
701
702Claude 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:
703
704* 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.
705* En un shell no interactivo, como un script de aprovisionamiento, pase `--yes` a `claude plugin install` o `claude plugin update` para aceptar el comando que imprime. Para aceptar solo el comando que una ejecución anterior de `--json` mostró, pase [`--accept-command`](/docs/es/plugins-reference#plugin-install) con el `sha256` que la ejecución reportó.
706* 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.
707* 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>`.
708
709Los 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.
710
711<h4 id="when-claude-code-re-runs-the-command">
712 Cuándo Claude Code vuelve a ejecutar el comando
713</h4>
714
715El 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:
716
717* Cada vez que el usuario instala o actualiza el plugin
718* 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
719* Al inicio o en `/reload-plugins`, cuando la versión instalada de un plugin habilitado falta en el caché de plugins
720
721Claude 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.
722
723Cuando 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).
724
725<h3 id="advanced-plugin-entries">
726 Entradas de plugins avanzadas
727</h3>
728
729Este ejemplo muestra una entrada de plugin usando muchos de los campos opcionales, incluidas rutas personalizadas para commands, agents, hooks y MCP servers:
730
731```json theme={null}
732{
733 "name": "enterprise-tools",
734 "source": {
735 "source": "github",
736 "repo": "company/enterprise-plugin"
737 },
738 "description": "Enterprise workflow automation tools",
739 "version": "2.1.0",
740 "author": {
741 "name": "Enterprise Team",
742 "email": "enterprise@example.com"
743 },
744 "homepage": "https://docs.example.com/plugins/enterprise-tools",
745 "repository": "https://github.com/company/enterprise-plugin",
746 "license": "MIT",
747 "keywords": ["enterprise", "workflow", "automation"],
748 "category": "productivity",
749 "commands": [
750 "./commands/core/",
751 "./commands/enterprise/",
752 "./commands/experimental/preview.md"
753 ],
754 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
755 "hooks": {
756 "PostToolUse": [
757 {
758 "matcher": "Write|Edit",
759 "hooks": [
760 {
761 "type": "command",
762 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
763 }
764 ]
765 }
766 ]
767 },
768 "mcpServers": {
769 "enterprise-db": {
770 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
771 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
772 }
773 },
774 "strict": false
775}
776```
777
778Cosas clave a notar:
779
780* **`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.
781 * 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
782* **`${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.
783 * 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
784 * 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
785* **`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.
786
787Por 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:
788
789```json theme={null}
790"skills": ["./skills/", "./extra-skills/"]
791```
792
793Cuando 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:
794
795```json theme={null}
796"source": "./",
797"skills": ["./skills/code-review", "./skills/docs"]
798```
799
800Con 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.
801
802<h3 id="strict-mode">
803 Modo estricto
804</h3>
805
806El campo `strict` controla si `plugin.json` es la autoridad para definiciones de componentes (skills, agents, hooks, MCP servers, estilos de salida).
807
808| Valor | Comportamiento |
809| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
810| `true` (predeterminado) | `plugin.json` es la autoridad. La entrada del marketplace puede complementarla con componentes adicionales, y ambas fuentes se fusionan. |
811| `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. |
812
813**Cuándo usar cada modo:**
814
815* **`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.
816* **`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.
817
818<h2 id="host-and-distribute-marketplaces">
819 Alojar y distribuir marketplaces
820</h2>
821
822Cuando los usuarios agregan un marketplace alojado en un repositorio de git, o instalan un plugin basado en git que enumera, Claude Code clona ese repositorio de marketplace o plugin en su máquina. El clon nunca descarga contenido de [Git LFS](https://git-lfs.com), por lo que los archivos rastreados por LFS llegan como archivos de puntero. Mantenga los archivos que sus plugins necesitan fuera de LFS.
823
824<h3 id="host-on-github-recommended">
825 Alojar en GitHub (recomendado)
826</h3>
827
828GitHub es la forma recomendada para alojar y distribuir un marketplace:
829
8301. **Crear un repositorio**: configure un nuevo repositorio para su marketplace
8312. **Agregar archivo de marketplace**: cree `.claude-plugin/marketplace.json` con sus definiciones de plugins
8323. **Compartir con equipos**: los usuarios agregan su marketplace con `/plugin marketplace add owner/repo`
833
834**Beneficios**: control de versiones integrado, seguimiento de problemas y características de colaboración en equipo.
835
836<h3 id="host-on-other-git-services">
837 Alojar en otros servicios de git
838</h3>
839
840Cualquier servicio de alojamiento de git funciona, como GitLab, Bitbucket y servidores autohospedados. Los usuarios agregan con la URL completa del repositorio:
841
842```shell theme={null}
843/plugin marketplace add https://gitlab.com/company/plugins.git
844```
845
846<h3 id="private-repositories">
847 Repositorios privados
848</h3>
849
850Claude 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 conexión GitHub o GitLab de su organización en claude.ai. Consulte [Distribuir a través de la configuración de la organización](#distribute-through-organization-settings) para saber qué fuentes de plugins pueden ser privadas.
851
852<h4 id="commands-you-run">
853 Comandos que ejecuta
854</h4>
855
856Cuando 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.
857
858<h4 id="background-auto-updates">
859 Actualizaciones automáticas en segundo plano
860</h4>
861
862La verificación de actualización en segundo plano comprueba el remoto del marketplace para nuevos commits con sus ayudantes de credenciales de git configurados, igual que los comandos que ejecuta. Para remotos SSH, una clave cargada en `ssh-agent` autentica la verificación. Claude Code ejecuta la verificación de forma no interactiva: desactiva los mensajes de terminal de git y los programas askpass, e indica a los ayudantes de credenciales que no soliciten. Si la verificación puede autenticarse en un repositorio privado sobre HTTPS depende de su ayudante:
863
864* Un ayudante que puede suministrar una credencial almacenada sin solicitar autentica la verificación. Git Credential Manager, el ayudante de Keychain de macOS y `git-credential-store` funcionan de esta manera una vez que tienen una credencial para el host.
865* Un ayudante que necesita solicitarle no puede responder en segundo plano. La actualización falla silenciosamente y el checkout existente permanece en su lugar, por lo que sus plugins siguen funcionando desde el último estado sincronizado. Ejecute `/plugin marketplace update <name>` para actualizar el marketplace con sus credenciales.
866
867Cuando la verificación encuentra el checkout actualizado, Claude Code lo deja como está. Cuando la verificación encuentra nuevos commits, o falla porque no puede alcanzar o autenticarse en el remoto, Claude Code clona el marketplace nuevamente e intercambia el nuevo clon. Si ese clon falla, el checkout existente permanece en su lugar. El re-clonado puede [agotar el tiempo de espera en repositorios grandes](#git-operations-time-out).
868
869Dos configuraciones hacen que los marketplaces privados se comporten de manera predecible:
870
871* Establezca `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` para mantener el checkout existente sin intentar el re-clonado cuando la verificación en segundo plano no puede alcanzar o autenticarse en el remoto. Sus plugins siguen funcionando desde el último estado sincronizado, y las actualizaciones manuales con `/plugin marketplace update` aún se autentican con sus credenciales.
872* Configure un ayudante de credenciales de git, por ejemplo con `gh auth setup-git` para GitHub, para que la verificación en segundo plano y el re-clonado puedan autenticarse sin solicitar.
873
874Establecer 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`.
875
876<Note>
877 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.
878</Note>
879
880<h3 id="distribute-through-organization-settings">
881 Distribuir a través de la configuración de la organización
882</h3>
883
884Si 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:
885
886* En github.com y gitlab.com, el repositorio del marketplace debe ser privado o interno. La sincronización de la organización lo lee a través de la conexión que coincide con su host:
887 * **github.com**: la Aplicación GitHub de Claude
888 * **Su host de GitHub Enterprise Server**: su [Aplicación GitHub Enterprise](/docs/es/github-enterprise-server#admin-setup) de la organización
889 * **gitlab.com o su instancia de GitLab autogestionada**: el token de acceso en su [configuración de GitLab](#sync-a-gitlab-hosted-marketplace) de la organización para ese host
890* 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`.
891* Una fuente de plugin puede ser privada en tres casos:
892 * Una fuente github.com que comparta el propietario del repositorio del marketplace
893 * Una fuente en el host GitHub Enterprise de su organización con la Aplicación GHE instalada en el repositorio
894 * Una fuente `url` o `git-subdir` en el mismo host de GitLab que el repositorio del marketplace. En gitlab.com, la fuente también debe estar bajo el mismo grupo de nivel superior o espacio de nombres de usuario que el repositorio del marketplace.
895* Cualquier otra fuente de plugin debe ser un repositorio público en github.com, gitlab.com o bitbucket.org, que la sincronización de la organización obtiene sin credenciales. La sincronización de la organización rechaza fuentes de plugins en hosts que estas reglas no cubren.
896
897Consulte [Administrar plugins para su organización](https://support.claude.com/en/articles/13837433) para el flujo de trabajo del administrador.
898
899Para 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.
900
901Por ejemplo, esta entrada de plugin `marketplace.json` hace referencia a un plugin que confirmó en `plugins/deploy-tools` en el repositorio del marketplace:
902
903```json theme={null}
904{
905 "name": "deploy-tools",
906 "source": "./plugins/deploy-tools"
907}
908```
909
910<h4 id="sync-a-gitlab-hosted-marketplace">
911 Sincronizar un marketplace alojado en GitLab
912</h4>
913
914Para sincronizar un marketplace desde gitlab.com o una instancia de GitLab autogestionada, un [Propietario](/docs/es/server-managed-settings#access-control) primero agrega una configuración de GitLab para ese host en [**Configuración de la organización > Claude Code**](https://claude.ai/admin-settings/claude-code). Las configuraciones de GitLab están en beta pública y se aplican solo a la sincronización del marketplace de plugins. Agregar una no hace que los repositorios de GitLab estén disponibles en [Claude Code en la web](/docs/es/claude-code-on-the-web#limitations). Consulte [Administrar plugins para su organización](https://support.claude.com/en/articles/13837433) para los pasos de configuración.
915
916Cuando agrega el marketplace, ingrese la URL HTTPS del proyecto, como `https://gitlab.example.com/platform/claude-plugins`. Los proyectos en subgrupos anidados funcionan. La sincronización de la organización lee la rama predeterminada del proyecto. Si activa **Sincronizar automáticamente**, solo los envíos a la rama predeterminada inician una sincronización.
917
918<h4 id="keep-executables-out-of-the-top-level-bin-directory">
919 Mantener ejecutables fuera del directorio bin de nivel superior
920</h4>
921
922No 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:
923
924* **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`.
925* **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.
926
927Mantenga 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).
928
929<h3 id="require-marketplaces-for-your-team">
930 Requerir marketplaces para su equipo
931</h3>
932
933Puede 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`:
934
935```json theme={null}
936{
937 "extraKnownMarketplaces": {
938 "company-tools": {
939 "source": {
940 "source": "github",
941 "repo": "your-org/claude-plugins"
942 }
943 }
944 }
945}
946```
947
948También puede especificar qué plugins deben estar habilitados de forma predeterminada:
949
950```json theme={null}
951{
952 "enabledPlugins": {
953 "code-formatter@company-tools": true,
954 "deployment-tools@company-tools": true
955 }
956}
957```
958
959Para opciones de configuración completas, consulte [Configuración de plugins](/docs/es/settings-reference#plugin-settings).
960
961<Note>
962 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.
963</Note>
964
965<h3 id="pre-populate-plugins-for-containers">
966 Precargar plugins para contenedores
967</h3>
968
969Para 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.
970
971Para 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.
972
973El directorio seed refleja la estructura de `~/.claude/plugins`:
974
975```
976$CLAUDE_CODE_PLUGIN_SEED_DIR/
977 known_marketplaces.json
978 marketplaces/<name>/...
979 cache/<marketplace>/<plugin>/<version>/...
980```
981
982Para 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.
983
984Para 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í:
985
986```bash theme={null}
987CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
988CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins
989```
990
991Luego 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.
992
993Al 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`.
994
995Detalles de comportamiento:
996
997* **Solo lectura**: Claude Code nunca escribe en el directorio seed.
998* **Actualizaciones automáticas deshabilitadas**: los marketplaces seed no se actualizan automáticamente.
999* **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.
1000* **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.
1001* **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.
1002* **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.
1003
1004<h3 id="managed-marketplace-restrictions">
1005 Restricciones de marketplace administrado
1006</h3>
1007
1008Para 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).
1009
1010`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).
1011
1012Cuando `strictKnownMarketplaces` se configura en configuración administrada, el comportamiento de restricción depende del valor:
1013
1014| Valor | Comportamiento |
1015| --------------------------- | --------------------------------------------------------------------------------------------------------- |
1016| Indefinido (predeterminado) | Sin restricciones. Los usuarios pueden agregar cualquier marketplace |
1017| Array vacío `[]` | Bloqueo completo. Bloquea cada fuente de marketplace, incluido el marketplace oficial de Anthropic |
1018| Lista de fuentes | Lista de permitidos aplicada. Los usuarios solo pueden agregar marketplaces que coincidan con una entrada |
1019
1020<h4 id="common-configurations">
1021 Configuraciones comunes
1022</h4>
1023
1024Deshabilitar todas las adiciones de marketplace, incluido el marketplace oficial de Anthropic:
1025
1026```json theme={null}
1027{
1028 "strictKnownMarketplaces": []
1029}
1030```
1031
1032Claude Code descarga los plugins [sincronizados desde claude.ai](/docs/es/plugins-reference#synced-plugins) desde su cuenta en lugar de desde un marketplace, por lo que este bloqueo no los cubre. Para detener también esos, establezca [`syncClaudeAiPlugins`](/docs/es/settings-reference#syncclaudeaiplugins) en `false` en configuración administrada, o desactive Skills para su organización en claude.ai.
1033
1034Permitir 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:
1035
1036```json theme={null}
1037{
1038 "strictKnownMarketplaces": [
1039 {
1040 "source": "github",
1041 "repo": "anthropics/claude-plugins-official"
1042 }
1043 ]
1044}
1045```
1046
1047Con 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.
1048
1049El registro automático no cubre todas las máquinas. Más comúnmente falta:
1050
1051* Entornos no interactivos que se ejecutan antes del primer lanzamiento interactivo de la máquina.
1052* 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.
1053
1054En 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`.
1055
1056Permitir solo marketplaces específicos:
1057
1058```json theme={null}
1059{
1060 "strictKnownMarketplaces": [
1061 {
1062 "source": "github",
1063 "repo": "acme-corp/approved-plugins"
1064 },
1065 {
1066 "source": "github",
1067 "repo": "acme-corp/security-tools",
1068 "ref": "v2.0"
1069 },
1070 {
1071 "source": "url",
1072 "url": "https://plugins.example.com/marketplace.json"
1073 }
1074 ]
1075}
1076```
1077
1078Permitir 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.
1079
1080```json theme={null}
1081{
1082 "strictKnownMarketplaces": [
1083 {
1084 "source": "github",
1085 "repo": "acme-corp/*"
1086 }
1087 ]
1088}
1089```
1090
1091Permitir 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:
1092
1093```json theme={null}
1094{
1095 "strictKnownMarketplaces": [
1096 {
1097 "source": "hostPattern",
1098 "hostPattern": "^github\\.example\\.com$"
1099 }
1100 ]
1101}
1102```
1103
1104Permitir marketplaces basados en sistema de archivos desde un directorio específico usando coincidencia de patrón regex en la ruta:
1105
1106```json theme={null}
1107{
1108 "strictKnownMarketplaces": [
1109 {
1110 "source": "pathPattern",
1111 "pathPattern": "^/opt/approved/"
1112 }
1113 ]
1114}
1115```
1116
1117Use `".*"` como `pathPattern` para permitir cualquier ruta del sistema de archivos mientras aún controla fuentes de red con `hostPattern`.
1118
1119<Note>
1120 `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`.
1121
1122 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).
1123</Note>
1124
1125<h4 id="how-restrictions-work">
1126 Cómo funcionan las restricciones
1127</h4>
1128
1129Las 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`.
1130
1131Dónde se aplican las dos listas depende de dónde las establezca:
1132
1133* **La consola de administración de claude.ai**: Claude Code aplica ambas listas en las sesiones que [leen configuración administrada gestionada por servidor](/docs/es/managed-settings#where-and-when-a-policy-applies). claude.ai también las verifica cuando alguien en su organización agrega un nuevo marketplace desde un repositorio de git en claude.ai, o desde **Personalizar** en la aplicación Claude Desktop fuera de su pestaña Code. Eso cubre un marketplace que un miembro agrega para su propia cuenta y uno agregado para toda la organización bajo [**Configuración de la organización > Plugins**](https://claude.ai/admin-settings/plugins). claude.ai rechaza un repositorio que la lista de permitidos no admite o que la lista de bloqueo nombra. No vuelve a verificar un marketplace que se agregó en cualquiera de los lugares antes de que establezca las listas, y no verifica plugins cargados.
1134* **Un archivo de configuración administrada, política de nivel de SO u otra fuente administrada**: Claude Code aplica ambas listas donde lee esa fuente. claude.ai no la lee.
1135
1136Para 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).
1137
1138Cuando 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.
1139
1140La 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:
1141
1142* 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`
1143* Para fuentes de URL: la URL completa debe coincidir exactamente
1144* Para fuentes `hostPattern`: el host del marketplace se compara contra el patrón regex
1145* Para fuentes `pathPattern`: la ruta del sistema de archivos del marketplace se compara contra el patrón regex
1146
1147La 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.
1148
1149Un [marketplace alojado en claude.ai](/docs/es/discover-plugins#add-from-claude-ai) se compara por host: una entrada `hostPattern` que coincida con `claude.ai` lo rige, en `strictKnownMarketplaces` y en `blockedMarketplaces`. En la lista de permitidos, tal entrada no admite las cargas personales de claude.ai de un miembro. Requiere Claude Code v2.1.273 o posterior.
1150
1151Debido 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.
1152
1153Para 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).
1154
1155<h3 id="version-resolution-and-release-channels">
1156 Resolución de versiones y canales de lanzamiento
1157</h3>
1158
1159Las 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`.
1160
1161<Warning>
1162 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. Un plugin [cargado en su lugar](/docs/es/plugins-reference#plugin-caching-and-file-resolution) desde un marketplace agregado como directorio local tampoco está fijado. 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.
1163
1164 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`.
1165</Warning>
1166
1167<h4 id="set-up-release-channels">
1168 Configurar canales de lanzamiento
1169</h4>
1170
1171Para 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:
1172
1173* 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.
1174* 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.
1175
1176La 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.
1177
1178<Warning>
1179 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.
1180</Warning>
1181
1182<h5 id="example">
1183 Ejemplo
1184</h5>
1185
1186```json theme={null}
1187{
1188 "name": "stable-tools",
1189 "plugins": [
1190 {
1191 "name": "code-formatter",
1192 "source": {
1193 "source": "github",
1194 "repo": "acme-corp/code-formatter",
1195 "ref": "stable"
1196 }
1197 }
1198 ]
1199}
1200```
1201
1202```json theme={null}
1203{
1204 "name": "latest-tools",
1205 "plugins": [
1206 {
1207 "name": "code-formatter",
1208 "source": {
1209 "source": "github",
1210 "repo": "acme-corp/code-formatter",
1211 "ref": "latest"
1212 }
1213 }
1214 ]
1215}
1216```
1217
1218<h5 id="assign-channels-to-user-groups">
1219 Asignar canales a grupos de usuarios
1220</h5>
1221
1222Asigne 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:
1223
1224```json theme={null}
1225{
1226 "extraKnownMarketplaces": {
1227 "stable-tools": {
1228 "source": {
1229 "source": "github",
1230 "repo": "acme-corp/stable-tools"
1231 }
1232 }
1233 }
1234}
1235```
1236
1237El grupo de acceso temprano recibe `latest-tools` en su lugar:
1238
1239```json theme={null}
1240{
1241 "extraKnownMarketplaces": {
1242 "latest-tools": {
1243 "source": {
1244 "source": "github",
1245 "repo": "acme-corp/latest-tools"
1246 }
1247 }
1248 }
1249}
1250```
1251
1252<h4 id="pin-dependency-versions">
1253 Fijar versiones de dependencias
1254</h4>
1255
1256Un 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](/docs/es/plugin-dependencies) 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.
1257
1258<h3 id="rename-or-remove-a-plugin">
1259 Renombrar o eliminar un plugin
1260</h3>
1261
1262El `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`](#optional-plugin-fields) y mantenga `name` sin cambios.
1263
1264Si 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:
1265
1266```json theme={null}
1267{
1268 "name": "acme-tools",
1269 "owner": { "name": "Acme" },
1270 "plugins": [
1271 { "name": "code-formatter", "source": "./plugins/code-formatter" }
1272 ],
1273 "renames": {
1274 "formatter": "code-formatter",
1275 "legacy-linter": null
1276 }
1277}
1278```
1279
1280Cuando un usuario inicia Claude Code con el nombre anterior aún en su configuración, Claude Code sigue el mapa `renames`:
1281
1282* 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.
1283* Para una entrada `null`, Claude Code elimina la clave anterior y el aviso reporta que el plugin fue eliminado del marketplace.
1284* 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.
1285
1286Trate `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`.
1287
1288Ejecute `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`.
1289
1290<Note>
1291 La configuración administrada y de política es de solo lectura para Claude Code, por lo que los plugins habilitados allí no pueden ser reescritos automáticamente. El plugin renombrado aún se carga cada sesión, pero el aviso de renombramiento recurrirá hasta que un administrador actualice `enabledPlugins` en el archivo de configuración administrada para usar el nuevo nombre. Lo mismo se aplica a los plugins habilitados a través de otras fuentes de solo lectura como `--add-dir`.
1292</Note>
1293
1294Las versiones anteriores de Claude Code ignoran el campo `renames` y reportan `plugin-not-found` para el nombre anterior.
1295
1296<h2 id="validation-and-testing">
1297 Validación y pruebas
1298</h2>
1299
1300Pruebe su marketplace antes de compartirlo. La validación verifica la estructura de archivos; para probar si un plugin cambia lo que Claude hace en indicaciones realistas, ejecute su suite de evaluación con [`claude plugin eval`](/docs/es/plugin-evals) antes de publicar una nueva versión.
1301
1302Desde su directorio de marketplace, valide la sintaxis JSON:
1303
1304```bash theme={null}
1305claude plugin validate .
1306```
1307
1308O desde dentro de Claude Code:
1309
1310```shell theme={null}
1311/plugin validate .
1312```
1313
1314Agregue el marketplace para pruebas:
1315
1316```shell theme={null}
1317/plugin marketplace add ./path/to/marketplace
1318```
1319
1320Instale un plugin de prueba para verificar que todo funciona:
1321
1322```shell theme={null}
1323/plugin install test-plugin@marketplace-name
1324```
1325
1326Para flujos de trabajo completos de prueba de plugins, consulte [Pruebe sus plugins localmente](/docs/es/plugins#test-your-plugins-locally). Para solución de problemas técnicos, consulte [Referencia de plugins](/docs/es/plugins-reference).
1327
1328<h2 id="manage-marketplaces-from-the-cli">
1329 Administrar marketplaces desde la CLI
1330</h2>
1331
1332Claude 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.
1333
1334<h3 id="plugin-marketplace-add">
1335 Plugin marketplace add
1336</h3>
1337
1338Agregue un marketplace desde un repositorio de GitHub, URL de git, URL remota o ruta local.
1339
1340```bash theme={null}
1341claude plugin marketplace add <source> [options]
1342```
1343
1344**Argumentos:**
1345
1346* `<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
1347
1348Una 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.
1349
1350**Opciones:**
1351
1352| Opción | Descripción | Predeterminado |
1353| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
1354| `--scope <scope>` | Dónde declarar el marketplace: `user`, `project` o `local`. Consulte [Plugin installation scopes](/docs/es/plugins-reference#plugin-installation-scopes) | `user` |
1355| `--sparse <paths...>` | Limitar el checkout a directorios específicos a través de git sparse-checkout. Útil para monorepos | |
1356| `--claudeai` | Lea el argumento como el nombre de un [marketplace alojado en claude.ai](/docs/es/discover-plugins#add-from-claude-ai) en lugar de una fuente. Requiere Claude Code v2.1.273 o posterior | |
1357
1358Agregue un marketplace desde GitHub usando la abreviatura `owner/repo`:
1359
1360```bash theme={null}
1361claude plugin marketplace add acme-corp/claude-plugins
1362```
1363
1364Fije a una rama o etiqueta específica con `@ref`:
1365
1366```bash theme={null}
1367claude plugin marketplace add acme-corp/claude-plugins@v2.0
1368```
1369
1370Agregue desde una URL de git en un host que no sea GitHub:
1371
1372```bash theme={null}
1373claude plugin marketplace add https://gitlab.example.com/team/plugins.git
1374```
1375
1376Agregue desde una URL remota que sirva el archivo `marketplace.json` directamente:
1377
1378```bash theme={null}
1379claude plugin marketplace add https://example.com/marketplace.json
1380```
1381
1382Agregue desde un directorio local para pruebas:
1383
1384```bash theme={null}
1385claude plugin marketplace add ./my-marketplace
1386```
1387
1388Declare el marketplace en alcance de proyecto para que se comparta con su equipo a través de `.claude/settings.json`:
1389
1390```bash theme={null}
1391claude plugin marketplace add acme-corp/claude-plugins --scope project
1392```
1393
1394Para un monorepo, limite el checkout a los directorios que contienen contenido de plugins:
1395
1396```bash theme={null}
1397claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins
1398```
1399
1400Agregue un [marketplace alojado en claude.ai](/docs/es/discover-plugins#add-from-claude-ai) por el nombre impreso en la sección `From claude.ai:` de `claude plugin marketplace list`:
1401
1402```bash theme={null}
1403claude plugin marketplace add --claudeai claudeai-organization-library
1404```
1405
1406Con `--claudeai`, el comando rechaza `--scope` y `--sparse`. El marketplace se aloja para su cuenta, no se declara en un archivo de configuración, por lo que no puede compartirlo a través del `.claude/settings.json` de un proyecto.
1407
1408<h3 id="plugin-marketplace-list">
1409 Plugin marketplace list
1410</h3>
1411
1412Enumere todos los marketplaces configurados.
1413
1414```bash theme={null}
1415claude plugin marketplace list [options]
1416```
1417
1418**Opciones:**
1419
1420| Opción | Descripción |
1421| :------- | :--------------- |
1422| `--json` | Salida como JSON |
1423
1424Con `--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.
1425
1426Un marketplace de [claude.ai](/docs/es/discover-plugins#add-from-claude-ai) agregado no tiene un clon local, por lo que su entrada lleva sus identificadores de claude.ai, `marketplaceId` y `organizationUuid`, en lugar de `installLocation`.
1427
1428En sesiones de terminal donde [los plugins se sincronizan desde su cuenta de claude.ai](/docs/es/plugins-reference#synced-plugins), el listado de texto termina con una sección `From claude.ai:` que nombra lo que claude.ai lista para su cuenta más allá de los marketplaces que ha agregado. Para agregar uno de ellos, consulte [Agregar desde claude.ai](/docs/es/discover-plugins#add-from-claude-ai). La salida `--json` cubre solo los marketplaces configurados y deja esa sección fuera. Requiere Claude Code v2.1.273 o posterior.
1429
1430<h3 id="plugin-marketplace-remove">
1431 Plugin marketplace remove
1432</h3>
1433
1434Elimine un marketplace configurado. El alias `rm` también se acepta.
1435
1436```bash theme={null}
1437claude plugin marketplace remove <name> [options]
1438```
1439
1440**Argumentos:**
1441
1442* `<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`
1443
1444**Opciones:**
1445
1446| Opción | Descripción | Predeterminado |
1447| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
1448| `--scope <scope>` | Restringir la eliminación a un único alcance de configuración: `user`, `project` o `local`. Consulte [Plugin installation scopes](/docs/es/plugins-reference#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) |
1449
1450<Warning>
1451 Eliminar un marketplace de su último alcance restante también desinstala cualquier plugin que haya instalado desde él. Para actualizar un marketplace sin perder plugins instalados, use `claude plugin marketplace update` en su lugar.
1452</Warning>
1453
1454<h3 id="plugin-marketplace-update">
1455 Plugin marketplace update
1456</h3>
1457
1458Actualice 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.
1459
1460```bash theme={null}
1461claude plugin marketplace update [name]
1462```
1463
1464**Argumentos:**
1465
1466* `[name]`: nombre del marketplace a actualizar, como se muestra en `claude plugin marketplace list`. Actualiza todos los marketplaces si se omite
1467
1468Tanto `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](#pre-populate-plugins-for-containers).
1469
1470<h2 id="troubleshooting">
1471 Solución de problemas
1472</h2>
1473
1474<h3 id="marketplace-not-loading">
1475 Marketplace no se carga
1476</h3>
1477
1478**Síntomas**: No puede agregar marketplace o ver plugins de él
1479
1480**Soluciones**:
1481
1482* Verifique que la URL del marketplace sea accesible
1483* Compruebe que `.claude-plugin/marketplace.json` existe en la ruta especificada
1484* 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)
1485* Para repositorios privados, confirme que tiene permisos de acceso
1486
1487<h3 id="marketplace-validation-errors">
1488 Errores de validación de marketplace
1489</h3>
1490
1491Ejecute `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 →`.
1492
1493A partir de Claude Code v2.1.196, el pase por entrada también:
1494
1495* incluye plugins cuya `source` es `.`
1496* se ejecuta cuando `marketplace.json` está fuera de un directorio `.claude-plugin`, resolviendo fuentes contra el directorio del archivo en sí
1497* reporta los problemas de cada entrada incluso cuando otra parte del archivo tiene errores de esquema
1498
1499Las versiones anteriores omiten plugins en la raíz del marketplace y solo descienden desde un `.claude-plugin/marketplace.json`.
1500
1501Desde 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:
1502
1503| Error | Causa | Solución |
1504| :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1505| `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 |
1506| `Invalid JSON syntax: Unexpected token...` | Error de sintaxis JSON en marketplace.json | Verifique comas faltantes, comas extra o cadenas sin comillas |
1507| `Duplicate plugin name "x" found in marketplace` | Dos plugins comparten el mismo nombre | Dé a cada plugin un valor `name` único |
1508| `plugins[0].source: Path contains ".."` | Un segmento de la ruta de fuente es `..` | Use rutas relativas a la raíz del marketplace sin segmentos `..`. Consulte [Rutas relativas](#relative-paths) |
1509| `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` |
1510| `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 |
1511
1512**Advertencias** (no bloqueantes):
1513
1514* `Marketplace has no plugins defined`: agregue al menos un plugin al array `plugins`
1515* `No marketplace description provided`: agregue una `description` de nivel superior para ayudar a los usuarios a entender su marketplace
1516* `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.
1517* `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.
1518* `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.
1519
1520<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">
1521 Validate a plugin or a directory without a manifest
1522</h4>
1523
1524Para 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.
1525
1526<h5 id="pick-the-directory-to-name">
1527 Pick the directory to name
1528</h5>
1529
1530Claude 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:
1531
1532| To check | Run | Claude Code checks |
1533| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1534| 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 |
1535| 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 |
1536| 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 |
1537| 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` |
1538| Your user-level directories | `claude plugin validate ~/.claude` | `~/.claude/skills`, `~/.claude/agents` y `~/.claude/commands` |
1539
1540<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">
1541 Check a plugin whose skill is its root `SKILL.md`
1542</h5>
1543
1544Cuando 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:
1545
1546* Nombre ese directorio `skills` para verificar el `SKILL.md` raíz del plugin.
1547* Nombre el directorio del plugin para verificar el resto.
1548
1549Cuando 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.
1550
1551<h5 id="check-files-behind-symlinks">
1552 Check files behind symlinks
1553</h5>
1554
1555Cuando 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:
1556
1557* **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.
1558* **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.
1559* **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.
1560
1561En 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:
1562
1563* **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.
1564* **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.
1565
1566<h5 id="read-the-validation-results">
1567 Read the validation results
1568</h5>
1569
1570Una ejecución limpia termina con `Validation passed`.
1571
1572`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.
1573
1574Dos de los errores que Claude Code reporta de estas ejecuciones, con la solución para cada uno:
1575
1576* `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
1577* `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
1578
1579En 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í.
1580
1581<h3 id="plugin-installation-failures">
1582 Fallos de instalación de plugins
1583</h3>
1584
1585**Síntomas**: El marketplace aparece pero la instalación del plugin falla
1586
1587**Soluciones**:
1588
1589* Verifique que las URLs de fuente del plugin sean accesibles
1590* Compruebe que los directorios de plugins contengan archivos requeridos
1591* Para fuentes de GitHub, asegúrese de que los repositorios sean públicos o tenga acceso
1592* Pruebe las fuentes de plugins manualmente clonando/descargando
1593* 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
1594
1595<h3 id="private-repository-authentication-fails">
1596 La autenticación del repositorio privado falla
1597</h3>
1598
1599**Síntomas**: Errores de autenticación al instalar plugins desde repositorios privados
1600
1601**Soluciones**:
1602
1603Para instalación manual y actualizaciones:
1604
1605* Verifique que esté autenticado con su proveedor de git (por ejemplo, ejecute `gh auth status` para GitHub)
1606* Compruebe que su ayudante de credenciales esté configurado: `git config --global credential.helper`
1607* 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`
1608
1609Para actualizaciones automáticas en segundo plano:
1610
1611* La verificación en segundo plano utiliza sus ayudantes de credenciales de git configurados pero nunca solicita, por lo que su ayudante debe poder responder con una credencial almacenada. Los remotos SSH con una clave cargada en `ssh-agent` también se autentican
1612* Si su ayudante necesita solicitarle, la actualización en segundo plano falla silenciosamente y el clon existente permanece en su lugar. Inicie sesión en su ayudante primero para que contenga una credencial para el host. Para GitHub, ejecute `gh auth login`, luego `gh auth setup-git`
1613* Cuando la verificación encuentra nuevos commits, o no puede alcanzar o autenticarse al remoto, Claude Code re-clona el marketplace con las mismas credenciales. El re-clonado puede agotar el tiempo de espera en repositorios grandes
1614* Establezca `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` para mantener el clon existente sin intentar el re-clonado cuando la verificación en segundo plano no puede alcanzar o autenticarse al remoto
1615* Si el re-clonado agota el tiempo de espera en un repositorio grande, aumente el límite con [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)
1616* O actualice marketplaces privados manualmente con `/plugin marketplace update <name>`, que usa sus credenciales
1617
1618Antes de v2.1.280, la verificación en segundo plano se ejecutaba sin sus ayudantes de credenciales y no podía autenticarse en repositorios privados sobre HTTPS.
1619
1620<h3 id="marketplace-updates-fail-in-offline-environments">
1621 Las actualizaciones del marketplace fallan en entornos sin conexión
1622</h3>
1623
1624**Síntomas**: En un entorno sin conexión o aislado, la actualización de marketplace en segundo plano no puede alcanzar el remoto y Claude Code intenta repetidamente un re-clonado que no puede tener éxito.
1625
1626**Causa**: La actualización en segundo plano verifica el remoto del marketplace para nuevos commits, y cuando la verificación no puede alcanzar el remoto, Claude Code intenta clonar el marketplace nuevamente. Sin conexión, el clonado falla de la misma manera y el clon existente permanece en su lugar. Antes de v2.1.274, la actualización ejecutaba `git pull` en el clon existente, movía el clon a un lado para re-clonar cuando el pull fallaba, y lo restauraba después en una base de mejor esfuerzo.
1627
1628La actualización se ejecuta en segundo plano después del inicio, por lo que no retrasa el inicio. Cada sesión aún repite el intento fallido, y cada operación de git puede esperar el [tiempo de espera de 120 segundos](#git-operations-time-out).
1629
1630**Solución**: Establezca `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` para omitir el intento de re-clonado y mantener el uso del clon existente cuando la verificación no puede alcanzar el remoto:
1631
1632```bash theme={null}
1633export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
1634```
1635
1636Para 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.
1637
1638<h3 id="git-operations-time-out">
1639 Las operaciones de Git agotan el tiempo de espera
1640</h3>
1641
1642**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`.
1643
1644**Causa**: Claude Code usa un tiempo de espera de 120 segundos para todas las operaciones de git, incluyendo clonación de repositorios de plugins y re-clonación de un marketplace para actualizarlo. Los repositorios grandes o las conexiones de red lentas pueden exceder este límite.
1645
1646**Solución**: Aumente el tiempo de espera usando la variable de entorno `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`. El valor está en milisegundos:
1647
1648```bash theme={null}
1649export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutos
1650```
1651
1652<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">
1653 Los plugins con rutas relativas fallan en marketplaces basados en URL
1654</h3>
1655
1656**Síntomas**: Agregó un marketplace a través de una URL como `https://example.com/marketplace.json`, pero plugins con fuentes de ruta relativa como `"./plugins/my-plugin"` fallan al instalar con `its marketplace entry path does not stay inside the marketplace directory`. Los plugins ya instalados fallan al cargar con `Plugin source path refused`. Ambos mensajes tienen una [entrada de referencia de error](/docs/es/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).
1657
1658**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.
1659
1660**Soluciones**:
1661
1662* **Use fuentes externas**: cambie las entradas de plugins a cualquier [plugin source](#plugin-sources) que no sea una ruta relativa:
1663 ```json theme={null}
1664 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
1665 ```
1666* **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.
1667
1668<h3 id="files-not-found-after-installation">
1669 Archivos no encontrados después de la instalación
1670</h3>
1671
1672**Síntomas**: El plugin se instala pero las referencias a archivos fallan, especialmente archivos fuera del directorio del plugin
1673
1674**Causa**: Claude Code copia plugins instalados a un directorio de caché, a menos que el plugin se cargue en el lugar. Una [`command` source in link mode](#copy-mode-and-link-mode) se carga en el lugar, y también lo hace una [relative path source](#relative-paths) en un marketplace agregado desde un directorio local. Las rutas que hacen referencia a archivos fuera del directorio del plugin copiado (como `../shared-utils`) no funcionarán porque esos archivos no se copian.
1675
1676**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.
1677
1678Para herramientas de depuración adicionales y problemas comunes, consulte [Debugging and development tools](/docs/es/plugins-reference#debugging-and-development-tools).
1679
1680<h2 id="see-also">
1681 Ver también
1682</h2>
1683
1684* [Descubrir e instalar plugins precompilados](/docs/es/discover-plugins) - Instalación de plugins desde marketplaces existentes
1685* [Plugins](/docs/es/plugins) - Creación de sus propios plugins
1686* [Referencia de plugins](/docs/es/plugins-reference) - Especificaciones técnicas completas y esquemas
1687* [Configuración de plugins](/docs/es/settings-reference#plugin-settings) - Opciones de configuración de plugins
1688* [Referencia de strictKnownMarketplaces](/docs/es/settings-reference#strictknownmarketplaces) - Restricciones de marketplace administrado