Distribuir plugin bundles via URL, --plugin-url en 30 minutos

Claude Code 2.1.129 recibió un flag nuevo en abril de 2026: --plugin-url. Le das una URL a un ZIP de plugin, trae el archivo al arrancar, carga el plugin solo para esta sesión, y al cerrar vuelve a desaparecer. Es el método de distribución de plugins más simple que Anthropic ofrece hasta ahora.

Suena pequeño. Pero tiene consecuencias prácticas cuando pruebas plugins, los compartes con colegas o los distribuyes como artefacto de build de CI. Aquí cuándo tiene sentido y cuándo no.

1. Qué hace --plugin-url exactamente

Cuando arrancas claude --plugin-url https://example.com/my-plugin.zip, pasa lo siguiente:

1. Claude Code carga el ZIP desde la URL al arrancar la sesión.
2. El archivo se descomprime en un directorio temporal bajo ~/.claude/plugins-session-cache/.
3. El plugin se activa para esta sesión. Skills, agents, hooks, MCP servers, todo como en un plugin normal.
4. Tras el fin de la sesión el directorio de caché se borra en la siguiente limpieza. El plugin no queda instalado de forma persistente.

Eso es explícitamente solo de sesión. Si quieres el plugin de forma permanente, tienes que ir por el camino del marketplace o montarlo localmente vía --plugin-dir.

Ante un error de fetch o un archivo inválido (sin .claude-plugin/plugin.json, estructura de ZIP rota) Claude Code reporta un error de carga de plugin y arranca sin el plugin.

2. Cuándo deberías usar --plugin-url

Tres casos de uso claros.

Primer caso de uso: compartir rápido con colegas. Construiste un plugin, quieres mostrárselo a un colega sin que monte un marketplace o se baje clones de GitHub. Empaquetas el plugin como ZIP, mandas la URL (bucket de S3, asset de release de GitHub, enlace de Dropbox), el colega arranca claude --plugin-url <link>, listo. Ambos trabajan contra la misma versión, el colega no tiene que instalar nada de forma permanente.

Segundo caso de uso: probar artefactos de build de CI. Tu CI construye un ZIP de plugin en cada push y lo fija a una URL versionada. Quieres probar la última versión de build antes de la release con tag. claude --plugin-url https://ci.example.com/builds/main-abc123/plugin.zip, prueba, listo. Sin setup local, pruebas contra la versión exacta de CI.

Tercer caso de uso: plugins desechables. Necesitas un plugin especial para una tarea puntual (p. ej. migración de un framework a otro). No quieres instalarlo de forma permanente porque tras la migración está muerto. Llamas la URL una vez, haces el trabajo, cierras la sesión, fuera.

3. Cuándo no deberías usarlo

Tres anti-patrones claros.

Usas el plugin a diario. Traer un ZIP de 5 MB en cada arranque de sesión es un desperdicio. Empaqueta el plugin en un marketplace o clónalo localmente con --plugin-dir. La carga por URL es para uso puntual, no para el daily driver.

El plugin necesita estado persistente. Si tu plugin guarda datos en ~/.claude/plugins/<name>/state.json o mantiene una DB local, eso no funciona con --plugin-url. El directorio de caché no se sincroniza entre sesiones.

La URL del plugin viene de una fuente dudosa. Archivos ZIP que no controlas, de posts de foros o enlaces de Discord, nunca los traigas a ciegas. El mismo problema de confianza que con npm install de paquetes aleatorios.

4. Formato del plugin bundle

Tienes que estructurar el ZIP exactamente como un directorio de plugin normal. Raíz del ZIP:

my-plugin.zip
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── agents/
│   └── my-agent.md
├── hooks/
│   └── hooks.json
└── README.md

plugin.json es obligatorio, todo lo demás opcional según el tipo de plugin. Importante: el ZIP no debe tener una carpeta envoltorio. Si tienes my-plugin/ como carpeta top-level en el ZIP en vez de .claude-plugin/ directamente, Claude Code no encuentra el manifiesto y falla.

Creación con cd my-plugin && zip -r ../my-plugin.zip . (desde dentro del contenido del plugin, no desde la carpeta padre).

5. Opciones de hosting de URL

Dónde dejas el ZIP. Tres caminos pragmáticos.

GitHub Releases. Si tienes un repo de GitHub, deja el ZIP como asset de release. La URL es https://github.com/user/repo/releases/download/v1.0/plugin.zip. Versionado, gratis, con caché por el CDN de GitHub.

S3 o Cloudflare R2. Para tus propios plugins sin repo público. Bucket con lectura pública para el ZIP, la URL es la URL del bucket. R2 no tiene costes de egress, lo cual es relevante con descargas frecuentes.

Servidor directo. Si ya tienes un dominio (p. ej. studiomeyer.io), simplemente deja el ZIP bajo studiomeyer.io/downloads/my-plugin.zip. El servidor web tiene que entregar Content-Type: application/zip correctamente, eso es todo.

En todas las opciones cuida el TLS. Claude Code (mi expectativa, no explícito en la documentación) o rechazará o avisará sobre URLs HTTP. Además: las URLs de plugin por HTTP son un vector MITM obvio. Siempre HTTPS.

6. Confianza y seguridad

Anthropic dice explícitamente en la documentación: aplican las mismas consideraciones de confianza que para todas las fuentes de plugins. Es decir, un plugin de una URL puede ser igual de dañino que un marketplace montado con mala intención. Carga solo plugins de fuentes que controlas tú mismo o que puedes atribuir claramente a una persona de confianza.

