Subagent 与 Skill 怎么分工

它替你干掉什么：把「读了四十个文件」从主对话里搬走

官方契约：一个 markdown 文件，两个必填字段

subagent 就是 .claude/agents/（项目）或 ~/.claude/agents/（全局）下的一个 .md 文件，两个目录都递归扫描。必填只有 name 和 description，正文是它的 system prompt。官方文档的可选字段里这几个值得记住：

# .claude/agents/api-developer.md
---
name: api-developer
description: Implement API endpoints following team conventions
tools: Read, Grep, Edit, Write, Bash   # 不写 = 继承全部；漏掉的工具压根不在它会话里
model: sonnet                          # sonnet/opus/haiku/fable/inherit
skills: [api-conventions, error-handling-patterns]  # ★ 启动时预载 skill
memory: project                        # user/project/local 持久记忆
isolation: worktree                    # ★ 给它一个独立 git worktree
omitClaudeMd: true                     # 不加载 CLAUDE.md（省 token）
maxTurns: 10                           # 到顶的输出被标记为 partial，可 resume
---
You are an API development specialist...

skills: 这一行就把「二选一」的伪命题打掉了：subagent 可以带着 skill 跑。反过来也成立——skill 的 frontmatter 里写 context: fork 就在隔离上下文里执行，agent: 还能指定用哪个 subagent 类型（见 官方 skills 文档）。

第一条立刻能跑的用法：不用装任何东西

Claude Code 自带三个内置 subagent，装机量为零、现在就能用：

# ① Explore —— 只读工具（Write/Edit 被拒），三档 thoroughness
Use the Explore subagent, very thorough, to map every place we validate JWTs

# ② Plan —— plan mode 下做调研的那个，同样只读
# ③ general-purpose —— subagent 能拿到的全部工具，可改代码

# 自己写完一个 agent 文件后，开会话前先验一遍 frontmatter
claude plugin validate .claude/agents

# 不写文件也能起：一次性 JSON 定义
claude --agents '{"code-reviewer":{"description":"Expert code reviewer.",
  "prompt":"You are a senior code reviewer.","tools":["Read","Grep","Glob"],"model":"sonnet"}}'

# 让整个会话直接以某个 agent 的身份跑
claude --agent code-reviewer

Explore 替你干掉的事很具体：四十次 grep 的输出不进你的对话。什么时候别用：答案本来就一行（「这函数在哪个文件」），派它去问要等冷启动加一轮往返，省下的 context 不值这个钱。

机制：一张继承表，解释了九成的「它怎么什么都不知道」

唯一那根管子的实际后果

SDK 文档写得很直白：The only content you pass from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt. 这就是「我明明刚跟它说过」的全部原因——你跟主对话说过，没跟它说过。

第三态：fork，别把它和 subagent 混着算

交互会话里的 /subtask <描述> 起的是一个 fork：独立 context window，但全量继承父对话的历史、system prompt、输出风格、模型，以及原样工具池（跳过后台 subagent 那道过滤）。fork 是「要隔离但不能失忆」那格的答案。代价：它继承了父对话的全部 token，省下的只有后续噪音。

为什么 skill 走的是另一条路

skill 的机制是指令注入：description 常驻（便宜），正文只在被调用时展开，展开后留在对话里跨 turn 生效。所以 skill 适合「接下来每一步都要守的规矩」，subagent 适合「这一段我不想看」。disable-model-invocation: true 让 skill 只能你手动喊，user-invocable: false 让它只能模型自动触发——两个字段合起来才是 skill 真正的调用契约。

真实用法与边界：五个可装可读的条目，逐个给命令

① obra/superpowers · subagent-driven-development

# 官方 marketplace 一条命令
/plugin install superpowers@claude-plugins-official

这个 skill 的 description 只有一句：Use when executing implementation plans with independent tasks in the current session。它的做法是：先开独立 git worktree、核计划、扫冲突、建一份 ledger 记进度；然后每个任务一轮「派实现者 → 收报告 → 针对性 review → 修，最多 5 轮」，第 1–3 轮 resume 原来那个实现者，第 4–5 轮换更强的模型；最后在最强模型上做一次整支分支的总 review。替你干掉的是：一条长计划做到第七个任务时，前六个任务的噪音已经把上下文挤满了。什么时候别装：它自己写了三条——没有实现计划、任务之间紧耦合而非独立、你的平台压根没有 subagent（那就内联执行）。

② 同仓 · dispatching-parallel-agents

它的触发条件写成 2+ independent tasks that can be worked on without shared state or sequential dependencies，而正文的门槛更高：3 个以上不同根因才值得并行。最该记住的是那句机制原话——Multiple dispatch calls in one response = parallel execution. One per response = sequential. 并行不是一个开关，是你在一条回复里发了几个调用。什么时候别用：失败之间相关（修一个可能连带修好别的）、需要全局上下文才能理解、几个 agent 会互相改同一批文件、根因未知的探索式调试。它还有一句值得贴墙上的：Do NOT just increase timeouts—find the real issue.

③ isolation: worktree：并行写文件的唯一正经办法

