Claude Code: Plugin-Referenzhandbuch

Plugins sind derKern der funktionalen Erweiterung, die dir helfen können, benutzerdefinierte Slash-Befehle, Subagenten, Automatisierungs-Hooks und weitere Funktionen hinzuzufügen. Dieses Tutorial behandeltKernkomponenten、und Konfigurationsspezifikationen、CLI-Verwaltungin drei Dimensionen, um dir schnell die wichtigsten Punkte der Plugin-Nutzung und -Entwicklung zu vermitteln.

Plugin-Kernkomponenten: 5 Arten von Erweiterungsfähigkeiten

Plugins erzielen funktionale Erweiterung durch 5 Arten von Komponenten, jede mit festen Speicherorten und Formatanforderungen.

Komponententyp	Speicherort	Dateiformat	Kernfunktion
Befehl	Plugin-Stammverzeichnis`commands/`	Markdown-Datei mit Frontmatter-Metadaten	Benutzerdefinierte Slash-Befehle hinzufügen, z. B.`/deploy` `/code-review`
Agent	Plugin-Stammverzeichnis`agents/`	Markdown-Datei	Dedizierte Subagenten bereitstellen, wie Code-Review-Agenten, Performance-Testing-Agenten
Skill	Plugin-Stammverzeichnis`skills/`	enthaltend`SKILL.md`Verzeichnis sichern	Claude ermöglichen, Szenarien automatisch zu erkennen und sie aufzurufen, z. B. PDF-Parsing, Datenvisualisierung
Hook	Plugin-Stammverzeichnis`hooks/hooks.json`oder`plugin.json`Inline	JSON-Konfigurationsdatei	Auf Claude-Ereignisse hören und automatisch reagieren, z. B. Code nach der Dateibearbeitung automatisch formatieren
MCP-Server	Plugin-Stammverzeichnis`.mcp.json`oder`plugin.json`Inline	JSON-Konfigurationsdatei	Externe Tools (wie GitHub, Jira) verbinden und ihre Funktionen in Tools umwandeln, die Claude nutzen kann
LSP-Server	Plugin-Stammverzeichnis`.lsp.json`oder`plugin.json`Inline	JSON-Konfigurationsdatei	Code-Intelligenz-Funktionen bereitstellen, wie Syntaxprüfung, Gehe-zu-Definition, Hover-Hinweise

Beispiele für Schlüsselkomponenten

1. Beispiel für Hook-Konfiguration: Nach der Dateibearbeitung automatisch formatieren

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

}

: Unterstützung für Go-Sprachintelligenz-Hinweise

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

Grundlegende Plugin-Spezifikationen: Installationsbereich und Manifest

1. Installationsbereich: Bestimmt den Verfügbarkeitsbereich des Plugins

Beim Installieren eines Plugins müssen Sie einen Bereich auswählen. Unterschiedliche Bereiche entsprechen unterschiedlichen Konfigurationsdateien und Nutzungsszenarien:

Geltungsbereich	Konfigurationsdateipfad	Anwendungsszenario
`user`	`~/.claude/settings.json`	Persönlich, gemeinsam für alle Projekte (Standard)
`project`	`.claude/settings.json`	Im Team geteilt, mit dem Repository synchronisiert
`local`	`.claude/settings.local.json`	Projektspezifisch, wird`.gitignore`ignoriert
`managed`	`managed-settings.json`	Verwaltetes Plugin, schreibgeschützt und automatisch aktualisiert

2. Plugin-Manifest:`plugin.json`Wichtige Punkte, die Sie kennen sollten

plugin.jsonist dieKernkonfigurationsdatei des Plugins, gespeichert in.claude-plugin/das Verzeichnis, das zum Definieren von Plugin-Metadaten und Komponentenpfaden verwendet wird.

a. Erforderliche Felder

Feld	Type	Voraussetzung	Beispiel
`name`	string	Eindeutiger Bezeichner, Kebab-Case-Format	`"go-code-helper"`

b. Kern-Metadatenfelder

{
  "version": "1.0.0", // 语义化版本
  "description": "提供 Go 语言代码智能和调试能力",
  "author": {
    "name": "Dev Team",
    "email": "[email protected]"
  },
  "license": "MIT"
}

c. Komponentenpfad-Felder

