SDK 中的 Plugins
通過 Agent SDK 加載自訂 plugins，以使用 skills、agents、hooks 和 MCP servers 擴展 Claude Code
Plugins 允許您使用可在專案間共享的自訂功能來擴展 Claude Code。通過 Agent SDK，您可以以程式方式從本地目錄加載 plugins，以將 skills、agents、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" }]
// Plugin skills 會以 plugin 名稱作為前綴出現
console.log("Skills:", message.skills);
// 範例：["my-plugin:greet"]
// Plugin 命令使用相同的前綴，skills 也會出現在這裡
console.log("Commands:", message.slash_commands);
// 範例：["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":
# 檢查已加載的 plugins
print("Plugins:", message.data.get("plugins"))
# 範例：[{"name": "my-plugin", "path": "./my-plugin"}]
# Plugin skills 會以 plugin 名稱作為前綴出現
print("Skills:", message.data.get("skills"))
# 範例：["my-plugin:greet"]
# Plugin 命令使用相同的前綴，skills 也會出現在這裡
print("Commands:", message.data.get("slash_commands"))
# 範例：["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
使用 plugin skills
來自 plugins 的 skills 會自動使用 plugin 名稱進行命名空間化，以避免衝突。若要直接調用，請在提示中發送 /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 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 結構參考
Plugin 目錄通常包含 .claude-plugin/plugin.json 清單文件。清單是可選的。省略時，Claude Code 會從目錄佈局自動發現組件。目錄可以包括：
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin 清單（可選，沒有它也會自動發現組件）
├── skills/ # Agent Skills（自主調用或通過 /skill-name）
│ └── my-skill/
│ └── SKILL.md
├── commands/ # 舊版：改用 skills/ 代替
│ └── custom-cmd.md
├── agents/ # 自訂代理
│ └── specialist.md
├── hooks/ # 事件處理程序
│ └── hooks.json
└── .mcp.json # MCP 伺服器定義
有關創建 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" }
];
故障排除
Plugin 未加載
如果您的 plugin 未出現在初始化消息中：
- 檢查路徑：確保路徑指向 plugin 根目錄，即
skills/、agents/、hooks/、commands/（舊版）或.claude-plugin/的父目錄 - 驗證 plugin.json：如果您的 plugin 包含清單，請確保它具有有效的 JSON 語法
- 檢查文件權限：確保 plugin 目錄可讀
Skills 未出現
如果 plugin skills 不起作用：
- 使用命名空間：以
/plugin-name:skill-name的方式調用 plugin skills - 檢查初始化消息：驗證 skill 是否以正確的命名空間出現在
skills列表中 - 驗證 skill 文件：確保每個 skill 在
skills/下的自己的子目錄中都有SKILL.md文件，例如skills/my-skill/SKILL.md
路徑解析問題
如果相對路徑不起作用：
- 檢查工作目錄：相對路徑從您的當前工作目錄解析
- 使用絕對路徑：為了可靠性，請考慮使用絕對路徑
- 規範化路徑：使用路徑實用程序正確構造路徑
另請參閱
- Plugins - 完整的 plugin 開發指南
- Plugins reference - 技術規範
- Commands - 在 SDK 中使用 commands
- Subagents - 使用專門的 agents
- Skills - 使用 Agent Skills