指南

SDK 中的插件

通过 Agent SDK 加载自定义插件，使用命令、代理、技能和钩子来扩展 Claude Code

插件允许您使用可在项目间共享的自定义功能来扩展 Claude Code。通过 Agent SDK，您可以以编程方式从本地目录加载插件，以便向代理会话添加自定义斜杠命令、代理、技能、钩子和 MCP 服务器。

什么是插件？

插件是 Claude Code 扩展的包，可以包括：

命令：自定义斜杠命令
代理：用于特定任务的专门子代理
技能：Claude 自主使用的模型调用功能
钩子：响应工具使用和其他事件的事件处理程序
MCP 服务器：通过模型上下文协议的外部工具集成

有关插件结构和如何创建插件的完整信息，请参阅插件。

加载插件

通过在选项配置中提供本地文件系统路径来加载插件。SDK 支持从不同位置加载多个插件。

TypeScript

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
}

Python

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in 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
        pass

asyncio.run(main())

路径规范

插件路径可以是：

相对路径：相对于您当前工作目录解析（例如，"./plugins/my-plugin"）
绝对路径：完整文件系统路径（例如，"/home/user/plugins/my-plugin"）

路径应指向插件的根目录（包含 .claude-plugin/plugin.json 的目录）。

验证插件安装

当插件成功加载时，它们会出现在系统初始化消息中。您可以验证您的插件是否可用：

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") {
    // Check loaded plugins
    console.log("Plugins:", message.plugins);
    // Example: [{ name: "my-plugin", path: "./my-plugin" }]

    // Check available commands from plugins
    console.log("Commands:", message.slash_commands);
    // Example: ["/help", "/compact", "my-plugin:custom-command"]
  }
}

使用插件命令

来自插件的命令会自动使用插件名称进行命名空间处理，以避免冲突。格式为 plugin-name:command-name。

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet",  // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

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

完整示例

以下是演示插件加载和使用的完整示例：

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.content);
    }
  }
}

runWithPlugin().catch(console.error);

插件结构参考

插件目录必须包含 .claude-plugin/plugin.json 清单文件。它可以选择性地包括：

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

有关创建插件的详细信息，请参阅：

插件 - 完整的插件开发指南
插件参考 - 技术规范和架构

常见用例

开发和测试

在开发期间加载插件，无需全局安装：

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

项目特定的扩展

在您的项目存储库中包含插件以实现团队范围的一致性：

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

多个插件源

组合来自不同位置的插件：

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

故障排除

插件未加载

如果您的插件未出现在初始化消息中：

检查路径：确保路径指向插件根目录（包含 .claude-plugin/）
验证 plugin.json：确保您的清单文件具有有效的 JSON 语法
检查文件权限：确保插件目录可读

命令不可用

如果插件命令不起作用：

使用命名空间：插件命令需要 plugin-name:command-name 格式
检查初始化消息：验证命令是否以正确的命名空间出现在 slash_commands 中
验证命令文件：确保命令 markdown 文件位于 commands/ 目录中

路径解析问题

如果相对路径不起作用：

检查工作目录：相对路径从您当前的工作目录解析
使用绝对路径：为了可靠性，请考虑使用绝对路径
规范化路径：使用路径实用程序正确构造路径

另请参阅

插件 - 完整的插件开发指南
插件参考 - 技术规范
斜杠命令 - 在 SDK 中使用斜杠命令
子代理 - 使用专门的代理
技能 - 使用 Agent Skills

指南

SDK 中的插件

通过 Agent SDK 加载自定义插件，使用命令、代理、技能和钩子来扩展 Claude Code

什么是插件？

插件是 Claude Code 扩展的包，可以包括：

命令：自定义斜杠命令
代理：用于特定任务的专门子代理
技能：Claude 自主使用的模型调用功能
钩子：响应工具使用和其他事件的事件处理程序
MCP 服务器：通过模型上下文协议的外部工具集成

有关插件结构和如何创建插件的完整信息，请参阅插件。

加载插件

通过在选项配置中提供本地文件系统路径来加载插件。SDK 支持从不同位置加载多个插件。

TypeScript

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
}

Python

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in 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
        pass

asyncio.run(main())

路径规范

插件路径可以是：

相对路径：相对于您当前工作目录解析（例如，"./plugins/my-plugin"）
绝对路径：完整文件系统路径（例如，"/home/user/plugins/my-plugin"）

路径应指向插件的根目录（包含 .claude-plugin/plugin.json 的目录）。

验证插件安装

当插件成功加载时，它们会出现在系统初始化消息中。您可以验证您的插件是否可用：

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") {
    // Check loaded plugins
    console.log("Plugins:", message.plugins);
    // Example: [{ name: "my-plugin", path: "./my-plugin" }]

    // Check available commands from plugins
    console.log("Commands:", message.slash_commands);
    // Example: ["/help", "/compact", "my-plugin:custom-command"]
  }
}

使用插件命令

来自插件的命令会自动使用插件名称进行命名空间处理，以避免冲突。格式为 plugin-name:command-name。

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet",  // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

完整示例

以下是演示插件加载和使用的完整示例：

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.content);
    }
  }
}

runWithPlugin().catch(console.error);

插件结构参考

插件目录必须包含 .claude-plugin/plugin.json 清单文件。它可以选择性地包括：

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

有关创建插件的详细信息，请参阅：

插件 - 完整的插件开发指南
插件参考 - 技术规范和架构

常见用例

开发和测试

在开发期间加载插件，无需全局安装：

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

项目特定的扩展

在您的项目存储库中包含插件以实现团队范围的一致性：

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

多个插件源

组合来自不同位置的插件：

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

故障排除

插件未加载

如果您的插件未出现在初始化消息中：

检查路径：确保路径指向插件根目录（包含 .claude-plugin/）
验证 plugin.json：确保您的清单文件具有有效的 JSON 语法
检查文件权限：确保插件目录可读

命令不可用

如果插件命令不起作用：

使用命名空间：插件命令需要 plugin-name:command-name 格式
检查初始化消息：验证命令是否以正确的命名空间出现在 slash_commands 中
验证命令文件：确保命令 markdown 文件位于 commands/ 目录中

路径解析问题

如果相对路径不起作用：

检查工作目录：相对路径从您当前的工作目录解析
使用绝对路径：为了可靠性，请考虑使用绝对路径
规范化路径：使用路径实用程序正确构造路径

另请参阅

插件 - 完整的插件开发指南
插件参考 - 技术规范
斜杠命令 - 在 SDK 中使用斜杠命令
子代理 - 使用专门的代理
技能 - 使用 Agent Skills