Plugins im SDK

Laden Sie benutzerdefinierte Plugins, um Claude Code mit Befehlen, Agenten, Skills und Hooks ü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 benutzerdefinierte Slash-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:

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

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") {
// 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"]
}
}

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":
# Check loaded plugins
print("Plugins:", message.data.get("plugins"))
# Example: [{"name": "my-plugin", "path": "./my-plugin"}]

# Check available commands from plugins
print("Commands:", message.data.get("slash_commands"))
# Example: ["/help", "/compact", "my-plugin:custom-command"]


asyncio.run(main())

Plugin-Skills verwenden

Skills aus Plugins werden automatisch mit dem Plugin-Namen versehen, um Konflikte zu vermeiden. Wenn sie als Slash-Befehle aufgerufen werden, ist das Format plugin-name:skill-name.

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 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 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 muss eine .claude-plugin/plugin.json-Manifestdatei enthalten. Es kann optional Folgendes enthalten:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (invoked autonomously or via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: use skills/ instead
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.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-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 .claude-plugin/ enthält)
Validieren Sie plugin.json: Stellen Sie sicher, dass Ihre Manifestdatei 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: Plugin-Skills erfordern das Format plugin-name:skill-name, wenn sie als Slash-Befehle aufgerufen werden
Überprüfen Sie die Init-Meldung: Überprüfen Sie, dass der Skill in slash_commands mit dem korrekten Namespace angezeigt wird
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:

Ü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

agent-sdk/plugins.md +16 −10

46 46

47 ```python Python theme={null}47 ```python Python theme={null}

48 import asyncio48 import asyncio

~~49 from claude_agent_sdk import query~~49 from claude_agent_sdk import query, ClaudeAgentOptions

50 50

51 51

52 async def main():52 async def main():

53 async for message in query(53 async for message in query(

54 prompt="Hello",54 prompt="Hello",

~~55 options={~~55 options=ClaudeAgentOptions(

~~56 "plugins": [~~56 plugins=[

57 {"type": "local", "path": "./my-plugin"},57 {"type": "local", "path": "./my-plugin"},

58 {"type": "local", "path": "/absolute/path/to/another-plugin"},58 {"type": "local", "path": "/absolute/path/to/another-plugin"},

59 ]59 ]

~~60 },~~60 ),

61 ):61 ):

62 # Plugin commands, agents, and other features are now available62 # Plugin commands, agents, and other features are now available

63 pass63 pass

106 106

107 ```python Python theme={null}107 ```python Python theme={null}

108 import asyncio108 import asyncio

109 from claude_agent_sdk import query109 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

110 110

111 111

112 async def main():112 async def main():

113 async for message in query(113 async for message in query(

114 prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]}114 prompt="Hello",

115 options=ClaudeAgentOptions(

116 plugins=[{"type": "local", "path": "./my-plugin"}]

117 ),

115 ):118 ):

116 if message.type == "system" and message.subtype == "init":119 if isinstance(message, SystemMessage) and message.subtype == "init":

117 # Check loaded plugins120 # Check loaded plugins

118 print("Plugins:", message.data.get("plugins"))121 print("Plugins:", message.data.get("plugins"))

119 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]122 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

151 154

152 ```python Python theme={null}155 ```python Python theme={null}

153 import asyncio156 import asyncio

154 from claude_agent_sdk import query, AssistantMessage, TextBlock157 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

155 158

156 159

157 async def main():160 async def main():

158 # Load a plugin with a custom /greet skill161 # Load a plugin with a custom /greet skill

159 async for message in query(162 async for message in query(

160 prompt="/demo-plugin:greet", # Use plugin skill with namespace163 prompt="/demo-plugin:greet", # Use plugin skill with namespace

161 options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]},164 options=ClaudeAgentOptions(

165 plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]

166 ),

162 ):167 ):

163 # Claude executes the custom greeting skill from the plugin168 # Claude executes the custom greeting skill from the plugin

164 if isinstance(message, AssistantMessage):169 if isinstance(message, AssistantMessage):

219 from claude_agent_sdk import (224 from claude_agent_sdk import (

220 AssistantMessage,225 AssistantMessage,

221 ClaudeAgentOptions,226 ClaudeAgentOptions,

227 SystemMessage,

222 TextBlock,228 TextBlock,

223 query,229 query,

224 )230 )

238 async for message in query(244 async for message in query(

239 prompt="What custom commands do you have available?", options=options245 prompt="What custom commands do you have available?", options=options

240 ):246 ):

241 if message.type == "system" and message.subtype == "init":247 if isinstance(message, SystemMessage) and message.subtype == "init":

242 print(f"Loaded plugins: {message.data.get('plugins')}")248 print(f"Loaded plugins: {message.data.get('plugins')}")

243 print(f"Available commands: {message.data.get('slash_commands')}")249 print(f"Available commands: {message.data.get('slash_commands')}")

244 250

agent-sdk/plugins.md 2026-05-14 17:02 UTC to 2026-05-15 22:58 UTC

Plugins im SDK

Was sind Plugins?

Plugins laden

Pfadangaben

Plugin-Installation überprüfen

Plugin-Skills verwenden

Vollständiges Beispiel

Plugin-Struktur-Referenz

Häufige Anwendungsfälle

Entwicklung und Tests

Projektspezifische Erweiterungen

Mehrere Plugin-Quellen

Fehlerbehebung

Plugin wird nicht geladen

Skills werden nicht angezeigt

Pfadauflösungsprobleme

Siehe auch