SDK 中的 Plugins · Claude Code 中文教程

通過 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 的外部工具集成

提示

commands/ 目錄是舊版格式。對於新 plugins，請使用 skills/。Claude Code 繼續支持兩種格式以實現向後相容性。

有關 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 的根目錄：skills/、agents/、hooks/、commands/（舊版）或 .claude-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())

提示

如果您通過 CLI 安裝了 plugin（例如，/plugin install my-plugin@marketplace），您仍然可以通過提供其安裝路徑在 SDK 中使用它。檢查 ~/.claude/plugins/ 以查找 CLI 安裝的 plugins。

完整示例

以下是演示 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