Customize behavior

Plugins in the SDK

Plugins in the SDK 这一页讲的，就是 Plugins in the SDK 这件事在 Claude Code 里到底怎么用。

页面信息

对应原页

Plugins in the SDK

页面性质

第三方中文解释页

使用建议

先看人话解释，再对照原页命令和代码

这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。

如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。

这一页先讲明白

这页主要讲 Plugins in the SDK：Load custom plugins to extend Claude Code with commands, agents, skills, and hooks through the Agent SDK

你可以把它当成"Customize behavior"这块里专门管这一摊事的说明书。

你可以把"Plugins in the SDK"理解成 Customize behavior 这一栏里的一把专门工具。这页不是让你背书，而是教你什么时候该把这把工具拿出来。

原文这页大多会按 What are plugins?、Loading plugins、Path specifications、Verifying plugin installation 这些环节往下讲。

翻成人话，大概就是：Path specifications

第一，先别一上来全开全配。先按最小一步试通，确认没跑偏，再继续往下加。

第二，命令、配置名、参数名这些硬东西尽量保留原样。人话解释是帮你听懂，不是帮你改关键字。

第三，照着原文这几个环节挨个过：What are plugins? -> Loading plugins -> Path specifications -> Verifying plugin installation。像下地先看水路、再试机器、再正式开干，一步一步最稳。

终端里敲

原页关键片段：Loading 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
}

终端里敲

原页关键片段：Verifying plugin installation

先别急着往下翻，下面这条命令跑完，心里才有底。

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

终端里敲

原页关键片段：Using plugin skills

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

原页关键片段：Complete example

看到这里，别光点头，下面这条命令先跑起来再说。

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

runWithPlugin().catch(console.error);

目录怎么摆

原页关键片段：Plugin structure reference

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (invoked autonomously or via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: use skills/ instead
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

关键片段

原页关键片段：Development and testing

这一段要真抓重点，通常就抓下面这块原文。

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

关键片段

原页关键片段：Project-specific extensions

下面这块是这一段最值钱的原文样板，先对着看一眼。

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

关键片段

原页关键片段：Multiple plugin sources

先看下面这块原始片段，等会儿再回头看解释会顺得多。

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

预留广告位

正文中段响应式广告 等你后面真接 AdSense，这里再放正式广告。

Documentation Index

这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

What are plugins?

这一块主要是在说"What are plugins?"真到手上该怎么用，哪里最容易踩坑。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Loading plugins

这一段主要是在把"Loading plugins"讲实，不是只摆个标题给你看。

终端里敲

Loading 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
}

Path specifications

这一块主要是在说"Path specifications"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Verifying plugin installation

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

终端里敲

Verifying plugin installation

先别急着往下翻，下面这条命令跑完，心里才有底。

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

Using plugin skills

看到这里，就把"Using plugin skills"当成一件真要上手的活来看。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Using plugin skills

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

Complete example

这一块主要是在说"Complete example"真到手上该怎么用，哪里最容易踩坑。

终端里敲

Complete example

看到这里，别光点头，下面这条命令先跑起来再说。

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

runWithPlugin().catch(console.error);

Plugin structure reference

这一段就是给你查规矩的，像看说明书那样一项项对着来。

目录怎么摆

Plugin structure reference

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (invoked autonomously or via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: use skills/ instead
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Common use cases

这一块主要是在说"Common use cases"真到手上该怎么用，哪里最容易踩坑。

Development and testing

这一段主要是在把"Development and testing"讲实，不是只摆个标题给你看。

关键片段

Development and testing

这一段要真抓重点，通常就抓下面这块原文。

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

Project-specific extensions

这里不是让你背"Project-specific extensions"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

关键片段

Project-specific extensions

下面这块是这一段最值钱的原文样板，先对着看一眼。

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

Multiple plugin sources

看到这里，就把"Multiple plugin sources"当成一件真要上手的活来看。

关键片段

Multiple plugin sources

先看下面这块原始片段，等会儿再回头看解释会顺得多。

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

Troubleshooting

这里讲的是怎么找毛病，先查明白哪一步出错，再决定怎么修。

Plugin not loading

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Skills not appearing

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

Path resolution issues

遇到这种内容，别急着大拆大改，先按它给的路子把问题缩小。

第 1 步：Loading 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
}

终端里敲

第 2 步：Verifying plugin installation

先别急着往下翻，下面这条命令跑完，心里才有底。

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

终端里敲

第 3 步：Using plugin skills

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

第 4 步：Complete example

看到这里，别光点头，下面这条命令先跑起来再说。

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

runWithPlugin().catch(console.error);

一眼看懂这一页

先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。

Plugins in the SDK
   |
   v
这是 Customize behavior 里的一摊要紧活
   |
   v
先弄懂，再下手

文末提醒

这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。

人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。