给 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 条。

比如:

  1. 改动必须带对应测试
  2. 不许在业务代码里写死密钥
  3. 新增依赖需要说明理由和许可证
  4. 错误必须带上下文,不能只抛一个字符串
  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)。

13 次浏览

评论(0)

登录后才能评论。

还没有评论。