Claude Code Subagent 失效？先改 description 字段

问题：你的 Subagent 形同虚设

你写了一个 .claude/agents/ 文件，但 Claude Code 从不把任务委托给它。文档听起来很简单——扔一个带 YAML frontmatter 的 Markdown 文件进去就完事了。然而大多数"我的 subagent 不起作用"的抱怨，追溯起来都指向三个容易一眼扫过的细节：description 字段是路由器、名称冲突会静默丢弃文件、以及一个劣质的 tools 条目会导致整个 agent 无法启动。

以下是完整的系统说明，已对照当前文档验证过，几分钟内就能修好你的配置。

30 秒版本

一个 subagent 就是一个带 YAML frontmatter 的 Markdown 文件：

---
name: code-improver
description: "Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code."
tools: Read, Grep, Glob
model: sonnet
---

You are a code review specialist. When given files, analyze them for
readability, performance, and adherence to best practices. Report
concrete, minimal suggestions with file:line references.

把它放在哪里决定了谁会用到它：

.claude/agents/ 在你的项目中 → 仅限此项目（通常会提交，所以团队共享）

~/.claude/agents/ → 你机器上的所有项目

两个位置都会递归扫描，所以你可以把文件组织成子文件夹，比如 agents/review/。子文件夹路径不会影响 agent 的识别方式——身份只来自 name 字段，与文件名或路径无关。只有 name 和 description 是必填的，其他都是可选的。

委托本质就是 Description 匹配

Claude 会读取每个 subagent 的 description，然后当任务与之匹配时决定委托。整个路由机制就是这样。没有注册步骤、没有配置开关——description 的质量就是触发条件。

这意味着最常见的失败是，把 description 写成了标题：

# 永远不会被用到
description: Database expert

# 会被用到
description: Reviews SQL queries and schema changes for slow patterns,
  missing indexes, and migration risks. Use when SQL or migration files change.

第二个有效是因为它描述的是何时委托，而不只是 agent 是什么。如果你希望无需询问就自动委托，就在 description 里说出来——"use proactively after code changes" 这样的措辞正是官方示例的做法。

你随时可以绕过路由显式调用："Use the code-improver subagent on the files I just changed."

真正重要的字段

完整的 frontmatter 列表很长，但这些才是你会经常用到的：

tools 有两个坑：条目必须解析为真实的工具名称——如果一个都解析不了，subagent 就会启动失败并报错，指出哪些条目有问题。另外，如果你想预加载一个 Skill，使用 skills 字段；在 tools 里写 Skill 只是授予调用工具，不会加载任何东西。

name 有一个坑：小写字母和连字符，不要有冒号——冒号是保留给插件作用域标识符的，比如 my-plugin:reviewer。当前版本会拒绝加载文件名包含冒号的文件，唯一的症状就是调试日志里的一行记录。

优先级：名称冲突时谁胜出

当多个 subagent 同名时，优先级高的位置获胜：托管（组织部署）的定义 > 项目定义 > 用户定义 > 插件 agent。在嵌套的项目目录中，距离工作目录最近的定义获胜。

危险的情况是同一 .claude/agents/ 树下（包括子文件夹）有两个同名文件。Claude Code 只加载其中一个，由文件系统读取顺序决定，没有任何文档化的规则。运行时不会有任何警告；你精心更新的定义可能根本就没在运行。/doctor 会报告同目录重复，所以当一个 subagent 表现得像旧版本时，就跑一下它。

还有一个值得知道的：项目或用户 subagent 如果命名为 Explore，会覆盖内置的只读 Explore agent。这偶尔有用（比如用 model: haiku 把探索固定在更便宜的模型上）——但也偶尔会成为事故，当有人给一个通用 agent 命名为"explore"，就悄悄替换了内置的那个。

关于 /agents 命令

较早的文章会告诉你跑 /agents 来获得交互式创建向导。在当前版本中这个向导已经没了——/agents 现在只是引导你直接编辑 .claude/agents/，或者让 Claude 帮你写文件。文件格式和位置没变，所以任何现有的 agent 文件都能继续用。

当 subagent 没被使用时，按这个顺序排查最快

文件能加载吗？name 有冒号，或 YAML 格式错误 → 被静默跳过。检查调试日志。

你的定义是在运行的那个吗？树中任何地方有重复名称 → 跑 /doctor。

你的 description 说了什么时候用它吗？把它重写成触发条件，而不是职位头衔。

tools 条目能解析吗？像 Greps 这样的拼写错误会导致启动失败并报零工具错误。

还是不行？显式按名称调用一次。如果显式调用能用但自动委托不行，那问题永远出在 description 上。

Originally published on gentic.news