当 SKILL.md 同时是文档和 Prompt：一次多 Agent 项目的一致性审计实录

多智能体项目里有个容易被忽略的事实：SKILL.md 这类文件不只是给人看的文档，它会被直接注入成 Agent 的行为指令。这意味着里面任何一处数字、示例、路径不一致，都不只是"文档瑕疵"，而是会在运行时变成真实的行为偏差。

本文记录一次真实审计过程。目标仓库是华为云 AI 办公实践中心的 ai-interview-swarm（WorkSwarm 多智能体面试系统，5 个 Agent 协作完成破冰 → 技术面 → HR 面 → 报告生成）。整个过程没有通读全仓，只用 clone + grep + git log 三件事，就定位到了几个真实存在的不一致。

一、这类项目的特殊性

先看它的信号设计。Leader 靠固定格式解析子 Agent 的返回值：

PROGRESS_REPORT|QUESTION_X|TOTAL_X|SCORE_X|JUSTIFICATION_简短原因

Leader 侧的结束判定是 QUESTION_X == TOTAL_X。这个设计本身没问题，但它建立在一个隐含前提上：TOTAL 这个数字在每个 Agent 手里都是同一个值。

一旦某个 SKILL 示例里写着 TOTAL_5，另一个文档写着"3 道题"，模型照着示例输出的概率远高于照着散文描述输出——因为示例是 few-shot，散文是说明。于是 QUESTION_2 == TOTAL_5 永远不会成立，流程要么提前收尾，要么等一个不存在的题号。

二、三行命令能查出来的东西

1. 验证"共 N 处"这类声明

README 里写着"共 14 处、分布在 5 个 SKILL.md"。这种数字最值得先验，因为改代码的人往往只改一部分。

git clone https://gitcode.com/agent-best-practices/ai-interview-swarm.git
cd ai-interview-swarm
grep -rnF 'D:\' Skills/ | wc -l

结果：14。数字是对的。

但这里有个坑。README 给的自查命令是：

grep -rn "D:\\" Skills/

这条命令在 GNU grep 下会直接报 grep: Trailing backslash，退出码 2，标准输出为空。也就是说——路径还在的时候它也不输出任何东西。如果把它写进"替换后应无输出"的自查项，无论替换做没做，看起来都是"通过"。

正确写法是固定字符串匹配：

grep -rnF 'D:\' Skills/

这不是理论推演。我在未做任何替换的原始仓库上跑这两条命令，前者空输出 exit 2，后者输出 14 行。一个用来做质量门禁的命令，在门禁对象完全没被处理时就已经返回"干净"了。

2. 用 git log 查修复的完整性

这条更容易被忽略。我查了一下最近一次 docs 修复提交：

git log -1 --format=%B 13cae30

提交信息里明确写着：

SKILL 示例内部矛盾修正：TOTAL_12→TOTAL_5、HR 题数示例对齐 README 设计 3 题

看 diff：

git show 13cae30 -- Skills/hr-interview-officer/SKILL.md

实际只改了两行，TOTAL_5 → TOTAL_3，位置在 L56 和 L59。但同一个文件往下翻，还有三处没动：

grep -n "TOTAL_\|all 5 questions" Skills/hr-interview-officer/SKILL.md

56:PROGRESS_REPORT|QUESTION_1|TOTAL_3|SCORE_8|动机清晰有规划          <- 已改
59:PROGRESS_REPORT|QUESTION_1|TOTAL_3|SCORE_8|回答有深度...          <- 已改
207:PROGRESS_REPORT|QUESTION_1|TOTAL_5|SCORE_8|动机清晰有规划         <- 仍是 5
214:PROGRESS_REPORT|QUESTION_2|TOTAL_5|SCORE_9|价值观匹配度高         <- 仍是 5
216:... (continue for all 5 questions)                             <- 仍是 5

这就变成"修了一半"。比不改更麻烦的地方在于：提交信息宣称已对齐，后续维护者会默认这块干净了，不会再查。

还有个细节值得说。L220 那条 HR_SCORING_DATA 示例是 8,9,7,8,6|38|7.6——五个分值，求和 38，均值 7.6，算术完全正确。正因为看起来完全正确，它反而成了更有力的"5 题"证据，直接抵消掉 L56 那两行的修正效果。如果一个示例既自洽又和设计不符，它在阅读时的说服力会强于一条干巴巴的数字声明。

三、几个可复用的检查思路

从这次审计里能提炼出几条通用做法：

先验声明里的数字。 “共 N 处”"分布在 M 个文件"这类表述是最高性价比的检查点。改的人多、验证的人少，而且一条命令就能证伪。

质量门禁命令本身要能证伪。 任何写成"执行后应该无输出"的自查项，都必须在已知有问题的状态下跑一遍，确认它真的会报错。否则它只是个仪式。

git log 优先于读全文。 提交信息里承诺的修复范围，和 diff 里的实际范围，经常不一致。git show <commit> -- <file> 比通读文件快得多，也更能发现"漏改"。

警惕过于自洽的错误示例。 算术正确的示例最难被质疑。核对示例时，除了验算，还要单独核对它和设计稿的口径是否一致。

同一实体在多处出现时，允许占位符。 如果题数未来可能做成可配置，那么示例里就不该硬编码具体数字，而应该统一用 TOTAL_${count} 这类占位符。硬编码的数字越多，未来调整时漏改的面越大。

四、小结

多 Agent 项目的一致性问题，本质上不是文档问题，是接口契约问题。信号协议里的每一个字段、每一个示例值，都在定义一套契约。示例写错，契约就错，运行时行为跟着错，而且错得很安静——不会抛异常，只会让流程在某个题号上永远等下去。

审计这类项目，不需要读完所有代码。clone 下来，验几个数字，看一眼最近的修复提交有没有做全，大部分结构性问题就暴露出来了。

本文基于对 agent-best-practices/ai-interview-swarm 仓库的实际检查（commit 13cae30）。文中所有命令输出均为实际执行结果。