即将进入在 SAP 工作的第 19 个年头

在这 19 年里，我对 SAP 产品的 Extensibility 设计也有一些自己的心得，写成了下面这些文章：

• SAP 产品的 Field Extensibility
• SAP Cloud for Customer Extensibility 的设计与实现
• 聊一聊 SAP S/4HANA Public Cloud 的 Key User Extensibility
• SAP S/4HANA 五种扩展方式介绍
• 项目实战中的 SAP Fiori Elements 扩展需求和实现细节

最近在系统学习 Claude Code，把学习心得写成了一个系列，这个系列过去的文章：

• Claude Code 学习笔记之一：理解 Agentic Loop 与内置工具
• Claude Code 学习笔记之二：理解 Sessions 机制
• Claude Code 学习笔记之三：Claude Code Context Window 全景解析

今天的文章聊一聊 Claude Code 的 Extensibility 设计思路和笔者的一些个人理解。

Claude Code 本身已经内置了强大的文件操作、搜索、执行和网络访问能力，这些内置工具覆盖了大部分日常开发任务。

但在实际项目中，我们总会遇到一些个性化的需求：比如希望 Claude 记住项目的特定约定、连接到外部服务、或者自动化某些重复性工作等等。

这就是 Claude Code 扩展层存在的意义。

本文系统介绍 Claude Code 提供的几种扩展机制，说清楚它们各自解决什么问题，以及什么时候该用哪个。

全文 8600 字，纯手工撰写，预计阅读时间 20 分钟。

扩展层的全景视图

Claude Code 的扩展能力可以插入到 agentic loop 的不同环节:

• CLAUDE.md
   - 持久化的上下文，每次会话都会自动加载
• Skills
   - 可复用的知识库和可调用的工作流
• MCP (Model Context Protocol)
   - 连接外部服务和工具的标准协议
• Subagents
   - 在隔离上下文中运行的独立工作单元
• Agent teams
   - 多个独立会话通过共享任务列表和点对点消息进行协作
• Hooks
   - 在生命周期事件触发时执行脚本、HTTP 请求、提示词或 subagent
• Plugins
   - 将上述能力打包成可分发的单元

Skills 是这里面最灵活的扩展方式。

一个 skill 本质上就是一个 Markdown 文件，里面可以包含知识、工作流或者指令。

我们可以通过 /deploy 这样的命令手动调用，也可以让 Claude 在相关场景下自动加载。

Skills 既可以在当前会话中运行，也可以通过 subagents 在隔离的上下文中执行。

根据目标选择合适的机制

下面这张表格给大家总结了 Claude Code 不同扩展机制的定位和适用场景:

Plugins 是打包层。

一个 plugin 可以把 skills、hooks、subagents 和 MCP servers 打包成一个可安装的单元。

Plugin 中的 skills 会被命名空间化(比如 /my-plugin:review)，这样多个 plugins 可以共存。

当我们想在多个代码仓库中复用同一套配置，或者通过 marketplace 分发给其他人时，就应该使用 plugins。

循序渐进地构建扩展体系

在实际使用 Claude Code 中，我们完全不需要急于求成，追求一上来就把所有扩展配置齐全。

上面介绍的每种扩展机制都有明确的触发信号。

笔者最近阅读了很多 Claude Code 相关的技术博客，发现很多人都推荐按照下面这个顺序逐步搭建属于自己的扩展机制:

这些触发信号告诉了我们，应该在什么时候更新 Claude Code 已有的配置。

比如一个重复出现的错误或反复出现的 review 评论，应该编辑到 CLAUDE.md 里，而不是在对话中一次性纠正。

一个我们一直在手动调整的工作流，就是一个需要再次修订的 skill。

区分相似的机制

上面有些机制看起来很像，但还是有细微的区别。

下面是笔者的个人理解。

Skills 和 Subagents 解决不同的问题

• Skills
   是可以加载到任何上下文中的可复用内容
• Subagents
   是与主会话分离运行的隔离工作单元

Skills 可以是参考型的，也可以是操作型的。

参考型 skills 提供 Claude 在整个会话中都会用到的知识，比如 API 风格指南。

操作型 skills 告诉 Claude 做某件具体的事，比如 /deploy 执行部署工作流。

subagent 的使用场景则是需要上下文隔离，或者当前上下文窗口快满了的时候。

Subagent 可能会读取几十个文件或进行大量搜索，但主会话只会收到一份摘要。

由于 subagent 的工作不会消耗主会话的上下文，这个优势在我们不需要中间过程保持可见的时候显得尤其有用。

自定义 subagents 可以有自己的指令，并且可以预加载 skills。

skills 和 subagent 可以组合使用。

一个 subagent 可以预加载特定的 skills(通过 skills: 字段)。一个 skill 可以使用 context: fork 在隔离上下文中运行。详见

CLAUDE.md 和 Skills

两者都存储指令，但加载方式和服务目标不同:

放到 CLAUDE.md 里 的内容是 Claude 应该始终知道的：编码约定、构建命令、项目结构、"绝不做 X" 的规则。

放到 skill 里 的内容是 Claude 有时需要的参考资料(API 文档、风格指南)，或者用 /<name> 触发的工作流(deploy、review、release)。

最佳实践: 保持 CLAUDE.md 在 200 行以内。

如果这个文件的内容持续增长，可以考虑把一部分内容移到 skills 里，或者拆分到 .claude/rules/ 文件中。

CLAUDE.md、Rules 和 Skills

三者都存储指令，但加载方式不同:

使用 CLAUDE.md 存储每个会话都需要的指令：构建命令、测试约定、项目架构。

使用 rules 保持 CLAUDE.md 专注。

带有 paths frontmatter 的 rules 只在 Claude 处理匹配文件时加载，节省上下文。

