近段时间，不少使用 Codex、Claude Code 或在团队中编写 AGENTS.md 的开发者，都遇到了一个共同难题：给 Agent 设定的规则越来越多，实际表现却未必同步提升。
起初，大家可能觉得解决方案很简单。模型没按预期执行，就补充一条规则；写作风格不够自然，就增加一段风格指南；代码修改出现偏差，就再塞入一份流程说明。几轮调整下来，Skill 文件越来越冗长，Agent 仍然可能漏读、误读关键指令，团队也难以判断哪些规则真正有效。
这场 AI Engineer 演讲的核心正是这个议题。演讲者 Matt Pocock 维护着一个广受欢迎的工程 Skill 仓库，他将这种混乱局面称为 Skill Hell。听起来像玩笑，但在工程团队中却非常现实：当你打算让 Agent 负责代码审查、撰写 PRD、排查问题、项目复盘等任务时，首先得学会编写一份 Agent 能真正执行的团队规程。否则，Skill 不过是用新名词包装的提示词堆叠。
别再单纯往 Skill 里叠加规则
Pocock 指出，开发者很擅长为自己制造新的困境。过去有 tutorial hell（教程地狱）：看了一大堆教程，仍拼不出完整的项目。随后有 framework hell（框架地狱）：框架迭代太快，开发者持续追赶新版本。现在轮到 skill hell（技能地狱）。
Skill Hell 不像错误日志那样直观显现。它通常看起来光鲜：GitHub 上遍布免费的 Skill，看似都能下载、改造、复用。问题藏在背后——你无法判断哪些 Skill 设计精良，也不清楚哪些文字仅仅是摆设。
放到日常工作中，典型场景是：你把“需求如何编写、代码如何排查、测试如何执行”写入 Skill，以为 Agent 会自动学会团队习惯。结果它有时照做，有时跳过，有时读完后毫无改变。Pocock 提出的审稿顺序很直接：先看触发方式，再看结构，然后检查文本是否改变了 Agent 的行为，最后删除无效内容。
安装一个 Skill 很快，但重新审视整套团队规程更慢，也更接近问题本质。团队规程原本为人设计，人会跳过废话，用经验填补空白。Agent 不会。它只能读取你写下的内容，也会被你写下的废话拖慢。
所以 Skill 写作不像写说明文，更像给一位勤快但刻板的新同事写交接指南。写得少，它不知道边界；写得多，它把边缘任务也当成核心。Skill Hell 便由此开始。一次失败往往不全是模型能力问题，团队也可能把交接写成了备忘录。
先决定由谁触发调用
一份 Skill 写好后，有两种入口方式。一种是用户手动调用。文件存放在本地，你明确告知 Agent：现在去读取这份 Skill。另一种是模型自动调用。Skill 的描述平时就放在 Agent 的上下文窗口中，模型接收到任务后自行判断是否打开。
许多人倾向于第二种方式。少了一步操作，看起来更智能。但 Pocock 提醒，自动触发并非免费午餐。每多一个模型可触发的 Skill，Agent 每次请求就要多背负一条描述，也多了一个选择负担。Skill 数量少时没感觉，当积累到几十上百个，模型就会被大量入口拖慢。
因此团队应先区分两类 Skill：高频、低风险、边界清晰的，可以让模型自行发现；低频、影响大、需要人工判断时机的，最好由用户手动触发。例如“生成提交说明”可以自动化，但“重写客户需求文档”就不该悄悄进行；“线上事故复盘”也不应在上下文不完整时自动启动。
很多团队会跳过入口设计，因为大家急于撰写正文。但入口选错，后面写得再细致也会别扭：要么 Agent 背负大量无关描述，要么用户记不清什么时候该用哪份 Skill。
Pocock 自己更偏向用户触发。他承认这样会让使用者多记一些东西，但换来的是更少的不确定性。模型自动触发看似省事，背后还需做另一件麻烦事：验证它是否在应该调用时真的调用。
公司内部的 Skill 更需要这个判断。一个客户交付流程、一次线上事故复盘、一次安全审查，触发错误会带来额外成本。与其把所有内容塞进模型视野，不如先让人决定何时打开哪扇门。这个选择看似微小，后续会影响每一次请求的上下文重量。
Skill.md 不应写成团队杂物柜
Pocock 拆解 Skill 的方式很朴素：一份 Skill 通常只包含两类内容。步骤，告诉 Agent 接下来如何行动；参考材料，帮助 Agent 在某个步骤中查阅信息。
他举了一个编写 PRD 的例子。该 Skill 需要将当前上下文整理成产品需求文档，所以步骤可以设定为：先找相关材料，再与用户确认 test seam，最后撰写 PRD。参考材料则是 test seam 的定义、PRD 模板。一类负责执行动作，另一类负责查阅信息。
团队最容易犯的错误，就是把这两类内容混在一起。今天有人加一段模板，明天有人补一段术语解释，后天又有人把一次项目复盘塞进去。半年后，Skill.md 变成谁都不敢删的公共文档。新人打开它，只能猜测哪几段是命令，哪几段只是背景。
Pocock 的建议是把主文件写得简短。主文件只保留公共入口：什么场景下使用、按什么顺序执行、遇到分支时去哪里取材料。模板、样例、ADR、glossary 都可以放到旁边文件。Agent 需要时再读取，人类 review 时也能一眼看出哪句话在控制行为。文件短，团队才敢改；团队敢改，Skill 才不会沉积。
他还举了另一个例子——domain modeling。这个 Skill 可能需要更新 glossary 或创建 ADR。ADR 模板只在其中一个分支中使用，就没必要塞进主文件。主文件里留一句“需要 ADR 模板时去读这个文件”就足够了。
如果你已有自己的 Skill.md，可以立刻做个检查：如果某段内容只在一种情况下使用，就应该挪出去；如果某段内容每次都会用到，才留在主文件中。这个动作很小，却能让 Skill 从“长篇文档”变回“可执行入口”。
一个短词，有时比一整段规则更有效
很多 Skill 读起来都很认真：“不要一次性实现完整功能”“请先做小范围验证”“尽量早点获取反馈”。这些话没有错，但 Agent 常常读完仍按旧习惯执行。
Pocock 给出的方法，是寻找 leading words，即能统领整套做法的短词。他举的例子是 vertical slice。Agent 处理大型需求时，往往会先写数据库层，再写 schema，再写 API，最后写前端，横向铺开。而 vertical slice 这个词会将其拉回另一种工程习惯：先做一个能跑通的小切片，早点验证，再向外扩展。
Pocock 提供了一个很实用的验证方式：你能从 Agent 的输出中看出它是否学进去了。当它开始说“先做一个薄的 vertical slice”，计划通常也会随之改变。团队写 Skill 时，与其堆叠十句近义提醒，不如先钉住几个能改变动作的关键词。比如“vertical slice”“deletion test”“read first”这类词，简短，但能让行为回归正轨。之后检查执行计划时，也能顺手确认这些词是否出现。
注意，短词要保持稳定。今天叫 vertical slice，明天又叫 thin slice，后天改成 minimum path，模型读到的是一串近义词，行为反而会不稳定。好的 Skill 应该像团队黑话一样，少数几个词反复出现，人和 Agent 都清楚它们指向什么。
让 Agent 一次只专注做好一件事
Pocock 还讲了一个常见的陷阱：Agent 在前置步骤上偷懒。最典型的是 plan mode。它通常要求 Agent 先提出澄清问题，再生成计划。结果你会发现，它匆匆问两句就急着交计划。
为什么？因为它已经看到了终点。只要最终目标写着“生成计划”，追问就容易被视为前奏，而不是任务本身。
他的做法是拆开来。先用一个专门的 Skill 负责追问和读取材料，比如 Grill with Docs：先把文档、仓库、历史 issue 和用户口述都问透，再交给下一份 Skill 写 PRD。这个阶段结束后，再进入写 PRD 的 Skill。Agent 当前只看到一件事，执行力就会更强。
放到团队工作中，这条原则很实用。代码库探索、需求追问、失败复盘、资料核对，都很容易被最终交付物挤压。要让 Agent 做扎实，就别把所有未来步骤一次性摊在它面前。先让它把当前阶段做厚，再把下一阶段交给它。Pocock 的 plan mode 例子，本质上就是把“问清楚”和“写计划”拆开。下次写 Skill 时，可以先问一句：哪一步最容易被 Agent 敷衍过去？那一步就值得单独拿出来。
拆开流程，是为了保护那些容易被压缩的工作。人类同事也一样。如果你一边让他调研，一边告诉他最后要交三页方案，他很可能会按方案倒推材料。Agent 更会这样。它会朝着最终交付物跑，除非你暂时把终点藏起来。
删掉那些不会改变结果的句子
最后是删减。Pocock 提到了几类坏味道：重复、沉积物、no-op。
重复很好理解。同一个模板、同一条约束、同一个术语解释，散落在好几个地方，后续一定会改漏。沉积物更麻烦。团队维护 markdown 时，每个人都往里加一点，却没人敢删除别人的旧话，Skill 就会慢慢积灰。那些被反复复制的旧说明，最容易留存。
No-op 最值得警惕。比如一个实现 Skill 里写了很长一段“请写详细 commit message”。删掉这段后，Agent 可能仍然会写出像样的提交说明。那这段文字就没有改变行为，只是在占用空间。
Pocock 的删除测试很简单：删掉一段，再看 Agent 的输出有没有变化。没变化，就别留。人读文档时会自动跳过废话，Agent 不会。它会把每一句都当成可能有用的上下文，哪怕那句话只是过去某次讨论留下的礼貌性提醒。
删除测试还能帮助团队减少争论。很多文档里的句子不是错，只是没用。说它错，作者会防御；说“删掉后 Agent 行为不变”，讨论就回到结果上。Skill 越短，留下的每句话就越有责任。保留下来的句子，应该能让 Agent 多执行一步、少犯一个错，或者少读一段无关材料。
Pocock 最后的扫尾清单其实很硬：重复的，合并；放错分支的，挪走；过期的，删掉；看起来像要求、实际不改变行为的，移除。Skill 不是越厚越专业，能让 Agent 稳定做对事才算数。
写在最后
如果团队已经开始为 Agent 编写 Skill，先别急着多装十份。拿出最常用的一份，看三件事：入口是否清晰，主文件是否能在十分钟内读完，删掉一段后 Agent 的结果是否改变。能把这一份改干净，后面的 Skill 才有可能越写越轻。先让一份 Skill 变好，比收集一堆 Skill 更可靠。