Plugin-Bundles per URL teilen, --plugin-url in 30 Minuten

Claude Code 2.1.129 hat im April 2026 einen neuen Flag bekommen: --plugin-url. Du gibst ihm eine URL zu einem Plugin-ZIP, er fetcht das Archiv beim Start, lädt das Plugin nur für diese Session, und nach dem Beenden ist es wieder weg. Das ist die einfachste Plugin-Distribution-Methode die Anthropic bisher anbietet.

Klingt klein. Hat aber praktische Folgen wenn Du Plugins testet, mit Kollegen teilst oder als CI-Build-Artefakt distribuierst. Hier wann das Sinn macht und wann eher nicht.

1. Was --plugin-url genau macht

Wenn Du claude --plugin-url https://example.com/my-plugin.zip startest, passiert folgendes:

1. Claude Code lädt das ZIP von der URL bei Session-Start.
2. Das Archiv wird in einem temporären Directory unter ~/.claude/plugins-session-cache/ ausgepackt.
3. Plugin wird für diese Session aktiviert. Skills, Agents, Hooks, MCP-Server alles wie bei einem normalen Plugin.
4. Nach Session-Ende wird das Cache-Directory beim nächsten Cleanup gelöscht. Plugin ist nicht persistent installiert.

Das ist explizit Session-only. Wenn Du das Plugin dauerhaft willst, musst Du den Marketplace-Pfad gehen oder per --plugin-dir lokal mounten.

Bei Fetch-Fehler oder ungültigem Archiv (kein .claude-plugin/plugin.json, kaputte ZIP-Struktur) reportet Claude Code einen Plugin-Load-Error und startet ohne das Plugin.

2. Wann Du --plugin-url nutzen solltest

Drei klare Use-Cases.

Erster Use-Case: schnelles Teilen mit Kollegen. Du hast ein Plugin gebaut, willst es einem Kollegen zeigen, ohne dass der einen Marketplace einrichtet oder sich GitHub-Klones holt. Du packst das Plugin als ZIP, schickst die URL (S3-Bucket, GitHub-Release-Asset, Dropbox-Link), Kollege startet claude --plugin-url <link>, fertig. Beide arbeiten gegen die gleiche Version, Kollege muss nichts dauerhaft installieren.

Zweiter Use-Case: CI-Build-Artefakte testen. Dein CI baut bei jedem Push ein Plugin-ZIP und pinned das auf eine Versionierte URL. Du willst die letzte Build-Version vor dem Tag-Release testen. claude --plugin-url https://ci.example.com/builds/main-abc123/plugin.zip, Test, fertig. Kein lokales Setup nötig, Du testest gegen die exakte CI-Version.

Dritter Use-Case: Throwaway-Plugins. Du brauchst für einen einmaligen Task ein spezielles Plugin (z.B. Migration von einem Framework auf ein anderes). Du willst das nicht permanent installieren weil es nach der Migration tot ist. URL einmal aufrufen, Job machen, Session schließen, weg.

3. Wann Du es nicht nutzen solltest

Drei klare Anti-Patterns.

Du nutzt das Plugin täglich. Bei jedem Session-Start ein 5-MB-ZIP fetchen ist Verschwendung. Pack das Plugin in einen Marketplace oder klone es lokal mit --plugin-dir. URL-Loading ist für Spike-Use, nicht Daily-Driver.

Plugin braucht persistent State. Wenn Dein Plugin Daten in ~/.claude/plugins/<name>/state.json speichert oder eine lokale DB pflegt, geht das mit --plugin-url nicht. Cache-Directory wird zwischen Sessions nicht synchronisiert.

Plugin-URL kommt aus dubioser Quelle. ZIP-Archive die Du nicht kontrollierst, von Foren-Posts oder Discord-Links, fetch nie blind. Dasselbe Trust-Problem wie bei npm install von Random-Packages.

4. Plugin-Bundle-Format

Du musst das ZIP genau so strukturieren wie ein normales Plugin-Verzeichnis. Wurzel des ZIPs:

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

