Skip to main content
Una dependencia de plugin es otro plugin del que su plugin depende, como uno cuyo servidor MCP o skill llama. Cada dependencia rastrea la versión más reciente que proporciona su marketplace a menos que declare una restricción de versión, un rango de versión semántica como ^2.0 o ~2.1.0 que haya probado. Esta página es para autores de plugins que declaran dependencias en plugin.json y para mantenedores de marketplace que etiquetan versiones.
Estos casos se cubren en otras páginas:
Para agregar una restricción, comience en Declare una dependencia con una restricción de versión. Si mantiene un plugin del que otros dependen, etiquete sus versiones para que sus restricciones puedan resolverse.

​
Declare dependencias

Sin una restricción de versión, una dependencia se mueve a cada nueva versión que su marketplace publica la próxima vez que los usuarios actualizan. Si esa versión cambia el nombre de una herramienta MCP que su plugin llama, su plugin se rompe para todos los que actualizan. Con una restricción como ~2.1.0 en una dependencia de una fuente respaldada por git, los usuarios que tienen su plugin instalado siguen recibiendo parches 2.1.x de la dependencia y nunca se mueven a 2.2. Para actualizar en su propio cronograma, pruebe contra una versión más reciente y luego publique una nueva versión de su plugin con una restricción más amplia.

​
Declare una dependencia con una restricción de versión

Liste las dependencias en el array dependencies del archivo .claude-plugin/plugin.json de su plugin. El siguiente manifiesto declara una dependencia sin versión y una dependencia con restricción:
.claude-plugin/plugin.json
Una entrada puede ser una cadena: solo el nombre del plugin, como "audit-logger" en este manifiesto, o "name@marketplace" para resolverlo en otro marketplace. Con una cadena simple, su plugin depende de cualquier versión que proporcione el marketplace de ese plugin. Para establecer una restricción de versión, use un objeto con estos campos, cada uno una cadena: Un rango no coincide con versiones previas al lanzamiento como 2.0.0-beta.1 a menos que opte por un sufijo previo al lanzamiento como ^2.0.0-0.

​
Agrupe plugins para un equipo

Para permitir que los ingenieros instalen un conjunto curado de plugins con un comando, publique un plugin cuyo manifiesto contenga un name y un array dependencies. Un manifiesto de plugin solo necesita name, por lo que este es un plugin válido, e instalarlo instala cada dependencia. Por ejemplo, un equipo de plataforma puede publicar bundles específicos de roles en un marketplace interno para que los ingenieros ejecuten un claude plugin install en lugar de instalar cada plugin por separado:
.claude-plugin/plugin.json
Para agregar un plugin al conjunto estándar más tarde, publique una nueva versión de backend-standard con la dependencia adicional. Cuando el marketplace no se actualiza automáticamente de forma predeterminada, los ingenieros activan la actualización automática para el marketplace o actualizan manualmente:
  • Activar la actualización automática para el marketplace: la próxima actualización automática mueve el bundle a la nueva versión e instala cualquier dependencia que agregue.
  • Actualizar manualmente: ejecute claude plugin update backend-standard en un shell, luego /reload-plugins en una sesión abierta para instalar las dependencias recién agregadas.
Para los pasos del lado del ingeniero, consulte Mantenga los plugins actualizados. Para implementar un bundle para todos en una organización, un administrador lo agrega a enabledPlugins en la configuración administrada. Consulte Pre-instalar y requerir plugins.

​
Dependa de un plugin de otro marketplace

De forma predeterminada, Claude Code no instala una dependencia de un marketplace diferente al del plugin declarante, a menos que el usuario ya tenga esa dependencia instalada y habilitada en el mismo alcance. Este valor predeterminado evita que un marketplace instale silenciosamente plugins de una fuente que el usuario no ha revisado. Para permitir la instalación, agregue el nombre del marketplace de destino a allowCrossMarketplaceDependenciesOn en el marketplace.json del marketplace raíz. El marketplace raíz es el que aloja el plugin que el usuario está instalando. Solo se aplica la lista de permitidos del marketplace raíz. El siguiente marketplace.json permite que deploy-kit dependa de un plugin de your-shared-marketplace:
.claude-plugin/marketplace.json
Si allowCrossMarketplaceDependenciesOn falta o no incluye el marketplace de destino, Claude Code no instala la dependencia. Cuando la dependencia se declara en la entrada del marketplace, la instalación se rechaza con un mensaje que comienza con Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist y nombra el campo a establecer. Cuando se declara en plugin.json, la instalación se completa sin la dependencia y su plugin luego falla al cargar. La verificación de la lista de permitidos no se aplica a una dependencia que ya está habilitada. Si un usuario instala audit-logger de your-shared-marketplace primero, en el mismo alcance, deploy-kit luego se instala sin ningún cambio en la lista de permitidos.

