Plugins sind der Erweiterungsmechanismus auf höchster Ebene in Claude Code. Sie bündeln Skills, Subagents, Hooks, MCP-Server und LSP-Konfigurationen in einem einzigen installierbaren Paket. Ein Team installiert ein Plugin und hat sofort alles konfiguriert — kein manuelles Setup für jede Komponente. Dieses Modul behandelt die Plugin-Struktur, das Manifest-Format, die Distributionsmechanismen und wie du dein eigenes baust.
Plugin-Architektur
Ein Plugin ist ein Verzeichnis mit einer bestimmten Struktur. Die einzige erforderliche Datei ist .claude-plugin/plugin.json, das Manifest, das die Identität des Plugins deklariert. Alles andere ist optional, folgt aber Konventionen, die Claude Code erkennt:
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.shEin Plugin, das genau einen Skill ausliefert, kann SKILL.md direkt im Plugin-Root platzieren, statt ein skills/ -Verzeichnis zu erstellen. Claude Code lädt es als einzelnen Skill und nutzt das Frontmatter- name -Feld für den Aufrufnamen. Nutze das skills/ -Layout für Plugins, die auf mehr als einen Skill anwachsen könnten.
Das Manifest identifiziert das Plugin und seine Metadaten:
{
"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"
}Plugin-Befehle und vom Plugin bereitgestellte Skills werden mit einem Namespace versehen als plugin-name:command-name um Konflikte mit der Konfiguration auf Projektebene zu vermeiden. Rufe sie in der vollständigen Namespace-Form auf, etwa /pr-review:check-security.
Manifest-Features
Das Manifest unterstützt mehrere mächtige Felder zur Konfiguration des Plugin-Verhaltens. userConfig deklariert vom Benutzer konfigurierbare Optionen. Felder, die als sensitive: true markiert sind, werden im System-Keychain statt in Klartext-Einstellungen gespeichert:
{
"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"
}
}
}Plugins erhalten ein persistentes Datenverzeichnis über ${CLAUDE_PLUGIN_DATA} (v2.1.78+). Es bleibt über Sessions hinweg erhalten und eignet sich daher für Caches, State-Dateien und Datenbanken. Nutze ${CLAUDE_PLUGIN_ROOT} um Pfade relativ zum Plugin-Installationsverzeichnis zu referenzieren — unverzichtbar für Hooks und MCP-Konfigurationen:
{
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/bin/audit.js"
}
]
}
]
}
}Plugin-Monitore erfordern Claude Code v2.1.105 oder neuer. Deklariere sie unter dem experimental -Schlüssel in deinem Manifest (experimental.monitors) — die Top-Level-Form funktioniert weiterhin, aber claude plugin validate wird eine Warnung ausgeben, und ein zukünftiges Release wird die verschachtelte Form erfordern. Der monitors -Manifest-Schlüssel verbindet das Plugin mit dem Monitor-Tool. Richte es auf eine JSON-Datei (oder inline die Konfiguration), und seine Hintergrund-Watches aktivieren sich automatisch in dem Moment, in dem das Plugin beim Session-Start aktiviert wird oder wenn einer der Skills des Plugins aufgerufen wird. So liefert ein Plugin ein Verhalten wie „CI überwachen, Fehler markieren“ oder „das Dev-Server-Log verfolgen“ aus, ohne dass der Nutzer es einrichten muss:
{
"name": "ci-watcher",
"version": "1.0.0",
"experimental": {
"monitors": "./monitors.json"
}
}Wenn das Manifest einen benutzerdefinierten monitors Pfad festlegt, wird der Standard- monitors/monitors.json Speicherort nicht mehr durchsucht — gib den Standard explizit an, wenn du ihn weiterhin zusammen mit deiner benutzerdefinierten Datei laden möchtest.
Die LSP-Unterstützung fügt eine Language-Server-Protocol-Integration in Echtzeit hinzu. Lege eine .lsp.json im Plugin-Root ab, um Language-Server zu konfigurieren, die sofortige Diagnosen, Go-to-Definition und Symbolsuche bereitstellen, während Claude Dateien bearbeitet:
{
"typescript": {
"command": "typescript-language-server",
"args": ["--stdio"],
"extensionToLanguage": {
".ts": "typescript",
".tsx": "typescriptreact"
}
}
}Verteilung und Entwicklung
Teste ein Plugin lokal mit dem --plugin-dir Flag, bevor du es verteilst. Es lädt das Plugin nur für diese Session — keine Installation:
claude --plugin-dir ./my-plugin
# Test multiple plugins simultaneously:
claude --plugin-dir ./my-plugin --plugin-dir ./another-pluginFür Plugins, die als .zip Archive gehostet werden, --plugin-url holt sie und installiert sie für die aktuelle Session ohne dauerhafte Installation. Wiederhole das Flag für mehrere Plugins:
claude --plugin-url https://example.com/my-plugin.zip
claude --plugin-url https://example.com/a.zip --plugin-url https://example.com/b.zipVerwende --plugin-url nur mit URLs, denen du vertraust — das Laden entfernter Archive führt Drittanbieter-Code auf deinem Rechner aus.
Nutze /reload-plugins um Plugin-Dateien während der Entwicklung ohne Neustart der Session per Hot-Reload zu aktualisieren. Dabei werden alle Manifeste, Skills, Agents, Hooks und MCP-Konfigurationen sofort neu eingelesen.
Das /plugin Die Bildschirme „Discover“ und „Browse“ zeigen jetzt eine vollständige Übersicht dessen, was ein Plugin installieren wird, bevor du dich dafür entscheidest — Befehle, Agents, Skills, Hooks sowie alle MCP- oder LSP-Server, die es mitbringt. Damit wird das Prüfen eines Marketplace-Plugins zu einer Entscheidung auf einem einzigen Bildschirm: Du kannst bestätigen, dass ein pr-review Plugin nicht heimlich MCP-Server oder Hooks registriert, die du nicht erwartet hast, oder prüfen, dass ein Deploy-Plugin tatsächlich den Skill mitbringt, dessentwegen du gekommen bist. „Browse“ listet das bereits Installierte mit derselben Aufschlüsselung auf; „Discover“ tut dasselbe für den Marketplace-Katalog. Die Vorschau ist rein informativ — das Plugin muss trotzdem installiert werden, bevor eine seiner Komponenten läuft.
Die Plugin-Verteilung folgt einem Marketplace-Modell. Der offizielle Anthropic-Marketplace ist claude-plugins-official. Füge weitere Marketplaces hinzu mit /plugin marketplace add owner/repo-name. Installiere Plugins mit /plugin install plugin-name oder claude plugin install plugin-name@marketplace:
# 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/pluginWenn eine Plugin-Quelle eine GitHub- owner/repo Kurzform ist, klont Claude Code standardmäßig über SSH. Das schlägt in CI-Runnern, Containern oder jeder Umgebung ohne konfigurierten SSH-Key für github.comfehl. Setze CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 , um stattdessen HTTPS-Cloning zu erzwingen — der Rest des Installationsablaufs bleibt identisch:
# Force HTTPS for plugin clones in CI
CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 claude plugin install owner/repoFür Enterprise-Umgebungen steuert managed-mcp.json , welche MCP-Server Plugins verwenden können. Die enabledPlugins, extraKnownMarketplaces, strictKnownMarketplaces, und blockedMarketplaces Einstellungen in der Managed Policy steuern, welche Plugins und Marketplaces organisationsweit erlaubt sind. Plugin-Subagents haben eingeschränktes Frontmatter — sie können hooks, mcpServers, oder permissionMode nicht definieren, um eine Rechteausweitung zu verhindern.
Zu den nützlichen Lifecycle-Befehlen gehört claude plugin list, claude plugin enable, claude plugin disable, claude plugin uninstall, claude plugin validate, claude plugin prune (neu in v2.1.121, mit Alias autoremove), das automatisch installierte Plugin-Abhängigkeiten entfernt, die kein anderes installiertes Plugin mehr benötigt — direkt von dir installierte Plugins werden nie angetastet; um ein Plugin zu deinstallieren und seine Abhängigkeiten in einem Schritt aufzuräumen, führe claude plugin uninstall <plugin> --prune. claude plugin details <name> zeigt die Komponentenübersicht eines Plugins, gruppiert nach Skills, Agents, Hooks, MCP-Servern und LSP-Servern, zusammen mit einer Schätzung, wie viele Token es jeder Session hinzufügt. Und claude plugin tag (neu in v2.1.118) erstellt einen Release-Git-Tag mit Versionsvalidierung. Marketplaces können Plugins aus GitHub, git-URLs, lokalen Pfaden, npm oder anderen unterstützten Paketquellen beziehen.
claude plugin enable und claude plugin disable schalten ein installiertes Plugin ein oder aus, ohne es zu entfernen. Beide akzeptieren einen <plugin> -Namen (oder <plugin>@<marketplace> zur Eindeutigkeit) und einen --scope -Wert von user, project, oder local (Standard: user). Ein Deaktivieren im project -Scope schreibt die Wahl in .claude/settings.json , sodass das ganze Team sie übernimmt; user -Scope hält sie persönlich:
# 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 projectDas Inline-Plugin-Muster (source: 'settings' in v2.1.80+) erlaubt es dir, eine Plugin-Definition direkt in eine Settings-Datei einzubetten, ohne ein separates Repository. Das ist nützlich für kleine teaminterne Tools, die kein vollständiges git-Repository rechtfertigen:
{
"pluginMarketplaces": [
{
"name": "internal-tools",
"source": "settings",
"plugins": [
{
"name": "code-standards",
"source": "./local-plugins/code-standards"
}
]
}
]
}