Plugins im SDK
Laden Sie benutzerdefinierte Plugins, um Claude Code mit Skills, Agenten, Hooks und MCP-Servern über das Agent SDK zu erweitern
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-nameaufgerufen 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
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
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
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 (zum Beispiel
"./plugins/my-plugin") - Absolute Pfade: Vollständige Dateisystempfade (zum Beispiel
"/home/user/plugins/my-plugin")
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"]
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./my-plugin"}]
),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
# Geladene Plugins überprüfen
print("Plugins:", message.data.get("plugins"))
# Beispiel: [{"name": "my-plugin", "path": "./my-plugin"}]
# Plugin-Skills erscheinen mit dem Plugin-Namen als Präfix
print("Skills:", message.data.get("skills"))
# Beispiel: ["my-plugin:greet"]
# Plugin-Befehle verwenden denselben Präfix, und Skills erscheinen auch hier
print("Commands:", message.data.get("slash_commands"))
# Beispiel: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
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);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
async def main():
# Load a plugin with a custom /greet skill
async for message in query(
prompt="/demo-plugin:greet", # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]
),
):
# Claude executes the custom greeting skill from the plugin
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")
asyncio.run(main())
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);
#!/usr/bin/env python3
"""Example demonstrating how to use plugins with the Agent SDK."""
from pathlib import Path
import anyio
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
SystemMessage,
TextBlock,
query,
)
async def run_with_plugin():
"""Example using a custom plugin."""
plugin_path = Path(__file__).parent / "plugins" / "demo-plugin"
print(f"Loading plugin from: {plugin_path}")
options = ClaudeAgentOptions(
plugins=[{"type": "local", "path": str(plugin_path)}],
max_turns=3,
)
async for message in query(
prompt="What custom commands do you have available?", options=options
):
if isinstance(message, SystemMessage) and message.subtype == "init":
print(f"Loaded plugins: {message.data.get('plugins')}")
print(f"Available skills: {message.data.get('skills')}")
print(f"Available commands: {message.data.get('slash_commands')}")
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Assistant: {block.text}")
if __name__ == "__main__":
anyio.run(run_with_plugin)
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:
- Plugins - Vollständiger Plugin-Entwicklungsleitfaden
- Plugins-Referenz - 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 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:
- Ü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/ - Validieren Sie plugin.json: Wenn Ihr Plugin ein Manifest enthält, stellen Sie sicher, dass es eine gültige JSON-Syntax hat
- Überprüfen Sie Dateiberechtigungen: Stellen Sie sicher, dass das Plugin-Verzeichnis lesbar ist
Skills werden nicht angezeigt
Wenn Plugin-Skills nicht funktionieren:
- Verwenden Sie den Namespace: Rufen Sie Plugin-Skills als
/plugin-name:skill-nameauf - Überprüfen Sie die Init-Meldung: Überprüfen Sie, dass der Skill in der
skills-Liste mit dem korrekten Namespace angezeigt wird - Validieren Sie Skill-Dateien: Stellen Sie sicher, dass jeder Skill eine
SKILL.md-Datei in seinem eigenen Unterverzeichnis unterskills/hat, zum Beispielskills/my-skill/SKILL.md
Pfadauflösungsprobleme
Wenn relative Pfade nicht funktionieren:
- Überprüfen Sie das Arbeitsverzeichnis: Relative Pfade werden von Ihrem aktuellen Arbeitsverzeichnis aus aufgelöst
- Verwenden Sie absolute Pfade: Verwenden Sie für Zuverlässigkeit absolute Pfade
- Normalisieren Sie Pfade: Verwenden Sie Pfad-Dienstprogramme, um Pfade korrekt zu konstruieren
Siehe auch
- Plugins - Vollständiger Plugin-Entwicklungsleitfaden
- Plugins-Referenz - Technische Spezifikationen
- Slash-Befehle - Verwendung von Slash-Befehlen im SDK
- Subagenten - Arbeiten mit spezialisierten Agenten
- Skills - Verwendung von Agent Skills