文档索引

获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面后再继续探索。

扩展 Claude Code

了解何时使用 CLAUDE.md、技能、子代理、钩子、MCP 和插件。

Claude Code 将一个能推理你代码的模型与用于文件操作、搜索、执行和网络访问的内置工具相结合。内置工具覆盖了大多数编码任务。本指南涵盖扩展层：你添加的功能，用于自定义 Claude 知道什么、连接外部服务和自动化工作流。

Note

有关核心代理循环如何工作，请参阅 Claude Code 工作原理。

Claude Code 新手？ 从 CLAUDE.md 开始设置项目规范，然后根据具体需要添加其他扩展。

概览

扩展插件到代理循环的不同部分：

CLAUDE.md 添加 Claude 每次会话都能看到的持久上下文
技能添加可复用的知识和可调用的工作流
代码智能 将 Claude 连接到语言服务器，实现符号级导航和实时类型错误提示
MCP 将 Claude 连接到外部服务和工具
子代理 在隔离的上下文中运行自己的循环，返回摘要
代理团队 协调多个独立会话，共享任务和对等消息
钩子在生命周期事件触发时运行脚本、HTTP 请求、提示词或子代理
插件和市场打包和分发这些功能

技能是最灵活的扩展。技能是一个包含知识、工作流或指令的 markdown 文件。你可以用 /deploy 等命令调用技能，Claude 也可以在相关时自动加载它们。技能可以在当前对话中运行，也可以通过子代理在隔离上下文中运行。

将功能匹配到你的目标

功能范围从 Claude 每次会话都能看到的始终在线上下文，到你或 Claude 可以调用的按需能力，再到在特定事件上运行的后台自动化。下表显示了可用的功能以及何时使用它们。

功能	作用	何时使用	示例
CLAUDE.md	每次对话加载的持久上下文	项目规范、"始终执行 X"规则	"使用 pnpm 而不是 npm。提交前运行测试。"
技能	Claude 可以使用的指令、知识和工作流	可复用内容、参考文档、可重复任务	`/deploy` 运行你的部署检查清单；包含端点模式的 API 文档技能
子代理	返回摘要结果的隔离执行上下文	上下文隔离、并行任务、专门工作者	读取多个文件但只返回关键发现的研究任务
代理团队	协调多个独立的 Claude Code 会话	并行研究、新功能开发、使用竞争假设调试	同时启动审查者检查安全性、性能和测试
代码智能	语言服务器导航和诊断	类型化语言、大型代码库中 grep 慢或不精确	跳转到符号定义而不是读取整个文件
MCP	连接到外部服务	外部数据或操作	查询数据库、发布到 Slack、控制浏览器
钩子	由事件触发的脚本、HTTP 请求、提示词或子代理	必须在每个匹配事件上运行的自动化	每次文件编辑后运行 ESLint

插件是打包层。插件将技能、钩子、子代理和 MCP 服务器打包成一个可安装的单元。插件技能有命名空间（如 /my-plugin:review），因此多个插件可以共存。当你想在多个仓库中复用相同设置或通过**市场**分发给他人时，使用插件。

随时间构建你的设置

你不需要一开始就配置所有内容。每个功能都有一个可识别的触发条件，大多数团队按大致以下顺序添加它们：

触发条件	添加
Claude 两次搞错一个规范或命令	将其添加到 CLAUDE.md
你反复输入相同的提示词来开始任务	将其保存为用户可调用的技能
你第三次将相同的剧本或多步骤流程粘贴到聊天中	将其捕获为技能
你不断从 Claude 看不到的浏览器标签页复制数据	将该系统连接为 MCP 服务器
Claude 读取多个文件来查找符号的定义或使用位置	为你的语言安装代码智能插件
一个副任务用你不会再引用的输出填满你的对话	通过子代理路由它
你希望某件事每次都自动发生而不用询问	编写一个钩子
第二个仓库需要相同的设置	将其打包为插件

同样的触发条件告诉你何时更新已有内容。重复的错误或反复出现的审查评论是 CLAUDE.md 编辑，而不是聊天中的一次性修正。一个你不断手动调整的工作流是需要再次修订的技能。

比较相似功能

某些功能可能看起来相似。以下是如何区分它们。

技能和子代理解决不同的问题：