​
Pruebe un plugin y su dependencia localmente

Si está desarrollando un plugin y el plugin del que depende al mismo tiempo, inicie Claude Code desde su shell y cargue ambos con --plugin-dir:
La copia local de la dependencia satisface la entrada de dependencia de su plugin, por lo que no necesita instalar la dependencia desde su marketplace.
  • Sin version necesaria: el plugin.json local tampoco necesita una version, porque una restricción de versión no se verifica contra una copia local.
  • Entradas que nombran un marketplace: una entrada que nombra un marketplace también coincide con la copia local en Claude Code v2.1.242 o posterior.
Hasta que instale la dependencia desde su marketplace, su plugin deja de cargar cada vez que la copia local está deshabilitada o ausente:
  • Deshabilitó la copia local: su plugin está deshabilitado en la próxima carga de plugin, con un error que termina con is disabled — enable it or remove the dependency. Cuando el error nombra la dependencia como <name>@inline, ese identificador se refiere a la copia de --plugin-dir.
  • Inició una sesión sin la bandera --plugin-dir de la dependencia: el error reporta que la dependencia no está instalada. Pase la bandera nuevamente, o instale la dependencia desde su marketplace.
Cuando ambos plugins están en una carpeta padre, puede pasar esa carpeta a --plugin-dir una vez. Si la carpeta no es en sí misma un plugin, Claude Code carga cada carpeta secundaria que tenga un .claude-plugin/plugin.json. Requiere Claude Code v2.1.265 o posterior.

​
Publique un plugin del que otros dependen

Si mantiene un plugin del que otros plugins dependen con una restricción de versión, etiquete sus versiones para que esas restricciones puedan resolverse. Una restricción se resuelve contra etiquetas git en el repositorio que aloja el plugin. Etiquete el repositorio al que apunta la fuente del plugin del plugin en marketplace.json:
  • Fuente github, url, o git-subdir: el repositorio del plugin, por lo que el autor del plugin crea las etiquetas
  • Ruta relativa como ./plugins/secrets-vault: el repositorio del marketplace, por lo que el mantenedor del marketplace crea las etiquetas

​
Cree una etiqueta de versión

Etiquete cada versión como <plugin-name>--v<version>, donde <version> coincide con el campo version en el plugin.json de ese commit. El prefijo plugin-name permite que un repositorio de marketplace aloje varios plugins con historiales de versión independientes. Cree la etiqueta desde el directorio del plugin, con un control remoto origin configurado para recibir la etiqueta enviada, usando claude plugin tag:
El comando construye el nombre de la etiqueta desde el manifiesto del plugin. Antes de crear la etiqueta, ejecuta estas verificaciones:
  • Valida el plugin
  • Verifica que plugin.json y la entrada del marketplace estén de acuerdo sobre la versión, cuando el directorio del plugin está dentro de un checkout del marketplace
  • Requiere un árbol de trabajo limpio bajo el directorio del plugin
  • Se niega si la etiqueta ya existe
Una ejecución exitosa imprime Created tag secrets-vault--v2.1.0. Con --push, también imprime Pushed to origin. Sin --push, imprime el comando git push para ejecutar usted mismo. Pase --dry-run para ver el plan sin crear nada. La referencia de claude plugin tag lista las banderas restantes. También puede ejecutar git tag secrets-vault--v2.1.0 directamente, siempre que mantenga la version en plugin.json y en la entrada del marketplace sincronizadas usted mismo.

​
Restrinja una dependencia que tiene una fuente que no es git