plugin.json ist Pflicht, alles andere optional je nach Plugin-Typ. Wichtig: das ZIP darf keinen Wrapper-Folder haben. Wenn Du my-plugin/ als Top-Level-Folder im ZIP hast statt direkt .claude-plugin/, findet Claude Code den Manifest nicht und scheitert.

Erstellung mit cd my-plugin && zip -r ../my-plugin.zip . (vom Plugin-Inhalt aus, nicht vom Parent-Folder).

5. URL-Hosting Optionen

Wo legst Du das ZIP ab. Drei pragmatische Pfade.

GitHub Releases. Wenn Du ein GitHub-Repo hast, lege das ZIP als Release-Asset ab. URL ist https://github.com/user/repo/releases/download/v1.0/plugin.zip. Versioniert, kostenlos, Cache-für-Cache by GitHub-CDN.

S3 oder Cloudflare R2. Für eigene Plugins ohne Public-Repo. Bucket mit Public-Read für das ZIP, URL ist die Bucket-URL. R2 hat keine Egress-Kosten, was bei häufigem Download relevant ist.

Direct Server. Wenn Du eh schon eine Domain hast (z.B. studiomeyer.io), lege das ZIP einfach unter studiomeyer.io/downloads/my-plugin.zip ab. Webserver muss Content-Type: application/zip korrekt liefern, das wars.

Achte bei allen Optionen auf TLS. Claude Code wird (meine Erwartung, in der Doku nicht explizit) HTTP-URLs entweder ablehnen oder warnen. Plus: HTTP-Plugin-URLs sind ein offensichtlicher MITM-Vektor. Immer HTTPS.

6. Trust und Security

Anthropic sagt explizit in der Doku: dieselben Trust-Considerations gelten wie für alle Plugin-Quellen. Heißt, ein Plugin von einer URL kann genauso schädlich sein wie ein böse-eingerichteter Marketplace. Lade nur Plugins von Quellen die Du selbst kontrollierst oder die Du klar einer vertrauenswürdigen Person zuordnen kannst.

Konkrete Risiken:

Plugin kann beliebige Bash-Befehle über allowed-tools ausführen wenn Du den Hooks-Setup nicht restringierst. allowed-tools: Bash(*) in einer Skill bedeutet Vollzugriff.

Plugin kann über MCP-Server-Configs externe HTTP-Calls machen. Ein boese gemeintes MCP-Server-Snippet im Plugin kann Daten exfiltrieren.

Plugin kann über Hooks bei jedem UserPromptSubmit oder PostToolUse Event triggern und das nutzen um Daten an einen Remote-Server zu schicken.

Schutzmaßnahmen:

--plugin-url mit lokal kontrollierten URLs ist OK. Mit fremden URLs ohne Code-Review, nicht.

Bei kritischen Plugins (z.B. für Production-Repos) immer das ZIP runterladen, manuell aufmachen, Code-Review, dann erst aktivieren. Nicht direkt per URL.

Falls Du Plugins für Dein Team distributierst, signiere die ZIPs (z.B. mit cosign) und stelle einen Verify-Schritt in Eure Onboarding-Doku.

7. Marketplace vs --plugin-url, die Entscheidung

Die offizielle Plugin-Distribution geht über Marketplaces. Du legst einen marketplace.json in einem Repo an, User registrieren das mit /plugin marketplace add <repo>, Du publishst Updates per Commit. Versionierung über version-Field oder Git-SHA.

Für langlebige Plugins die Du dauerhaft distributierst ist das die richtige Methode. Marketplace gibt User auto-Updates, einfaches Browse-Erlebnis, klare Versionsverwaltung.

--plugin-url ist die kurze Variante für Faelle wo Marketplace overkill ist. Single-Use, Test-Build, throwaway, Demo. Keine Marketplace-Pflege.

Praktische Faustregel: wenn Du einen festen Slug brauchst und mehrere User pflegen sollen, Marketplace. Wenn Du das Plugin bei jedem Run frisch fetchen willst oder es nur für eine Demo brauchst, URL.

