写好一个 AI Agent Skill 的 5 条原则
基于 agent-skills 项目 24 个 production-grade skill 的写作经验总结。
你写了一个 prompt，丢给 Claude Code，它扫了一眼，继续按自己的方式写代码。你把同样的内容写成 SKILL.md，按规范放到 skills/ 目录下——这次 agent 加载了它，一步一步跟着执行：先 spec、再 plan、写完测试才写实现、merge 前做五轴 review。
区别在哪？不是内容变了，是形式变了。prompt 是建议，agent 可以忽略。skill 是工作流，agent 被约束执行。怎么写一个 agent 会真正遵守的 skill？以下是 5 条原则。
原则一：在 agent 想偷懒的地方提前埋伏
所有 24 个 skill 都有一个共同章节：Common Rationalizations（常见合理化借口）。
这不是装饰，这是整个设计中最精妙的部分。它的洞察是：LLM 极其擅长给自己找合理化理由。"这个需求很简单""我先实现再补测试""这个没必要写 spec"——这不叫偷懒，这叫 agent 在"理性地"说服自己跳步。反合理化表是一种对抗性设计：在你开口之前，先告诉你为什么这借口不成立。
来自 test-driven-development skill 的实例：
| 借口 | 现实 |
|------|------|
| "I'll write tests after the code works" | 你永远不会加。事后写的测试测的是实现细节，不是行为。 |
| "This is too simple to test" | 简单代码会变复杂。测试文档化了期望行为。 |
| "I tested it manually" | 手动测试不留痕迹。明天的改动不会知道它被打破了。 |
来自 spec-driven-development：
| 借口 | 现实 |
|------|------|
| "This is simple, I don't need a spec" | 简单任务不需要长 spec，但至少需要验收条件。两行 spec 也算。 |
| "I'll write the spec after I code it" | 那是文档，不是 spec。spec 的价值在编码*之前*强迫你厘清需求。 |
| "A spec will slow us down" | 15 分钟的 spec 能避免 15 小时的 debug。 |
怎么写好这一节： 回想你的 agent 在什么时候最爱说"算了，跳过这一步"。把每个场景写进左栏，把事实性反驳写进右栏。不要写道德判断（"这是不对的"），写后果判断（"你会浪费 15 小时"）。
原则二：让每一步都可以被无脑执行
差的 skill 写知识，好的 skill 写指令。
❌ "Make sure the tests pass"
✅ "Run `npm test -- --coverage`. All 24 tests must pass. Coverage must not decrease."
❌ "Write clean, readable code"
✅ "Named exports only. Components colocated with tests: Button.tsx → Button.test.tsx."
来自 incremental-implementation 的 Rule 0——不是写"保持简单"，而是给出可执行检查：
写完代码后，逐条问自己：
- Can this be done in fewer lines?
- Are these abstractions earning their complexity?
- Would a staff engineer say "why didn't you just..."?
自检： 读完 Process 节，能不能不假思索地执行每一步？如果需要 agent 去猜、去判断、去"根据情况决定"，它就会在第一步合理化掉。
原则三：description 是 agent "看见"你的唯一机会
Agent 通过读取 description 来决定是否加载一个 skill，不是靠文件名。
description 会被注入 system prompt，这是你的 skill 在 agent 眼里的"一句话定位"。两个最常见的错误：
错误 1：把工作流总结写进去
❌ "This skill guides through a 5-step process: define, plan, build, test, ship..."
→ agent 看了 summary 就觉得够了，不会再加载正文
description 只写"做什么"和"何时用"，不写"怎么做"。
错误 2：只写做什么，不写何时用
❌ "Guides agents through writing tests."
✅ "Drives development with tests. Use when implementing any logic, fixing any bug, or changing any behavior."
好的 description 同时回答了：这是什么能力？什么时候该加载它？
原则四：没有证据 = 没完成
每个 skill 必须以 Verification（验证） 收尾——一份可逐项打勾的证据清单。这是把 skill 从"参考建议"变成"质量门禁"的关键一步。
"Seems right" 永远不够。必须是可验证的东西：测试输出、构建日志、运行时数据、截图。
来自 shipping-and-launch skill 的验证清单：
Before deploying:
- [ ] Pre-launch checklist completed (all sections green)
- [ ] Feature flag configured
- [ ] Rollback plan documented
- [ ] Monitoring dashboards set up
After deploying:
- [ ] Health check returns 200
- [ ] Error rate is normal
- [ ] Critical user flow works
- [ ] Rollback tested or verified ready
自检： 每个 checkbox 是否都能用一条命令或一个数字来回答？如果需要"感觉一下""判断一下"，就不是验证。
原则五：每行字都要挣得自己的 token 预算
Skill 是给 agent 读的，agent 的 context window 有成本。每写一段就问自己：
删掉这段，agent 的行为会变吗？
会变 → 保留。不会变 → 删掉。
三条具体做法：
1. 主文件控制在 500 行以内。
agent-skills 中最长的 skill 文件是 security-and-hardening（461 行），大部分在 200-350 行。详细参考资料放到 references/ 目录，需要时再按需加载。
2. 代码示例一个就够。
展示一个正确的写法，比列举五种都正确的方法更有效。展示反例也是一样——一个就够了，不需要十个。
3. 不要写 agent 已经知道的东西。
"Unit tests should be fast"——agent 知道这个。不需要在 skill 里重复。skill 应该写 agent 不知道但需要遵守的东西。
总结：好 skill 的自检清单
写完一个 skill 后，逐条确认：
- [ ] 它有反合理化表吗？至少 3 条常见的跳过借口 + 事实性反驳
- [ ] Process 的每一步是否有明确的输入和输出、不需要 agent 猜测？
- [ ] description 是否同时包含"做什么"和"何时用"、且没有泄露工作流？
- [ ] Verification 是否全是可以被命令/数据验证的 checkbox？
- [ ] 删掉任何一段，agent 的行为会变吗？（不变就删）
- [ ] 有没有写 agent 已经知道的基础知识？
- [ ] 总长度超过 500 行了吗？超过就考虑拆分参考资料
这 5 条原则不是凭空想出来的。它们是 agent-skills 项目 24 个 skill 的共同特征，每一个 skill 都经过了作者 Addy Osmani（Google Chrome 工程 VP）和他团队的实战验证。遵循这些原则写出来的 skill，agent 会更愿意读，读了更愿意执行，执行了更容易出正确结果。