Wird verwendet, um den Speicherort benutzerdefinierter Komponenten anzugeben. Der Pfad mussrelativ zum Plugin-Wurzelverzeichnissein und./beginnen mit:

{
  "commands": ["./custom-commands/deploy.md"],
  "agents": "./custom-agents/",
  "hooks": "./hooks.json"
}

d. Umgebungsvariablen

${CLAUDE_PLUGIN_ROOT}Absoluter Pfad des Plugin-Wurzelverzeichnisses, verwendet, um in Skripten und Konfigurationen auf Dateien innerhalb des Plugins zu verweisen und Pfadfehler zu vermeiden.

3. Standard-Plugin-Verzeichnisstruktur

my-plugin/
├── .claude-plugin/           # 元数据目录
│   └── plugin.json          # 插件清单（必需）
├── commands/                 # 自定义斜杠命令
├── agents/                   # 子代理定义
├── skills/                   # 自动技能
├── hooks/                    # 事件钩子配置
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 服务器配置
└── scripts/                 # 钩子执行脚本

Hinweis:commands/ agents/Komponentenverzeichnisse wie diese müssen sich im PluginWurzelverzeichnisbefinden und dürfen nicht.claude-plugin/darin abgelegt werden.

Plugin-Verwaltung: Schnellreferenz für CLI-Befehle

Über die Claude Code CLI können Sie Plugins schnell installieren, deinstallieren, aktivieren/deaktivieren, geeignet für Skripting- und Automatisierungsszenarien.

Befehl	Zweck	Beispiel
`claude plugin install <插件名> -s <范围>`	Plugin installieren	`claude plugin install go-lsp --scope project`
`claude plugin uninstall <插件名>`	Plugin deinstallieren	`claude plugin uninstall go-lsp`
`claude plugin enable <插件名>`	Deaktiviertes Plugin aktivieren	`claude plugin enable go-lsp`
`claude plugin disable <插件名>`	Plugin deaktivieren (ohne zu deinstallieren)	`claude plugin disable go-lsp`
`claude plugin update <插件名>`	Plugin auf die neueste Version aktualisieren	`claude plugin update go-lsp`

Debugging und Fehlerbehebung: Lösungen für häufige Probleme

1. Debugging-Befehle

Führen Sie den folgenden Befehl aus, um Details zum Laden von Plugins anzuzeigen und Konfigurations- und Ladeprobleme zu lokalisieren:

claude --debug

Sie können Folgendes anzeigen: Plugin-Ladestatus, Manifest-Syntaxfehler, Komponentenregistrierungsstatus, Initialisierungsprotokolle des MCP/LSP-Servers.

2. Häufige Probleme und Lösungen

Problem	Ursache	Lösung
Plugin nicht geladen	`plugin.json`Syntaxfehler oder fehlende Pflichtfelder	Verwenden Sie`claude plugin validate`JSON-Syntax validieren, das Fehlende hinzufügen`name`Feld
Benutzerdefinierte Befehle werden nicht angezeigt	Befehlsdatei abgelegt in`.claude-plugin/`innerhalb	wird`commands/`Verschieben Sie das Verzeichnis in das Plugin-Stammverzeichnis
Hook-Skript wird nicht ausgeführt	Skript hat keine Ausführungsberechtigung	Führen Sie`chmod +x scripts/your-script.sh`um die Berechtigung zu erteilen
LSP-Eingabeaufforderung`Executable not found`	Entsprechender Language-Server ist nicht installiert	Binärdatei installieren (z. B. erfordert Go die Installation`gopls`）
Start des MCP-Servers fehlgeschlagen	Pfad verwendet absoluten Pfad, nicht verwendet`${CLAUDE_PLUGIN_ROOT}`	Durch Umgebungsvariablenreferenz ersetzen, wie z. B.`${CLAUDE_PLUGIN_ROOT}/server`

Versionsverwaltung und Distribution

Versionsspezifikation: Semantic Versioning befolgenMAJOR.MINOR.PATCH, zum Beispiel1.2.3
Distributionskanäle: Über den Plugin-Marktplatz verteilen oder das Plugin-Verzeichnis direkt teilen (muss die vollständige Struktur enthalten)
Changelog: Es wird empfohlen, einen Changelog im Plugin-Stammverzeichnis hinzuzufügenCHANGELOG.mdum den Inhalt von Versionsaktualisierungen aufzuzeichnen

Andere Erweiterungen