Claude Code Agent SDK 插件组件全景（Skills / Agents / Hooks / MCP / LSP 各自承担什么）

Claude Code Agent SDK 的插件是一个”自包含目录”，一个插件可以同时捆绑 Skills、Agents、Hooks、MCP servers、LSP servers 与 Monitors 六大组件。插件设计已逐步放弃早期 commands/ 这种扁平结构，新建插件建议统一走 skills/ 目录承载可复用 prompt 流程，再由 agents/hooks/mcp/lsp 提供”专业分工 + 事件拦截 + 外部世界接入”。下面把这六类组件的作用、配置位置与典型用法逐一拆开。

一、插件根目录的统一结构

一个合规的插件根目录大致长这样：

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 可选 manifest
├── skills/
│   ├── pdf-processor/
│   │   ├── SKILL.md
│   │   └── scripts/
│   └── code-reviewer/
│       └── SKILL.md
├── agents/
│   ├── code-reviewer.md
│   └── test-generator.md
├── hooks/
│   ├── hooks.json
│   └── scripts/
├── .mcp.json                # 插件自带的 MCP server
├── .lsp.json                # 插件自带的 LSP server
└── monitors/                # 后台观察进程

SDK 启动时按目录名自动发现 Skills、Agents、Hooks 与 MCP server，开发者只需要在配置中给出插件根目录的本地路径。

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

const options: ClaudeAgentOptions = {
  plugins: [
    { type: "local", path: "./my-plugin" },
    { type: "local", path: "/absolute/path/to/another-plugin" },
  ],
};

for await (const message of query({ prompt: "Hello", options })) {
  // 启动后 SystemMessage.subtype=init 里会回带 plugins / skills / slash_commands
}

二、Skills：可被模型自动调用的能力包

2.1 形态与发现机制

