SDK 中的 Plugins

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

Agent SDK

核心概念

輸入和輸出

使用工具擴充

自訂行為

控制與可觀測性

部署

SDK 參考資料

什麼是 plugins？

加載 plugins

路徑規範

驗證 plugin 安裝

使用 plugin skills

完整示例

Plugin 結構參考

常見用例

開發和測試

專案特定的擴展

多個 plugin 來源

故障排除

Plugin 未加載

Skills 未出現

路徑解析問題

另請參閱

​什麼是 plugins？

​加載 plugins

​路徑規範

​驗證 plugin 安裝

​使用 plugin skills

​完整示例

​Plugin 結構參考

​常見用例

​開發和測試

​專案特定的擴展

​多個 plugin 來源

​故障排除

​Plugin 未加載

​Skills 未出現

​路徑解析問題

​另請參閱

什麼是 plugins？

加載 plugins

路徑規範

驗證 plugin 安裝

使用 plugin skills

完整示例

Plugin 結構參考

常見用例

開發和測試

專案特定的擴展

多個 plugin 來源

故障排除

Plugin 未加載

Skills 未出現

路徑解析問題

另請參閱