Restringir versiones de dependencias de plugins

Declare restricciones de versión en las dependencias de plugins e incluya un conjunto de plugins curado detrás de una única instalación.

Un plugin puede depender de otros plugins listándolos en plugin.json o en su entrada de marketplace. De forma predeterminada, una dependencia rastrea la versión más reciente disponible, por lo que un lanzamiento ascendente puede cambiar la dependencia bajo su plugin sin previo aviso. Las restricciones de versión le permiten mantener una dependencia en un rango de versión probado hasta que elija cambiar.

Cuando instala un plugin que declara dependencias, Claude Code resuelve e instala automáticamente, excepto una dependencia cuya entrada de marketplace tiene una command source o una headersHelper, que instala usted mismo primero. Más tarde, /reload-plugins, la actualización automática del marketplace del plugin dependiente, volver a ejecutar claude plugin install en el plugin dependiente, y claude plugin marketplace add cada uno instala cualquier dependencia declarada que no esté instalada aún, bajo las mismas reglas; si una permanece sin resolver, consulte Resolver errores de dependencia.

Esta guía es para autores de plugins que declaran dependencias en plugin.json y para mantenedores de marketplace que etiquetan lanzamientos. Las dependencias aquí son otros plugins; para los paquetes npm y Bun que usa el plugin en sí, consulte Dependencias de paquetes Node.js. Para instalar plugins que tienen dependencias, consulte Descubrir e instalar plugins. Para el esquema de manifiesto completo, consulte la referencia de Plugins.

Por qué restringir versiones de dependencias

Considere un marketplace interno donde dos equipos publican plugins. El equipo de plataforma mantiene secrets-vault, un servidor MCP que envuelve un backend de secretos. El equipo de implementación mantiene deploy-kit, que llama a secrets-vault para obtener credenciales durante las implementaciones.

deploy-kit se prueba contra secrets-vault v2.1.0. Sin una restricción de versión, la próxima vez que el equipo de plataforma etiquete un lanzamiento que renombre una herramienta MCP, la actualización automática mueve secrets-vault de cada ingeniero a la nueva versión y deploy-kit se rompe.

Con una restricción de versión, deploy-kit declara que necesita secrets-vault en el rango ~2.1.0. Los ingenieros con deploy-kit instalado permanecen en el parche 2.1.x más alto que coincida. El equipo de implementación se actualiza en su propio cronograma publicando una nueva versión de deploy-kit con una restricción más amplia.

Declarar una dependencia con una restricción de versión

Liste las dependencias en el array dependencies del plugin.json de su plugin.

El siguiente manifiesto declara una dependencia sin versión y una dependencia restringida:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Una entrada puede ser una cadena simple con solo el nombre del plugin, como "audit-logger" en el ejemplo anterior, que depende de cualquier versión que proporcione el marketplace de ese plugin. Para más control, use un objeto con estos campos:

Las versiones previas al lanzamiento como 2.0.0-beta.1 se excluyen a menos que su rango opte por un sufijo previo al lanzamiento como ^2.0.0-0.

Agrupar plugins para un equipo

Además del name requerido, un manifiesto de plugin puede consistir únicamente en un array dependencies. Instalarlo extrae todas las dependencias, lo que lo convierte en una forma de empaquetar un conjunto de plugins curado detrás de una única instalación.

Por ejemplo, un equipo de plataforma puede publicar paquetes específicos de roles en un marketplace interno para que los ingenieros ejecuten un único claude plugin install en lugar de instalar cada herramienta por separado:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Instalar backend-standard resuelve e instala las cuatro dependencias.

Para agregar una herramienta al conjunto estándar más adelante, publique una nueva versión de backend-standard con la dependencia adicional. La actualización automática está desactivada de forma predeterminada para marketplaces que no son de Anthropic, por lo que los ingenieros adoptan la nueva versión de una de dos formas:

• Habilite la actualización automática para el marketplace en /plugin. La siguiente actualización automática mueve el paquete a la nueva versión e instala cualquier dependencia que agregue.
• Ejecute claude plugin update backend-standard, luego /reload-plugins para instalar las dependencias recién agregadas.

Para implementar paquetes en toda una organización, agregue el plugin de paquete a enabledPlugins en configuración administrada.

Depender de un plugin de otro marketplace

De forma predeterminada, Claude Code se niega a instalar automáticamente una dependencia que vive en un marketplace diferente al del plugin que la declara. Esto evita que un marketplace extraiga silenciosamente plugins de una fuente que no ha revisado.

Para permitirlo, el mantenedor del marketplace raíz agrega el nombre del marketplace de destino a allowCrossMarketplaceDependenciesOn en marketplace.json. El marketplace raíz es el que aloja el plugin que el usuario está instalando; solo se consulta su lista de permitidos, por lo que la confianza no se encadena a través de marketplaces intermedios.

El siguiente marketplace.json permite que deploy-kit dependa de un plugin de acme-shared:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

