Zum Hauptinhalt springen
Plugins ermöglichen es Ihnen, Claude Code mit benutzerdefinierten Funktionen zu erweitern, die projektübergreifend gemeinsam genutzt werden können. Über das Agent SDK können Sie Plugins programmgesteuert aus lokalen Verzeichnissen laden, um Skills, Agenten, Hooks und MCP-Server zu Ihren Agent-Sitzungen hinzuzufügen.

​
Was sind Plugins?

Plugins sind Pakete von Claude Code-Erweiterungen, die Folgendes enthalten können:
  • Skills: Von Modellen aufgerufene Funktionen, die Claude autonom nutzt (können auch mit /skill-name aufgerufen werden)
  • Agenten: Spezialisierte Subagenten für spezifische Aufgaben
  • Hooks: Event-Handler, die auf Tool-Nutzung und andere Ereignisse reagieren
  • MCP-Server: Externe Tool-Integrationen über das Model Context Protocol
Das Verzeichnis commands/ ist ein veraltetes Format. Verwenden Sie skills/ für neue Plugins. Claude Code unterstützt weiterhin beide Formate für Rückwärtskompatibilität.
Vollständige Informationen zur Plugin-Struktur und zum Erstellen von Plugins finden Sie unter Plugins.

​
Plugins laden

Laden Sie Plugins, indem Sie ihre lokalen Dateisystempfade in Ihrer Optionskonfiguration angeben. Das Feld type muss "local" sein, der einzige Wert, den das SDK akzeptiert. Um ein Plugin zu verwenden, das über einen Marketplace oder ein Remote-Repository verteilt wird, laden Sie es zunächst herunter und geben Sie den lokalen Verzeichnispath an. Das SDK unterstützt das Laden mehrerer Plugins aus verschiedenen Speicherorten. 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [
      { type: "local", path: "./my-plugin" },
      { type: "local", path: "/absolute/path/to/another-plugin" }
    ]
  }
})) {
  // Plugin commands, agents, and other features are now available
}

​
Pfadangaben

Plugin-Pfade können sein:
  • Relative Pfade: Aufgelöst relativ zu Ihrem aktuellen Arbeitsverzeichnis (zum Beispiel "./plugins/my-plugin")
  • Absolute Pfade: Vollständige Dateisystempfade (zum Beispiel "/home/user/plugins/my-plugin")
Der Pfad sollte auf das Root-Verzeichnis des Plugins verweisen: das übergeordnete Verzeichnis von skills/, agents/, hooks/, commands/ (Legacy) oder .claude-plugin/, nicht auf ein Unterverzeichnis.

​
Plugin-Installation überprüfen

Wenn Plugins erfolgreich geladen werden, erscheinen sie in der Systeminitalisierungsmeldung. Sie können überprüfen, dass Ihre Plugins verfügbar sind: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Geladene Plugins überprüfen
    console.log("Plugins:", message.plugins);
    // Beispiel: [{ name: "my-plugin", path: "./my-plugin" }]

    // Plugin-Skills erscheinen mit dem Plugin-Namen als Präfix
    console.log("Skills:", message.skills);
    // Beispiel: ["my-plugin:greet"]

    // Plugin-Befehle verwenden denselben Präfix, und Skills erscheinen auch hier
    console.log("Commands:", message.slash_commands);
    // Beispiel: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
  }
}

​
Plugin-Skills verwenden

