Plugins sind der höchste Erweiterungsmechanismus in Claude Code: Sie bündeln Skills, Subagents, Hooks, MCP- und LSP-Server in einem einzigen installierbaren Paket, sodass ein Team nach der Installation nicht mehr jede Komponente einzeln einrichten muss. Dieses Modul zeigt, wie ein Plugin aufgebaut ist und was sein Manifest mindestens enthält, welche Manifest-Felder das Verhalten steuern — von sicherer Konfiguration über persistente Datenverzeichnisse bis zu Hintergrund-Monitoren und LSP-Servern —, und wie du Plugins lokal testest, über Marketplaces verteilst und ihren Lifecycle verwaltest.
Wie ein Plugin aufgebaut ist
Ein Plugin ist im Kern ein Verzeichnis mit einer festen Struktur. Die einzige Datei, die Claude Code zwingend erwartet, ist .claude-plugin/plugin.json — das Manifest, das die Identität des Plugins deklariert. Alles andere ist optional, folgt aber Konventionen, die Claude Code automatisch erkennt: Skills liegen unter skills/, Subagents unter agents/, Hook-Konfiguration in hooks/hooks.json, MCP-Server in .mcp.json, LSP-Server in .lsp.json, Standard-Einstellungen in settings.json und ausführbare Dateien unter bin/, die während der Plugin-Laufzeit in den PATH des Bash-Tools aufgenommen werden. Wichtig: Diese Ordner gehören alle auf die oberste Ebene des Plugin-Verzeichnisses, nicht in .claude-plugin/ — dort erwartet Claude Code ausschließlich die Manifest-Datei selbst.
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Required manifest
├── skills/ # SKILL.md files
│ └── my-skill/
│ └── SKILL.md
├── agents/ # Subagent definitions
│ └── specialist.md
├── commands/ # Legacy command files (also work)
│ └── my-command.md
├── hooks/
│ └── hooks.json # Plugin-scoped hooks
├── .mcp.json # MCP server configs
├── .lsp.json # LSP server configs
├── settings.json # Default settings
└── bin/
└── helper.sh Für Skills gibt es eine Abkürzung: Ein Plugin, das genau einen Skill ausliefert, kann SKILL.md direkt im Plugin-Root platzieren, statt ein eigenes skills/-Verzeichnis anzulegen. Claude Code lädt die Datei dann als einzelnen Skill und verwendet das name-Feld aus dem Frontmatter als Aufrufnamen. Für Plugins, die auf mehr als einen Skill anwachsen könnten, ist das skills/-Layout mit je einem Unterordner pro Skill die richtige Wahl; ältere Plugins verwenden dafür teils noch flache Markdown-Dateien unter commands/, was weiterhin funktioniert.
Das Manifest identifiziert das Plugin über Felder wie name, description, version, author, repository und license. Von diesen ist ausschließlich name zwingend erforderlich — ein eindeutiger, in Kebab-Case geschriebener Bezeichner.
{
"name": "pr-review",
"description": "Complete PR review workflow with security and test coverage checks",
"version": "1.0.0",
"author": {
"name": "Your Name"
},
"repository": "https://github.com/you/pr-review",
"license": "MIT"
} Genau dieser Name bestimmt zugleich den Namespace: Ein Skill hello aus einem Plugin namens my-first-plugin wird zu /my-first-plugin:hello, ein Agent agent-creator aus einem Plugin namens plugin-dev erscheint als plugin-dev:agent-creator. Du rufst Plugin-Skills entsprechend immer in dieser vollständigen, namensraumgebundenen Form auf. Ohne Manifest funktioniert ein Plugin ebenfalls — Claude Code sucht die Komponenten dann an den Standardpfaden und leitet den Plugin-Namen aus dem Verzeichnisnamen ab; ein Manifest lohnt sich, sobald du Metadaten oder abweichende Komponentenpfade brauchst.
Erweiterte Manifest-Felder
Das Manifest-Feld userConfig deklariert Werte, nach denen Claude Code beim Aktivieren des Plugins fragt, statt dich zum manuellen Bearbeiten von settings.json zu zwingen. Markierst du ein Feld mit sensitive: true, landet der Wert nicht im Klartext: Er wird im macOS Keychain gespeichert oder, auf Plattformen ohne unterstützten Schlüsselbund, als Fallback in ~/.claude/.credentials.json — demselben Speicher, den auch OAuth-Tokens nutzen, mit einem Gesamtlimit von rund 2 KB. Nicht-sensible Werte landen dagegen ganz normal unter dem pluginConfigs-Schlüssel in deiner settings.json.
{
"name": "my-plugin",
"version": "1.0.0",
"userConfig": {
"apiKey": {
"description": "API key for the integration",
"sensitive": true
},
"region": {
"description": "Deployment region",
"default": "us-east-1"
}
}
} Für Zustand, der Sessions überdauern soll, stellt Claude Code ${CLAUDE_PLUGIN_DATA} bereit (seit v2.1.78): ein persistentes Datenverzeichnis, das Plugin-Updates übersteht und sich für Caches, State-Dateien oder kleine Datenbanken eignet. Davon zu unterscheiden ist ${CLAUDE_PLUGIN_ROOT}, der Pfad zum aktuellen Installationsverzeichnis des Plugins — unverzichtbar, um in Hooks und MCP-Konfigurationen zuverlässig auf mitgelieferte Skripte und Konfigurationsdateien zu verweisen.
{
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/bin/audit.js"
}
]
}
]
}
} Ab Claude Code v2.1.105 können Plugins zusätzlich Hintergrund-Monitore ausliefern. Du deklarierst sie über experimental.monitors im Manifest; die ältere Top-Level-Form monitors funktioniert zwar weiterhin, aber claude plugin validate gibt dafür eine Warnung aus, und ein zukünftiges Release wird die verschachtelte Form verlangen. Ein Monitor bindet das Plugin an das Monitor-Tool: Sobald das Plugin beim Session-Start aktiviert wird oder einer seiner Skills aufgerufen wird, armt sich der Hintergrund-Watch automatisch — ohne dass du ihn selbst einrichten musst.
{
"name": "ci-watcher",
"version": "1.0.0",
"experimental": {
"monitors": "./monitors.json"
}
} Legst du im Manifest einen abweichenden monitors-Pfad fest, wird der Standardort monitors/monitors.json nicht mehr automatisch mitgescannt; willst du beide zusammen laden, musst du den Standardpfad explizit ergänzen.
Für Sprachintelligenz in Echtzeit legst du eine .lsp.json im Plugin-Root ab. Sie konfiguriert Language-Server, die Claude sofortige Diagnosen, Go-to-Definition und Symbolsuche liefern, während Dateien bearbeitet werden. Für verbreitete Sprachen wie TypeScript, Python oder Rust lohnt sich meist kein eigenes LSP-Plugin: Die vorgefertigten LSP-Plugins im offiziellen Marketplace decken diese bereits ab, eine eigene .lsp.json-Konfiguration bleibt vor allem für Sprachen ohne ein solches Angebot sinnvoll.
{
"typescript": {
"command": "typescript-language-server",
"args": ["--stdio"],
"extensionToLanguage": {
".ts": "typescript",
".tsx": "typescriptreact"
}
}
}Plugins testen, verteilen und verwalten
Bevor du ein Plugin verteilst, testest du es lokal. Das --plugin-dir-Flag lädt es ausschließlich für die laufende Session, ohne Installation; es akzeptiert neben einem Verzeichnis auch ein .zip-Archiv (ab v2.1.128) und lässt sich mehrfach wiederholen, um mehrere Plugins gleichzeitig zu laden.
claude --plugin-dir ./my-plugin
# Test multiple plugins simultaneously:
claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin Liegt ein Plugin bereits als gehostetes .zip-Archiv vor, etwa als CI-Build-Artefakt, holt --plugin-url es beim Start und lädt es ebenfalls nur für diese Session.
claude --plugin-url https://example.com/my-plugin.zip
claude --plugin-url https://example.com/a.zip --plugin-url https://example.com/b.zip Verwende --plugin-url ausschließlich mit URLs, denen du vertraust, denn das Laden eines fremden Archivs führt Drittanbieter-Code mit deinen Nutzerrechten aus.
Für Plugins, die du dauerhaft lokal weiterentwickelst, ohne sie über einen Marketplace zu installieren, scaffoldet claude plugin init <name> ein Grundgerüst direkt unter ~/.claude/skills/<name>/. Ab der nächsten Session lädt es automatisch als <name>@skills-dir — ganz ohne Marketplace-Eintrag und ohne separaten Installationsschritt. Änderungen an Plugin-Dateien übernimmst du während der Entwicklung mit /reload-plugins, ohne die Session neu zu starten; der Befehl liest Manifeste, Skills, Agents, Hooks sowie sämtliche Plugin-MCP- und Plugin-LSP-Server neu ein.
Das /plugin-Interface gliedert sich in vier Tabs: Discover, Installed, Marketplaces und Errors. Seit v2.1.145 zeigt der Discover-Tab beim Durchstöbern eines Marketplace-Katalogs eine vollständige Vorschau dessen, was ein noch nicht installiertes Plugin mitbringen wird — Befehle, Agents, Skills, Hooks sowie alle MCP- oder LSP-Server. Der Installed-Tab zeigt dieselbe Komponentenaufschlüsselung in seiner Detailansicht für bereits installierte Plugins, deckungsgleich mit claude plugin details. Damit wird das Prüfen eines Plugins zur Entscheidung auf einem Bildschirm, bevor überhaupt eine seiner Komponenten läuft.
Die Verteilung folgt einem Marketplace-Modell. Der offizielle Marketplace claude-plugins-official ist automatisch verfügbar, sobald du Claude Code startest; weitere Marketplaces fügst du mit /plugin marketplace add owner/repo hinzu, Plugins installierst du mit /plugin install plugin-name@marketplace-name.
# Install from official marketplace
/plugin install pr-review
# Install from GitHub
/plugin install github:username/my-plugin
# Install from local path (for testing)
/plugin install ./path/to/plugin Für GitHub-owner/repo-Kurzformen klont Claude Code dabei standardmäßig über SSH — in CI-Umgebungen ohne hinterlegten SSH-Key schlägt das fehl. Setze in diesem Fall CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1, um stattdessen über HTTPS zu klonen.
# Force HTTPS for plugin clones in CI
CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 claude plugin install owner/repo Für Organisationen steuert managed-mcp.json, welche MCP-Server Plugins überhaupt nutzen dürfen; die Managed-Settings-Felder enabledPlugins, extraKnownMarketplaces, strictKnownMarketplaces und blockedMarketplaces legen organisationsweit fest, welche Plugins und Marketplaces erlaubt sind. Unabhängig davon — und nicht auf Enterprise-Umgebungen beschränkt — gilt für Plugin-Subagents grundsätzlich, in jeder Umgebung: Ihr Frontmatter darf hooks, mcpServers oder permissionMode nicht definieren; diese Felder werden aus Sicherheitsgründen beim Laden eines Agenten aus einem Plugin schlicht ignoriert.
Zu den Lifecycle-Befehlen gehören claude plugin list, enable, disable, uninstall und validate. claude plugin prune (neu in v2.1.121, Alias autoremove) entfernt automatisch installierte Abhängigkeiten, die kein anderes installiertes Plugin mehr benötigt — direkt von dir installierte Plugins bleiben unangetastet; claude plugin uninstall <plugin> --prune erledigt Deinstallation und Aufräumen in einem Schritt. claude plugin details <name> zeigt die Komponenten eines Plugins gruppiert nach Skills, Agents, Hooks, MCP-Servern und LSP-Servern samt geschätzter Token-Kosten, getrennt nach always-on und on-invoke. claude plugin tag (neu in v2.1.118) erstellt einen Release-Git-Tag mit Versionsvalidierung, --push pusht ihn direkt mit, --dry-run zeigt vorab eine Vorschau.
enable und disable akzeptieren zusätzlich einen --scope-Wert von user, project oder local; lässt du ihn weg, erkennt Claude Code automatisch den Scope, in dem das Plugin installiert ist. Ein Deaktivieren im project-Scope schreibt die Wahl in .claude/settings.json, sodass das ganze Team sie übernimmt.
# Personal: turn off a noisy plugin just for you
claude plugin disable formatter@anthropics/claude-plugins
# Team: keep the plugin in settings but turn it off project-wide
claude plugin disable formatter --scope project
# Re-enable later without touching its install or version
claude plugin enable formatter --scope project Für kleine teaminterne Tools, die kein eigenes Repository rechtfertigen, gibt es außerdem das Inline-Plugin-Muster: Mit "source": "settings" bettest du eine Plugin-Definition direkt in eine Settings-Datei ein, ganz ohne separaten Marketplace.
{
"pluginMarketplaces": [
{
"name": "internal-tools",
"source": "settings",
"plugins": [
{
"name": "code-standards",
"source": "./local-plugins/code-standards"
}
]
}
]
}