Claude Code 六种扩展能力整理小结

处理Claude Code 六种扩展能力整理小结这类问题时，先确认目标场景，再按步骤核对配置或玩法细节。

0. 一句话记住六者分工

核心判断链：常驻规则 → CLAUDE.md；重复方法 → Skill；要隔离上下文 → Subagent；要连外部 → MCP；必须发生 → Hook；要发给别人 → Plugin。

1. 为什么需要这六套，而不是"一个万能 Prompt"

纯聊天在实际落地时会失效，原因有两个：

1. 规则会被稀释。 Claude 要读几十个文件、跑命令、处理测试失败，还可能经历上下文压缩。你临时交代的"这个项目用 pnpm"“改完跑单测”，会和越来越多新信息挤在同一个上下文里。
2. 经验无法复用。 规则只活在你的会话里，换同事、换机器、换项目就得重讲一遍。

所以六种能力各自回答一个问题：每次进项目该知道什么（CLAUDE.md）→ 某类任务怎么做（Skill）→ 谁去做、要不要隔离（Subagent）→ 怎么拿到仓库外的信息（MCP）→ 哪些动作不许漏（Hook）→ 怎么发给团队（Plugin）。

2. CLAUDE.md：项目的"上岗说明书"

放什么：技术栈；构建/测试/格式化命令；核心目录与模块边界；编码规范；不能改的文件；团队踩过且容易重踩的坑。

和 README 的区别：README 面向人，讲"项目是什么、怎么启动"；CLAUDE.md 面向 Agent，讲"接到任务后应该怎么行动"。

四个存放位置：

大仓库不要把所有模块规则塞进根文件——根目录管全局，各模块（前端/支付/数据）放自己的。

该不该写进去，问三个问题：以后还会反复用到吗？它会改变 Claude 的行动吗？值得每个会话都占上下文吗？三个都是"是"再写。发布清单、安全审查步骤、几十页 API 文档不要塞——那是 Skill 的活。

⚠️ CLAUDE.md 不是安全边界。 它是行为指导，不是强制执行器。写"不要执行危险命令"能降低误操作概率，但没有绝对保证。真正必须拦住的动作要交给权限设置或 PreToolUse Hook。

规则不生效时：先跑 /memory 确认文件真的加载了，再检查是不是太模糊、太长、或彼此冲突。

3. Skills：按需加载的"专项工具箱"

解决的问题：一套发布流程（检查工作区 → 跑测试 → 生成变更说明 → 检查 DB 变更 → 给回滚方案）很重要，但写普通业务代码时用不上。塞进 CLAUDE.md 会让每个会话都背着它。Skill 只在相关任务出现时加载。

目录结构：

.claude/skills/release-check/├── SKILL.md          ← 入口，只做导航├── checklist.md      ← 大段参考资料单独放└── scripts/verify.sh ← 确定性检查交给脚本

SKILL.md 的 frontmatter 关键字段：

1. name —— skill 名，对应 /name 调用。
2. description —— 不是写给人看的广告，而是告诉 Claude 什么时候该加载它。要写清任务、触发语境、以及不适用范围。
3. disable-model-invocation: true —— 只允许用户主动调用，模型不得自动触发。

分工原则：脚本负责确定性检查，Claude 负责结合现场解释结果。

什么时候该做 Skill（信号不是"知识很高级"，而是重复）：同一段说明已经复制第三次；CLAUDE.md 某节越来越像操作手册；任务有固定输入/步骤/输出格式；需要模板、示例或脚本；多个角色要复用同一套知识。

反面：description 写太宽会在不相关任务里乱触发；内容太大加载后一样挤占上下文。Skill 不是越多越好。

4. Subagents：独立上下文里的专门角色

为什么有 Skill 还要 Subagent：Skill 给当前 Agent 加方法，但工作仍发生在当前上下文。安全审查、全仓探索、测试排查会读大量文件、产生大量中间输出，全塞进主会话就把上下文弄脏了。更麻烦的是，让写代码的 Agent 审自己的代码，容易产生"我已经改好了所以应该没问题"的自我认可。

Subagent 的价值：另开独立上下文，让专门角色完成任务，只把结论和证据带回来。

定义（.claude/agents/.md）的关键字段：name、description、tools（限制可用工具）、model（可 inherit）、skills（预加载方法）。正文写角色职责和输出格式要求。

一个实用技巧：要求它"若无问题，列出检查了什么，不要只回 looks good"——避免拿到无信息量的结论。

适合拆的任务（共同点：过程很长，但主会话只要结果）：只读探索大代码库；安全/性能/测试独立复核；多个互不依赖模块的并行调查；需要不同角色从相反角度挑错；想给角色限制工具、模型或权限。

不适合拆：单文件小修改；强依赖主会话大量隐含信息；子任务互相等待；拆分成本超过任务本身。

组合用法：Skill 是方法，Subagent 是拿着方法独立干活的角色——在 Subagent 的 skills 字段里预加载安全规范或测试方法。

5. MCP：接上仓库外的世界

是什么：Model Context Protocol，解决"AI 应用如何用统一方式发现和调用外部工具与数据"。MCP Server 暴露能力，Claude Code 作为 Client 连接调用——不用给每个 Agent 手写一套集成。

典型外部系统：代码托管平台、工单系统（Jira/Linear）、Sentry 与日志平台、数据库/数仓、内部文档与发布平台、浏览器或设计工具。

添加与检查：

claude mcp add --transport http issue-tracker https://mcp.example.com/mcpclaude mcp add --transport stdio my-tools -- node ./tools/mcp-server.jsclaude mcp listclaude mcp get issue-tracker