技能是可以加载到任何上下文中的可复用内容
子代理是与主对话分开运行的隔离工作者

方面	技能	子代理
是什么	可复用的指令、知识或工作流	拥有自己上下文的隔离工作者
关键优势	跨上下文共享内容	上下文隔离。工作独立进行，只返回摘要
上下文窗口影响	添加到你的主窗口	使用单独的窗口，有自己的输入和输出 token
最适合	参考材料、可调用工作流	读取多个文件的任务、并行工作、专门工作者

技能可以是参考型或操作型。 参考型技能提供 Claude 在整个会话中使用的知识（如你的 API 风格指南）。操作型技能告诉 Claude 做特定的事情（如运行部署工作流的 /deploy）。

使用子代理当你需要上下文隔离或当你的上下文窗口快满时。子代理可能读取数十个文件或运行大量搜索，但你的主对话只接收摘要。由于子代理工作不消耗你的主上下文，当你不需要中间工作保持可见时也很有用。自定义子代理可以有自己的指令并可以预加载技能。

它们可以结合。 子代理可以预加载特定技能（skills: 字段）。技能可以使用 context: fork 在隔离上下文中运行。详见技能。

两者都存储指令，但加载方式不同，用途也不同。

方面	CLAUDE.md	技能
加载方式	每次会话，自动	按需
可以包含文件	可以，使用 `@path` 导入	可以，使用 `@path` 导入
可以触发工作流	不可以	可以，使用 `/<name>`
最适合	"始终执行 X"规则	参考材料、可调用工作流

放在 CLAUDE.md 中如果 Claude 应该始终知道它：编码规范、构建命令、项目结构、"绝不执行 X"规则。

放在技能中如果它是 Claude 有时需要的参考材料（API 文档、风格指南）或你用 /<name> 触发的工作流（部署、审查、发布）。

经验法则： 保持 CLAUDE.md 在 200 行以内。如果它在增长，将参考内容移到技能或拆分为 .claude/rules/ 文件。

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

方面	CLAUDE.md	`.claude/rules/`	技能
加载方式	每次会话	每次会话，或当匹配文件被打开时	按需，当被调用或相关时
范围	整个项目	可以限定到文件路径	任务特定
最适合	核心规范和构建命令	语言特定或目录特定的指南	参考材料、可重复工作流

使用 CLAUDE.md 用于每次会话都需要的指令：构建命令、测试规范、项目架构。

使用规则 保持 CLAUDE.md 聚焦。带有 paths 前置数据的规则只在 Claude 处理匹配文件时加载，节省上下文。

使用技能 用于 Claude 只有时需要的内容，如 API 文档或你用 /<name> 触发的部署检查清单。

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

子代理在你的会话内运行并将结果报告回你的主上下文
代理团队是相互通信的独立 Claude Code 会话

方面	子代理	代理团队
上下文	自己的上下文窗口；结果返回给调用者	自己的上下文窗口；完全独立
通信	只向主代理报告结果	队友直接互相发消息
协调	主代理管理所有工作	共享任务列表，自我协调
最适合	只需要结果的专注任务	需要讨论和协作的复杂工作
Token 成本	较低：结果摘要回主上下文	较高：每个队友是单独的 Claude 实例

使用子代理当你需要快速、专注的工作者：研究一个问题、验证一个声明、审查一个文件。子代理完成工作并返回摘要。你的主对话保持干净。

使用代理团队当队友需要共享发现、互相质疑和独立协调时。代理团队最适合有竞争假设的研究、并行代码审查和每个队友负责独立部分的新功能开发。

转折点： 如果你正在运行并行子代理但遇到上下文限制，或者你的子代理需要相互通信，代理团队是自然的下一步。

Note

代理团队是实验性的，默认禁用。详见代理团队了解设置和当前限制。

MCP 将 Claude 连接到外部服务。技能扩展 Claude 知道的内容，包括如何有效使用这些服务。

方面	MCP	技能
是什么	连接外部服务的协议	知识、工作流和参考材料
提供	工具和数据访问	知识、工作流、参考材料
示例	Slack 集成、数据库查询、浏览器控制	代码审查检查清单、部署工作流、API 风格指南

这些解决不同的问题，可以很好地协同工作：