Si el campo falta o no incluye el marketplace de destino, la instalación falla con un error cross-marketplace que nombra el campo a establecer. Los usuarios aún pueden instalar la dependencia manualmente primero, lo que satisface la restricción sin cambiar 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, cargue ambos con --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

La copia local de la dependencia satisface la entrada de dependencia de su plugin, incluso cuando la entrada nombra un marketplace, por lo que no necesita instalar la dependencia desde su marketplace. Claude Code no verifica una restricción de versión contra una copia local, por lo que el plugin.json local no necesita una version. Antes de v2.1.242, una entrada de dependencia que nombraba un marketplace nunca coincidía con la copia local, y Claude Code deshabilitaba su plugin al cargar.

Cuando ambos plugins se encuentran en una carpeta padre común, puede pasar esa carpeta a --plugin-dir una sola 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.

Si no ha instalado la dependencia desde su marketplace, su plugin deja de cargar cuando la copia local desaparece:

• Deshabilitó la copia local: Claude Code deshabilita su plugin en la siguiente carga de plugin. Para una entrada de dependencia que nombra un marketplace, Claude Code reporta Dependency "<name>@inline" is disabled — enable it or remove the dependency; para una entrada de nombre simple, lo reporta por su nombre simple. <name>@inline es cómo Claude Code identifica cada plugin --plugin-dir y --plugin-url.
• Inició una sesión sin la bandera --plugin-dir de la dependencia: Claude Code reporta la dependencia como no instalada. Pase la bandera nuevamente, o instale la dependencia desde su marketplace.

Etiquetar lanzamientos de plugins para la resolución de versiones

Claude Code resuelve restricciones de versión contra etiquetas de git en el repositorio que aloja la dependencia: el repositorio propio del plugin para fuentes de plugin github, url y git-subdir plugin sources, o el repositorio del marketplace para un plugin al que el marketplace hace referencia mediante una ruta relativa. Para que Claude Code encuentre las versiones disponibles de una dependencia, los lanzamientos del plugin ascendente deben etiquetarse utilizando una convención de nomenclatura específica.

Etiquete cada lanzamiento como {plugin-name}--v{version}, donde {version} coincide con el campo version en el plugin.json de ese commit. Desde el directorio del plugin, ejecute:

claude plugin tag --push

El comando claude plugin tag deriva el nombre de la etiqueta del manifiesto del plugin y de la entrada del marketplace que lo contiene. Antes de crear la etiqueta, valida el contenido del plugin, verifica que plugin.json y la entrada del marketplace coincidan en la versión, requiere un árbol de trabajo limpio bajo el directorio del plugin y se niega si la etiqueta ya existe.

• --push envía la etiqueta al remoto origin, por lo que el repositorio necesita un remoto origin configurado. Pase --remote para enviar a uno diferente.
• Si el envío falla, la etiqueta se crea localmente de todas formas y el comando sale con un error.
• Con --push, una ejecución exitosa termina con Created tag secrets-vault--v2.1.0 y Pushed to origin, donde la última línea nombra el remoto al que se envió. Sin --push, el comando imprime el comando git push a ejecutar en su lugar.
• --dry-run imprime lo que se etiquetaría sin crearlo.

Ejecutar git tag secrets-vault--v2.1.0 directamente es equivalente si mantiene plugin.json y la entrada del marketplace sincronizados usted mismo.

El prefijo del nombre del plugin permite que un repositorio de marketplace aloje múltiples plugins con líneas de versión independientes. El separador --v se analiza como una coincidencia de prefijo en el nombre completo del plugin, por lo que los nombres de plugin que contienen guiones se manejan correctamente.