上面两个 skill 都从开 worktree 起手，不是巧合：多个 subagent 同时改同一棵工作树就是在互相覆盖。frontmatter 一行 isolation: worktree 就给它一棵独立的；superpowers 里还有个专门的 using-git-worktrees skill 管这条链路。什么时候别开：任务只读（Explore 那类），开 worktree 纯加 IO。

④ wshobson/agents：现成 agent 库

/plugin marketplace add wshobson/agents
/plugin install python-development

自称 94 plugins, 202 agents, 183 skills, 105 commands（据该仓 README，2026-09 读取；MIT），一份 markdown 源生成多个 harness 的产物。价值在于读别人的 description 怎么写——subagent 能不能被自动派到全看它。什么时候别装：整包装进来就是交 description 税（见 04 节那条 15,000 token 警告），按需只装你真用的那个 plugin。

⑤ Agent SDK：把这套写进代码

SDK 里 subagent 是 query() 的 agents 参数，AgentDefinition 的字段和文件版几乎一一对应（description / prompt 必填，其余 tools / disallowedTools / model / skills / maxTurns / background / effort 可选）。两个坑：Python SDK 里 disallowedTools / mcpServers 保持 camelCase；检测有没有真派出去要同时匹配 "Agent" 和旧名 "Task"。规模再大就不该用 subagent 了——官方指向 dynamic workflows 的 Workflow 工具，把编排搬到对话之外的脚本里。什么时候别上 Workflow：一轮里只派两三个 agent，subagent 直接够用。

三条判据，用来在上面这几条之间取舍

1. 中间过程你还要不要看？要跟着它一步步走 → skill（就在对话里）。只要结论 → subagent。这一条能定八成的局。
2. 它需要你说过的话吗？需要全量历史 → /subtask 起 fork。只需要几个路径和一段报错 → 普通 subagent，把它们写进 prompt 字符串。
3. 真的独立吗？3 个以上不同根因、不共享状态、不改同一批文件 → 并行派。否则串行，或者一个 agent 干完。

代价与替代品：15 倍 token，和一个「越强越爱派」的新问题

最硬的那个数

Anthropic 在 《How we built our multi-agent research system》（2025-06-13）里给了三个数：agent 大约是聊天的 4 倍 token，多 agent 系统大约是聊天的 15 倍；他们的内部研究评测上多 agent 比单体 Claude Opus 4 好 90.2%；而 token 用量本身就解释了浏览能力差异的 80%。同一篇文章明确列了不适用的场景：所有 agent 需要共享同一份上下文的任务、agent 之间依赖很多的领域，以及「大多数编码任务」——原话是编码可并行的部分比研究少。这三个数一起读才对：15 倍换 90.2%，值不值取决于你的任务长得像研究还是像改代码。

Opus 5 之后多出来的一笔

Prompting Claude Opus 5 里写得很清楚：Claude Opus 5 delegates to subagents more readily than prior models. 官方给的对策是两层——一层是 prompt，一层是硬闸：

# ① prompt 层（官方示例，逐字可抄）
Delegate to a subagent only for large tasks that are genuinely independent and
parallelizable, such as a wide multi-file investigation. Do not delegate work you
can finish yourself in a handful of tool calls, and do not use subagents to verify
or double-check your own work. If one subagent can complete the task, use one
rather than several, and keep spawn counts low.

# ② 硬闸层（.claude/settings.json 的 env；默认 深度 3 / 并发 20）
"env": { "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1",
         "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5" }
# SDK 里还有第三道：maxBudgetUsd / max_budget_usd，到顶返回 error_max_budget_usd

同一份文档还有一条反直觉的：Opus 5 会自己验证自己的工作，所以 prompt 里「用一个 subagent 复核」这类老指令要删掉——留着只会过度验证、白烧 token。注意上面这两个环境变量要 Claude Code 2.1.217 以上。

三笔容易漏算的账

• description 也要交税。官方原文：自定义 subagent 的 description 加起来超过 15,000 token，Claude Code 启动时就会警告。细节要挪到正文里去——正文只在它真跑的时候才加载。
• subagent 问不了你。AskUserQuestion 在 subagent 里不可用（EnterPlanMode / ScheduleWakeup / Workflow 也一样）。它卡住了只能自己猜，猜错了你在报告里才看见。后台运行的 subagent 工具池还要再砍一刀。
• 协调本身要人干。superpowers 那条流水线里最贵的不是实现者，是 ledger、冲突扫描、修复轮次上限、最后一次全分支 review。派 agent 一行命令，收 agent 一套制度。

不上 subagent，你还能怎么办

1. 写成 skill。要的是「每一步都守的规矩」而不是「这段我不想看」——skill 更便宜，而且你看得见它在干什么。
2. 用 fork。/subtask 要隔离不要失忆，代价是继承全部历史 token。
3. 钉成 hook。确定性的事别派 agent 去做（Skill 27 专讲）。
4. 上 Workflow。几十上百个 agent 的编排搬进脚本，别塞在对话里。
5. 自己干完。官方那段 delegation 指令的第二句就是这个意思：几次工具调用能做完的事，别派。