使用 skills 存储 Claude 只是偶尔需要的内容，比如 API 文档或者用 /<name> 触发的部署检查清单。

Subagent 和 Agent team

两者都能并行化工作，但架构不同:

二者有各自最擅长的场合。

使用 subagent 做快速聚焦的工作：研究一个问题、验证一个说法、审查一个文件。Subagent 完成工作并返回摘要。主会话保持清爽。

使用 agent team 处理团队成员需要分享发现、相互质疑、独立协调的场景。Agent teams 最适合用于有竞争性假设的研究、并行代码审查，以及每个团队成员拥有独立部分的新功能开发。

如何选择: 如果我们正在运行并行的 subagents 但遇到上下文限制，或者 subagents 需要相互通信，agent teams 就是自然的下一步。

MCP 和 Skill

MCP 把 Claude 连接到外部服务。

Skills 扩展 Claude 知道的内容，包括如何有效使用这些服务。

这些机制解决不同的问题，而且配合得很好:

MCP 赋予 Claude Code 与外部系统交互的能力。没有 MCP，Claude Code 就无法查询数据库或发送 Slack 消息。

Skills 让 Claude Code 知道如何有效使用这些工具，加上可以用 /<name> 触发的工作流。

一个 skill 可能包含团队的数据库 schema 和查询模式，或者一个 /post-to-slack 工作流，里面有团队的消息格式规则。

比如 一个 MCP server 把 Claude Code 连接到数据库。一个 skill 教 Claude Code 数据模型、常见查询模式，以及不同任务应该使用哪些表。

Hook 和 Skill

Hook 在生命周期事件触发时执行；skill 被加载到上下文中供 Claude 应用。

hook 最适合完成那些必须每次以相同方式发生、不需要 Claude 思考的操作。比如保存时格式化、拒绝 rm -rf /、会话结束时发送 Slack 消息。

使用 skill 处理 Claude 应该自行决定如何应用步骤，或者内容是知识而非脚本的情况。比如:/release 检查清单、API 风格指南、调试手册。

在 CLAUDE.md 或 skill 中写「绝不编辑 .env」只是一个请求，不是保证，因此 Claude Code 不一定每一次执行都会遵守。

如果一条规则必须每次都严格得到执行，把它做成 hook 而不是 skill，比如把这个规则写入 PreToolUse hook 中。

相应的，Hook 的输出会进入上下文。

一个 PostToolUse hook 运行 linter 后把结果作为文本反馈给 Claude Code，而一个 /fix-lint skill 告诉 Claude Code 如何解决这些问题。

理解机制的层次关系

以上这些扩展机制可以定义在多个层级：用户级、项目级、通过 plugins，或者通过托管策略。

我们还可以在子目录中嵌套 CLAUDE.md 文件，或者在 monorepo 的特定 package 里放置 skills。

当同一个机制存在于多个层级时，它们的层次关系如下:

• CLAUDE.md 文件
   是累加的：所有层级的内容同时贡献到 Claude 的上下文中。工作目录及以上的文件在启动时加载。子目录的文件在我们进入它们时加载。当指令冲突时，Claude Code 会自行判断调和，更具体的指令通常会优先得到执行。
• Skills 和 subagents
   按名称覆盖：当同一个名称存在于多个层级时，skills 的优先级是 managed > user > project；subagents 的优先级是 managed > CLI flag > project > user > plugin。
• MCP servers
   按名称覆盖：local > project > user。
• Hooks
   是合并的:所有注册的 hooks 都会针对匹配的事件触发，无论来源如何。

组合使用多种机制

每种扩展机制解决不同的问题：CLAUDE.md 处理始终在线的上下文，skills 处理按需的知识和工作流，MCP 处理外部连接，subagents 处理隔离，hooks 处理自动化。

比如我们可能在 CLAUDE.md 中存放项目约定，用 skill 管理部署工作流，用 MCP 连接数据库，用 hook 在每次编辑后运行 linting。

总之每种机制处理它最擅长的事情。

留意上下文成本

我们添加的每个机制都会消耗 Claude 的一部分上下文。

一个 Claude Code 项目的扩展实现如果太多，会迅速填满上下文窗口，而且还会增加噪音，降低 Claude Code 的效率和准确率。

比如 skills 可能无法正确触发，或者 Claude 可能忘记约定。

了解每种机制对应的上下文成本，有助于我们做好权衡，构建更有效的 Claude Code 配置。

各机制的上下文成本

每种机制有不同的加载策略和上下文成本:

注意在默认情况下，skill 描述在会话启动时加载，这样 Claude Code 可以决定何时使用它们。

在 skill 的 frontmatter 中设置 disable-model-invocation: true 可以把 skill 完全隐藏，这意味着它只剩下我们手动调用一种触发途径了。

每种机制在会话的不同时间点加载。

小结

扩展 Claude Code 的关键，不在于一开始就把所有机制配置齐全，而在于理解每种机制解决什么问题，然后在遇到问题时选对工具，不断进行迭代优化。

CLAUDE.md 是持久层，保证核心约定每次会话都在场。

Skills 是知识库和工具箱，既可以做随时调阅的参考手册，也可以做一键触发的自动化流程。

MCP 是外部能力的接入层，把 Claude 的视野从本地代码库扩展到数据库、问题跟踪器、监控系统。

Subagents 和 agent teams 是并行化和隔离的手段，前者适合快速的单向任务，后者适合需要协作和讨论的复杂工作。

Hooks 是自动化的底线，用确定性的脚本执行替代指令式的要求，保证关键规则每次都能被遵守。

这些机制各司其职，又能灵活组合。

真正理解它们，才能把 Claude Code 从一个聊天工具变成一个贴合项目实际，提高工作效率的开发伙伴。