Skills aus Plugins werden automatisch mit dem Plugin-Namen versehen, um Konflikte zu vermeiden. Um einen direkt aufzurufen, senden Sie /plugin-name:skill-name als Eingabeaufforderung. 
import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet skill
for await (const message of query({
  prompt: "/my-plugin:greet", // Use plugin skill with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting skill from the plugin
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}
Wenn Sie ein Plugin über die CLI installiert haben (zum Beispiel /plugin install my-plugin@marketplace), können Sie es im SDK weiterhin verwenden, indem Sie seinen Installationspfad angeben. Überprüfen Sie ~/.claude/plugins/ auf über die CLI installierte Plugins.

​
Vollständiges Beispiel

Hier ist ein vollständiges Beispiel, das das Laden und die Verwendung von Plugins demonstriert: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import * as path from "path";

async function runWithPlugin() {
  const pluginPath = path.join(__dirname, "plugins", "my-plugin");

  console.log("Loading plugin from:", pluginPath);

  for await (const message of query({
    prompt: "What custom commands do you have available?",
    options: {
      plugins: [{ type: "local", path: pluginPath }],
      maxTurns: 3
    }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      console.log("Loaded plugins:", message.plugins);
      console.log("Available skills:", message.skills);
      console.log("Available commands:", message.slash_commands);
    }

    if (message.type === "assistant") {
      console.log("Assistant:", message.message.content);
    }
  }
}

runWithPlugin().catch(console.error);

​
Plugin-Struktur-Referenz

Ein Plugin-Verzeichnis enthält typischerweise eine .claude-plugin/plugin.json-Manifestdatei. Das Manifest ist optional. Wenn es weggelassen wird, erkennt Claude Code Komponenten automatisch aus dem Verzeichnislayout. Das Verzeichnis kann Folgendes enthalten: 
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin-Manifest (optional, Komponenten werden ohne es automatisch erkannt)
├── skills/                   # Agent Skills (werden autonom aufgerufen oder über /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: verwenden Sie stattdessen skills/
│   └── custom-cmd.md
├── agents/                   # Benutzerdefinierte Agenten
│   └── specialist.md
├── hooks/                    # Event-Handler
│   └── hooks.json
└── .mcp.json                # MCP-Server-Definitionen
Detaillierte Informationen zum Erstellen von Plugins finden Sie unter:

​
Häufige Anwendungsfälle

​
Entwicklung und Tests

Laden Sie Plugins während der Entwicklung, ohne sie global zu installieren: 
plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }];

​
Projektspezifische Erweiterungen

Beziehen Sie Plugins in Ihr Projekt-Repository ein, um teamweite Konsistenz zu gewährleisten: 
plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];

​
Mehrere Plugin-Quellen

Kombinieren Sie Plugins aus verschiedenen Speicherorten: 
plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];

​
Fehlerbehebung

​
Plugin wird nicht geladen

Wenn Ihr Plugin nicht in der Init-Meldung angezeigt wird:
  1. Überprüfen Sie den Pfad: Stellen Sie sicher, dass der Pfad auf das Plugin-Root-Verzeichnis verweist, das übergeordnete Verzeichnis von skills/, agents/, hooks/, commands/ (veraltet) oder .claude-plugin/
  2. Validieren Sie plugin.json: Wenn Ihr Plugin ein Manifest enthält, stellen Sie sicher, dass es eine gültige JSON-Syntax hat
  3. Überprüfen Sie Dateiberechtigungen: Stellen Sie sicher, dass das Plugin-Verzeichnis lesbar ist

​
Skills werden nicht angezeigt

Wenn Plugin-Skills nicht funktionieren:
  1. Verwenden Sie den Namespace: Rufen Sie Plugin-Skills als /plugin-name:skill-name auf
  2. Überprüfen Sie die Init-Meldung: Überprüfen Sie, dass der Skill in der skills-Liste mit dem korrekten Namespace angezeigt wird
  3. Validieren Sie Skill-Dateien: Stellen Sie sicher, dass jeder Skill eine SKILL.md-Datei in seinem eigenen Unterverzeichnis unter skills/ hat, zum Beispiel skills/my-skill/SKILL.md

​
Pfadauflösungsprobleme

Wenn relative Pfade nicht funktionieren:
  1. Überprüfen Sie das Arbeitsverzeichnis: Relative Pfade werden von Ihrem aktuellen Arbeitsverzeichnis aus aufgelöst
  2. Verwenden Sie absolute Pfade: Verwenden Sie für Zuverlässigkeit absolute Pfade
  3. Normalisieren Sie Pfade: Verwenden Sie Pfad-Dienstprogramme, um Pfade korrekt zu konstruieren

​
Siehe auch