Claude Code 子智能体是什么，怎样创建一个？

子智能体启动时知道什么，最后交回什么

你问 Claude 一个牵涉整个代码库的问题，它会主动把搜索交给 Explore。Explore 在自己的上下文窗口里读文件，读完把摘要放进你的对话。它打开过的文件、跑过的命令，都不会进来。

子智能体看不到你们之前的对话，也看不到你调用过的技能和 Claude 已经读过的文件。它的工具和权限单独设定。系统提示词由这个智能体自己的提示词和 Claude Code 附上的环境信息组成，不是 Claude Code 本身的系统提示词（见 Anthropic 的子智能体文档）。

CLAUDE.md 文件倒是会跟着加载，一起带上的还有一份 git status 快照，以及它预载技能的全文。所以 CLAUDE.md 写得越长，每个自定义子智能体启动时重复加载的内容就越多，占用的上下文也越多。内置的 Explore 和 Plan 不加载 CLAUDE.md，也不带 git 快照。

动手做一个：示例智能体文件

整个定义就是一个文件。顶部的 YAML 写名称、描述，以及工具、模型这类限制，下面的 Markdown 正文就是子智能体的系统提示词。必填的只有 name 和 description。其余可选字段，从 maxTurns、skills 到 memory、isolation，字段说明里都列了。

下面的示例是我们为这篇文章写的，用来检查 docs 文件夹里的链接，正是 Anthropic 建议交给 Haiku 的那种简单任务。它的 tools 一行只列了 Read、Grep 和 Glob，改文件这件事由 Claude Code 直接挡住。要是只在提示词里写一句“不要修改任何文件”，那只是请求，不算限制。

---
name: docs-link-checker
description: Checks relative links and anchors in Markdown files under docs/ and reports broken ones. Use proactively after editing files in docs/.
tools: Read, Grep, Glob
model: haiku
---

You check links in the Markdown files you are given, or in docs/ if none are named.

1. Find every relative link and every #anchor.
2. Confirm each target file exists and each anchor matches a heading in it.
3. Skip links that start with http:// or https://.

Reply with one line per broken link: file, line, target and the reason.
If every link resolves, reply "All links resolve" and nothing else.

• name 是 Claude 和钩子看到的标识，不能有冒号，也不必和文件名一致。
• tools 是允许清单。不写这一项，子智能体会继承子智能体能用的全部工具。
• model 可以填 sonnet、opus、haiku、fable、完整的模型 ID，也可以填 inherit，表示沿用主对话的模型。

1. 团队共用的智能体，放进项目里的 .claude/agents/ 文件夹。想在所有项目里都能用，就放进 ~/.claude/agents/。
2. 把示例存进去，文件名叫 docs-link-checker.md。
3. 点名使用，比如说“对 docs/ 使用 docs-link-checker 子智能体”。

智能体文件放在哪里，出了问题先查什么

输入 /agents 只看到一行提醒，没有弹出菜单，这不是出了故障。在当前版本里，这个命令只会提醒你去找 Claude，或者直接编辑 .claude/agents/ 和 ~/.claude/agents/。原来那个交互向导，只存在于 v2.1.197 及更早的版本。

让 Claude 来写，也是文档快速上手里走的路。说清楚要什么样的智能体、存在哪里，比如放在 ~/.claude/agents/、只读、用 Sonnet 的代码改进助手。写好之后打开文件，看文件头和你的要求是否一致，包括模型选得对不对。

Claude Code 会从五个地方读取智能体文件，两个定义重名时，优先级高的位置胜出。同一个 .claude/agents/ 文件夹及其子文件夹里，就没有这种排序了：两个文件声明了同一个名字，Claude Code 只加载其中一个，挑哪个取决于文件系统返回的顺序。名字别重复。

字段拼错了，不会有任何提示。字段名用驼峰写法，Claude Code 碰到不认识的字段会直接忽略，也不报错。maxTurns 或 permissionMode 好像不起作用时，先查拼写。

插件能把智能体连同技能、钩子和 MCP 服务器一起带到别的团队，但插件里的智能体还有一处要注意。出于安全考虑，它们会忽略 hooks、mcpServers 和 permissionMode 三个字段，写在这几项里的设置不会生效。

2025 年那条发布帖在 X 官方嵌入卡片里的截图，拍摄于 2026 年 11 月 3 日，时间为美国太平洋时间，没有收入帖子里的视频。点击截图可到 X 上打开原帖。

Claude 怎样挑子智能体，你又怎样自己挑

Claude 决定交给哪个子智能体时会看几样东西，其中只有 description 是你事先写好的。像示例那样，在描述末尾写上“Use proactively”和适用场景，Claude 就更可能主动用它。

描述还是要写短。所有子智能体的描述加起来超过 15,000 个 token，Claude Code 启动时就会警告，不过照样全部加载。

• 直接说：“用 test-runner 子智能体修复失败的测试”。Claude 通常会照办，但用不用还是由它决定。
• 输入 @，从联想列表里选中它，跟引用文件一样。这样运行的一定是你选的那个，不过整条消息仍然交给 Claude，任务提示词也由 Claude 来写。
• 用 claude --agent code-reviewer 启动会话，主线程就变成这个智能体，套用它的工具限制和模型。在 .claude/settings.json 里设置 agent，就能把它设成项目的默认值。

用子智能体还是技能，子智能体什么时候值得用

技能会加载进你当前的对话，占用这段对话的上下文。技能是可以反复使用的内容，比如操作说明或参考资料。

子智能体的 skills 字段会预先载入所列技能的全文，设了 context: fork 的技能则会放到子智能体里运行。

互不依赖、可以同时进行的几件事，适合交给子智能体。整轮测试这类很长的输出也一样，交出去就不会堆进你的对话。代码评审是另一种用法：没写这段代码的智能体，不会带着你们对话里的那些预设去看它。

每个子智能体都单独发请求，和主对话共用同一份用量上限，所以主要开销是 token。新的子智能体还得重新收集主对话已经有的背景，比如把读过的文件再读一遍，所以可能比直接在主对话里做更慢。答案也不会更好：默认情况下，它就是同一个模型，或者更小的模型，在做同一件事。

要是你每次改完文档都派一个子智能体去查链接，交代的话也都一样，就把它存成示例那样的智能体文件。

参考：智能体文件从哪里加载，以及默认上限

这里的每个事实都来自下方来源里列出的 Anthropic 页面，阅读日期为 2026 年 11 月 2 日和 3 日。本文是对官方文档的解读，不是实际测试，Claude Code 的字段、默认值和命令也会随版本变化。

常见问题

资料来源

1. Claude Code 文档：创建自定义子智能体 (2026年11月3日 查阅)https://code.claude.com/docs/en/sub-agents
2. Claude Code 文档：最佳实践 (2026年11月2日 查阅)https://code.claude.com/docs/en/best-practices
3. Claude Code 文档：扩展 Claude Code (2026年11月2日 查阅)https://code.claude.com/docs/en/features-overview
4. Claude Code 文档：用技能扩展 Claude (2026年11月2日 查阅)https://code.claude.com/docs/en/skills
5. Claude Code 文档：Claude 如何记住你的项目 (2026年11月2日 查阅)https://code.claude.com/docs/en/memory