跳轉到主要內容
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
}

​
路徑規範

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"]
  }
}

​
使用 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);
  }
}
如果您通過 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);

​
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，無需全局安裝它們： 
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 未出現在初始化消息中：
  1. 檢查路徑：確保路徑指向 plugin 根目錄，即 skills/、agents/、hooks/、commands/（舊版）或 .claude-plugin/ 的父目錄
  2. 驗證 plugin.json：如果您的 plugin 包含清單，請確保它具有有效的 JSON 語法
  3. 檢查文件權限：確保 plugin 目錄可讀

​
Skills 未出現

如果 plugin skills 不起作用：
  1. 使用命名空間：以 /plugin-name:skill-name 的方式調用 plugin skills
  2. 檢查初始化消息：驗證 skill 是否以正確的命名空間出現在 skills 列表中
  3. 驗證 skill 文件：確保每個 skill 在 skills/ 下的自己的子目錄中都有 SKILL.md 文件，例如 skills/my-skill/SKILL.md

​
路徑解析問題

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

​
另請參閱