写了半年 SKILL.md，我踩遍了这 6 个坑

一、写了半年才发现的问题

我之前写了一篇《从堆规则到删规则》，讲的是我怎么把 swarm-content-factory 从 831 行删到 636 行。那篇文章的核心方法是"删除测试"——删掉一句话，看 Agent 输出有没有变化，没变化就不留。

方法有用，但我一直觉得缺了点什么。

后来看到有人用 Matt Pocock 的 writing-great-skills（来自他那个 170k⭐ 的 skills 仓库）给自己的一套技能做了全面体检，当场找出 6 个问题。我对着自己的 SKILL.md 逐条对照了一遍，6 个一个没落下。

今天把这 6 个坑和修法整理出来。

二、坑一：过早收工

表现

完成标准写得太松。看一段常见的写法：

抽查几条字幕，没问题就进入下一步。

"抽查几条"是几条？"没问题"怎么定义？Agent 完全可以扫一眼就宣布"没问题"，然后溜到下一步去了。

为什么是坑

Agent 天然倾向于"完成任务"，而不是"做对任务"。完成标准越模糊，它越容易提前收工。不是它想偷懒，是它没收到明确的"做到什么程度才算做完"的信号。

修法

把模糊的完成标准换成可勾选的验收条件。

❌ 抽查几条没问题
✅ 首尾各 3 条字幕时间戳和音频对齐，没有空档（验收脚本验证通过）

验收脚本是关键。一个脚本，一个明确的结果，Agent 想赖都赖不掉。

对照你的系统：content-reviewer 的 verdict 有 approved_with_notes 这个状态，但"带着 notes 通过"本身就是一个模糊边界。可以考虑加一条：notes 归零才算完成。

三、坑二：重复

表现

同一条规则在文件里出现多次。我查自己的一份 SKILL.md 时发现：同一个约束条件，在描述里写过一次，在开头的铁律里又写一次，在分工表里写一次，在正文步骤里写一次，在避坑清单里写一次，在验收清单里再来一次。

一共 6 次。

为什么是坑

重复有三个问题：

1. 维护负担——以后想改这个规则，要改 6 个地方。漏改一个就自相矛盾。
2. Token 浪费——每次加载多背 5 倍的无关上下文。
3. 权重失真——同一条规则出现 6 次，它在 Agent 眼中的"重要性"会被放大。

修法

一条规则只在一个权威位置写清楚。别的地方要引用就写"参见 XXX"，不要复述。

四、坑三：沉积

表现

旧办法换掉了，但相关说法没清理干净。一个文件里前面还写着"含4K超采样"，翻到后面却有一句更正"这其实是原声渲染加放大，不是真的超采样"。同一个文件自己跟自己打架。

为什么是坑

沉积比重复更隐蔽。重复至少是一致的，沉积是事实矛盾。Agent 读到自相矛盾的指令，不知道信谁的，最后可能随机选一个。

修法

旧办法一旦换掉，全局搜索这个名字、相关术语、所有引用，全部更新。不要只改正文，不改注释。

我第一次做 delete testing 时删了不少沉积内容——把一段标注"已归档"的架构参考从主文件挪走，把内嵌的配置表格替换成 cat 指令。沉积清理干净后，Agent 的行为反而更一致了。

五、坑四：膨胀

表现

SKILL.md 太长，哪怕每一行都有用，光是长度就已经阻断了可读性。我的文件在删减前是 831 行，避坑清单本身就堆了 17 条，每条还是一整段。它早就不像一张技能卡，更像一本参考手册。

为什么是坑

Agent 每次加载都得从这一大坨里翻。而且上下文 token 是有限的，长文件占了大量空间，留给实际输入的空间就少了。

修法

渐进披露——正文只留主流程加最核心的规则，详尽的细节移到单独的文件里，Agent 需要时才去读。

对照我的实践：把 Pipeline Architecture 的 50 行拆到 references/ 下，把内嵌的配置表格替换为 cat 指令，把伪代码速查也拆出去。831 行变成 636 行，瘦了四分之一。

六、坑五：空转

表现

写了一句话，Agent 本来就会照做，加了等于没加。比如一个分析步骤的标题写着"第一步：数据采集与核实"。后面跟了一句"这是核心步骤，要认真做"。

Agent 看到"第一步"就知道要做数据采集，后面那句"要认真做"不改变任何行为。

为什么是坑

空转不产生价值，但占用上下文。一条两条不明显，多了就累积成实质浪费。最麻烦的是它很难自我检测——每一条看起来都像是有用的提醒。

修法

Pocock 给的验证方法很直接：删掉一段，看 Agent 输出有没有变化。没变化，就别留。

这就是我之前说的"删除测试"。删了跑一次，输出不变就说明这段在沉默地消耗上下文。

七、坑六：否定式

表现

在 SKILL.md 里写"不要用紫蓝渐变""不要用毛玻璃""不要科技感线条"——结果 Agent 反而更关注这些元素。

为什么是坑

否定式陷阱的根源在语言模型的工作方式上。说"不要用红色"，模型需要先想到红色，理解"红色是被禁止的"，然后在生成时绕过它。但这个"想到"的过程就已经把红色的特征激活了，有时反而更容易出现。

修法

用正面描述替代"不要"。

❌ 不要用紫蓝渐变，不要毛玻璃，不要科技感线条
✅ 使用暖色系，主色调为白色/暖灰/橙色点缀，材质纸感平面，无发光效果

八、好了，现在照着查一遍

我用上面这 6 条重新查了自己最常用的几份 SKILL.md，发现了不少之前漏掉的问题。下面是我整理的自检清单，你可以直接拿来对照你自己的文件：

6 条过一遍，不超过 30 分钟。效果大概率比加十条新规则好。