Cuando instala un plugin que declara { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code enumera las etiquetas en el repositorio que aloja secrets-vault, filtra las que comienzan con secrets-vault--v y obtiene la versión más alta que satisface ~2.1.0. Si ninguna etiqueta en el repositorio propio del plugin satisface el rango, la instalación falla con Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0, que nombra la dependencia junto con su marketplace. Para un plugin de ruta relativa sin etiqueta coincidente, Claude Code instala la copia actual del marketplace en su lugar y verifica la restricción cuando se carga el plugin.

Para un plugin al que el marketplace hace referencia mediante una ruta relativa, un marketplace agregado como una ruta de carpeta local resuelve etiquetas de la misma manera cuando la carpeta es un repositorio de git. Esto requiere Claude Code v2.1.196 o posterior. En dos casos Claude Code instala la dependencia desde el contenido actual de la carpeta en su lugar:

• Las versiones anteriores no leen etiquetas de un marketplace de carpeta local, por lo que una dependencia restringida se carga solo si esa copia satisface el rango.
• Una carpeta local que no es un repositorio de git no tiene etiquetas, independientemente de la versión.

El semver de la etiqueta resuelta se registra por separado del version de plugin.json, por lo que las comprobaciones de restricción utilizan la etiqueta que se obtuvo realmente incluso si el plugin.json en ese commit tiene un valor obsoleto. El nombre del directorio de caché para una instalación resuelta por etiqueta incluye un sufijo SHA de commit de 12 caracteres, por lo que si un mantenedor mueve forzadamente una etiqueta a un commit diferente, la siguiente instalación obtiene un directorio de caché nuevo en lugar de reutilizar contenido obsoleto.

Cómo interactúan las restricciones

Cuando varios plugins instalados restringen la misma dependencia, Claude Code intersecta sus rangos y resuelve la dependencia a la versión más alta que satisface todos ellos. La tabla a continuación muestra cómo se resuelven las combinaciones comunes.

La actualización automática obtiene una dependencia restringida en la etiqueta git más alta que satisface el rango de cada plugin instalado, en lugar de obtenerla en la versión más reciente del marketplace, por lo que la dependencia continúa recibiendo actualizaciones dentro de su rango permitido. Si ninguna etiqueta satisface todos los rangos, la actualización automática omite esa dependencia y enumera la omisión en la pestaña Errores de /plugin, nombrando el plugin que la restringe.

Cuando desinstala el último plugin que restringe una dependencia, la dependencia ya no se mantiene y reanuda el seguimiento de su entrada de marketplace en la próxima actualización.

Habilitar o deshabilitar un plugin con dependencias

Esta sección cubre plugins instalados desde un marketplace. Para una copia que cargó con --plugin-dir, consulte Probar un plugin y su dependencia localmente.

Habilitar un plugin también habilita los plugins de los que depende, y deshabilitar un plugin se bloquea si otro plugin habilitado aún lo necesita.

Cuando habilita un plugin, Claude Code también habilita sus dependencias en el mismo ámbito. Si una dependencia tiene sus propias dependencias, Claude Code también las habilita. El mensaje de éxito lista qué más se habilitó junto con el plugin que nombró. Si una dependencia no se puede habilitar, el comando se rechaza y le dice qué está bloqueando y cómo solucionarlo:

Esto se mantiene incluso cuando una dependencia establece defaultEnabled: false en su manifiesto, porque Claude Code escribe un true explícito para ella. Lo mismo se aplica en la instalación: una dependencia extraída para satisfacer un plugin activo se instala con true independientemente de su propio valor predeterminado.

Cuando deshabilita un plugin, Claude Code se rechaza si otro plugin habilitado aún depende de él. El error nombra los plugins que dependen de él y le da un comando encadenado que los deshabilita en el orden correcto, terminando con el que pidió.

Por ejemplo, si deploy-kit depende de secrets-vault, deshabilitar secrets-vault solo falla con una salida similar a la siguiente:

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

Copie el comando encadenado del error para deshabilitar el conjunto completo en un paso.

Eliminar dependencias auto-instaladas huérfanas

Las dependencias auto-instaladas permanecen en el disco después de que se desinstalan los plugins que las instalaron, en caso de que desee reinstalar un plugin dependiente o desee seguir usando la dependencia directamente. Para limpiarlas, ejecute claude plugin prune para listar las dependencias auto-instaladas que ya no tienen ningún plugin instalado que las requiera y eliminarlas después de un mensaje de confirmación.

claude plugin prune

Si nada califica para su eliminación, el comando imprime Nothing to prune con la razón y sale. Esta es la salida esperada en una instalación nueva, no un error.

De forma predeterminada, prune opera en el ámbito del usuario y solicita confirmación antes de eliminar cualquier cosa:

• --scope project o --scope local se dirige a un ámbito diferente.
• --dry-run lista qué se eliminaría sin cambiar nada.
• -y omite el mensaje de confirmación. Cuando stdin o stdout no es una terminal, prune lista los huérfanos y sale sin eliminarlos a menos que se pase -y.

Para prune como parte de una desinstalación, pase --prune a claude plugin uninstall. Después de eliminar el plugin nombrado, Claude Code escanea y elimina cualquier dependencia auto-instalada que ahora esté huérfana. Los plugins que instaló usted mismo nunca se podan, solo los instalados automáticamente a través del array dependencies de otro plugin.

El mismo comportamiento de confirmación se aplica. Cuando stdin o stdout no es una terminal, la desinstalación se completa, pero el paso prune lista los huérfanos y no elimina nada a menos que se pase -y.

Por ejemplo, para desinstalar deploy-kit y limpiar las dependencias que deja atrás:

claude plugin uninstall deploy-kit --prune

Resolver errores de dependencia

Los problemas de dependencia aparecen en claude plugin list y en la interfaz /plugin, como mensajes de error descriptivos en lugar de los códigos literales en esta tabla. Claude Code deshabilita el plugin afectado hasta que resuelva el error. La tabla a continuación enumera los errores más comunes y cómo resolverlos.

Para verificar estos errores mediante programación, ejecute claude plugin list --json. Los plugins con problemas incluyen un campo errors que los enumera. Los plugins que se cargaron correctamente omiten el campo.

Ver también

• Crear plugins: construir plugins con skills, agentes y hooks
• Crear y distribuir un marketplace de plugins: alojar plugins para su equipo
• Referencia de Plugins: el esquema completo de plugin.json
• Gestión de versiones: cómo se resuelve la versión propia de un plugin y se utiliza como clave de caché