Skills 存放在 skills/<skill-name>/SKILL.md，根目录下也可以直接放一个 SKILL.md 表示单一 skill。SKILL.md 顶部是 YAML frontmatter，常见字段包括 name、description、version。Skills 与旧的 commands/*.md 形式并存，但官方明确建议新插件使用 skills/，因为它支持子目录、scripts/、references/ 等附属资源，更适合承载复杂能力。

2.2 命名空间与调用方式

插件加载后，skill 与命令会自动带 插件名: 前缀，避免重名冲突。手动调用时写 /my-plugin:code-review，模型自动调用则依赖 description 字段匹配任务上下文。

---
name: code-review
description: 对一段 diff 做评审，重点关注命名、错误处理与边界条件
version: 1.0.0
---
# 评审流程
1. 读取 diff；
2. 按"命名 / 错误处理 / 边界条件"三段输出意见；
3. 用 Markdown 列表给出改进建议。

三、Agents：可被自动调用的专业子代理

3.1 形态与字段

Agent 是 agents/<role>.md 文件，frontmatter 支持 name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation 等字段。isolation 唯一有效值是 "worktree"，用于让该子代理独立 git worktree 运行，避免污染主分支。

---
name: code-reviewer
description: 负责评审 PR/差异，擅长发现命名、错误处理与边界条件问题
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---
你是一名资深 code reviewer，请按"命名 / 错误处理 / 边界条件"三段给出可执行建议。

3.2 集成点

插件 agent 会出现在 /agents 界面，也会在 @-mention 自动补全里以 my-plugin:code-reviewer 形式暴露。出于安全考虑，插件提供的 agents 不支持 hooks、mcpServers、permissionMode 三个字段——这三个能力由插件根目录的其它组件分别承担，避免一处越权。

四、Hooks：生命周期事件拦截器

4.1 事件矩阵

Hooks 通过 hooks/hooks.json 注册，响应与用户定义 hooks 同样的事件。Claude Code 现行版本已支持 30+ 种事件，覆盖会话、提示、工具调用、任务、子代理、上下文压缩等。

事件	触发时机	常见用途
`SessionStart`	会话开始或恢复	准备环境变量、打印欢迎信息
`UserPromptSubmit`	提交提示后，模型处理前	注入额外上下文
`PreToolUse`	工具调用执行前	拦截危险命令、改写参数
`PostToolUse`	工具调用成功后	自动格式化、跑 lint
`PostToolUseFailure`	工具调用失败后	上报失败、追加日志
`TaskCreated` / `TaskCompleted`	任务创建/完成	同步外部系统
`SubagentStop`	子代理结束	汇总报告
`SessionEnd`	会话结束	清理临时文件

4.2 四种 Hook 类型

每条 hook 实际执行体有四种：command（跑 shell）、http（POST JSON）、mcp_tool（调用已注册 MCP 工具）、prompt（用模型打分判定）、agent（让智能体验证器跑任务）。PreToolUse 是最常见的拦截点：检查参数、合规、敏感词。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/scripts/format-code.sh" }
        ]
      }
    ]
  }
}

五、MCP servers：把外部世界拉进上下文

5.1 形态与作用域

MCP server 配置写在 .mcp.json（或 plugin.json 内联），结构与全局 .mcp.json 一致。插件自带的 MCP server 启动后，其暴露的工具会以 mcp__plugin_<plugin-name>_<server-name>__<tool> 形式出现在 Claude 工具集，Hook 的 matcher 必须使用这种作用域名字才能命中。

5.2 启动行为

启用插件时 MCP server 自动启动；用户级 MCP server 与插件级 MCP server 并存。用户可以关闭自己添加的 server，但通常无法关闭插件捆绑的 server——这一点对”把内部知识库”作为企业基线尤为重要。

六、LSP servers 与 Monitors：代码智能与后台观察

LSP servers 放在 .lsp.json，把语言服务器映射到文件扩展名，启用后 Claude 能在每次编辑后拿到即时诊断、跳转定义、悬停信息。Monitors 是后台常驻进程，用于观察会话状态、跟踪任务进展、向主 agent 推送结构化事件。

组件	主要作用	配置位置
Skills	复用 prompt 流程，模型按上下文自动调用	`skills/<name>/SKILL.md`
Agents	专项子代理，按任务被自动或手动调用	`agents/<role>.md`
Hooks	拦截生命周期事件，改写/阻断/通知	`hooks/hooks.json`
MCP servers	把外部工具/数据接入模型上下文	`.mcp.json`
LSP servers	提供代码智能（诊断、跳转、悬停）	`.lsp.json`
Monitors	后台观察会话，向上游推送事件	`monitors/`

七、SDK 加载插件的工程要点

加载插件有几个工程化细节值得注意：

路径必须指向根目录：./my-plugin 是 skills/ 的父目录，指向 skills/ 子目录会无法发现。
市场插件先下载再传路径：marketplace 上分发的插件需要先 clone 到本地，再传本地目录。
可移植路径：所有 hooks/commands/mcp 字段都应用 ${CLAUDE_PLUGIN_ROOT} 占位，避免硬编码绝对路径。
init 消息自检：监听 SystemMessage.subtype === "init"，从 data.plugins / skills / slash_commands 字段即可确认插件是否真的生效。

到这里，一份合规的 Claude Code 插件就能在团队多个项目里复用：skills 负责”做什么”，agents 负责”谁来做”，hooks 负责”什么时候介入”，mcp/lsp/monitors 负责”接什么外部能力”。

常见问题（FAQ）

Q1：插件里 commands/ 和 skills/ 能不能混用？

可以，但官方建议新插件统一用 skills/，因为 skills 支持子目录、附属脚本与资源，更易扩展。

Q2：plugin 提供的 agent 能配置自己的 MCP server 吗？

出于安全原因，插件 agent 的 frontmatter 不支持 hooks、mcpServers、permissionMode，需在插件根目录的其它组件里定义。

Q3：插件如何在团队里分发？

先打包到 marketplace（GitHub repo + manifest），团队成员用 /plugin Discover 安装；或者直接把插件目录提交到仓库，配合 plugins: [{ type: "local", path: "./plugins/xxx" }] 加载。