会话内用 /mcp 看连接与认证状态。团队共享配置可写进 .mcp.json——但从仓库拉下来的配置需要经过信任和审批，不要因为文件进了 Git 就默认它安全。

三个坑：

1. 权限给太大。查库就用只读账号，别上生产写权限；代码评审只需读 PR，别顺手给删仓库权限。
2. 工具太多。一口气接几十个 Server、暴露几百个工具，既增加选择成本又污染上下文。先接最常用、返回结果最干净的。
3. 把 MCP 当成工作方法。MCP 只负责"能连接、能调用"；查什么、怎么判断、输出什么格式，仍归 CLAUDE.md / Skill / Subagent。

一句话：MCP 提供手和眼，Skill 提供做事方法。

6. Hooks：不再依赖"记得"

和提醒的区别：在 CLAUDE.md 写"每次改完文件都要格式化"是提醒；配 PostToolUse Hook 在编辑成功后自动跑格式化是确定性动作。

可挂的事件：会话开始注入环境信息；工具执行前检查或拦截；文件修改后自动格式化；工具失败后记录诊断；等待确认时发桌面通知；上下文压缩前保存关键状态。

配置（.claude/settings.json 或 ~/.claude/settings.json）：

{  "hooks": {    "PostToolUse": [      {        "matcher": "Edit|Write",        "hooks": [          { "type": "command", "command": ".claude/hooks/check-edited-file.sh" }        ]      }    ]  }}

建议把复杂逻辑放进独立脚本（如上），而不是把一长串 shell 塞进 JSON——脚本能进 Git、能单独测试。配完跑 /hooks 确认事件、匹配器、命令都加载了。

不要变成新坑：matcher 尽量窄，别什么都用 .*；默认快速执行，重任务不要卡住每次编辑；脚本要有明确退出码和错误信息；不要在 Hook 里偷偷做发布、删除、推送等高风险动作；先手动跑脚本再接 Hook；需要复杂判断时用 Skill 或独立审查 Agent，不要堆一坨 shell。

判据："发生到这里就必须做"→ Hook；"需要读大量上下文、权衡多个方案"→ 不要 Hook。

7. Plugins：打包分发，不是第七种能力

Plugin 更像包装和分发格式，可以同时带 Skills、Subagents、Hooks、MCP Server 配置、LSP 配置等。

什么时候做：在单个项目的 .claude/ 里做实验适合快速迭代；等配置稳定、需要跨项目跨团队安装/升级/版本管理时，再打成 Plugin。

最小结构：

team-toolkit/├── .claude-plugin/plugin.json   ← name / description / version├── skills/release-check/SKILL.md├── agents/security-reviewer.md├── hooks/hooks.json└── .mcp.json

本地开发：claude --plugin-dir ./team-toolkit；安装市场插件：/plugin 面板或 /plugin install 。

注意：安装前看清它提供什么组件、要什么权限、连哪些外部系统——安装插件不等于给它无限授权。Plugin 只解决分发，不会自动修好里面写得差的 Skill、过宽的 Hook 或权限过大的 MCP。

8. 配置顺序（从零开始）

不要第一天就装几十个 Plugin、接十几个 MCP、开一队 Subagents——配置越多，冲突、权限和上下文成本越高。按问题出现的顺序来：

1. 根 CLAUDE.md 写到能用：只写命令、架构、禁区、最常见的坑。/memory 验证加载。
2. 把重复流程做成一个 Skill：从最常复制的发布/评审/排障流程开始。/skills 检查描述和作用域。
3. 给"必须发生"的动作加 Hook：先接格式化、lint、危险命令拦截。/hooks 检查，手动验证成功和失败两条路径。
4. 只为明确场景建 Subagent：优先安全审查、大范围只读探索。/agents 检查工具/模型/skills。
5. 按真实需求接 MCP：先接一个高频系统，给最小权限。/mcp 看认证连接状态。
6. 稳定后再做 Plugin：先证明有用，再跨项目分发。插件化太早只会把没想清楚的配置更快复制出去。

配置不生效时的排查顺序：/doctor → /status → /permissions，先确认"有没有加载、从哪加载、最终权限是什么"，再怀疑模型。

9. 最容易配错的六个地方

10. 高频问题

CLAUDE.md 和自动 Memory 的区别？ CLAUDE.md 是团队明确维护的项目规则，进 Git、可评审；自动 Memory 是 Claude 在使用中积累的本机经验，适合存调试发现和个人习惯。团队制度写进 CLAUDE.md，不要等自动 Memory 自己猜。

Skill 还是 Hook？ 需要结合上下文判断、执行一套方法 → Skill；命中事件就必须执行且结果稳定可验证 → Hook。"按团队标准审查 PR"是 Skill，"编辑后自动格式化"是 Hook。

Skill 还是 Subagent？ 给当前上下文补知识 → Skill；把长过程隔离出去只拿结果 → Subagent。安全角色需要固定审查方法时，让 Subagent 预加载对应 Skill。

MCP 和 Plugin 的关系？ MCP 是连接协议（Claude 怎么调外部系统）；Plugin 是分发包（怎么把 MCP 配置连同 Skills/Agents/Hooks 一起发给别人）。

配齐六件套一定更好吗？ 不一定。这些不是等级勋章。小项目可能只需要 30 行 CLAUDE.md 加一个格式化 Hook。重复流程出现了才加 Skill；上下文需要隔离才加 Subagent；仓库外能力确实要用才接 MCP。最好的配置不是组件最多，而是每一层都在解决真实问题。