写Agent Skills前,先看它怎么失败
写Agent Skills最大的坑是写得太早。让agent先跑起来,记录失败,把这些失败变成skill的骨架。Akshay的15条建议,外加网友的真实反馈。
写Agent Skills最常见的问题,是写得太早。
Skill是Claude Code这类AI编程工具里的可复用工作流,agent根据描述判断是否加载。你花几小时做一份排版漂亮的Markdown,描述完美工作流,agent跑起来,照样犯同样的错。问题不在body,在更早的地方。
Akshay在推特上列了15条建议,核心就一条:先让agent失败,再动手写。
失败清单就是skill
让agent在3个真实任务上不带skill跑一遍,把每个搞错的地方记下来。那个清单,就是你的skill,其余都是填充。有网友补了一句:失败先于代码,才是唯一诚实的规格。
描述是触发器,不是摘要
agent在决定加载skill之前,只看得到名称和描述。描述模糊,后面写的所有内容都不会被读。
把“何时使用这个”全部写进描述,别在描述里总结工作流。body在agent做出加载决定后才被读到。而且一行摘要会被直接当指令执行,而不是你写的完整流程。
用词用用户实际会输入的:文件名、错误信息、工具名、偷懒版的请求。不用内部黑话。
停止解释模型已经知道的事
Claude知道PDF是什么。每一行要么改变行为,要么删掉。
全大写的ALWAYS和NEVER是红旗。带理由的规则,才能覆盖你没想过的场景。Anthropic的Claude Code团队管这叫gotchas,他们最好的skill从几行加一个坑开始,每次Claude绊倒,就长一条。
什么不是skill
每次都要发生的,是hook。agent每个任务都需要的,放CLAUDE.md或AGENTS.md。skill是中间地带。有网友清理过自己的配置,从60个skill删到只剩2个——大多数skill根本不该存在。
像测分类器一样测触发器
20个prompt,一半该触发,一半不该。负面样本做成近似匹配,不是“今天天气怎么样”这种搞笑case。
同一组prompt,不带skill,干净上下文,跑多轮。agent不是确定性的,一次绿灯证明不了什么。
读日志,别只看输出。文件打开顺序、从未被touch的reference、每轮重读的同一个文件,真正的bug都藏在这。有网友说第12条最省时间:先搞清哪个阶段坏了。没加载,修描述。加载了但做错事,修body。他以前花几小时改body,其实skill压根没加载过。
写skill用两个agent:一个帮你写,一个只加载skill来实际用。写的那个人已经知道你的意图,看不到缺口。
一次只改一件事
留held-out测试集,不然只是在过拟合你最爱的5个prompt。每个真实失败变成一个test和一个gotcha,模型更新后全量重跑。上个月能用的skill这周可能就坏了,有时新模型根本不需要它。
Akshay的pro tip:把这篇帖子复制进Claude Code或Codex,指向skills文件夹,让它按这15条审计你已有的每个skill。
然后,保持迭代。
想了解.claude文件夹的完整配置,包括CLAUDE.md、hooks、agents、permissions,可以看Akshay的这篇:Anatomy of the .claude/ folder
发布时间: 2026-11-21 21:34