La resolución basada en etiquetas se aplica solo a fuentes respaldadas por git. Para una dependencia con una fuente de plugin npm, archive, o command, la restricción no controla qué versión se obtiene. Aún se verifica cuando el plugin carga, y el plugin dependiente se deshabilita si la versión instalada no la satisface. Para fuentes npm, archive, y command, la versión verificada es la version en el plugin.json de la dependencia. Establezca una allí antes de restringir esa dependencia, porque un plugin.json que no establece versión no satisface ninguna restricción. Claude Code nunca instala una dependencia con una fuente command en sí, por lo que los usuarios la instalan primero. Tampoco ejecuta nunca el headersHelper de una dependencia, por lo que los usuarios también instalan una dependencia cuya entrada de marketplace establece uno antes de instalar su plugin. Además de claude plugin install, estas operaciones también instalan cualquier dependencia declarada faltante, y los límites de command y headersHelper se aplican a ellas también:
  • /reload-plugins
  • Auto-actualización del marketplace del plugin dependiente
  • Re-ejecutar claude plugin install en el plugin dependiente
  • claude plugin marketplace add

​
Cómo se comportan las dependencias para sus usuarios

Estas secciones describen cómo Claude Code resuelve, verifica y combina las restricciones que declara una vez que su plugin está instalado junto con otros.

​
Cómo una restricción se resuelve contra etiquetas

Cuando un usuario instala un plugin que declara { "name": "secrets-vault", "version": "~2.1.0" }, la dependencia se instala desde la etiqueta secrets-vault--v más alta que satisface ~2.1.0 en el repositorio que aloja secrets-vault. Cuando ninguna etiqueta satisface el rango, la instalación falla o usa la copia actual del marketplace:
  • Plugin con su propio repositorio: la instalación falla con un mensaje que contiene Dependency "secrets-vault@your-marketplace" has no git tag satisfying.
  • Plugin referenciado por una ruta relativa: la instalación usa la copia actual del marketplace en su lugar, y la restricción se verifica cuando el plugin carga. Si esa copia está fuera del rango, el plugin dependiente permanece deshabilitado y claude plugin list muestra Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0.
Para un plugin que el marketplace referencia por una ruta relativa, un marketplace que agregó como una ruta de carpeta local también resuelve restricciones contra las etiquetas git de esa carpeta, cuando la carpeta es un repositorio git. Esto requiere Claude Code v2.1.196 o posterior. Una carpeta local que no es un repositorio git no tiene etiquetas, por lo que Claude Code instala la dependencia desde el contenido actual de la carpeta en su lugar.

​
Confirme la versión resuelta

Para confirmar qué versión una restricción se resolvió, ejecute claude plugin list en su shell. Una dependencia resuelta por etiqueta muestra su versión con un sufijo de commit de 12 caracteres, como 2.1.0-8713c5b11005. Las verificaciones de restricción usan la versión de la etiqueta en lugar de la version en plugin.json, incluso si plugin.json en ese commit se queda atrás. Si fuerza el movimiento de una etiqueta a un commit diferente, la próxima instalación obtiene el contenido de ese commit en lugar de reutilizar una copia en caché obsoleta. Consulte Versiones y actualizaciones para ver cómo la versión de un plugin se convierte en su clave de caché.

​
Combine restricciones de varios plugins

Cuando varios plugins instalados restringen la misma dependencia, la dependencia se resuelve a la versión más alta que satisface todos sus rangos. Las combinaciones comunes se resuelven así: La auto-actualización obtiene una dependencia restringida en la etiqueta git más alta que satisface el rango de cada plugin instalado, en lugar de en la versión más reciente del marketplace. Si los rangos de los plugins instalados no se superponen, la auto-actualización deja esa dependencia en su versión actual, y la pestaña Errors de /plugin muestra una entrada que nombra el plugin que restringe. Si se superponen pero ninguna etiqueta cae en el rango, la auto-actualización obtiene la copia actual del marketplace y omite la actualización cuando la version de esa copia cae fuera del rango de cualquier plugin instalado. Cuando un usuario desinstala el último plugin que restringe una dependencia, la dependencia ya no está restringida a un rango de versión y reanuda el seguimiento de su entrada de marketplace en la próxima actualización.

​
Véase también