SpyBara
Go Premium

plugins-reference.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 108 additions and 66 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Plugins-Referenz

Vollständige technische Referenz für das Claude Code Plugin-System, einschließlich Schemas, CLI-Befehle und Komponentenspezifikationen.

Ein Plugin ist ein eigenständiges Verzeichnis von Komponenten, das Claude Code mit benutzerdefinierten Funktionen erweitert. Plugin-Komponenten umfassen Skills, Agents, Hooks, MCP-Server, LSP-Server und Monitore.

Referenz für Plugin-Komponenten

Skills

Plugins fügen Claude Code Skills hinzu und erstellen /name Shortcuts, die Sie oder Claude aufrufen können.

Speicherort: skills/ oder commands/ Verzeichnis im Plugin-Root oder eine einzelne SKILL.md Datei im Plugin-Root

Dateiformat: Skills sind Verzeichnisse mit SKILL.md; Commands sind einfache Markdown-Dateien

Skill-Struktur:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

Skills und Commands werden automatisch erkannt, wenn das Plugin installiert wird.

Wenn ein Plugin kein skills/ Verzeichnis und kein skills Manifest-Feld hat, wird eine SKILL.md im Plugin-Root als einzelner Skill geladen. Setzen Sie das Frontmatter-Feld name, um den Aufrufen-Namen des Skills zu steuern. Ohne dieses Feld greift Claude Code auf den Installationsverzeichnisnamen zurück. Für ein Plugin, das in den Cache kopiert wurde, ist dieser Name ein Versionsstring, der sich bei jedem Update ändert. Für Plugins, die mehr als einen Skill bereitstellen, verwenden Sie das oben gezeigte skills/ Verzeichnis-Layout.

In Plugin-Skills und Commands akzeptieren Boolean-Frontmatter-Felder wie disable-model-invocation yes, no, on, off, 1 und 0 in beliebiger Schreibweise zusätzlich zu true und false. Vor v2.1.218 erkannte Claude Code nur true und false.

Vollständige Details finden Sie unter Skills.

Agents

Plugins können spezialisierte Subagents für spezifische Aufgaben bereitstellen, die Claude automatisch aufrufen kann, wenn dies angemessen ist.

Speicherort: agents/ Verzeichnis im Plugin-Root

Dateiformat: Markdown-Dateien, die Agent-Fähigkeiten beschreiben

Agent-Struktur:

---
name: agent-name
description: Worauf sich dieser Agent spezialisiert und wann Claude ihn aufrufen sollte
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detaillierte Systemaufforderung für den Agent, die seine Rolle, Expertise und sein Verhalten beschreibt.

Plugin-Agents unterstützen die Frontmatter-Felder name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd und isolation. Der einzige gültige isolation Wert ist "worktree".

Aus Sicherheitsgründen unterstützen von Plugins bereitgestellte Agents nicht hooks, mcpServers oder permissionMode.

Claude Code lädt einen Plugin-Agent auch dann, wenn sein Frontmatter kein name Feld hat oder nicht geparst werden kann:

  • Kein name: Claude Code benennt den Agent nach der Datei, also wird agents/reviewer.md in einem Plugin namens my-plugin als my-plugin:reviewer geladen
  • Frontmatter, das nicht geparst werden kann: Claude Code benennt den Agent nach der Datei, verwendet Agent from my-plugin plugin als Beschreibung und ignoriert jedes Feld in der Datei

Im Gegensatz dazu überspringt Claude Code eine Projekt-, Benutzer- oder verwaltete Agent-Datei, deren Frontmatter kein name Feld hat oder nicht geparst werden kann.

Um Dateien im Standard-agents/ Verzeichnis eines Plugins zu finden, deren Frontmatter nicht geparst werden kann, führen Sie claude plugin validate aus. Der Pfad, den Sie übergeben, hängt davon ab, ob das Plugin ein Manifest hat, und beide Beispiele verwenden ./my-plugin als Plugin-Verzeichnis:

  • Ein Plugin mit Manifest: claude plugin validate ./my-plugin
  • Ein Plugin ohne Manifest: claude plugin validate ./my-plugin/agents. Erfordert Claude Code v2.1.233 oder später.

Agents erscheinen in der @-Mention Typeahead unter ihrem scoped Namen, wie my-plugin:code-reviewer, sobald das Plugin aktiviert ist.

Vollständige Details finden Sie unter Subagents.

Hooks

Plugins können Event-Handler bereitstellen, die automatisch auf Claude Code Events reagieren.

Speicherort: hooks/hooks.json im Plugin-Root oder inline in plugin.json

Format: JSON-Konfiguration mit Event-Matchern und Aktionen

hooks/hooks.json kann einen Top-Level-Schlüssel $schema enthalten, der eine JSON-Schema-URL für Editor-Autovervollständigung und Validierung benennt. Claude Code ignoriert den Schlüssel beim Laden.

Hook-Konfiguration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Plugin-Hooks reagieren auf die gleichen Lifecycle-Events wie benutzerdefinierte Hooks:

Ereignis Wann es ausgelöst wird
SessionStart Wenn eine Sitzung beginnt oder fortgesetzt wird
Setup Wenn Sie Claude Code mit --init-only starten oder mit --init oder --maintenance im -p-Modus. Für einmalige Vorbereitung in CI oder Skripten
UserPromptSubmit Wenn Sie eine Eingabeaufforderung absenden, bevor Claude sie verarbeitet
UserPromptExpansion Wenn ein von Ihnen eingegebener Befehl in eine Eingabeaufforderung erweitert wird, bevor sie Claude erreicht. Kann die Erweiterung blockieren
PreToolUse Bevor ein Werkzeugaufruf ausgeführt wird. Kann ihn blockieren
PermissionRequest Wenn ein Werkzeugaufruf eine Genehmigungsentscheidung benötigt
PermissionDenied Wenn der automatische Modus einen Werkzeugaufruf ablehnt, einschließlich Ablehnungen ohne Klassifizierer-Urteil. Verwenden Sie JSON hookSpecificOutput.retry: true, um dem Modell mitzuteilen, dass es den abgelehnten Werkzeugaufruf möglicherweise erneut versuchen kann. Claude Code ignoriert retry, wenn der Klassifizierer kein Urteil gefällt hat
PostToolUse Nach erfolgreichem Werkzeugaufruf
PostToolUseFailure Nach fehlgeschlagenem Werkzeugaufruf
PostToolBatch Nach Auflösung eines vollständigen Satzes paralleler Werkzeugaufrufe, bevor der nächste Modellaufruf erfolgt
Notification Wenn Claude Code eine Benachrichtigung sendet
MessageDisplay Während der Text der Assistentnachricht angezeigt wird
SubagentStart Wenn ein Subagent erzeugt wird
SubagentStop Wenn ein Subagent beendet wird
TaskCreated Wenn eine Aufgabe über TaskCreate erstellt wird
TaskCompleted Wenn eine Aufgabe als abgeschlossen markiert wird
Stop Wenn Claude die Antwort beendet
StopFailure Wenn die Runde aufgrund eines API-Fehlers endet
TeammateIdle Wenn ein Agent-Team-Teamkollege im Begriff ist, untätig zu werden
InstructionsLoaded Wenn eine CLAUDE.md- oder .claude/rules/*.md-Datei in den Kontext geladen wird. Wird beim Sitzungsstart und beim verzögerten Laden von Dateien während einer Sitzung ausgelöst
ConfigChange Wenn sich eine Konfigurationsdatei während einer Sitzung ändert
CwdChanged Wenn sich das Arbeitsverzeichnis ändert, z. B. wenn Claude einen cd-Befehl ausführt. Nützlich für reaktive Umgebungsverwaltung mit Tools wie direnv
DirectoryAdded Wenn ein Arbeitsverzeichnis während einer Sitzung über /add-dir oder die SDK-Steueranforderung register_repo_root hinzugefügt wird
FileChanged Wenn sich eine überwachte Datei auf der Festplatte ändert. Das Feld matcher gibt an, welche Dateinamen überwacht werden sollen
WorktreeCreate Wenn ein Worktree über --worktree, isolation: "worktree" oder für eine Hintergrundsitzung erstellt wird. Ersetzt das Standard-Git-Verhalten
WorktreeRemove Wenn ein Worktree beim Sitzungsende, beim Beenden eines Subagenten oder beim Löschen einer Hintergrundsitzung entfernt wird
PreCompact Vor Kontextkomprimierung
PostCompact Nach Abschluss der Kontextkomprimierung
PreModelSwitch Bevor Claude Code einen Modellwechsel anwendet, den Sie oder ein Client angefordert haben. Kann den Wechsel blockieren
PostModelSwitch Nach Änderung des Modells der Sitzung, einschließlich Änderungen, die Claude Code selbst vornimmt, z. B. Wiederherstellung des Modells beim Fortsetzen einer Sitzung
Elicitation Wenn ein MCP-Server während eines Werkzeugaufrufs Benutzereingaben anfordert
ElicitationResult Nachdem ein Benutzer auf eine MCP-Abfrage antwortet, bevor die Antwort an den Server zurückgesendet wird
SessionEnd Wenn eine Sitzung beendet wird

Hook-Typen:

  • command: Shell-Commands oder Scripts ausführen
  • http: Das Event-JSON als POST-Request an eine URL senden
  • mcp_tool: Ein Tool auf einem konfigurierten MCP Server aufrufen
  • prompt: Eine Aufforderung mit einem LLM evaluieren (verwendet $ARGUMENTS Platzhalter für Kontext)
  • agent: Einen agentic Verifier mit Tools für komplexe Verifikationsaufgaben ausführen

Hooks, die auf den eigenen gebündelten MCP Server des Plugins abzielen, müssen seine scoped Namen verwenden. Tool-Matcher und if Felder verwenden den scoped Tool-Namen mcp__plugin_<plugin-name>_<server-name>__<tool>, und das server Feld eines mcp_tool Hooks verwendet plugin:<plugin-name>:<server-name>. Ein Matcher, der gegen den bloßen Server-Schlüssel geschrieben wird, wird nie ausgelöst. Siehe Match MCP tools und Plugin-bereitgestellte MCP Server.

MCP servers

Plugins können Model Context Protocol (MCP) Server bündeln, um Claude Code mit externen Tools und Services zu verbinden.

Speicherort: .mcp.json im Plugin-Root oder inline in plugin.json

Format: Standard MCP Server-Konfiguration

MCP Server-Konfiguration:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

Integrations-Verhalten:

  • Plugin MCP Server starten automatisch, wenn das Plugin aktiviert ist
  • Server erscheinen als Standard MCP Tools in Claudes Toolkit
  • Plugin Server können unabhängig von Benutzer MCP Servern konfiguriert werden
  • Wenn Sie /reload-plugins während einer Session ausführen, behält Claude Code die Live-Verbindungen von Servern bei, deren Konfiguration unverändert ist

LSP servers

Plugins können Language Server Protocol (LSP) Server bereitstellen, um Claude Echtzeit-Code-Intelligenz beim Arbeiten an Ihrer Codebasis zu geben.

Speicherort: .lsp.json im Plugin-Root oder inline in plugin.json

Format: JSON-Konfiguration, die Language Server Namen ihren Konfigurationen zuordnet

.lsp.json Dateiformat:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Inline in plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Erforderliche Felder:

Feld Beschreibung
command Die auszuführende LSP-Binärdatei (muss in PATH sein)
extensionToLanguage Ordnet Dateierweiterungen Sprachbezeichnern zu

Optionale Felder:

Feld Beschreibung
args Befehlszeilenargumente für den LSP Server
transport Kommunikations-Transport: stdio (Standard) oder socket. Claude Code akzeptiert socket, führt aber jeden Server über stdio aus, daher gelten die stdout-Protokoll-Regeln für alle Server
env Umgebungsvariablen, die beim Starten des Servers gesetzt werden
initializationOptions Optionen, die während der Initialisierung an den Server übergeben werden
settings Einstellungen, die über workspace/didChangeConfiguration übergeben werden
workspaceFolder Workspace-Ordnerpfad für den Server
startupTimeout Maximale Wartezeit für Server-Start (Millisekunden)
shutdownTimeout Maximale Wartezeit für ordnungsgemäßes Herunterfahren (Millisekunden). Wenn das Timeout abläuft, beendet Claude Code den Server-Prozess. Wenn nicht gesetzt, gilt kein Timeout
restartOnCrash Ob der Server nach einem Absturz neu gestartet werden soll. Standard ist true. Setzen Sie auf false, um einen abgestürzten Server gestoppt zu lassen, anstatt ihn neu zu starten
maxRestarts Maximale Anzahl von Neustartversuchen, bevor aufgegeben wird
diagnostics Ob Diagnostiken nach Änderungen in Claudes Kontext eingefügt werden sollen (Standard true). Setzen Sie auf false, um Code-Navigation beizubehalten, aber automatische Diagnostik-Einspeisung zu unterdrücken.

restartOnCrash und shutdownTimeout erfordern Claude Code v2.1.205 oder später. Vor v2.1.205 akzeptierte das Config-Schema beide Optionen, aber das Setzen einer dieser Optionen führte dazu, dass Claude Code diesen LSP Server beim Start vollständig übersprang, wobei der Grund nur in der claude --debug Ausgabe sichtbar war.

Mehrere Server für die gleiche Erweiterung: Wenn mehr als ein aktivierter LSP Server die gleiche Dateierweiterung in extensionToLanguage deklariert, ob die Server von einem Plugin oder von verschiedenen Plugins stammen, verarbeitet der zuerst registrierte Server Dateien mit dieser Erweiterung und die anderen starten nie. Die /plugin Schnittstelle zeigt eine Warnung an, die das Plugin benennt, dessen Server aktiv ist.

Server, die nicht initialisiert werden können: Claude Code überspringt einen Server, dessen Konfiguration ungültig ist, z. B. einer, dem command oder extensionToLanguage fehlt, und die anderen konfigurierten Server starten trotzdem. Führen Sie claude --debug aus, um zu sehen, warum ein Server übersprungen wurde.

Ein übersprungener Server beansprucht seine Dateierweiterungen nicht, daher kann ein anderer gültiger Server, der die gleiche Erweiterung deklariert, vom gleichen oder einem anderen Plugin, diese Dateien trotzdem verarbeiten.

Senden Sie Log-Ausgabe an stderr, nicht stdout: Claude Code liest den stdout eines Servers nur als Protokollmeldungen und akzeptiert Nachrichtenheader bis zu 64 KiB und einen Nachrichtentext bis zu 32 MiB. Claude Code trennt einen Server, der eines dieser Limits überschreitet oder nicht-Protokoll-Ausgabe an stdout schreibt, und zählt die Trennung als Absturz für restartOnCrash und maxRestarts. Wenn Sie mit --debug ausführen, schreibt Claude Code einen Fehler, der die Ursache benennt, in das Debug-Log.

Verfügbare LSP Plugins:

Plugin Language Server Installationsbefehl
pyright-lsp Pyright (Python) pip install pyright oder npm install -g pyright
typescript-lsp TypeScript Language Server npm install -g typescript-language-server typescript
rust-analyzer-lsp rust-analyzer Siehe rust-analyzer Installation

Installieren Sie zuerst den Language Server und dann das Plugin aus dem Marketplace.

Monitors

Plugins können Background-Monitore deklarieren, die Claude Code automatisch startet, wenn das Plugin aktiv ist. Jeder Monitor führt einen Shell-Befehl für die Lebensdauer der Session aus und liefert jede stdout-Zeile als Benachrichtigung an Claude, damit Claude auf Log-Einträge, Statusänderungen oder abgerufene Events reagieren kann, ohne aufgefordert zu werden, die Überwachung selbst zu starten.

Plugin-Monitore verwenden den gleichen Mechanismus wie das Monitor Tool und teilen seine Verfügbarkeitsbeschränkungen. Sie laufen nur in interaktiven CLI-Sessions, laufen unsandboxed auf der gleichen Vertrauensebene wie Hooks und werden auf Hosts übersprungen, wo das Monitor Tool nicht verfügbar ist.

Speicherort: monitors/monitors.json im Plugin-Root oder inline in plugin.json

Format: JSON-Array von Monitor-Einträgen

Die folgende monitors/monitors.json überwacht einen Deployment-Status-Endpunkt und ein lokales Error-Log:

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Um Monitore inline zu deklarieren, setzen Sie experimental.monitors in plugin.json auf das gleiche Array. Um von einem nicht-Standard-Pfad zu laden, setzen Sie experimental.monitors auf einen relativen Pfad-String wie "./config/monitors.json". Monitore sind eine experimentelle Komponente.

Erforderliche Felder:

Feld Beschreibung
name Bezeichner, der innerhalb des Plugins eindeutig ist. Verhindert doppelte Prozesse, wenn das Plugin neu geladen wird oder ein Skill erneut aufgerufen wird
command Shell-Befehl, der als persistenter Background-Prozess im Session-Arbeitsverzeichnis ausgeführt wird
description Kurze Zusammenfassung dessen, was überwacht wird. Wird im Task-Panel und in Benachrichtigungszusammenfassungen angezeigt

Optionale Felder:

Feld Beschreibung
when Steuert, wann der Monitor startet. "always" startet ihn beim Session-Start und beim Plugin-Reload und ist der Standard. "on-skill-invoke:<skill-name>" startet ihn das erste Mal, wenn der benannte Skill in diesem Plugin versendet wird

Der command Wert unterstützt die Pfad-Substitutionen ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} und ${CLAUDE_PROJECT_DIR}, plus alle ${ENV_VAR} aus der Umgebung. Präfixieren Sie den Befehl mit cd "${CLAUDE_PLUGIN_ROOT}" && , wenn das Script aus dem eigenen Verzeichnis des Plugins ausgeführt werden muss.

Ein Monitor command kann nicht auf ${user_config.*} Werte verweisen. Der Befehl läuft durch eine Shell, daher lehnt Claude Code den Monitor mit einem Fehler ab, anstatt den Wert zu ersetzen. Monitor-Prozesse erhalten keine CLAUDE_PLUGIN_OPTION_<KEY> Umgebungsvariablen, daher sollte das Monitor-Script den Wert aus einer Konfigurationsdatei lesen, die es besitzt.

Wenn Sie ein Plugin während einer Session deaktivieren, stoppt Claude Code nicht die Monitore, die bereits laufen; sie stoppen, wenn die Session endet.

Themes

Plugins können Farbthemes bereitstellen, die in /theme neben den integrierten Voreinstellungen und den lokalen Themes des Benutzers erscheinen. Ein Theme ist eine JSON-Datei in themes/ mit einer base Voreinstellung und einer sparsamen overrides Map von Farb-Tokens. Themes sind eine experimentelle Komponente.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Wenn ein Benutzer ein Plugin-Theme auswählt, speichert Claude Code custom:<plugin-name>:<slug> in seiner Konfiguration. Plugin-Themes sind schreibgeschützt: Wenn ein Benutzer Ctrl+E auf einem in /theme drückt, kopiert Claude Code es in ~/.claude/themes/, damit er die Kopie bearbeiten kann.


Installationsbereiche für Plugins

Wenn Sie ein Plugin installieren, wählen Sie einen Bereich aus, der bestimmt, wo das Plugin verfügbar ist und wer es sonst noch verwenden kann:

Bereich Einstellungsdatei Anwendungsfall
user ~/.claude/settings.json Persönliche Plugins, die in allen Projekten verfügbar sind (Standard)
project .claude/settings.json Team-Plugins, die über Versionskontrolle freigegeben werden
local .claude/settings.local.json Projektspezifische Plugins, gitignored, wenn Claude Code eine Einstellung darin speichert
managed Managed settings Verwaltete Plugins (schreibgeschützt, nur Update)

Plugins verwenden das gleiche Bereichssystem wie andere Claude Code-Konfigurationen. Installationsanweisungen und Bereichsflags finden Sie unter Plugins installieren. Eine vollständige Erklärung der Bereiche finden Sie unter Konfigurationsbereiche.


Plugins aus dem Skills-Verzeichnis

Jeder Ordner unter einem Skills-Verzeichnis, der ein .claude-plugin/plugin.json-Manifest enthält, wird in der nächsten Sitzung als Plugin mit dem Namen <name>@skills-dir geladen, ohne Marketplace und ohne Installationsschritt. Erstellen Sie eines mit plugin init. Im Gegensatz zu einer kopierten Marketplace-Installation wird das Plugin an Ort und Stelle erkannt, anstatt in den Plugin-Cache kopiert zu werden.

Eine Skills-Verzeichnisstruktur unterstützt drei verschiedene Dinge:

Was Sie haben Was es ist
<skills-dir>/foo/SKILL.md ohne Manifest Ein einfaches Skill mit dem Namen foo
<skills-dir>/foo/.claude-plugin/plugin.json Ein Plugin foo@skills-dir, das seine eigenen Skills, Agents, Hooks und mehr bündeln kann
<plugin>/skills/bar/SKILL.md Ein Skill bar, das in einem Plugin verpackt ist

Wählen Sie, von wo aus das Plugin geladen wird

Skills-Verzeichnis Bereich Lädt
~/.claude/skills/ persönlich In jedem Projekt, da der Speicherort nur Ihnen gehört
<cwd>/.claude/skills/ Projekt Nur nachdem Sie den Workspace-Vertrauensdialog für diesen Ordner akzeptiert haben

Ein Plugin im Projektbereich wird in das Repository eingecheckt und erreicht jeden Mitarbeiter, der es klont. Da dieser Inhalt aus dem Repository und nicht von Ihnen stammt, wird er nur nach demselben Vertrauenstor geladen, das die Projekterlaubnisregeln in .claude/settings.json regelt. Das Vertrauen in einen übergeordneten Ordner oder das Ausführen mit -p ist daher nicht ausreichend, und Komponenten, die Code ausführen, sind weiter eingeschränkt:

Plugins im persönlichen Bereich haben keine dieser Einschränkungen.

Bearbeiten, neu laden und deaktivieren Sie ein Plugin aus dem Skills-Verzeichnis

Änderungen, die Sie an der SKILL.md eines Skills vornehmen, werden sofort in der aktuellen Sitzung wirksam. Änderungen an anderen Komponenten des Plugins, wie hooks/, .mcp.json, agents/ und output-styles/, werden nicht wirksam. Führen Sie /reload-plugins aus oder starten Sie Claude Code neu, um diese zu übernehmen. Siehe Live-Änderungserkennung.

Um das Laden eines Plugins aus dem Skills-Verzeichnis zu beenden, löschen Sie seinen Ordner oder deaktivieren Sie es nach Name. Es gibt keinen uninstall-Schritt, da nichts von einem Marketplace installiert wurde.

claude plugin disable my-tool@skills-dir

Plugins synchronisiert von claude.ai

Claude Code lädt die für Ihr claude.ai-Konto aktivierten Plugins, einschließlich Plugins, die Ihre Organisation für ihre Mitglieder aktiviert, zusammen mit den Plugins, die Sie aus Marketplaces installieren. Es lädt jedes in ~/.claude/plugins/synced/ herunter und lädt es als <name>@synced, ohne Marketplace und ohne Installationsdatensatz. Ein synchronisiertes Plugin wird mit dem gleichen Vertrauen ausgeführt wie ein Marketplace-Plugin, das Sie installiert haben: seine Skills, Agents, Hooks, MCP-Server und LSP-Server werden alle geladen.

Wo Claude Code diese Plugins synchronisiert, hängt von der Sitzung ab:

  • In Cowork und Cloud-Sitzungen lädt Claude Code sie in die eigene Umgebung der Sitzung herunter, wenn die Sitzung startet. Vor v2.1.239 lud Claude Code diese Plugins als <name>@inline, die Identität, die --plugin-dir-Plugins verwenden.
  • In Terminal-Sitzungen, in denen Sie sich mit Ihrem claude.ai-Konto anmelden, prüft Claude Code Ihr Konto einmal jedes Mal, wenn es startet, und lädt dann neue und aktualisierte Plugins herunter und entfernt die Plugins, die Sie oder Ihre Organisation ausgeschaltet haben, alles im Hintergrund. Die Synchronisierung in Terminal-Sitzungen erfordert Claude Code v2.1.273 oder später.

Die Startprüfung wird im Hintergrund ausgeführt, sodass sie nach dem Start Ihrer Sitzung abgeschlossen sein kann. Wenn sie ein synchronisiertes Plugin in einer interaktiven Sitzung hinzufügt, aktualisiert oder entfernt, zeigt Claude Code Plugins changed. Run /reload-plugins to activate. an. Führen Sie /reload-plugins aus, um die Änderung in dieser Sitzung zu laden, oder lassen Sie sie für das nächste Mal, wenn Sie Claude Code starten. Wenn Sie ein Plugin auf claude.ai aktivieren, während eine Sitzung läuft, lädt Claude Code es beim nächsten Start herunter.

Die Plugin-Synchronisierung in Terminal-Sitzungen wird unter den gleichen Anmeldebedingungen ausgeführt wie Skills, die von claude.ai synchronisiert werden. Sie benötigt auch eine Anmeldung, die Claude Code Zugriff auf die Plugins Ihres Kontos gewährt.

Eine Anmeldung aus einer früheren Version von Claude Code erhält Plugin-Zugriff beim nächsten Mal, wenn Claude Code diese Anmeldung im Hintergrund erneuert, innerhalb weniger Stunden, oder sofort, wenn Sie /login erneut ausführen. Die Plugin-Synchronisierung startet beim nächsten Mal, wenn Sie Claude Code danach starten.

claude plugin list zeigt synchronisierte Plugins unter einer Synced from claude.ai-Überschrift an, und die /plugin Installed-Registerkarte listet sie mit synced als Quelle auf. Verwalten Sie ein synchronisiertes Plugin über die <name>@synced-ID, die claude plugin list ausgibt:

  • Eines ausschalten: Führen Sie claude plugin disable <name>@synced aus, oder deaktivieren Sie es über die /plugin Installed-Registerkarte. Claude Code speichert die Auswahl als "<name>@synced": false in Ihren Benutzer-Level-enabledPlugins. Um das Plugin wieder einzuschalten, führen Sie claude plugin enable <name>@synced aus.
  • Eines überall heraushalten: schalten Sie das Plugin für Ihr claude.ai-Konto aus. Um es aus einem Projekt in jeder Umgebung herauszuhalten, setzen Sie "<name>@synced": false unter enabledPlugins in der committed .claude/settings.json dieses Projekts.
  • Verwalten Sie das Plugin selbst auf claude.ai: claude plugin install, update und uninstall gelten nicht für ein synchronisiertes Plugin. Claude Code lädt die Updates eines Plugins bei der nächsten Synchronisierung herunter. Um eines zu entfernen, schalten Sie das Plugin für Ihr claude.ai-Konto aus, und Claude Code entfernt es bei der nächsten Synchronisierung.
  • Synchronisierung auf einem Computer stoppen: setzen Sie syncClaudeAiPlugins in Ihren Benutzereinstellungen auf false. Claude Code stoppt das Herunterladen, und beim nächsten Start verschiebt es die Plugins, die es bereits synchronisiert hat, in ~/.claude/plugins/.trash/ und lädt sie nicht mehr. Ihre Organisation kann denselben Schlüssel in verwalteten Einstellungen setzen oder Skills auf claude.ai ausschalten, was auch verhindert, dass Plugins synchronisiert werden.

Sie können ein Plugin nicht ausschalten, das Ihre Organisation auf claude.ai als erforderlich markiert. Claude Code lädt es auch dann, wenn Sie es zuvor deaktiviert haben, und claude plugin disable weigert sich mit Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it. In claude plugin list sind diese Plugins mit required by your org gekennzeichnet.

Wenn ein aktiviertes Plugin aus einer anderen Quelle den Namen eines synchronisierten Plugins entspricht, lädt Claude Code dieses Plugin und meldet die synchronisierte Kopie als nicht geladen. Andere Quellen umfassen Marketplace-Installationen, Skills-Directory-Plugins, --plugin-dir-Plugins und in Claude Code integrierte Plugins. Um stattdessen die claude.ai-Kopie zu verwenden, deaktivieren Sie Ihre eigene Kopie. Vor v2.1.239 lud Claude Code die synchronisierte Kopie statt einer gleichnamigen Marketplace-Installation.


Plugin-Manifest-Schema

Die Datei .claude-plugin/plugin.json definiert die Metadaten und Konfiguration Ihres Plugins.

Das Manifest ist optional. Falls weggelassen, erkennt Claude Code Komponenten automatisch in Standardpfaden und leitet den Plugin-Namen aus dem Verzeichnisnamen ab. Verwenden Sie ein Manifest, wenn Sie Metadaten oder benutzerdefinierte Komponentenpfade bereitstellen müssen.

Vollständiges Schema

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Erforderliche Felder

Wenn Sie ein Manifest einbeziehen, ist name das einzige erforderliche Feld.

Feld Typ Beschreibung Beispiel
name string Eindeutige Kennung in Kebab-Case, ohne Leerzeichen, Steuerzeichen oder bidirektionale Formatierungszeichen. Wenn ein Marketplace-Eintrag das Plugin unter einem anderen Namen auflistet, ist der Name des Marketplace-Eintrags das, was enabledPlugins-Schlüssel und /plugin verwenden "deployment-tools"

Dieser Name wird für die Namensgebung von Komponenten verwendet. Beispielsweise wird der Agent agent-creator für das Plugin mit dem Namen plugin-dev in der Benutzeroberfläche als plugin-dev:agent-creator angezeigt.

Nicht erkannte Felder

Claude Code ignoriert Felder auf oberster Ebene, die nicht erkannt werden. Sie können Metadaten aus einem anderen Ökosystem in plugin.json behalten und das Plugin wird trotzdem geladen. Dies macht es praktisch, ein Manifest zu verwalten, das gleichzeitig als VS Code- oder Cursor-Erweiterungsmanifest, eine npm package.json oder ein MCPB/DXT-Bundle-Manifest dient.

claude plugin validate meldet nicht erkannte Felder als Warnungen, nicht als Fehler. Wenn ein Feld ein oder zwei Zeichen von einem erkannten Feld entfernt ist, schlägt die Warnung den wahrscheinlich beabsichtigten Namen vor. Ein Plugin mit nur Warnungen zu nicht erkannten Feldern besteht die Validierung und wird zur Laufzeit geladen.

Wie Claude Code ein erkanntes Feld mit falschem Werttyp behandelt, hängt vom Feld ab:

  • Die meisten Felder: Das Plugin kann nicht geladen werden. Beispielsweise ist ein keywords-Wert, der ein String statt eines Arrays ist, ein Ladefehler, und claude plugin validate meldet ihn als solchen.
  • experimental und metadata: Claude Code ignoriert einen Nicht-Objekt-Wert, und claude plugin validate meldet eine Warnung.

Übergeben Sie --strict, um Warnungen als Fehler zu behandeln. Verwenden Sie es in CI, um einen falsch geschriebenen Feldnamen oder ein Feld, das von einem anderen Tool-Manifest übrig ist, vor der Veröffentlichung zu erfassen, obwohl das Plugin zur Laufzeit geladen würde.

claude plugin validate ./my-plugin --strict

Metadatenfelder

Feld Typ Beschreibung Beispiel
$schema string JSON-Schema-URL für Editor-Autovervollständigung und Validierung. Claude Code ignoriert dieses Feld zur Ladezeit. "https://json.schemastore.org/claude-code-plugin-manifest.json"
displayName string Benutzerfreundlicher Name, der in der /plugin-Auswahl und anderen UI-Oberflächen angezeigt wird. Für ein auf dem Marketplace installiertes Plugin hat ein displayName im Marketplace-Eintrag Vorrang vor diesem Wert. Wenn an keiner Stelle ein Anzeigename festgelegt ist, sehen Benutzer name. Im Gegensatz zu name kann es Leerzeichen und beliebige Groß-/Kleinschreibung enthalten. Wird nicht für Namensgebung oder Suche verwendet. "Deployment Tools"
version string Optional. Semantische Versionierung. Das Festlegen dieser Einstellung heftet das Plugin an diese Versionsnummer, sodass Benutzer nur Updates erhalten, wenn Sie diese erhöhen, außer für eine command-Quelle oder ein Plugin das an Ort und Stelle geladen wird; siehe Versionsverwaltung. Wenn auch im Marketplace-Eintrag festgelegt, gewinnt plugin.json. Falls weggelassen, kommt die Version aus der nächsten Quelle in Versionsverwaltung. "2.1.0"
description string Kurze Erklärung des Plugin-Zwecks "Deployment automation tools"
author object Autoreninformationen {"name": "Dev Team", "email": "dev@company.com"}
homepage string Dokumentations-URL "https://docs.example.com"
repository string Quellcode-URL "https://github.com/user/plugin"
license string Lizenzkennung "MIT", "Apache-2.0"
keywords array Erkennungs-Tags ["deployment", "ci-cd"]
metadata object Freiformes Objekt für Ihre eigenen Daten, wie Berechtigungs- oder Katalogfelder. Claude Code liest es nicht, daher beeinflussen die Werte niemals das Plugin-Verhalten. Claude Code ignoriert einen Nicht-Objekt-Wert, und claude plugin validate meldet ihn als Warnung. Vor v2.1.222 behandelte Claude Code den Schlüssel als nicht erkanntes Feld. {"catalogId": "cat-123"}
defaultEnabled boolean Ob das Plugin in einem aktivierten Zustand startet, wenn der Benutzer keinen festgelegt hat. Standardmäßig true. Siehe Standardaktivierung. false

Standardaktivierung

Setzen Sie defaultEnabled: false in plugin.json, um ein Plugin zu versenden, das deaktiviert installiert wird. Der Benutzer aktiviert es mit claude plugin enable <plugin> oder der /plugin-Schnittstelle. Verwenden Sie dies für Plugins, die Kosten hinzufügen oder einen Umfang haben, den ein Benutzer akzeptieren sollte, wie eines, das sich mit einem externen Service verbindet.

defaultEnabled ist der Fallback, wenn nichts anderes den Zustand des Plugins entschieden hat. Die Einstellung des Benutzers und eine Abhängigkeitsanforderung haben Vorrang:

  • Die Einstellung des Benutzers: ein Eintrag für das Plugin in enabledPlugins in jedem Einstellungsbereich. Nach dem Schreiben bleibt es über Plugin-Updates und Neuinstallationen hinweg bestehen, daher ändert das Ändern von defaultEnabled in einer späteren Version nicht den Zustand eines bestehenden Benutzers.
  • Eine Abhängigkeitsanforderung: Wenn ein Plugin von einem anderen erforderlich ist, das aktiv ist, schreibt Claude Code true dafür zur Installations- oder Aktivierungszeit. Das gibt ihm eine explizite Einstellung, daher gilt sein eigener Standard nicht mehr. Siehe Plugin mit Abhängigkeiten aktivieren oder deaktivieren.

Das gleiche Feld kann im Marketplace-Eintrag eines Plugins erscheinen, wo es Vorrang vor dem Wert in plugin.json hat. Siehe Optionale Plugin-Felder.

Komponentenpfad-Felder

Feld Typ Beschreibung Beispiel
skills string|array Benutzerdefinierte Skill-Verzeichnisse mit <name>/SKILL.md. Ergänzt den Standard-skills/-Scan. Siehe Pfadverhaltenregeln für die Marketplace-Root-Ausnahme "./custom/skills/"
commands string|array Benutzerdefinierte flache .md-Skill-Dateien oder Verzeichnisse (ersetzt Standard-commands/) "./custom/cmd.md" oder ["./cmd1.md"]
agents string|array Benutzerdefinierte Agent-Dateien (ersetzt Standard-agents/) "./custom/agents/reviewer.md"
workflows string|array Benutzerdefinierte Workflow-Skriptdateien oder Verzeichnisse (ersetzt Standard-workflows/) "./custom/workflows/"
hooks string|array|object Hook-Konfigurationspfade oder Inline-Konfiguration "./my-extra-hooks.json"
mcpServers string|array|object MCP-Konfigurationspfade oder Inline-Konfiguration "./my-extra-mcp-config.json"
outputStyles string|array Benutzerdefinierte Ausgabestil-Dateien/Verzeichnisse (ersetzt Standard-output-styles/) "./styles/"
lspServers string|array|object Language Server Protocol-Konfigurationen für Code-Intelligenz (Gehe zu Definition, Finde Referenzen usw.) "./.lsp.json"
experimental.themes string|array Farbthema-Dateien/Verzeichnisse (ersetzt Standard-themes/). Siehe Themes "./themes/"
experimental.monitors string|array Hintergrund-Monitor-Konfigurationen, die automatisch starten, wenn das Plugin aktiv ist. Siehe Monitors "./monitors.json"
experimental.evals string|array Verzeichnis unter dem Plugin-Root, das die Eval-Fälle des Plugins enthält, wenn es nicht das Standard-evals/ ist. claude plugin eval --eval-dir überschreibt es "quality/evals"
userConfig object Benutzerkonfigurierbare Werte, die zur Aktivierungszeit abgefragt werden. Siehe Benutzerkonfiguration
channels array Kanal-Deklarationen für Nachrichteneinspeisung (Telegram, Slack, Discord-Stil). Siehe Kanäle
dependencies array Andere Plugins, die dieses Plugin benötigt, optional mit Semver-Versionsbeschränkungen. Siehe Plugin-Abhängigkeitsversionen einschränken [{ "name": "secrets-vault", "version": "~2.1.0" }]

Experimentelle Komponenten

Komponenten unter dem experimental-Schlüssel, themes und monitors, haben ein Manifest-Schema, das sich zwischen Releases ändern kann, während sie stabilisieren. Wo Sie sie deklarieren, ist eine separate Migration: Die oberste Ebene funktioniert immer noch, claude plugin validate warnt, und eine zukünftige Version wird experimental.* erfordern.

Benutzerkonfiguration

Das Feld userConfig deklariert Werte, die Claude Code dem Benutzer abfragt, wenn das Plugin aktiviert wird. Verwenden Sie dies, anstatt Benutzer zu zwingen, settings.json manuell zu bearbeiten.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Schlüssel müssen gültige Bezeichner sein. Jede Option unterstützt diese Felder:

Feld Erforderlich Beschreibung
type Ja Einer von string, number, boolean, directory oder file
title Ja Beschriftung im Konfigurationsdialog
description Ja Hilfetext unter dem Feld
sensitive Nein Wenn true, maskiert die Eingabe und speichert den Wert in sicherer Speicherung statt in settings.json
required Nein Wenn true, schlägt die Validierung fehl, wenn das Feld leer ist
default Nein Wert, der verwendet wird, wenn der Benutzer nichts bereitstellt
options Nein Für string-Typ die Werte, die das Feld akzeptiert, angezeigt in /config als Auswahl über ihnen. Erfordert Claude Code v2.1.271 oder später
multiple Nein Für string-Typ, erlauben Sie ein Array von Strings
min / max Nein Grenzen für number-Typ

Außer sensitive-Felder und multiple-Listen erscheint jedes Feld jedes aktivierten Plugins auch als Zeile im /config-Panel. Die Zeilen erfordern Claude Code v2.1.269 oder später.

Jeder Wert ist für die Substitution als ${user_config.KEY} in MCP- und LSP-Server-Konfigurationen und Hook-Befehlen verfügbar. Nicht-sensitive Werte können auch in Skill- und Agent-Inhalten ersetzt werden. Alle Werte werden an Hook-Prozesse als CLAUDE_PLUGIN_OPTION_<KEY>-Umgebungsvariablen exportiert, wobei <KEY> der Optionsschlüssel in Großbuchstaben ist.

Felder, die in einer Shell ausgeführt werden, lehnen ${user_config.*} ab: Das Ersetzen eines konfigurierten Werts in einem Shell-Befehl würde der Shell erlauben, alles auszuführen, was dieser Wert enthält, daher schlägt die Komponente mit einem Fehler fehl. Jedes abgelehnte Feld hat eine alternative Möglichkeit, den Wert zu übergeben:

Abgelehntes Feld Wie man den Wert übergibt
Shell-Form-Hook-Befehle Verwenden Sie Exec-Form mit args, oder lesen Sie CLAUDE_PLUGIN_OPTION_<KEY> aus der Hook-Umgebung
Monitor-Befehle Lesen Sie den Wert aus einer Konfigurationsdatei im Skript
MCP headersHelper Lesen Sie den Wert aus einer Konfigurationsdatei im Skript

Vor v2.1.207 ersetzten diese Felder ${user_config.KEY}-Werte; aktualisieren Sie Plugins, die sich darauf verlassen haben.

Nicht-sensitive Werte werden unter dem pluginConfigs-Schlüssel in Ihrer Benutzer-settings.json als pluginConfigs[<plugin-id>].options gespeichert.

Auf macOS speichert Claude Code sensitive Werte in der macOS Keychain und fällt auf ~/.claude/.credentials.json zurück, wenn die Keychain den Schreibvorgang ablehnt. Auf Plattformen ohne unterstützte Keychain speichert es sie in ~/.claude/.credentials.json. Keychain-Speicherung wird mit OAuth-Tokens geteilt und hat eine ungefähre Gesamtgrenze von 2 KB, daher halten Sie sensitive Werte klein.

Claude Code liest alle pluginConfigs-Werte nur aus drei Einstellungsquellen:

  • Benutzereinstellungen: ~/.claude/settings.json, die Datei, in die die Aktivierungsaufforderung schreibt
  • --settings: das CLI-Flag oder SDK-Inline-Einstellungen
  • Verwaltete Einstellungen: organisationskontrollierte Richtlinie

Wenn mehr als eine Quelle denselben Schlüssel setzt, haben verwaltete Einstellungen Vorrang, dann --settings, dann Benutzereinstellungen. Die einzige Quelle, die Sie aus dieser Liste entfernen können, sind Benutzereinstellungen: Übergeben Sie --setting-sources ohne user und Claude Code überspringt sie. Verwaltete Einstellungen und --settings bleiben, was Sie übergeben. Die settingSources-Option des SDK setzt die gleiche Liste.

Einträge in einer Projekt-.claude/settings.json oder .claude/settings.local.json werden ignoriert. Beide Dateien befinden sich im Workspace, daher könnte ein geklontes Repository Werte dort bereitstellen, und diese Werte würden in Plugin-Hook-Befehle, MCP-Server-Konfigurationen, LSP-Befehle und Monitor-Befehle fließen. Vor v2.1.207 wurden diese Einträge gelesen. Die Einschränkung ist spezifisch für pluginConfigs: enabledPlugins berücksichtigt immer noch Projekt- und lokale Einstellungen.

Kanäle

Das Feld channels ermöglicht es einem Plugin, einen oder mehrere Nachrichtenkanäle zu deklarieren, die Inhalte in die Konversation einspritzen. Jeder Kanal bindet sich an einen MCP-Server, den das Plugin bereitstellt.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Das Feld server ist erforderlich und muss einem Schlüssel in den mcpServers des Plugins entsprechen. Das optionale Pro-Kanal-userConfig verwendet das gleiche Schema wie das Feld auf oberster Ebene, wodurch das Plugin Bot-Tokens oder Owner-IDs abfragen kann, wenn das Plugin aktiviert wird.

Pfadverhaltenregeln

Ob ein benutzerdefinierter Pfad das Standard-Verzeichnis des Plugins ersetzt oder erweitert, hängt vom Feld ab:

  • Ersetzt den Standard: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Beispielsweise wird das Standard-commands/-Verzeichnis nicht gescannt, wenn das Manifest commands angibt. Um den Standard zu behalten und mehr hinzuzufügen, listen Sie ihn explizit auf: "commands": ["./commands/", "./extras/"]
  • Ergänzt den Standard: skills. Das Standard-skills/-Verzeichnis wird immer gescannt, und Verzeichnisse, die in skills aufgelistet sind, werden zusammen mit ihm geladen. Ausnahme: Für einen Marketplace-Eintrag, dessen source zum Marketplace-Root aufgelöst wird, ersetzt das Deklarieren spezifischer Unterverzeichnisse den Standard-skills/-Scan
  • Eigene Merge-Regeln: hooks, MCP-Server und LSP-Server. Siehe jeden Abschnitt für die Kombination mehrerer Quellen

Wenn ein Plugin sowohl einen Standard-Ordner als auch den entsprechenden Manifest-Schlüssel hat, warnt Claude Code vor dem ignorierten Ordner in claude plugin list und der /plugin-Detailansicht. Das Plugin wird immer noch mit den Manifest-Pfaden geladen. Claude Code warnt nicht, wenn der Manifest-Schlüssel in den Standard-Ordner zeigt, beispielsweise "commands": ["./commands/deploy.md"], da dieser Pfad den Ordner explizit benennt.

Für alle Pfadfelder:

  • Alle Pfade müssen relativ zum Plugin-Root sein und mit ./ beginnen, außer dass das Feld skills auch "." akzeptiert
    • Sowohl "." als auch "./" bezeichnen den Plugin-Root selbst
    • Vor v2.1.221 schlug "." bei der Manifest-Validierung fehl und das Plugin wurde nicht geladen, daher verwenden Sie "./", um frühere Versionen zu unterstützen
  • Komponenten aus benutzerdefinierten Pfaden verwenden die gleichen Benennungs- und Namensgebungsregeln
  • Mehrere Pfade können als Arrays angegeben werden
  • Ein Skill-Pfad kann auf ein Verzeichnis zeigen, das direkt ein SKILL.md enthält, beispielsweise "skills": ["."] für den Plugin-Root
    • Claude Code nimmt den Skill-Aufrufinamen aus dem Frontmatter-Feld name in SKILL.md, daher bleibt der Name stabil, unabhängig davon, wie das Installationsverzeichnis benannt ist
    • Wenn name nicht im Frontmatter festgelegt ist, fällt Claude Code auf den Verzeichnis-Basename zurück

Ein Plugin, das ein SKILL.md an seinem Root hat, kein skills/-Unterverzeichnis und kein skills-Manifest-Feld hat, wird automatisch als Single-Skill-Plugin geladen. Sie müssen "skills": ["./"] in plugin.json für dieses Layout nicht festlegen.

Pfadbeispiele:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Umgebungsvariablen

Claude Code stellt drei Variablen zum Referenzieren von Pfaden bereit:

Variable Wird aufgelöst zu Verwenden Sie es für
${CLAUDE_PLUGIN_ROOT} Absoluter Pfad zum Installationsverzeichnis des Plugins Skripte, Binärdateien und Konfigurationsdateien, die mit dem Plugin gebündelt sind
${CLAUDE_PLUGIN_DATA} Persistentes Verzeichnis, das Plugin-Updates überlebt, beim ersten Zugriff erstellt Installierte Abhängigkeiten wie node_modules oder Python-Virtualumgebungen, generierter Code und Caches
${CLAUDE_PROJECT_DIR} Das Projekt-Root Projektlokale Skripte und Konfigurationsdateien

Alle drei werden als Umgebungsvariablen an Hook-Prozesse und an MCP- und LSP-Server-Subprozesse exportiert. Sie sind nicht in der Umgebung von Befehlen vorhanden, die Claude durch das Bash-Tool ausführt, in der Hauptsitzung oder in einem Sub-Agent. Schreiben Sie in Plugin-Inhalten stattdessen den Platzhalter, und Claude Code ersetzt den Pfad inline, wenn es den Inhalt lädt. Welche Felder sie inline ersetzen, hängt von der Plugin-Komponente ab:

Plugin-Komponente Felder, in denen Platzhalter aufgelöst werden
Skill- und Agent-Inhalte Überall dort, wo der Platzhalter erscheint
Hook- und Monitor-Befehle Überall dort, wo der Platzhalter erscheint
MCP stdio-Server command, args, env
MCP http, sse, ws-Server url, headers, headersHelper
LSP-Server command, args, env, workspaceFolder

Verwenden Sie in Hook-Befehlen Exec-Form mit args, damit jeder Pfad als ein Argument ohne Anführungszeichen übergeben wird. Wickeln Sie in Shell-Form-Hooks und Monitor-Befehlen die Variablen in doppelte Anführungszeichen ein, wie in "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Dieser Shell-Form-Hook führt ein mit einem Plugin gebündeltes Skript aus:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Für ein kopiertes Plugin ändert sich ${CLAUDE_PLUGIN_ROOT}, wenn das Plugin aktualisiert wird. Das Verzeichnis der vorherigen Version bleibt nach einem Update für eine Kulanzfrist auf der Festplatte, aber behandeln Sie es als kurzlebig und schreiben Sie keinen Zustand dort. Für ein Plugin, das an Ort und Stelle aus einem lokalen Verzeichnis-Marketplace geladen wird, zeigt die Variable auf das stabile Quellverzeichnis. Siehe Plugin-Caching für welche Plugins kopiert werden und für Cleanup-Semantik.

Wenn ein kopiertes Plugin während einer Sitzung aktualisiert wird, verwenden Hook-Befehle, Monitors, MCP-Server und LSP-Server weiterhin den Pfad der vorherigen Version. Führen Sie /reload-plugins aus, um Hooks, MCP-Server und LSP-Server zum neuen Pfad zu wechseln; Monitors erfordern einen Sitzungsneustart. In einer Sitzung ohne interaktives Terminal lässt das Neuladen Plugin-MCP-Server auf dem alten Pfad, bis die nächste Sitzung beginnt.

Für ein Plugin mit einer command-Quelle kann Claude Code das Plugin selbst neu laden.

MCP-Server können auch die roots/list-Anfrage aufrufen, um die Arbeitsverzeichnisse der Sitzung zur Laufzeit zu lesen. Siehe was roots/list zurückgibt und wann Claude Code den Server über Änderungen benachrichtigt.

Persistentes Datenverzeichnis

Das Verzeichnis ${CLAUDE_PLUGIN_DATA} wird zu ~/.claude/plugins/data/{id}/ aufgelöst, wobei {id} die Plugin-Kennung mit Zeichen außerhalb von a-z, A-Z, 0-9, _ und - ist, die durch - ersetzt werden. Für ein Plugin, das als formatter@my-marketplace installiert ist, ist das Verzeichnis ~/.claude/plugins/data/formatter-my-marketplace/.

Eine häufige Verwendung ist die einmalige Installation von Sprachabhängigkeiten und deren Wiederverwendung über Sitzungen und Plugin-Updates hinweg. Verwenden Sie es für Python-Abhängigkeiten, Abhängigkeiten, die mit Yarn oder pnpm gesperrt sind, und Pakete, deren Lifecycle-Skripte ausgeführt werden müssen. Für ein auf dem Marketplace installiertes Plugin benötigen Sie es möglicherweise überhaupt nicht: Claude Code installiert automatisch berechtigte Node.js-Paketabhängigkeiten, wenn es das Plugin zwischenspeichert.

Da das Datenverzeichnis länger lebt als jede einzelne Plugin-Version, kann eine Überprüfung auf Verzeichnisexistenz allein nicht erkennen, wenn ein Update das Abhängigkeitsmanifest des Plugins ändert. Das empfohlene Muster vergleicht das gebündelte Manifest mit einer Kopie im Datenverzeichnis und installiert neu, wenn sie sich unterscheiden.

Dieser SessionStart-Hook installiert node_modules beim ersten Durchlauf und erneut, wenn ein Plugin-Update eine geänderte package.json enthält:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

Das diff beendet sich mit Nonzero, wenn die gespeicherte Kopie fehlt oder sich vom gebündelten unterscheidet, was sowohl den ersten Durchlauf als auch abhängigkeitsändernde Updates abdeckt. Wenn npm install fehlschlägt, entfernt das nachfolgende rm das kopierte Manifest, damit die nächste Sitzung erneut versucht.

Skripte, die in ${CLAUDE_PLUGIN_ROOT} gebündelt sind, können dann gegen die persistierten node_modules ausgeführt werden:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Das Datenverzeichnis wird automatisch gelöscht, wenn Sie das Plugin aus dem letzten Bereich deinstallieren, in dem es installiert ist. Die /plugin-Schnittstelle zeigt die Verzeichnisgröße an und fordert vor dem Löschen auf. Die CLI löscht standardmäßig; übergeben Sie --keep-data, um es zu behalten.


Plugin-Caching und Dateiauflösung

Plugins werden auf eine von drei Arten angegeben:

  • Über claude --plugin-dir oder claude --plugin-url für die Dauer einer Sitzung.
  • Über einen Marketplace, installiert für zukünftige Sitzungen.
  • Über Ihr claude.ai-Konto, synchronisiert in ~/.claude/plugins/synced/.

Aus Sicherheits- und Verifizierungsgründen kopiert Claude Code Marketplace-Plugins in den lokalen Plugin-Cache des Benutzers (~/.claude/plugins/cache), anstatt sie an Ort und Stelle zu verwenden, es sei denn, das Plugin wird an Ort und Stelle geladen. Eine command-Quelle im Link-Modus wird an Ort und Stelle über Links im Cache-Eintrag geladen. Eine Quelle mit relativem Pfad in einem Marketplace, der aus einem lokalen Verzeichnis hinzugefügt wurde, wird an Ort und Stelle aus dem Marketplace-Ordner geladen.

Für ein Plugin, das an Ort und Stelle aus einem lokalen Verzeichnis-Marketplace geladen wird, werden Ihre Änderungen am Quellverzeichnis beim nächsten Sitzungsstart oder /reload-plugins wirksam. Sie benötigen keine Versionsbumps. Der Hook-Prozess des Plugins und die MCP- und LSP-Server erhalten ein CLAUDE_PLUGIN_ROOT, das auf das Quellverzeichnis verweist. Claude Code installiert die Node.js-Paketabhängigkeiten des Plugins nicht in das Quellverzeichnis. Installieren Sie diese selbst dort oder von einem Hook aus in das persistente Datenverzeichnis.

Für kopierte Plugins ist jede installierte Version ein separates Verzeichnis im Cache, gruppiert nach Marketplace und Plugin und benannt nach der aufgelösten Version, mit einer eigenen Kopie der Plugin-Dateien und Node.js-Paketabhängigkeiten. Eine Abhängigkeit, die von einem Release-Tag aufgelöst wird, erhält einen Verzeichnisnamen mit einem Commit-SHA-Suffix.

Wenn Sie ein Plugin aktualisieren oder deinstallieren, markiert Claude Code das vorherige Versionsverzeichnis als verwaist und entfernt es in einem Hintergrund-Sweep ungefähr 14 Tage später. Die Kulanzfrist ermöglicht es gleichzeitigen Claude Code-Sitzungen, die bereits die alte Version geladen haben, ohne Fehler weiter zu laufen. Claude Code führt den Sweep nur aus, wenn mindestens ein Plugin installiert ist; nachdem Sie Ihr letztes Plugin deinstalliert haben, bleiben verwaiste Verzeichnisse auf der Festplatte, bis Sie ein Plugin erneut installieren.

Claude Code entfernt einen Plugin- oder Marketplace-Ordner aus dem Cache nur, wenn er kein Verzeichnis oder Symlink mehr enthält. Wenn Sie einen Entwicklungs-Checkout als Versionseinträge eines Plugins in den Cache symlinken, markiert Claude Code den Link niemals als verwaist und entfernt ihn oder die Ordner, die ihn enthalten, niemals. Claude Code schreibt auch niemals seine Versions-Tracking-Dateien in den verlinkten Checkout.

Die Glob- und Grep-Tools von Claude überspringen verwaiste Versionsverzeichnisse während Suchen, sodass Dateiergebnisse keinen veralteten Plugin-Code enthalten.

Node.js-Paketabhängigkeiten

Wenn Claude Code ein Plugin in den Cache kopiert, installiert es auch die Node.js-Paketabhängigkeiten des Plugins dort, damit die Hooks und MCP-Server des Plugins diese laden können. Dieser Abschnitt behandelt die npm- und Bun-Pakete, die ein Plugin in seiner eigenen package.json deklariert. Für Plugins, die von anderen Plugins abhängen, siehe Plugin-Abhängigkeitsversionen.

Claude Code führt die Installation im kopierten Versionsverzeichnis jedes Mal aus, wenn es eines erstellt: wenn Sie ein Plugin installieren, wenn Claude Code ein Plugin auf eine neue Version aktualisiert, und beim Sitzungsstart, wenn ein aktiviertes Plugin noch nicht zwischengespeichert ist, z. B. auf einem neuen Computer. Die Installation wird nur ausgeführt, wenn das Plugin-Stammverzeichnis sowohl eine package.json als auch eine unterstützte Sperrdatei enthält:

Sperrdatei Befehl
bun.lock oder bun.lockb bun install --frozen-lockfile --ignore-scripts
npm-shrinkwrap.json oder package-lock.json npm ci --ignore-scripts

Wenn ein Plugin mehr als eine dieser Sperrdateien enthält, verwendet Claude Code die erste Übereinstimmung und prüft in dieser Reihenfolge: bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json.

Claude Code überspringt die Installation in zwei Fällen, jeweils mit einer eigenen Lösung:

  • Wenn Ihr Plugin nur eine yarn.lock oder pnpm-lock.yaml enthält, ersetzen Sie diese durch eine npm-Sperrdatei.
  • Wenn eine bunfig.toml neben der Bun-Sperrdatei liegt, entfernen Sie die bunfig.toml, oder ersetzen Sie die Bun-Sperrdatei durch eine npm-Sperrdatei.

Versenden Sie eine npm-Sperrdatei für die größtmögliche Reichweite. Claude Code führt den Paketmanager der übereinstimmenden Sperrdatei aus dem PATH des Benutzers aus und fällt nicht auf die andere Sperrdatei zurück, wenn sie fehlt. Verwenden Sie für ein Plugin, das über eine npm-Quelle verteilt wird, npm-shrinkwrap.json; npm schließt package-lock.json aus veröffentlichten Paketen aus.

Claude Code beschränkt diese Abhängigkeitsinstallation so, dass während der Installation kein Code aus dem Plugin oder seinen Paketen ausgeführt wird, und begrenzt, wie lange sie ausgeführt werden kann:

  • Gefrorene Auflösung: Bun und npm installieren genau das, was die Sperrdatei festlegt, und schlagen fehl, anstatt Versionen erneut aufzulösen, wenn package.json und die Sperrdatei nicht übereinstimmen.
  • Keine Lifecycle-Skripte: --ignore-scripts verhindert, dass preinstall-, install- und postinstall-Skripte ausgeführt werden, sodass Abhängigkeiten, die native Module in diesen Skripten erstellen, heruntergeladen, aber während dieser Installation nicht kompiliert werden.
  • 60-Sekunden-Timeout: Claude Code stoppt eine Installation, die länger läuft, und behandelt sie als fehlgeschlagen.

Claude Code ruft ein npm-Quellen-Plugin vor dieser Abhängigkeitsinstallation ab, und keines der eigenen Installationsskripte des Pakets wird während des Abrufs ausgeführt. Siehe npm-Pakete.

Eine fehlgeschlagene oder übersprungene Installation blockiert das Plugin niemals. Wenn die Installation fehlschlägt oder Claude Code sie überspringt, weil eine yarn- oder pnpm-Sperrdatei vorhanden ist oder eine bunfig.toml daneben liegt, wird der Grund als Warnung in der Debug-Ausgabe aufgezeichnet. Ein Plugin mit einer package.json und ohne Sperrdatei wird ohne Logeintrag übersprungen. Eine Timeout-Installation kann einen partiellen node_modules-Baum in der zwischengespeicherten Kopie hinterlassen.

Sie können die automatische Installation nicht ausschalten; keine Einstellung oder Umgebungsvariable deaktiviert sie. In eingeschränkten Netzwerken siehe die Netzwerkzugriffsanforderungen für die Hosts, die Sie zulassen müssen.

Für Abhängigkeiten, die die automatische Installation nicht bereitstellen kann, z. B. Pakete, die ihre Lifecycle-Skripte zum Erstellen benötigen, Python-Abhängigkeiten oder ein Plugin, das mit Yarn oder pnpm gesperrt ist, installieren Sie diese von einem Hook in das persistente Datenverzeichnis.

Einschränkungen bei der Pfadtraversierung

Claude Code erlaubt einem Plugin nicht, auf Dateien außerhalb seines eigenen Verzeichnisses zu verweisen. Es lehnt einen Komponentenpfad ab, der außerhalb des Plugin-Stammverzeichnisses aufgelöst wird, unabhängig davon, ob der Pfad in plugin.json oder in einem Marketplace-Eintrag deklariert ist. Dies umfasst einen Pfad, der außerhalb des Plugins verweist, wie geschrieben, z. B. ../shared-utils, und einen Symlink, der außerhalb des Plugins führt, mit Ausnahme von Links innerhalb eines Marketplace.

Auf macOS und Linux lehnt Claude Code auch einen Komponentenpfad ab, der an irgendeiner Stelle einen Backslash enthält, auch wenn der Pfad innerhalb des Plugins bleibt. Komponenten, die mit Backslash-Pfaden deklariert sind, werden daher nur unter Windows geladen. Schreiben Sie Komponentenpfade mit Schrägstrichen, z. B. ./commands/deploy.md.

Wenn Claude Code einen Pfad ablehnt, meldet es einen path escapes plugin directory-Fehler und lädt das Plugin ohne diese Komponente.

Claude Code kopiert auch keine Dateien außerhalb des Plugin-Verzeichnisses in den Cache, wenn es das Plugin installiert. Wenn also ein Skript in einem kopierten Plugin einen Pfad über dem Plugin-Stammverzeichnis liest, findet es diese Dateien auch nicht.

Wenn Ihr Plugin Dateien mit anderen Teilen desselben Marketplace freigeben muss, können Sie symbolische Links in Ihrem Plugin-Verzeichnis erstellen. Wie ein Symlink behandelt wird, wenn das Plugin in den Cache kopiert wird, hängt davon ab, wo sein Ziel aufgelöst wird:

  • Innerhalb des eigenen Verzeichnisses des Plugins: Der Symlink wird als relativer Symlink im Cache beibehalten, sodass er zur Laufzeit weiterhin zum kopierten Ziel aufgelöst wird.
  • Anderswo innerhalb desselben Marketplace: Der Symlink wird dereferenziert. Der Inhalt des Ziels wird an seiner Stelle in den Cache kopiert. Dies ermöglicht es dem skills/-Verzeichnis eines Meta-Plugins, auf Skills zu verlinken, die von anderen Plugins im Marketplace definiert werden.
  • Außerhalb des Marketplace: Der Symlink wird aus Sicherheitsgründen übersprungen. Dies verhindert, dass Plugins beliebige Host-Dateien wie Systempfade in den Cache ziehen.

Für Plugins, die mit --plugin-dir installiert sind, von einem lokalen Pfad oder von einer command-Quelle im Copy-Modus, werden nur Symlinks beibehalten, die innerhalb des eigenen Verzeichnisses des Plugins aufgelöst werden. Alle anderen werden übersprungen.

Der folgende Befehl erstellt einen Link von innerhalb eines Marketplace-Plugins zu einem gemeinsamen Skill, der von einem Sibling-Plugin definiert wird. Verwenden Sie unter Windows mklink /D von einer erhöhten Eingabeaufforderung oder aktivieren Sie den Entwicklermodus:

ln -s ../../shared-plugin/skills/foo ./skills/foo

Verzeichnisstruktur von Plugins

Standard-Plugin-Layout

Ein vollständiges Plugin folgt dieser Struktur:

enterprise-plugin/
├── .claude-plugin/           # Metadaten-Verzeichnis (optional)
│   └── plugin.json             # Plugin-Manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills als flache .md-Dateien
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent-Definitionen
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Workflow-Skripte
│   └── release-audit.js
├── output-styles/            # Ausgabestil-Definitionen
│   └── terse.md
├── themes/                   # Farbschema-Definitionen
│   └── dracula.json
├── monitors/                 # Hintergrund-Monitor-Konfigurationen
│   └── monitors.json
├── hooks/                    # Hook-Konfigurationen
│   ├── hooks.json           # Haupt-Hook-Konfiguration
│   └── security-hooks.json  # Zusätzliche Hooks
├── bin/                      # Plugin-Ausführbare Dateien, die zu PATH hinzugefügt werden
│   └── my-tool               # Aufrufbar als einfacher Befehl im Bash-Tool
├── settings.json            # Standardeinstellungen für das Plugin
├── .mcp.json                # MCP-Server-Definitionen
├── .lsp.json                # LSP-Server-Konfigurationen
├── scripts/                 # Hook- und Utility-Skripte
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Lizenzdatei
└── CHANGELOG.md             # Versionsverlauf

Eine CLAUDE.md-Datei im Plugin-Stammverzeichnis wird nicht als Projektkontext geladen. Plugins tragen Kontext durch Skills, Agents und Hooks bei, nicht durch CLAUDE.md. Um Anweisungen bereitzustellen, die in Claudes Kontext geladen werden, platzieren Sie diese in einem Skill.

Dateistandorte-Referenz

Komponente Standardort Zweck
Manifest .claude-plugin/plugin.json Plugin-Metadaten und Konfiguration (optional)
Skills skills/ Skills mit <name>/SKILL.md-Struktur
Befehle commands/ Skills als flache Markdown-Dateien. Verwenden Sie skills/ für neue Plugins
Agents agents/ Subagent-Markdown-Dateien
Workflows workflows/ Workflow-Skriptdateien
Ausgabestile output-styles/ Ausgabestil-Definitionen
Designs themes/ Farbschema-Definitionen
Hooks hooks/hooks.json Hook-Konfiguration
MCP-Server .mcp.json MCP-Server-Definitionen
LSP-Server .lsp.json Language-Server-Konfigurationen
Monitore monitors/monitors.json Hintergrund-Monitor-Konfigurationen
Ausführbare Dateien bin/ Ausführbare Dateien, die zum PATH des Bash-Tools hinzugefügt werden und als einfache Befehle aufrufbar sind, während das Plugin aktiviert ist. Sie können dieses Verzeichnis nicht in ein Plugin einbeziehen, das Sie über die Organisationseinstellungen von claude.ai verteilen
Einstellungen settings.json Standardkonfiguration, die angewendet wird, wenn das Plugin aktiviert ist. Nur die agent- und subagentStatusLine-Schlüssel werden unterstützt

CLI-Befehle – Referenz

Claude Code bietet CLI-Befehle für nicht-interaktive Plugin-Verwaltung, nützlich für Skripte und Automatisierung.

plugin init

Gerüst für ein neues Plugin unter ~/.claude/skills/<name>/ erstellen. In der nächsten Claude Code-Sitzung wird es automatisch als <name>@skills-dir geladen und erscheint in /plugin und claude plugin list ohne Installationsschritt.

Siehe Skills-directory plugins für Umfang und Vertrauensanforderungen.

claude plugin init <name> [options]

Der Befehl nimmt diese Argumente an:

  • <name>: Plugin-Name. Wird zum Skill-Namespace und zum Verzeichnisnamen unter ~/.claude/skills/, daher darf er keine Leerzeichen oder Pfad-Trennzeichen enthalten.

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
--description <text> Manifest-Beschreibung
--author <name> Autorname git config user.name
--author-email <email> Autor-E-Mail git config user.email
--with <components...> Auch Komponentenordner gerüsten. Gültige Werte: skills, agents, hooks, mcp, lsp, output-style, channel
-f, --force Vorhandenes .claude-plugin/ am Ziel überschreiben
-h, --help Hilfe für Befehl anzeigen

claude plugin new ist ein Alias für diesen Befehl.

Jeder --with-Wert fügt eine Starter-Datei für diese Komponente hinzu, bereit zum Bearbeiten:

Komponente Was es gerüstet
skills Ein zusätzlicher Namespace-Skill <name>:example neben dem Standard-Skill
agents Eine agents/-Subagent-Definition
hooks Eine hooks/hooks.json mit einem Beispiel-Event-Handler
mcp Eine .mcp.json mit HTTP- und Stdio-Server-Beispielen
lsp Ein .lsp.json-Language-Server-Beispiel
output-style Ein output-styles/<name>.md, das automatisch angewendet wird, während das Plugin aktiviert ist
channel Ein MCP-basierter channel: ein Stdio-Server (server.ts), seine .mcp.json und eine package.json

Das gerüstete Plugin verwendet die @skills-dir-Quelle statt eines Marketplace. Administratoren können diese Quelle mit strictKnownMarketplaces blockieren oder indem sie {"source": "skills-dir"} zu blockedMarketplaces in managed settings hinzufügen. Wenn blockiert, schlägt plugin init fehl, bevor etwas geschrieben wird.

Diese Beispiele zeigen häufige Aufrufe:

# Minimales Plugin gerüsten
claude plugin init my-helper

# Mit Skill- und Hook-Ordnern gerüsten
claude plugin init my-helper --with skills hooks

# Vorhandenes Gerüst überschreiben
claude plugin init my-helper --force

plugin install

Ein Plugin aus verfügbaren Marketplaces installieren.

claude plugin install <plugin> [options]

Der Befehl nimmt diese Argumente an:

  • <plugin>: Plugin-Name oder plugin-name@marketplace-name für einen bestimmten Marketplace

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
-s, --scope <scope> Installationsumfang: user, project oder local user
--config <key=value> Setzen Sie eine userConfig-Option, die im Plugin-Manifest deklariert ist. Wiederholen Sie das Flag, um mehrere Optionen zu setzen
-y, --yes Akzeptieren Sie einen Befehl, den der Marketplace des Plugins deklariert, ohne die Bestätigungsaufforderung: den Befehl, der ein Plugin mit einer command-Quelle erzeugt, oder den headersHelper, der einen Archiv-Download authentifiziert. Das Akzeptieren eines headersHelper erfordert Claude Code v2.1.238 oder später. Claude Code druckt den Befehl trotzdem zuerst. Erforderlich, wenn stdin oder stdout kein TTY ist, es sei denn, Sie übergeben --accept-command. Hat keine Auswirkung innerhalb einer Claude Code-Sitzung, daher führen Sie den Befehl von Ihrem eigenen Terminal aus
--accept-command <sha256> Akzeptieren Sie den vom Marketplace deklarierten Befehl, dessen sha256 ein vorheriger --json-Lauf in shownCommand gemeldet hat, anstelle von -y. Die Akzeptanz zählt für genau diesen Befehl, dieses Plugin und diesen Marketplace-Katalog. Wenn sich einer von ihnen seit der Anzeige des Befehls geändert hat, einschließlich durch den eigenen Marketplace-Refresh des Laufs, akzeptiert Claude Code den Digest nicht und zeigt den Befehl erneut an. Kann nicht mit -y kombiniert werden. Hat keine Auswirkung innerhalb einer Claude Code-Sitzung, daher führen Sie den Befehl von Ihrem eigenen Terminal aus. Erfordert Claude Code v2.1.271 oder später
--json Geben Sie das Ergebnis als ein JSON-Objekt in der letzten Zeile von stdout aus, anstelle der benutzerfreundlichen Nachricht, zur Verwendung in Skripten. Siehe JSON-Ergebnisformat. Erfordert Claude Code v2.1.268 oder später
-h, --help Hilfe für Befehl anzeigen

Der Umfang bestimmt, welche Einstellungsdatei das installierte Plugin hinzugefügt wird. Beispielsweise schreibt --scope project zu enabledPlugins in .claude/settings.json, wodurch das Plugin für alle verfügbar wird, die das Projekt-Repository klonen.

Mit --json ist die letzte Zeile von stdout ein JSON-Objekt. Analysieren Sie nur diese Zeile, da Claude Code jeden Befehl, den der Marketplace deklariert, davor druckt. Drei Felder sind immer vorhanden:

  • command: der Unterbefehl, der ausgeführt wurde, wie install
  • outcome: ok oder failed
  • message: eine benutzerfreundliche Beschreibung des Ergebnisses

Andere Felder, wie pluginId, scope und failureCode, erscheinen nur, wenn sie zutreffen. Die --json-Option auf plugin uninstall, plugin update, plugin enable und plugin disable druckt das gleiche Objekt mit den eigenen Feldern dieses Unterbefehls. Ein Nutzungsfehler, wie ein ungültiger --scope, druckt keine Ergebniszeile und beendet sich mit 1 mit dem Grund auf stderr.

Wenn ein Lauf einen vom Marketplace deklarierten Befehl anzeigt und ihn nicht ausführt, trägt das failed-Ergebnis auch ein shownCommand-Objekt, dessen Felder den angezeigten Befehl, das Plugin, zu dem er gehört, und den sha256 des Befehls enthalten. Um genau diesen Befehl zu akzeptieren, führen Sie ihn erneut mit diesem sha256 als --accept-command aus. Erfordert Claude Code v2.1.271 oder später.

Wenn shownCommand.acceptCommandMatched false ist, stimmt der übergebene Digest nicht mit dem jetzt angezeigten Befehl überein. Zeigen Sie diesen Befehl einer Person, bevor Sie seinen sha256 übergeben.

Diese Beispiele zeigen häufige Aufrufe:

# Im Benutzerumfang installieren (Standard)
claude plugin install formatter@my-marketplace

# Im Projektumfang installieren (mit Team geteilt)
claude plugin install formatter@my-marketplace --scope project

# Im lokalen Umfang installieren (nicht mit Team geteilt)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Ein installiertes Plugin entfernen.

claude plugin uninstall <plugin> [options]

Der Befehl nimmt diese Argumente an:

  • <plugin>: Plugin-Name oder plugin-name@marketplace-name

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
-s, --scope <scope> Aus Umfang deinstallieren: user, project oder local user
--keep-data Das persistent data directory des Plugins beibehalten
--prune Auch automatisch installierte Abhängigkeiten entfernen, die kein anderes Plugin benötigt. Siehe plugin prune
-y, --yes Bestätigungsaufforderung für --prune überspringen. Erforderlich, wenn stdin oder stdout kein TTY ist
--json Geben Sie das Ergebnis als ein JSON-Objekt in der letzten Zeile von stdout aus, im gleichen Format wie plugin install --json. Kann nicht mit --prune kombiniert werden. Erfordert Claude Code v2.1.268 oder später
-h, --help Hilfe für Befehl anzeigen

claude plugin remove und claude plugin rm sind Aliase für diesen Befehl.

Standardmäßig werden beim Deinstallieren aus dem letzten verbleibenden Umfang auch das ${CLAUDE_PLUGIN_DATA}-Verzeichnis des Plugins gelöscht. Verwenden Sie --keep-data, um es zu bewahren, beispielsweise beim Neuinstallieren nach dem Testen einer neuen Version.

plugin prune

Automatisch installierte Plugin-Abhängigkeiten entfernen, die nicht mehr von einem installierten Plugin benötigt werden. Abhängigkeiten, die Claude Code eingezogen hat, um das dependencies-Feld eines anderen Plugins zu erfüllen, werden entfernt; Plugins, die Sie direkt installiert haben, werden nie berührt.

claude plugin prune [options]

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
-s, --scope <scope> Im Umfang bereinigen: user, project oder local user
--dry-run Auflisten, was entfernt würde, ohne etwas zu entfernen
-y, --yes Bestätigungsaufforderung überspringen. Erforderlich, wenn stdin oder stdout kein TTY ist
-h, --help Hilfe für Befehl anzeigen

claude plugin autoremove ist ein Alias für diesen Befehl.

Der Befehl listet verwaiste Abhängigkeiten auf und fragt vor dem Entfernen um Bestätigung. Um ein Plugin zu entfernen und seine Abhängigkeiten in einem Schritt zu bereinigen, führen Sie claude plugin uninstall <plugin> --prune aus.

plugin enable

Ein deaktiviertes Plugin aktivieren. Wenn das Ziel aus einem Marketplace installiert ist und Abhängigkeiten deklariert, aktiviert Claude Code diese transitiv im gleichen Umfang. Der Befehl schlägt unter den Bedingungen fehl, die Enable or disable a plugin with dependencies auflistet.

claude plugin enable <plugin> [options]

Der Befehl nimmt diese Argumente an:

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
-s, --scope <scope> Umfang zum Aktivieren: user, project oder local. Wenn weggelassen, erkennt Claude Code den Umfang, in dem das Plugin installiert ist Automatische Erkennung
--json Geben Sie das Ergebnis als ein JSON-Objekt in der letzten Zeile von stdout aus, im gleichen Format wie plugin install --json. Erfordert Claude Code v2.1.268 oder später
-h, --help Hilfe für Befehl anzeigen

plugin disable

Ein Plugin deaktivieren, ohne es zu deinstallieren.

Wenn das Ziel aus einem Marketplace installiert ist, schlägt der Befehl fehl, wenn ein anderes aktiviertes Plugin davon abhängt. Die Fehlermeldung enthält einen verketteten Befehl, der zuerst alle abhängigen Plugins deaktiviert.

Für ein synced plugin, das Ihre Organisation benötigt, schlägt der Befehl fehl und speichert nichts.

claude plugin disable [plugin] [options]

Der Befehl nimmt diese Argumente an:

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
-a, --all Alle aktivierten Plugins deaktivieren. Kann nicht mit --scope kombiniert werden
-s, --scope <scope> Umfang zum Deaktivieren: user, project oder local. Wenn weggelassen, erkennt Claude Code den Umfang, in dem das Plugin installiert ist Automatische Erkennung
--json Geben Sie das Ergebnis als ein JSON-Objekt in der letzten Zeile von stdout aus, im gleichen Format wie plugin install --json. Erfordert Claude Code v2.1.268 oder später
-h, --help Hilfe für Befehl anzeigen

plugin update

Ein Plugin auf die neueste Version aktualisieren.

claude plugin update <plugin> [options]

Der Befehl nimmt diese Argumente an:

  • <plugin>: Plugin-Name oder plugin-name@marketplace-name

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
-s, --scope <scope> Umfang zum Aktualisieren: user, project, local oder managed user
-y, --yes Akzeptieren Sie einen Befehl, den der Marketplace des Plugins deklariert, ohne die Bestätigungsaufforderung: den Befehl, der ein Plugin mit einer command-Quelle erzeugt, oder den headersHelper, der einen Archiv-Download authentifiziert. Das Akzeptieren eines headersHelper erfordert Claude Code v2.1.238 oder später. Claude Code druckt den Befehl trotzdem zuerst. Erforderlich, wenn stdin oder stdout kein TTY ist, es sei denn, Sie übergeben --accept-command. Hat keine Auswirkung innerhalb einer Claude Code-Sitzung, daher führen Sie den Befehl von Ihrem eigenen Terminal aus
--accept-command <sha256> Akzeptieren Sie den vom Marketplace deklarierten Befehl, dessen sha256 ein vorheriger --json-Lauf in shownCommand gemeldet hat, anstelle von -y. Die Akzeptanz zählt für genau diesen Befehl, dieses Plugin und diesen Marketplace-Katalog. Wenn sich einer von ihnen seit der Anzeige des Befehls geändert hat, einschließlich durch den eigenen Marketplace-Refresh des Laufs, akzeptiert Claude Code den Digest nicht und zeigt den Befehl erneut an. Kann nicht mit -y kombiniert werden. Hat keine Auswirkung innerhalb einer Claude Code-Sitzung, daher führen Sie den Befehl von Ihrem eigenen Terminal aus. Erfordert Claude Code v2.1.271 oder später
--json Geben Sie das Ergebnis als ein JSON-Objekt in der letzten Zeile von stdout aus, im gleichen Format wie plugin install --json. Erfordert Claude Code v2.1.268 oder später
-h, --help Hilfe für Befehl anzeigen

plugin list

Installierte Plugins mit ihrer Version, Quell-Marketplace und Aktivierungsstatus auflisten.

claude plugin list [options]

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
--json Ausgabe als JSON. Eine Plugin-Zeile mit Ladeproblemen oder Authoring-Warnungen trägt errors- oder notes-String-Arrays. Auf Claude Code v2.1.268 oder später geben parallele errorDetails- und noteDetails-Arrays jedem Eintrag seinen diagnostischen type und die Namen, auf die er sich bezieht, wie das Plugin, den Marketplace, den Server oder die Datei
--available Verfügbare Plugins aus Marketplaces einschließen. Erfordert --json
-h, --help Hilfe für Befehl anzeigen

Innerhalb einer interaktiven Sitzung druckt /plugin list eine ähnliche Auflistung inline, aber sie umfasst nur Marketplace-installierte Plugins:

  • Plugins, die aus Skills-Verzeichnissen geladen werden, erscheinen in der /plugin-Schnittstelle und in claude plugin list, aber nicht in der Inline-Ausgabe /plugin list.
  • Plugins, die von claude.ai synchronisiert werden erscheinen in claude plugin list auf Claude Code v2.1.239 oder später und in der /plugin-Schnittstelle, aber nicht in der Inline-Ausgabe /plugin list.
  • Plugins, die für die Sitzung mit --plugin-dir oder --plugin-url geladen werden, erscheinen in der /plugin-Schnittstelle und in claude plugin list nur, wenn das gleiche Flag dem Unterbefehl vorangeht, wie in claude --plugin-dir <dir> plugin list. Nur das Flag benennt ihren Standort, daher kann ein einfaches claude plugin list sie nicht finden, anders als synchronisierte Plugins und Skills-Directory-Plugins, deren feste Verzeichnisse Claude Code scannt.

Die interaktive Form akzeptiert --enabled oder --disabled, um nur Plugins in diesem Zustand anzuzeigen, und ls als Kurzform für list.

plugin details

Zeigen Sie das Komponenten-Inventar eines Plugins und die geschätzte Token-Kosten an. Die Ausgabe listet alle Komponenten auf, die das Plugin beiträgt, gruppiert als Skills, Agents, Hooks, MCP-Server und LSP-Server, zusammen mit einer Schätzung, wie viele Token es jeder Sitzung hinzufügt. Die Skills-Gruppe umfasst sowohl skills/- als auch commands/-Einträge.

claude plugin details <name>

Der Befehl nimmt diese Argumente an:

  • <name>: Plugin-Name oder plugin-name@marketplace-name

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
-h, --help Hilfe für Befehl anzeigen

Die Ausgabe zeigt zwei Kostenzahlen für jede Komponente:

  • Always-on: Token, die jeder Sitzung durch den Auflistungstext des Plugins hinzugefügt werden, wie Skill-Beschreibungen, Agent-Beschreibungen und Befehlsnamen, unabhängig davon, ob eine Komponente ausgelöst wird.
  • On-invoke: Token, die eine Komponente kostet, wenn sie ausgelöst wird. Wird pro Komponente angezeigt, nicht als Plugin-Gesamtsumme, da eine typische Sitzung nur eine Teilmenge von Komponenten aufruft.

Dieses Beispiel zeigt, wie die Ausgabe für ein Plugin mit zwei Skills aussieht:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

Die Always-on-Gesamtsumme wird über die count_tokens-API für Ihr aktives Modell berechnet. Pro-Komponenten-Zahlen werden proportional von dieser Gesamtsumme skaliert. Wenn die API nicht erreichbar ist, greift der Befehl auf eine zeichenbasierte Schätzung zurück.

plugin validate

Überprüfen Sie ein Plugin oder einen Marketplace auf Syntax- und Schema-Fehler, bevor Sie veröffentlichen.

Der Befehl beendet sich mit 0, wenn die Validierung erfolgreich ist, mit 1, wenn sie fehlschlägt, und mit 2, wenn der Validierungslauf selbst fehlschlägt, z. B. wenn der übergebene Pfad nicht lesbar ist.

claude plugin validate <path> [options]

Der Befehl nimmt diese Argumente an:

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
--strict Warnungen als Fehler behandeln und mit 1 beenden. Verwenden Sie in CI, um Probleme zu erfassen, die die Laufzeit toleriert, wie unrecognized fields
--json Geben Sie den Validierungsbericht als ein JSON-Objekt aus mit den gleichen Exit-Codes. Erfordert Claude Code v2.1.259 oder später
-h, --help Hilfe für Befehl anzeigen

Mit --json schreibt Claude Code den Bericht auf stdout als ein JSON-Objekt mit diesen Top-Level-Feldern:

  • success: das gleiche Urteil, das der Exit-Code gibt
  • strict: ob der Lauf Warnungen als Fehler behandelt hat
  • target: der aufgelöste Pfad, den Claude Code validiert hat
  • manifest: das eigene Ergebnis des Manifests oder null für einen Lauf ohne Manifest
  • contents: Pro-Datei-Ergebnisse, jede benannt nach ihrer file und mit errors-, warnings- und notes-Arrays

Bei Exit 2 schreibt der Befehl nichts auf stdout; die Fehlermeldung geht auf stderr.

Innerhalb einer interaktiven Sitzung führt /plugin validate <path> die gleichen Überprüfungen inline aus.

plugin eval

Führen Sie die eval cases eines Plugins aus und melden Sie bewertete Ergebnisse. Erfordert Claude Code v2.1.269 oder später. Jeder Fall ist ein Prompt plus Bewerter; Claude Code führt ihn mehrmals in einer isolierten Sitzung aus, in der nur das Ziel-Plugin geladen ist, und standardmäßig auch ohne das Plugin, damit der Bericht den Unterschied zeigt. Siehe Test plugins with evals für das Case-Format, Bewerter, Ergebnisse und CI-Nutzung.

claude plugin eval [target] [options]

Das optionale target ist ein Plugin-Verzeichnis, eine einzelne prompt.md- oder case.yaml-Datei, ein installiertes Plugin als name oder name@marketplace, oder name@skills-dir, und standardmäßig das aktuelle Verzeichnis. Platzieren Sie es vor --tag, --allow-tools und --json.

Diese Tabelle listet die Optionen auf, die die meisten Läufe verwenden. Führen Sie claude plugin eval --help aus, um den vollständigen Satz zu sehen, einschließlich --case, --tag, --output-dir, --report, --allow-real-servers, --keep-temp und --verbose.

Option Beschreibung Standard
--runs <n> Läufe pro Fall pro Arm Jedes Case's runs, sonst 3
-j, --concurrency <n> Agent-Sitzungen, die gleichzeitig ausgeführt werden, 1 bis 8. Sie teilen Ihr Rate Limit 1
--model <model> Modell für den getesteten Agent Jedes Case's model, sonst ANTHROPIC_MODEL falls gesetzt, sonst Claude Code's Standard
--judge-model <model> Modell für llm- und baseline-Bewerter Ein kleines schnelles Modell
--ablation <mode> none oder with-without. Siehe Compare against a no-plugin baseline with-without wenn ein Plugin aufgelöst wird, sonst none
--threshold <0..1> Beenden Sie mit 1, wenn ein Case unter diesem Wert bewertet wird 1.0
--max-cost-usd <usd> Stoppen Sie vor dem nächsten Lauf, sobald die Ausgaben diesen Betrag erreichen, beenden Sie mit 2 und melden Sie Teilergebnisse Keine Obergrenze
--allow-tools <tools...> Gewähren Sie Tools über den schreibgeschützten Satz hinaus, wie Bash, Write, Edit oder "mcp__plugin_<plugin>_<server>__*". Siehe Grant tools
--scaffold Führen Sie das scaffold_script jedes Cases aus Aus
--trust-plugin Überspringen Sie die Vertrauensaufforderung beim ersten Lauf, für CI. Siehe What a run can access Aus
--mocks <mode> record oder off. Siehe Mock MCP servers record
--eval-dir <dir> Verzeichnis unter dem Plugin, das die Cases enthält Das Manifest's experimental.evals, sonst evals
--json [path] Drucken Sie das result document auf stdout, oder schreiben Sie es in einen .json-Pfad
--no-publish Halten Sie den HTML-Bericht lokal
-h, --help Hilfe für Befehl anzeigen

Der Befehl beendet sich mit 0, wenn jeder Fall den Schwellenwert erfüllt, mit 1 bei einem fehlgeschlagenen Fall, einem Ladefehler oder einem nicht vertrauenswürdigen Plugin-Verzeichnis, mit 2 bei einem Teillauf, mit 130 bei Unterbrechung und mit 143 bei Beendigung. Siehe Run evals in CI.

plugin eval init

Erstellen Sie eine Eval-Suite für das Plugin im aktuellen Verzeichnis. Erfordert Claude Code v2.1.269 oder später. In einem Terminal startet dies ein Authoring-Interview, das das Plugin liest, Cases und Bewerter vorschlägt, sie pilotiert und die Dateien schreibt. Mit --bare oder ohne Terminal schreibt es stattdessen eine leere Single-Case-Vorlage. Wenn Sie von einer interaktiven Claude Code-Sitzung aus ausgeführt werden, druckt es die Interview-Anweisungen für diese Sitzung, um sie zu befolgen, anstatt eine Vorlage zu schreiben. Siehe Create your first eval suite.

claude plugin eval init [name] [options]

Das optionale name ist ein Case-Name: Das Interview benötigt keinen, während --bare und die No-Terminal-Vorlagenpfad ihn benötigen. Es akzeptiert diese Optionen:

Option Beschreibung Standard
--bare Schreiben Sie stattdessen ein leeres prompt.md und graders/criteria.md für <name>
-i, --interactive Erfordern Sie das Interview. Schlägt ohne Terminal fehl, anstatt eine Vorlage zu schreiben
--eval-dir <dir> Verzeichnis unter dem aktuellen Verzeichnis, um Cases hineinzuschreiben Das Manifest's experimental.evals, sonst evals
-h, --help Hilfe für Befehl anzeigen

plugin tag

Erstellen Sie ein Release-Git-Tag für ein Plugin. Standardmäßig taggt der Befehl das Plugin im aktuellen Verzeichnis; übergeben Sie einen Pfad, um ein Plugin an anderer Stelle zu taggen. Siehe Tag plugin releases.

claude plugin tag [path] [options]

Der Befehl nimmt diese Argumente an:

  • [path]: Pfad zum Plugin-Verzeichnis. Standardmäßig das aktuelle Verzeichnis.

Der Befehl akzeptiert diese Optionen:

Option Beschreibung Standard
--push Das Tag nach dem Erstellen zum Remote pushen
--dry-run Drucken Sie, was getaggt würde, ohne das Tag zu erstellen
-f, --force Das Tag erstellen, auch wenn der Working Tree schmutzig ist oder das Tag bereits existiert
-m, --message <msg> Tag-Anmerkungsnachricht. Verwenden Sie %s als Platzhalter für die Version
--remote <name> Remote zum Pushen mit --push origin
-h, --help Hilfe für Befehl anzeigen

Debugging- und Entwicklungstools

Debugging-Befehle

Verwenden Sie claude --debug, um Details zum Laden von Plugins anzuzeigen:

Dies zeigt:

  • Welche Plugins geladen werden
  • Alle Fehler in Plugin-Manifesten
  • Registrierung von Skills, Agents und Hooks
  • MCP-Server-Initialisierung

Häufige Probleme

Problem Ursache Lösung
Plugin wird nicht geladen Ungültige plugin.json Führen Sie claude plugin validate ./my-plugin oder /plugin validate ./my-plugin aus, wobei ./my-plugin Ihr Plugin-Verzeichnis ist, um plugin.json, hooks/hooks.json und die Frontmatter der Skills, Agents und Commands in den Standard-Verzeichnissen des Plugins auf Syntax- und Schema-Fehler zu überprüfen. Siehe Plugin oder Verzeichnis ohne Manifest validieren, um zu erfahren, was eine Ausführung abdeckt
Skills werden nicht angezeigt Falsche Verzeichnisstruktur Stellen Sie sicher, dass skills/ oder commands/ sich im Plugin-Root befindet, nicht in .claude-plugin/
Hooks werden nicht ausgelöst Skript ist nicht ausführbar Führen Sie chmod +x script.sh aus
MCP-Server schlägt fehl Fehlende ${CLAUDE_PLUGIN_ROOT} Verwenden Sie Variable für alle Plugin-Pfade
Pfadfehler Absolute Pfade verwendet Machen Sie Pfade relativ, beginnend mit ./; siehe Pfad-Verhaltensregeln, die die "." Ausnahme des skills-Feldes abdecken
LSP Executable not found in $PATH Language Server nicht installiert Installieren Sie die Binärdatei (z. B. npm install -g typescript-language-server typescript)

Beispiel-Fehlermeldungen

Manifest-Validierungsfehler:

  • Invalid JSON syntax: Unexpected token } in JSON at position 142: Überprüfen Sie auf fehlende Kommas, zusätzliche Kommas oder nicht in Anführungszeichen gesetzte Strings
  • Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: Ein erforderliches Feld fehlt
  • Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: JSON-Syntaxfehler. Vor v2.1.246 erzeugte Claude Code diesen Fehler auch für eine plugin.json, die als UTF-8 mit einer führenden Byte-Order-Mark (BOM) gespeichert wurde, selbst wenn das JSON ansonsten gültig war.

Plugin-Ladefehler:

  • Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: Befehlspfad existiert, enthält aber keine gültigen Befehlsdateien
  • Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: Der source-Pfad in marketplace.json verweist auf ein nicht vorhandenes Verzeichnis
  • Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: Entfernen Sie doppelte Komponentendefinitionen oder entfernen Sie strict: false im Marketplace-Eintrag

Hook-Fehlerbehebung

Hook-Skript wird nicht ausgeführt:

  1. Überprüfen Sie, dass das Skript ausführbar ist: chmod +x ./scripts/your-script.sh
  2. Überprüfen Sie die Shebang-Zeile: Die erste Zeile sollte #!/bin/bash oder #!/usr/bin/env bash sein
  3. Überprüfen Sie, dass der Pfad ${CLAUDE_PLUGIN_ROOT} verwendet: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
  4. Testen Sie das Skript manuell: ./scripts/your-script.sh

Hook wird bei erwarteten Ereignissen nicht ausgelöst:

  1. Überprüfen Sie, dass der Ereignisname korrekt ist (Groß-/Kleinschreibung beachten): PostToolUse, nicht postToolUse
  2. Überprüfen Sie, dass das Matcher-Muster Ihre Tools entspricht: "matcher": "Write|Edit" für Dateivorgänge
  3. Bestätigen Sie, dass der Hook-Typ gültig ist: command, http, mcp_tool, prompt oder agent

MCP-Server-Fehlerbehebung

Server startet nicht:

  1. Überprüfen Sie, dass der Befehl existiert und ausführbar ist
  2. Überprüfen Sie, dass alle Pfade die ${CLAUDE_PLUGIN_ROOT} Variable verwenden
  3. Überprüfen Sie die MCP-Server-Protokolle: claude --debug zeigt Initialisierungsfehler
  4. Testen Sie den Server manuell außerhalb von Claude Code

Server-Tools werden nicht angezeigt:

  1. Stellen Sie sicher, dass der Server ordnungsgemäß in .mcp.json oder plugin.json konfiguriert ist
  2. Überprüfen Sie, dass der Server das MCP-Protokoll korrekt implementiert
  3. Überprüfen Sie auf Verbindungs-Timeouts in der Debug-Ausgabe

Fehler in der Verzeichnisstruktur

Symptome: Plugin wird geladen, aber Komponenten (Skills, Agents, Hooks) fehlen.

Korrekte Struktur: Komponenten müssen sich im Plugin-Root befinden, nicht in .claude-plugin/. Nur plugin.json gehört in .claude-plugin/.

Debug-Checkliste:

  1. Führen Sie claude --debug aus und suchen Sie nach „loading plugin"-Meldungen
  2. Überprüfen Sie, dass jedes Komponenten-Verzeichnis in der Debug-Ausgabe aufgelistet ist
  3. Überprüfen Sie, dass Dateiberechtigungen das Lesen der Plugin-Dateien ermöglichen

Verteilungs- und Versionierungsreferenz

Versionsverwaltung

Claude Code verwendet die Version des Plugins als Cache-Schlüssel, der bestimmt, ob ein Update verfügbar ist. Wenn Sie /plugin update ausführen oder Auto-Update aktiviert ist, berechnet Claude Code die aktuelle Version und überspringt das Update, wenn sie mit der bereits installierten Version übereinstimmt. Ein Plugin, das an Ort und Stelle geladen wird, aus einem lokalen Marketplace-Verzeichnis lädt seine aktuellen Quelldateien bei jedem Sitzungsstart, unabhängig davon, was die Versionsnummer sagt.

Für jeden Quellentyp außer command löst Claude Code die Version aus dem ersten dieser Punkte auf, der gesetzt ist:

  1. Das Feld version in der plugin.json des Plugins
  2. Das Feld version im Marketplace-Eintrag des Plugins in marketplace.json
  3. Der Git-Commit-SHA des Plugin-Quellcodes für github, url, git-subdir und relative-path-Quellen in einem Git-gehosteten Marketplace
  4. Der SHA-256-Digest für archive-Quellen: der sha256-Pin im Marketplace-Eintrag oder der Digest der heruntergeladenen Datei, wenn Sie keinen Pin setzen. Claude Code kürzt ihn auf die ersten 12 Zeichen
  5. unknown für npm-Quellen oder lokale Verzeichnisse, die sich nicht in einem Git-Repository befinden. Claude Code nimmt die Version nicht aus einem Repository, das den Installationspfad umschließt, wie ein Git-verwaltetes ~/.claude

Für eine command-Quelle leitet Claude Code die Version immer aus dem ab, was der Befehl produziert: einen 12-stelligen Content-Hash allein oder an die plugin.json-Version als <version>-<hash> angehängt, wenn einer gesetzt ist. Claude Code ignoriert das Feld version des Marketplace-Eintrags für Command-Quellen. Ein Befehl, dessen gehashte Ausgabe sich ändert, produziert daher eine neue Version, auch wenn die verfasste Versionsnummer gleich bleibt. Im Link-Modus deckt der Hash den echten Pfad des gedruckten Verzeichnisses und seine Einträge auf oberster Ebene ab, anstatt der Dateiinhalte.

Für diese Quellentypen gibt es drei Möglichkeiten, ein Plugin zu versionieren:

Ansatz Wie Update-Verhalten Am besten für
Explizite Version Setzen Sie "version": "2.1.0" in plugin.json Benutzer erhalten Updates nur, wenn Sie dieses Feld erhöhen. Das Pushen neuer Commits ohne Erhöhung hat keine Auswirkung, und /plugin update meldet „bereits auf der neuesten Version". Für ein Plugin, das an Ort und Stelle geladen wird, wird der neue Inhalt trotzdem geladen. Veröffentlichte Plugins mit stabilen Release-Zyklen
Commit-SHA-Version Lassen Sie version sowohl in plugin.json als auch im Marketplace-Eintrag weg Benutzer erhalten Updates, wenn sich der aufgelöste Commit der Quelle ändert Interne oder Team-Plugins unter aktiver Entwicklung
Digest-Version Verwenden Sie eine archive-Quelle und lassen Sie version sowohl in plugin.json als auch im Marketplace-Eintrag weg Mit einem sha256-Pin erhalten Benutzer Updates, wenn Sie den Pin ändern. Ohne einen erhalten Benutzer Updates, wenn sich die Bytes der gehosteten ZIP-Datei ändern Plugins, die als ZIP-Dateien auf einem statischen Server oder in einem Artefakt-Repository veröffentlicht werden

Wenn Sie explizite Versionen verwenden, folgen Sie semantischer Versionierung (MAJOR.MINOR.PATCH): erhöhen Sie MAJOR für Breaking Changes, MINOR für neue Funktionen, PATCH für Bugfixes. Dokumentieren Sie Änderungen in einer CHANGELOG.md.


Siehe auch

  • Plugins - Tutorials und praktische Verwendung
  • Plugin-Marktplätze - Erstellen und Verwalten von Marktplätzen
  • Skills - Skill-Entwicklungsdetails
  • Subagents - Agent-Konfiguration und Fähigkeiten
  • Hooks - Event-Handling und Automatisierung
  • MCP - Integration externer Tools
  • Einstellungen - Konfigurationsoptionen für Plugins