给 Agent 写第一份 skill:一份能直接抄的模板
不用抄大仓库,半天给你的 coding agent 写出一份真会被用起来的 skill。含完整模板、description 写法三个坑、约束可验证的改写规则。
今天的 GitHub 周榜里,anthropics/skills 和 addyosmani/agent-skills 又涨了几千星。但大多数人的用法还是「看着不错,先收藏」。
这篇想解决一件事:不用抄大仓库,半天时间给你的 coding agent 写出一份真的会被用起来的 skill。
先说为什么 skill 比调提示词更值得投入
提示词是每次会话都要重新说一遍的话,skill 是可以版本化、可以 review、可以被复用的那份约定。
同一个任务,你可以在提示词里写「改代码前先跑一遍测试」,但这句话只在那一轮对话里有效。写成 skill 之后,它跟着仓库走,新人 clone 下来就有,CI 里也有,review 的时候还能逐条讨论「这条约束要不要这么严」。
成本极低这件事常被低估了:一个 markdown 文件,一次 commit,不用申请预算,不用等排期。
一、skill 的最小结构
不是所有 agent 框架都一样,但 Anthropic 那套是最通用的参考,结构基本是三段:
---
name: code-review-checklist
description: 当用户要求审查代码、做 code review 或提交 PR 前自查时使用
---
# Code Review Checklist
提交前必须逐条确认:
1. 改动是否覆盖了边界情况(空值、超长输入、并发)
2. 是否有硬编码的密钥、路径或环境变量
3. 新增依赖是否必要,许可证是否兼容
4. 错误路径是否有兜底,会不会静默吞异常
5. 公开 API 的变更是否需要同步文档
三段的意思是:
name —— 一个短的、稳定的标识,agent 靠它决定要不要加载。
description —— 这是最关键的一行,它决定这份 skill 会不会被用上。写「用于代码审查」和写「当用户要求审查代码、做 code review 或提交 PR 前自查时使用」,效果差别很大:后者包含了触发场景,agent 更容易匹配上。
正文 —— 具体的、可勾选的约束。写「代码要写得优雅一点」没用,写「新增依赖必须写明理由」才有用。
二、写 description 时最容易犯的三个错
错一:写能力,不写场景。
差:一个代码审查助手
好:当用户要求审查代码、做 code review 或提交 PR 前自查时使用
agent 读的是「我现在这个请求,匹配哪一份说明」。能力描述是抽象的,场景描述才是能对上的。
错二:塞太多。
一份 skill 只做一件事。如果 description 里出现「代码审查、写测试、重构建议、生成文档」,agent 会犹豫该不该加载,最后往往不加载。拆成四份小 skill,效果好过一份大 skill。
错三:写成给人看的介绍。
差:本文介绍了代码审查的重要性,并列举了常见问题类型。
好:当用户要求审查代码、做 code review 或提交 PR 前自查时使用
前半句是给人读的,后半句是给 agent 匹配的。
三、约束要可验证
这是区分「有用的 skill」和「正确的废话」的关键。
一条约束如果没法判断有没有做到,它就没法执行:
无效:代码质量要高
有效:新增函数必须有测试,且测试覆盖正常路径
无效:注意性能
有效:列表渲染的单次渲染项数不得超过 1000
无效:注意安全
有效:不得把用户输入直接拼进 SQL 查询
改写规则很简单:问自己「怎么用一句话判断它做到了没有」。答不上来的,就重写。
四、从 5 条开始,不要一次写 30 条
第一个 skill 不要写完整套规范,写你们团队真正会吵起来的 5 条。
比如:
- 改动必须带对应测试
- 不许在业务代码里写死密钥
- 新增依赖需要说明理由和许可证
- 错误必须带上下文,不能只抛一个字符串
- 公共接口变更要同步 README
先跑两周,看 agent 是不是真的在按这 5 条执行,哪条老被忽略——被忽略的那条通常写得太模糊,改精确。
五、什么时候别写 skill
不是所有约束都适合放进去。
只对一次的任务 —— 写进提示词就行,存成 skill 是负担。
agent 做不到的 —— skill 改不了模型能力上限,约束写得再细也变不出它没有的能力。
纯价值观 —— 「代码要优雅」这类没法验证的判断,放进 skill 只会稀释真正的约束。
六、最后
那份能抄走的模板大概长这样:
---
name: <动词开头的短名>
description: <当<场景>时使用;包含 2-3 个同义说法>
---
# <标题>
<一条一条的可验证约束>
<明确的例外情况>
半小时,五个条目,一次 commit。这是本周性价比最高的动作。
你的团队有哪些「每次都要重复交代」的要求?
评论区贴出来,我可以挑几条改写成可直接用的 skill,尤其是那些约束特别啰嗦、但其实一句话就能说清的。这篇如果帮到了你,欢迎点个赞让更多人看到。
参考:本周社区《GitHub 周榜:这周的星全给了「让 Agent 能被信任」的那一层》中提到的 anthropics/skills(累计 196,240 star)与 addyosmani/agent-skills(118,429 star)。
登录后才能评论。