写 Agent 技能前,先看它怎么把事搞砸
如何写出真正能用的 Agent 技能:
1. 先看 Agent 失败,再动手写(不给任何技能,让它跑 3 个真实任务,把它出错的每一处都记下来。这份清单就是你的技能,其余都是废话)
2. 把描述当成触发器,而不是摘要。Agent 在决定加载技能之前,只能看到名称和描述,所以如果描述含糊,你写的其他内容都没用。
3. 把所有「何时使用」的条件都写进描述,绝不在那里概括工作流程(正文只有在 Agent 已经决定加载之后才会被读到,而一行摘要会被直接照做,而不是真正执行技能)
4. 用人们实际会输入的词(文件名、报错信息、工具名、最偷懒的请求方式,而不是你的内部黑话)
5. 别再解释模型已经知道的东西(Claude 知道 PDF 是什么。每一行都必须能改变行为,否则就是浪费上下文)
6. 建一个「坑点」章节。Anthropic 的 Claude Code 团队说这是所有技能中信号最强的部分。他们最好的技能最初只有几行和一个坑点,之后每次 Claude 踩新坑就加一条。
7. 解释「为什么」,而不是吼(全大写的 ALWAYS 和 NEVER 是危险信号。一条带理由的规则能处理你没想到的情况)
8. 搞清楚什么不是技能(如果每次都必须执行,那是 hook。如果 Agent 每个任务都需要,就放进 𝗖𝗟𝗔𝗨𝗗𝗘.𝗺𝗱 或 𝗔𝗚𝗘𝗡𝗧𝗦.𝗺𝗱。技能是给中间地带的)
9. 像测试分类器一样测试触发器(约 20 个提示,一半应该触发,一半不应该。让不触发的那些是「擦边球」,而不是「今天天气怎么样」这种)
10. 永远和基线对比,每个用例跑不止一次(相同提示、无技能、干净上下文。Agent 不是确定性的,一次跑通证明不了什么)
11. 读完整对话记录,而不只是输出(文件以奇怪的顺序打开、引用从未被触碰、每次运行都重读同一个文件。真正的 bug 都藏在这些地方)
12. 先搞清楚是哪个环节坏了,再动手修(没加载 = 修描述。加载了但做错了 = 修正文。很多人一直在改正文,结果技能根本没被加载)
13. 用两个 Agent。一个帮你写技能,另一个全新的、只加载这个技能的 Agent 来实际使用它。写技能的那个已经知道你的意图,所以它看不出漏洞。
14. 一次只改一个东西,并保留一组留出测试集(否则你只是在对你最喜欢的 5 个提示过拟合)
15. 把每一次真实失败变成一个测试和一个坑点,并在每次模型更新后重跑所有测试(上个月能用的技能可能会失效,有时新模型根本不需要它)
专业提示:这份清单就是用来复制粘贴的。把整篇帖子丢进 Claude Code 或 Codex,指向你的技能文件夹,让它对照这 15 点审计并改进你已经写好的每一个技能。如果你还在搞清楚技能和 𝗖𝗟𝗔𝗨𝗗𝗘.𝗺𝗱、hooks、子 Agent 和权限之间的关系
本文由 AI 翻译自英文原帖,技术名词保留英文。
查看 X 原帖