Riesgos concretos:

El plugin puede ejecutar comandos Bash arbitrarios vía allowed-tools si no restringes el setup de hooks. allowed-tools: Bash(*) en una skill significa acceso total.

El plugin puede hacer llamadas HTTP externas vía configs de MCP server. Un snippet de MCP server con mala intención en el plugin puede exfiltrar datos.

El plugin puede disparar vía hooks en cada evento UserPromptSubmit o PostToolUse y usar eso para mandar datos a un servidor remoto.

Medidas de protección:

--plugin-url con URLs controladas localmente está OK. Con URLs ajenas sin code review, no.

Para plugins críticos (p. ej. para repos de producción) siempre baja el ZIP, ábrelo a mano, code review, y solo entonces actívalo. No directamente vía URL.

Si distribuyes plugins para tu equipo, firma los ZIPs (p. ej. con cosign) y pon un paso de verify en vuestra documentación de onboarding.

7. Marketplace vs --plugin-url, la decisión

La distribución oficial de plugins va vía marketplaces. Pones un marketplace.json en un repo, los usuarios lo registran con /plugin marketplace add <repo>, tú publicas actualizaciones vía commit. Versionado vía el campo version o el SHA de git.

Para plugins de larga vida que distribuyes de forma permanente, ese es el método correcto. El marketplace da a los usuarios auto-updates, una experiencia de browse sencilla, gestión de versiones clara.

--plugin-url es la variante corta para casos donde el marketplace es excesivo. Uso único, build de prueba, desechable, demo. Sin mantenimiento de marketplace.

Regla aproximada práctica: si necesitas un slug fijo y varios usuarios deben mantenerlo, marketplace. Si quieres traer el plugin fresco en cada run o solo lo necesitas para una demo, URL.

8. Migración de --plugin-dir a --plugin-url

Probablemente ya probaste con --plugin-dir ./my-plugin. El paso a --plugin-url es pequeño.

# Antes: localmente con --plugin-dir
claude --plugin-dir ./my-plugin

# Empaquetar el ZIP
cd my-plugin && zip -r ../my-plugin.zip .

# Subir, ejemplo S3
aws s3 cp ../my-plugin.zip s3://your-bucket/my-plugin.zip --acl public-read

# Arrancar con la URL
claude --plugin-url https://your-bucket.s3.amazonaws.com/my-plugin.zip

Lo que no cambia: el comportamiento del plugin, las skills, los hooks. Idéntico a --plugin-dir.

Lo que cambia: sin live reload al editar. Si estás construyendo el plugin, --plugin-dir es mucho más práctico, el comando /reload-plugins recoge los cambios directamente. El modo URL es basado en snapshot, tienes que volver a comprimir y volver a subir por cada cambio.

9. Las dos trampas

Carpeta envoltorio del ZIP. Si comprimes el directorio del plugin desde fuera (zip -r my-plugin.zip my-plugin/) el ZIP tiene una carpeta top-level. Claude Code encuentra entonces .claude-plugin/plugin.json bajo my-plugin/.claude-plugin/plugin.json en vez de directamente bajo .claude-plugin/plugin.json y falla. Obligatorio: comprime desde dentro del contenido del plugin con cd my-plugin && zip -r ../my-plugin.zip ..

La persistencia de la caché se subestima. Hay una entrada de caché implícita para plugins por URL para que no traigas fresco en cada arranque. Si cambias el ZIP en la URL, en el peor caso tienes un acierto de caché obsoleto. Workaround: en actualizaciones de plugin cambia la ruta de la URL (versionado), p. ej. plugin-v1.zip, plugin-v2.zip. O borra la caché antes del siguiente run con rm -rf ~/.claude/plugins-session-cache/.

10. Qué viene después

Si nunca construiste un plugin, empieza con --plugin-dir, familiarízate con el formato, y solo entonces la distribución por URL. Lectura obligatoria es la documentación oficial de plugins de Anthropic.

Si ya tienes plugins en el marketplace, --plugin-url vale la pena como pipeline de prueba. CI construye un ZIP en cada commit, pruebas contra la última versión pre-release, y luego pones el tag para la release del marketplace.

Además mira la lección L4-06 en la Academy para patrones de descubrimiento de marketplace. Entra en detalle sobre cómo construyes el marketplace.json y distribuyes plugins vía el marketplace oficial de Anthropic.

Si quieres hostear tus propios marketplaces de plugins (p. ej. para tu equipo o tu proyecto open source), el playbook mcp-server-publishen es complementario, va sobre listings de MCP server, pero la lógica de marketplace detrás es emparentada.

Source

Specs verificadas vía documentación oficial de Anthropic el 2026-05-07:

• code.claude.com/docs/en/plugins (comportamiento de --plugin-url, formato de bundle, consideraciones de confianza, comparación con marketplace)
• github.com/anthropics/claude-code/releases/tag/v2.1.129 (release notes, --plugin-url como flag nuevo)

Fuentes secundarias consultadas:

• claude-world.com release notes de Claude Code 2.1.129 (cobertura de fetching de plugins por URL)
• github.com/anthropics/claude-plugins-official/marketplace.json (ejemplo de formato de marketplace oficial)

Recipes consultados en la Academy:

• Phase 1 Recipe 1.5 setup de plugins
• Lección L4-06 descubrimiento de MCP y marketplaces
• Playbook eigene-slash-commands-für-claude-code (equivalente de plugin)