MCP 为外部系统给 Claude 提供专用工具，连接和认证由服务器处理。

技能给 Claude 提供如何有效使用这些工具的知识，以及你可以用 /<name> 触发的工作流。技能可能包含你团队的数据库架构和查询模式，或带有团队消息格式规则的 /post-to-slack 工作流。

示例：MCP 服务器将 Claude 连接到你的数据库。技能教 Claude 你的数据模型、常见查询模式和不同任务使用哪些表。

钩子在生命周期事件上触发；技能加载到上下文中供 Claude 应用。

方面	钩子	技能
运行	Shell 命令、HTTP 请求、LLM 提示词或子代理	Claude 读取并遵循的指令
触发方式	生命周期事件如 `PostToolUse` 或 `SessionStart`	你输入 `/<name>`，或 Claude 将描述匹配到你的任务
确定性	总是在其事件上触发；触发是保证的	Claude 解释指令；结果可能变化
上下文成本	除非钩子返回输出，否则为零	描述每次会话加载；使用时加载完整内容
最适合	编辑后 lint、阻止不安全命令、日志记录、通知	需要推理的工作流、参考材料、多步骤任务

使用钩子当操作必须每次都以相同方式发生且不需要 Claude 思考时。例如：保存时格式化、拒绝 rm -rf /、会话结束时发送 Slack 消息。

使用技能当 Claude 应该决定如何应用步骤，或者内容是知识而非脚本时。例如：/release 检查清单、你的 API 风格指南、调试剧本。

在钩子中设置护栏。 CLAUDE.md 或技能中的"绝不编辑 .env"指令是一个请求，不是保证。阻止编辑的 PreToolUse 钩子是强制执行。如果规则必须每次都成立，将其做成钩子而不是提示词指令。

钩子输出进入上下文。 运行 linter 的 PostToolUse 钩子将结果作为文本反馈给 Claude 阅读；/fix-lint 技能告诉 Claude 如何解决它们。

理解功能如何分层

功能可以在多个级别定义：用户级、项目级、通过插件或通过托管策略。你也可以在子目录中嵌套 CLAUDE.md 文件或在 monorepo 的特定包中放置技能。当同一功能存在于多个级别时，以下是如何分层：

CLAUDE.md 文件是累加的：所有级别同时向 Claude 的上下文贡献内容。工作目录及以上的文件在启动时加载；子目录在你工作时加载。当指令冲突时，Claude 使用判断来调和它们，更具体的指令通常优先。详见 CLAUDE.md 文件如何加载。
技能和子代理按名称覆盖：当同一名称存在于多个级别时，一个定义根据优先级胜出（技能：托管 > 用户 > 项目；子代理：托管 > CLI 标志 > 项目 > 用户 > 插件）。插件技能有命名空间以避免冲突。详见技能发现和子代理范围。
MCP 服务器按名称覆盖：本地 > 项目 > 用户。详见 MCP 范围。
钩子合并：所有注册的钩子都在匹配事件上触发，无论来源。详见钩子。

组合功能

每个扩展解决不同的问题：CLAUDE.md 处理始终在线的上下文，技能处理按需知识和工作流，MCP 处理外部连接，子代理处理隔离，钩子处理自动化。实际设置根据你的工作流组合它们。

例如，你可能使用 CLAUDE.md 设置项目规范，使用技能设置部署工作流，使用 MCP 连接数据库，使用钩子在每次编辑后运行 lint。每个功能处理它最擅长的事情。

模式	工作方式	示例
技能 + MCP	MCP 提供连接；技能教 Claude 如何很好地使用它	MCP 连接到你的数据库，技能记录你的架构和查询模式
技能 + 子代理	技能启动子代理进行并行工作	`/audit` 技能启动在隔离上下文中工作的安全、性能和风格子代理
CLAUDE.md + 技能	CLAUDE.md 持有始终在线的规则；技能持有按需加载的参考材料	CLAUDE.md 说"遵循我们的 API 规范"，技能包含完整的 API 风格指南
钩子 + MCP	钩子通过 MCP 触发外部操作	编辑后钩子在 Claude 修改关键文件时发送 Slack 通知

理解上下文成本

