Plugins im SDK

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 benutzerdefinierte Schrägstrich-Befehle, Agenten, Skills, 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:

• Commands: Benutzerdefinierte Schrägstrich-Befehle
• Agents: Spezialisierte Subagenten für spezifische Aufgaben
• Skills: Von Modellen aufgerufene Funktionen, die Claude autonom nutzt
• Hooks: Event-Handler, die auf Tool-Nutzung und andere Ereignisse reagieren
• MCP servers: Externe Tool-Integrationen über Model Context Protocol

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 SDK unterstützt das Laden mehrerer Plugins von verschiedenen Standorten.

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
}

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in 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
        pass

asyncio.run(main())

Pfadangaben

Plugin-Pfade können sein:

• Relative Pfade: Aufgelöst relativ zu Ihrem aktuellen Arbeitsverzeichnis (z. B. "./plugins/my-plugin")
• Absolute Pfade: Vollständige Dateisystempfade (z. B. "/home/user/plugins/my-plugin")

Plugin-Installation überprüfen

Wenn Plugins erfolgreich geladen werden, erscheinen sie in der Systeminitalisierungsmeldung. Sie können überprüfen, ob 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") {
    // Check loaded plugins
    console.log("Plugins:", message.plugins);
    // Example: [{ name: "my-plugin", path: "./my-plugin" }]

    // Check available commands from plugins
    console.log("Commands:", message.slash_commands);
    // Example: ["/help", "/compact", "my-plugin:custom-command"]
  }
}

Plugin-Befehle verwenden

Befehle von Plugins werden automatisch mit dem Plugin-Namen versehen, um Konflikte zu vermeiden. Das Format ist plugin-name:command-name.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet",  // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

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 commands:", message.slash_commands);
    }

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

runWithPlugin().catch(console.error);

Plugin-Struktur-Referenz

Ein Plugin-Verzeichnis muss eine .claude-plugin/plugin.json Manifestdatei enthalten. Es kann optional Folgendes enthalten:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Detaillierte Informationen zum Erstellen von Plugins finden Sie unter:

• Plugins - Vollständiger Plugin-Entwicklungsleitfaden
• Plugins reference - Technische Spezifikationen und Schemas

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 von verschiedenen Standorten:

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 (enthält .claude-plugin/)
2. Validieren Sie plugin.json: Stellen Sie sicher, dass Ihre Manifestdatei eine gültige JSON-Syntax hat
3. Überprüfen Sie Dateiberechtigungen: Stellen Sie sicher, dass das Plugin-Verzeichnis lesbar ist

Befehle nicht verfügbar

Wenn Plugin-Befehle nicht funktionieren:

1. Verwenden Sie den Namespace: Plugin-Befehle erfordern das Format plugin-name:command-name
2. Überprüfen Sie die Init-Meldung: Überprüfen Sie, ob der Befehl in slash_commands mit dem korrekten Namespace angezeigt wird
3. Validieren Sie Befehlsdateien: Stellen Sie sicher, dass sich Befehlsmarkdown-Dateien im Verzeichnis commands/ befinden

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-Utilities, um Pfade korrekt zu konstruieren

Siehe auch

• Plugins - Vollständiger Plugin-Entwicklungsleitfaden
• Plugins reference - Technische Spezifikationen
• Slash Commands - Verwendung von Schrägstrich-Befehlen im SDK
• Subagents - Arbeiten mit spezialisierten Agenten
• Skills - Verwendung von Agent Skills