SDK 中的 Plugins

通過 Agent SDK 加載自訂 plugins，以使用命令、agents、skills 和 hooks 擴展 Claude Code

Plugins 允許您使用可在專案間共享的自訂功能來擴展 Claude Code。通過 Agent SDK，您可以以程式方式從本地目錄加載 plugins，以將自訂 slash commands、agents、skills、hooks 和 MCP servers 添加到您的 agent sessions。

什麼是 plugins？

Plugins 是 Claude Code 擴展的套件，可以包括：

Skills：Claude 自主使用的模型調用功能（也可以使用 /skill-name 調用）
Agents：用於特定任務的專門子 agents
Hooks：響應工具使用和其他事件的事件處理程序
MCP servers：通過 Model Context Protocol 的外部工具集成

有關 plugin 結構和如何創建 plugins 的完整信息，請參閱 Plugins。

加載 plugins

通過在選項配置中提供本地文件系統路徑來加載 plugins。type 字段必須是 "local"，這是 SDK 接受的唯一值。要使用通過 marketplace 或遠程存儲庫分發的 plugin，請先下載它並提供本地目錄路徑。SDK 支持從不同位置加載多個 plugins。

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())

路徑規範

Plugin 路徑可以是：

相對路徑：相對於您的當前工作目錄解析（例如，"./plugins/my-plugin"）
絕對路徑：完整文件系統路徑（例如，"/home/user/plugins/my-plugin"）

驗證 plugin 安裝

當 plugins 成功加載時，它們會出現在系統初始化消息中。您可以驗證您的 plugins 是否可用：

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") {
// 檢查已加載的 plugins
console.log("Plugins:", message.plugins);
// 範例：[{ name: "my-plugin", path: "./my-plugin" }]

// 檢查來自 plugins 的可用命令
console.log("Commands:", message.slash_commands);
// 範例：["/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":
# 檢查已加載的 plugins
print("Plugins:", message.data.get("plugins"))
# 範例：[{"name": "my-plugin", "path": "./my-plugin"}]

# 檢查來自 plugins 的可用命令
print("Commands:", message.data.get("slash_commands"))
# 範例：["/help", "/compact", "my-plugin:custom-command"]


asyncio.run(main())

使用 plugin skills

來自 plugins 的 skills 會自動使用 plugin 名稱進行命名空間化，以避免衝突。當作為 slash commands 調用時，格式為 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())

完整示例

以下是演示 plugin 加載和使用的完整示例：

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 結構參考

Plugin 目錄必須包含 .claude-plugin/plugin.json 清單文件。它可以選擇性地包括：

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

有關創建 plugins 的詳細信息，請參閱：

Plugins - 完整的 plugin 開發指南
Plugins reference - 技術規範和架構

常見用例

開發和測試

在開發期間加載 plugins，無需全局安裝它們：

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

專案特定的擴展

在您的專案存儲庫中包含 plugins，以實現團隊範圍的一致性：

plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];

多個 plugin 來源

結合來自不同位置的 plugins：

plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];

Troubleshooting

Plugin 未加載

如果您的 plugin 未出現在初始化消息中：

檢查路徑：確保路徑指向 plugin 根目錄（包含 .claude-plugin/）
驗證 plugin.json：確保您的清單文件具有有效的 JSON 語法
檢查文件權限：確保 plugin 目錄可讀

Skills 未出現

如果 plugin skills 不起作用：

使用命名空間：Plugin skills 在作為 slash commands 調用時需要 plugin-name:skill-name 格式
檢查初始化消息：驗證 skill 是否以正確的命名空間出現在 slash_commands 中
驗證 skill 文件：確保每個 skill 在 skills/ 下的自己的子目錄中都有 SKILL.md 文件（例如，skills/my-skill/SKILL.md）

路徑解析問題

如果相對路徑不起作用：

檢查工作目錄：相對路徑從您的當前工作目錄解析
使用絕對路徑：為了可靠性，請考慮使用絕對路徑
規範化路徑：使用路徑實用程序正確構造路徑

另請參閱

Plugins - 完整的 plugin 開發指南
Plugins reference - 技術規範
Slash Commands - 在 SDK 中使用 slash commands
Subagents - 使用專門的 agents
Skills - 使用 Agent Skills

agent-sdk/plugins.md +24 −18

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

93 }93 }

94 })) {94 })) {

95 if (message.type === "system" && message.subtype === "init") {95 if (message.type === "system" && message.subtype === "init") {

~~96 // Check loaded plugins~~96 // 檢查已加載的 plugins

97 console.log("Plugins:", message.plugins);97 console.log("Plugins:", message.plugins);

~~98 // Example: [{ name: "my-plugin", path: "./my-plugin" }]~~98 // 範例：[{ name: "my-plugin", path: "./my-plugin" }]

99 99

100 // Check available commands from plugins100 // 檢查來自 plugins 的可用命令

101 console.log("Commands:", message.slash_commands);101 console.log("Commands:", message.slash_commands);

102 // Example: ["/help", "/compact", "my-plugin:custom-command"]102 // 範例：["/help", "/compact", "my-plugin:custom-command"]

103 }103 }

104 }104 }

105 ```105 ```

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 # 檢查已加載的 plugins

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

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

120 123

121 # Check available commands from plugins124 # 檢查來自 plugins 的可用命令

122 print("Commands:", message.data.get("slash_commands"))125 print("Commands:", message.data.get("slash_commands"))

123 # Example: ["/help", "/compact", "my-plugin:custom-command"]126 # 範例：["/help", "/compact", "my-plugin:custom-command"]

124 127

125 128

126 asyncio.run(main())129 asyncio.run(main())

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

SDK 中的 Plugins

什麼是 plugins？

加載 plugins

路徑規範

驗證 plugin 安裝

使用 plugin skills

完整示例

Plugin 結構參考

常見用例

開發和測試

專案特定的擴展

多個 plugin 來源

Troubleshooting

Plugin 未加載

Skills 未出現

路徑解析問題

另請參閱