Versionado y dependencias

Un plugin que usa todo el equipo necesita disciplina de versiones: que una mejora tuya no rompa a nadie, y que las dependencias entre plugins no se muevan solas. Esta lección cierra el curso con cómo mantener tu plugin en producción.

Versionar releases

El campo version del plugin.json controla las actualizaciones:

• Con version: los usuarios solo reciben updates cuando lo subes (1.0.0 → 1.1.0). Control explícito.
• Sin version (distribuido por git): se usa el commit SHA, así que cada commit cuenta como versión nueva.

Para que las dependencias por rango funcionen (abajo), etiqueta cada release con la convención {plugin}--v{version}:

claude plugin tag --push

claude plugin tag deriva el tag del manifest y de la entrada del marketplace, valida el contenido del plugin, comprueba que plugin.json y la entrada del marketplace coinciden en la versión, exige el working tree limpio bajo el directorio del plugin y se niega si el tag ya existe. (Con --dry-run ves qué tag crearía sin crearlo.)

Tu turno: publica la 1.1.0 de dev-tools

Vas a sacar un release reproducible de principio a fin sobre el plugin dev-tools que construiste en la lección 03. La regla de oro: con version fijado, nadie recibe nada hasta que subes el campo. Así que el release son dos gestos tuyos —subir versión y etiquetar— y dos del equipo —refrescar y actualizar.

1 · Sube la versión en dev-tools/.claude-plugin/plugin.json de 1.0.0 a 1.1.0 (lo dejaste en 1.0.0 en la lección 03):

{
  "name": "dev-tools",
  "description": "Skills, hooks y revisor del equipo",
  "version": "1.1.0"
}

Si lo distribuyes en un marketplace y la versión también está en la entrada del marketplace, súbela en los dos sitios: deben coincidir, y claude plugin tag aborta si no.

2 · Commit y etiqueta, desde el directorio del plugin (claude plugin tag exige el working tree limpio):

git commit -am "release dev-tools 1.1.0"
claude plugin tag --push

El comando lee el manifest, valida, comprueba que las versiones coinciden y crea el tag dev-tools--v1.1.0 (el formato {plugin}--v{version}), empujándolo al remoto. (El detalle exacto de su salida no está documentado; espera una confirmación del tag creado y empujado. Si quieres ensayar sin tocar el remoto, primero claude plugin tag --dry-run.)

3 · El equipo recibe el update —dos comandos, en este orden, dentro de su sesión:

/plugin marketplace update       # refresca el catálogo: ve que dev-tools es 1.1.0
/plugin update                   # actualiza los plugins instalados a esa versión

/plugin marketplace update vuelve a leer el marketplace.json desde su fuente (el primero detecta el cambio de versión); /plugin update instala la versión nueva de los plugins ya instalados. Si la versión resuelta es la que ya tienen, ambos se saltan el plugin —por eso el paso 1 es obligatorio—. Tras actualizar, /reload-plugins activa los cambios sin reiniciar.

Atajo: si el marketplace tiene auto-update activado (los oficiales lo traen de serie; los de terceros, no), Claude Code refresca y actualiza solo al arrancar, y avisa con un aviso para correr /reload-plugins. Subir la versión sigue siendo tu responsabilidad.

Verifica que el release llegó: en una sesión con dev-tools instalado, abre /plugin → pestaña Installed, selecciona dev-tools y comprueba que figura como 1.1.0. Ese update entregado y recibido es el artefacto de esta lección.

Si falla

• tag already exists (o similar) → ya etiquetaste esta versión: dev-tools--v1.1.0 existe. Sube version a la siguiente (1.1.1) y vuelve a etiquetar; claude plugin tag no pisa un tag existente a propósito.
• claude plugin tag aborta por versiones que no coinciden → es la validación de la que hablamos: plugin.json dice 1.1.0 pero la entrada del marketplace sigue en 1.0.0 (o al revés). Iguala las dos y reintenta.
• El equipo no ve la 1.1.0 → casi siempre falta un paso. Si solo corrieron /plugin update, el catálogo local sigue en 1.0.0: hay que correr antes /plugin marketplace update. Y si version no se subió, no hay update que recibir.

Dependencias entre plugins

Un plugin puede depender de otros, declarándolos en dependencies del plugin.json. Sin restricción de versión, una dependencia sigue la última disponible — y un cambio upstream puede romperte sin avisar. Con un rango semver, la fijas a una versión probada:

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

• Una entrada string ("audit-logger") usa lo que dé el marketplace.
• Una entrada objeto con version (un rango semver: ~2.1.0, ^2.0, >=1.4) la fija: el usuario se queda en la versión más alta que cumpla el rango.

El caso real: deploy-kit está probado contra secrets-vault 2.1.x. Si otro equipo publica secrets-vault 3.0 con un cambio incompatible, sin rango el auto-update rompería a todo el mundo. Con ~2.1.0, los que tienen deploy-kit se quedan en 2.1.x hasta que tú decidas mover. Al instalar un plugin con dependencias, Claude Code las resuelve e instala solas.

Las dependencias también gobiernan activar y desactivar: activar un plugin activa de paso sus dependencias, y desactivar uno se bloquea si otro plugin activo aún lo necesita (el error te da el comando encadenado para desactivar ambos en orden). Y cuando desinstalas el plugin que las trajo, esas dependencias se quedan en disco; claude plugin prune lista y borra las huérfanas (o claude plugin uninstall <plugin> --prune para limpiarlas al desinstalar).

Recomendar tu plugin (hints)

Si mantienes una CLI propia y tienes un plugin en el marketplace oficial, tu CLI puede sugerir su instalación: emite una línea marcador (<claude-code-hint ... />) a stderr cuando detecta que corre dentro de Claude Code (variable CLAUDECODE). Claude Code la lee, la quita de la salida y ofrece instalar el plugin una vez, con confirmación del usuario. Útil para que quien use tu herramienta descubra tu integración sin fricción.

Cierre del curso y del nivel

Has cerrado el círculo: lo que fabricaste suelto (skills, subagentes, hooks, MCP) ahora es un plugin versionado en un marketplace que tu equipo instala y actualiza de un comando. Has pasado de configuración personal a infraestructura de equipo.

Con esto cierras el nivel "Integración y empaquetado". El último nivel del plan es Escalar y producción: llevar Claude a tu CI (que trabaje en los PRs sin que abras el terminal), orquestar varios agentes a la vez, y —opcional— construir tu propio agente con el SDK.

Fuente oficial: Constrain plugin dependency versions · Recommend your plugin from your CLI