8. Migration von --plugin-dir zu --plugin-url

Du hast vermutlich schon mit --plugin-dir ./my-plugin getestet. Schritt zu --plugin-url ist klein.

# Vorher: lokal mit --plugin-dir
claude --plugin-dir ./my-plugin

# ZIP packen
cd my-plugin && zip -r ../my-plugin.zip .

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

# Mit URL starten
claude --plugin-url https://your-bucket.s3.amazonaws.com/my-plugin.zip

Was sich nicht ändert: das Plugin-Verhalten, die Skills, die Hooks. Identisch zu --plugin-dir.

Was sich ändert: kein Live-Reload bei Edit. Wenn Du am Plugin baust, ist --plugin-dir viel praktischer, der /reload-plugins Befehl picked Änderungen direkt auf. URL-Mode ist Snapshot-basiert, Du musst neu zippen und neu hochladen für jede Änderung.

9. Die zwei Stolperfallen

ZIP-Wrapper-Folder. Wenn Du das Plugin-Verzeichnis von ausserhalb zippst (zip -r my-plugin.zip my-plugin/) hat das ZIP einen Top-Level-Folder. Claude Code findet .claude-plugin/plugin.json dann unter my-plugin/.claude-plugin/plugin.json statt direkt unter .claude-plugin/plugin.json und scheitert. Pflicht: vom Plugin-Inhalt aus zippen mit cd my-plugin && zip -r ../my-plugin.zip ..

Cache-Persistenz wird unterschaetzt. Es gibt einen impliziten Cache-Eintrag für URL-Plugins damit Du nicht bei jedem Start neu fetchst. Änderst Du das ZIP an der URL, hast Du im Worst-Case einen Stale-Cache-Hit. Workaround: bei Plugin-Updates URL-Pfad ändern (Versionierung), z.B. plugin-v1.zip, plugin-v2.zip. Oder Cache vor dem nächsten Run loeschen mit rm -rf ~/.claude/plugins-session-cache/.

10. Was als nächstes

Wenn Du noch nie ein Plugin gebaut hast, fang mit --plugin-dir an, get vertraut mit dem Format, dann erst URL-Distribution. Pflicht-Lesen ist die offizielle Anthropic-Plugins-Doku.

Wenn Du Plugins schon im Marketplace hast, lohnt --plugin-url als Test-Pipeline. CI baut bei jedem Commit ein ZIP, Du tests gegen die letzte Pre-Release-Version, dann tagst Du für den Marketplace-Release.

Plus check Lesson L4-06 in der Academy für Marketplace-Discovery-Patterns. Die geht in Detail darueber wie Du den marketplace.json aufbaust und Plugins über den offiziellen Anthropic-Marketplace verteilst.

Wenn Du selbst eigene Plugin-Marketplaces hosten willst (z.B. für Dein Team oder Dein Open-Source-Projekt), ist das Playbook mcp-server-publishen ergaenzend, da geht es zwar um MCP-Server-Listings, aber die Marketplace-Logik dahinter ist verwandt.

Source

Specs verifiziert via offizielle Anthropic-Dokumentation am 2026-05-07:

• code.claude.com/docs/en/plugins (--plugin-url Verhalten, Bundle-Format, Trust-Considerations, Marketplace-Vergleich)
• github.com/anthropics/claude-code/releases/tag/v2.1.129 (Release-Notes, --plugin-url als neuer Flag)

Konsultierte Sekundaer-Quellen:

• claude-world.com Claude-Code-2.1.129-Release-Notes (URL-Plugin-Fetching Coverage)
• github.com/anthropics/claude-plugins-official/marketplace.json (offizielles Marketplace-Format-Beispiel)

Konsultierte Recipes in der Academy:

• Phase 1 Recipe 1.5 Plugins-Setup
• Lesson L4-06 MCP-Discovery und Marketplaces
• Playbook eigene-slash-commands-für-claude-code (Plugin-Pendant)