← 学习站 · AI 辅助编程
你的 skill 明明写得很清楚,但 agent 就是不按你说的做。问题不在 agent——在于你还没掌握「引导词」这门手艺。
原文:mp.weixin.qq.com/s/5QGM0X3IiM_qY1qVRWtjPw · Matt Pocock Skills:github.com/mattpocock
PROLOGUE · 你正困在第三种地狱
你有没有经历过这种绝望:下载了一堆 AI coding 工具,装了二十个社区 skill,以为从此开发效率要起飞了。结果发现 agent 要么根本不调用你的 skill,要么调用了也不按里面的流程走,要么产出的东西和 skill 里承诺的效果差了十万八千里。
如果你有过这种感受,恭喜你——你正困在 Skill Hell 里。这个概念来自 Matt Pocock(mattpocock Skills 仓库作者,目前最流行的工程 skill 集合之一)在一场技术演讲中的分享。他把这种现象命名为「Skill Hell」,是继 Tutorial Hell 和 Framework Hell 之后,AI 时代开发者面临的第三种困境:
问题的根因很简单:我们没有一个评判 skill 好坏的标准。没有人告诉你"看一个 skill 的时候应该关注哪些维度"。于是社区里充斥着大量看似有内容、实际对 agent 行为零影响的 skill。Matt 给出的答案,就是下面这份 4 维度的 Skill 检查清单。
DIMENSION 01
这是 skill 设计的第一道选择题——你的 skill 是用户手动调用(user-invoked),还是模型自动判断激活(model-invoked)?
技术上,区分两者的关键是一个叫 context pointer(上下文指针)的东西——就是 skill 的 description 字段。如果 skill 包含 description,它就会常驻在 agent 的系统上下文中,agent 可以根据描述自动判断"我现在需要调用这个 skill",这是 model-invoked 模式。如果不写 description、或者显式设置 disableModelInvocation: true,那这个 skill 就只是一个躺在文件系统里的 .md 文件,agent 不会主动去读——除非用户通过 /skill-name 或自然语言明确要求。
每种选择都有代价:
| 选择 | 代价 | 典型代表 |
|---|---|---|
| model-invoked | Context Load(上下文负担):每多一个 model-invoked skill,agent 的上下文就多一条 description,耗费 token 不说,还增加 agent 的决策负担。 | Superpowers |
| user-invoked | Cognitive Load(认知负担):用户需要记住有哪些 skill 可用、什么情况下该用哪个。 | Matt Pocock Skills |
Matt 的选择是偏好 user-invoked。原因很直白:model-invoked 带来的是不可预测性——即使某个 skill 完全适用于当前任务,模型也可能"选择不调用它"。你无法 100% 确定你的 skill 会在正确的时间被激活,除非你专门去做 eval 测试;而对大多数个人开发者来说,做 skill 级别的 eval 几乎是不可能的。
Tip #1:在 user-invoked 和 model-invoked 之间做一次有意识的决策,而不是随大流。
DIMENSION 02
Matt 提出了一个极其简洁的 skill 内部模型:任何 skill 都可以拆成两种基本单元——Steps(按顺序执行的操作流程)和 Reference(辅助执行步骤的静态资料:模板、术语表、检查清单、PRD 模板等)。有些 skill 只有 Steps(纯流程),有些只有 Reference(比如术语表),但大多数是两者的组合。
以 Matt 的 to-PRD skill 为例:Steps 有 3 个——寻找相关上下文 → 和用户确认测试场景 → 写 PRD 文档;Reference 有 2 个——「什么是测试场景」的说明 + PRD 模板。
Tip #3:skill.md 是 skill 的核心文件,让它越小越好。小的 skill.md = 更好维护 + 更容易审查 + 更少 token 消耗。每砍掉一个不必要的词,就是替用户省了好几次调用的 token。
原文 Tip 编号即从 #1 跳到 #3(无 #2),保留原编号。
让 skill.md 变小的关键技术,是识别 skill 的 branches——不同的使用场景分支:
to-PRD 只有一个 branch:永远创建 PRD → 所有 reference 都应该常驻主 skill.md。Domain-Modeling 有两到三个 branch:更新 context.md / 创建 ADR / 也可能什么都不做 → ADR 模板和 context.md 模板不需要常驻主 skill.md。对于多分支 skill,把只在特定分支有用的 reference 外置为独立文件,通过 context pointer 按需加载。Matt 管这叫 External Reference——一个"如果你需要 X 就去读那个文件"的指针。
to-PRD · 单分支
Domain-Modeling · 多分支
核心操作:把分支专属的参考资料藏在 context pointer 后面。
DIMENSION 03 · 整场演讲最值钱的部分
这是整场演讲里最值钱的部分。Matt 用两个技术解决了"skill 写得很清楚但 agent 不照做"这个千古难题。
Leading Words(德语文学理论中叫 Leitwort)是一种自带"压缩包"效果的词或短语——你用短短两三个词,就能激发 agent 激活一整套行为模式。
Matt 举的例子是 vertical slice(垂直切片)。每个工程师都知道 agent 有一个经典毛病:拿到一个任务后逐层编码——先写数据库层、再写 schema 层、再写 API 层、再写前端……而不是像人一样先做一个最小可工作的端到端切片。如果你只在 skill 里写"不要逐层编码,先做一个小功能再扩展",agent 大概率还是逐层来。但如果你在 skill 里反复使用 vertical slice 这个 Leading Word:
# skill 里的写法:重复同一引导词,而不是写一段"不要逐层"的说教 用 vertical slice 的方式来实现功能 先做一个 thin vertical slice 验证全链路 每个 vertical slice 完成后再扩展下一个
效果验证方式:去 agent 的 reasoning traces 里看——如果 agent 在思考过程中自己说出了 "let me approach this as a vertical slice",那就说明 Leading Word 起作用了。Agent 在自我复述这个短语的过程中,会被自己的"推理"引导到正确的行为模式上。
Matt 说几乎所有听过这个技巧的人都回应"哦对,我其实一直在下意识这么做"。他的建议是:从现在开始,有意识地在 skill 里保持一致、有力的 Leading Words,并去 reasoning traces 里检验它们是否真的生效。
他还有一个很妙的比喻:英语就像一套有着巨大 API 的编程语言,不同的词就是在调用不同的"函数",而 Leading Words 就是那些最常用、最可靠的函数名。
另一个常见问题是 agent 在某个步骤"不够用力"。Matt 举了一个他称之为"无处不在"的经典案例:Plan Mode。几乎所有 Plan Mode 的实现都有两步——先问澄清问题,再写计划。但 agent 知道自己的终极目标是"写出一个计划",所以它在第一步(问澄清问题)上总是浅尝辄止——问一两句就急着跳到第二步。
Matt 的解法是把计划流程拆成两个独立 skill:grill-with-docs(纯提问阶段,agent 看不到"写计划"这个后续步骤)和 to-PRD(拿到足够信息后,才进入写文档阶段)。
agent 视野:①② 全都看得见,知道交出计划就算完 → ① 草草了事。
症状:第一步总是不够用力。
agent 视野:提问阶段只见提问,没有捷径可抄 → 只能认真问。
解法:让 agent 只看得到当前步骤。
核心原理:当你让 agent 只看得到当前步骤时,它会在这个步骤上投入更多"腿力"——因为它没有捷径可抄。
这不是每个 skill 都需要做的事,但在那些"第一步总是做不好"的场景里,这是唯一有效的解法。
DIMENSION 04
一个 skill 的臃肿往往是其他问题的症状,而不是原因本身。Matt 指出了三种最常见的失败模式:
1 · 重复 DRY
同一份 reference material 出现在多个地方。
解法:Single Source of Truth —— 每个信息只在一处定义。
2 · 沉积 Sediment
多人协作的产物——每个人都在往同一个 markdown 文件里加东西,但没人敢删别人的内容,日积月累变成沉积层。
解法:按 branches 归位,或直接删除过时的东西。
3 · 空操作 No-ops
Agent 生成 skill 最容易出现的毛病:看起来在说点什么,但删掉后 agent 的行为完全不变。
解法:Deletion Test —— 见下方演示。
Matt 给出了一个实用的 Deletion Test:假设你的 skill 里有一整段告诉 agent "要写详细的长 commit message"。删掉这段——agent 大概率还是会写正常的 commit message,因为这是它从训练数据里就会的基本行为。凡是通过 Deletion Test 的内容,都是 no-op——大胆删。
DELETION TEST · 对下面这行 skill 指令做一次删除测试
npm test,红了不许提交。
演示用例:commit message 行取自 Matt 的原例;"跑测试"对照行为本站构造,用于对照 no-op 与真正起作用的指令。
✂ 该行已删除 — agent 的行为完全不变。
"写详细的 commit message" 是 agent 从训练数据里就会的基本行为,这句指令是 no-op:只耗 token,不改变任何输出 → 大胆删。而"先跑测试再提交"是 agent 默认不会做的额外约束,删掉后行为立刻改变——这才是 skill 该写的东西。
RECAP
把四个维度串起来,就是一份完整的 Skill 质量审查清单:
▸ 点击任意条目可勾选——拿它逐条过你手头的 skill。
ONE MORE THING
如果你现在手头有正在维护的 skill,立刻拿这份清单过一遍。Matt 已经把整套方法论编码成了一个叫 writing-great-skills 的 skill(就在他的 Matt Pocock Skills 仓库里),可以直接用它来审查和改写你的 skill。
如果你对 AI 工程化开发感兴趣,Matt 还在 aihero.dev 有一个 newsletter,接下来几个月会发布 AI Coding 速成课程。