你添加的每个功能都会消耗 Claude 的一些上下文。太多会填满你的上下文窗口，但也可能增加噪音使 Claude 效率降低；技能可能无法正确触发，或者 Claude 可能失去对你规范的跟踪。理解这些权衡有助于你构建有效的设置。有关这些功能在运行会话中如何组合的交互式视图，请参阅探索上下文窗口。

按功能的上下文成本

每个功能有不同的加载策略和上下文成本：

功能	加载时机	加载内容	上下文成本
CLAUDE.md	会话开始	完整内容	每次请求
技能	会话开始 + 使用时	开始时加载描述，使用时加载完整内容	低（每次请求加载描述）*
MCP 服务器	会话开始	工具名称；按需加载完整 schema	低，直到使用工具
代码智能	文件编辑后和按需	编辑后加载诊断；查找时加载符号位置	低；减少其他地方的文件读取
子代理	启动时	包含指定技能的新鲜上下文	与主会话隔离
钩子	触发时	无（外部运行）	零，除非钩子返回额外上下文

*默认情况下，技能描述在会话开始时加载，以便 Claude 决定何时使用它们。在技能的前置数据中设置 disable-model-invocation: true 可以完全对 Claude 隐藏它，直到你手动调用它。这将你自己触发的技能的上下文成本降为零。对于你没有编写的技能，在设置中设置 skillOverrides 可以在不编辑其文件的情况下实现相同效果。

理解功能如何加载

每个功能在会话的不同时间点加载。以下标签页解释每个功能何时加载以及什么进入上下文。

上下文加载：CLAUDE.md 在会话开始时加载并保留在每次请求中。MCP 工具名称在开始时加载，完整 schema 延迟到使用时。技能在开始时加载描述，调用时加载完整内容。子代理获得隔离上下文。钩子外部运行。

何时： 会话开始

加载什么： 所有 CLAUDE.md 文件的完整内容（托管、用户和项目级别）。

继承： Claude 从你的工作目录向上读取 CLAUDE.md 文件到根目录，并在访问子目录中的文件时发现嵌套的文件。详见 CLAUDE.md 文件如何加载。

Tip

保持 CLAUDE.md 在 200 行以内。将参考材料移到技能中，按需加载。

技能是 Claude 工具包中的额外能力。它们可以是参考材料（如 API 风格指南）或你用 /<name> 触发的可调用工作流（如 /deploy）。Claude Code 包含内置技能如 /code-review、/batch 和 /debug，开箱即用。你也可以创建自己的技能。Claude 在适当时使用技能，或者你可以直接调用一个。

何时： 取决于技能的配置。默认情况下，描述在会话开始时加载，使用时加载完整内容。对于仅用户技能（disable-model-invocation: true），在你调用之前不加载任何内容。

加载什么： 对于模型可调用的技能，Claude 在每次请求中看到名称和描述。当你用 /<name> 调用技能或 Claude 自动加载它时，完整内容加载到你的对话中。

Claude 如何选择技能： Claude 将你的任务与技能描述匹配来决定哪些相关。如果描述模糊或重叠，Claude 可能加载错误的技能或错过有帮助的技能。要告诉 Claude 使用特定技能，用 /<name> 调用它。disable-model-invocation: true 的技能在你调用之前对 Claude 不可见。

上下文成本： 使用前低。仅用户技能在调用前为零成本。

在子代理中： 技能在子代理中的工作方式不同。不是按需加载，子代理 skills 字段中列出的技能在启动时完全预加载到其上下文中。子代理仍然可以通过技能工具发现和调用未列出的项目、用户和插件技能。

Tip

对有副作用的技能使用 disable-model-invocation: true。这节省上下文并确保只有你触发它们。

何时： 会话开始

加载什么： 已连接服务器的工具名称。完整的 JSON schema 保持延迟，直到 Claude 需要特定工具。

上下文成本： 工具搜索默认开启，因此空闲的 MCP 工具消耗最少的上下文。

Tip

运行 /mcp 查看连接状态和每个服务器的 token 成本。Claude Code 在远程服务器断开时自动重新连接，你可以断开不活跃使用的服务器。

何时： 文件编辑后，以及 Claude 导航代码时按需。

加载什么： 每次文件编辑后的类型错误和警告。Claude 查找符号时的定义、引用和类型信息。

上下文成本： 低。符号查找通常替代广泛的文件读取，因此净上下文使用可能下降。