怎么写一个真正好用的 AI agent Skill

写在前面

上一篇我讲了怎么把一整条测试流程做成 3 个能串起来跑的 Skill。

「那一个 Skill 到底怎么写才算写好？」

这篇就专门回答这个。不讲某条具体流水线，只讲写 Skill 这件事本身的手艺——从零起步，怎么写出一个模型愿意用、用得对、还能复用的 Skill。

先纠正一个几乎人人都有的误解：Skill 不是「存起来的 Prompt」。Prompt 是你写给模型的一句话，Skill 是你教给模型的一项本领。前者用完即弃，后者进了它的能力清单，该出手时自己出手。这个视角的转变，是写好 Skill 的前提。

一、先搞懂：一个 Skill 是怎么被加载的

不理解加载机制就动手写，是新手最大的坑。Skill 用的是一套三层渐进式加载，越往下越「重」，按需付费：

这张表里藏着三条设计直觉，记住它们，后面所有取舍都有依据：

1. description永远在线，所以它得替整个 Skill「拉客」——模型是靠它决定要不要点开你的 Skill 的。
2. 正文触发后才加载，所以别塞废话——它每次都要占掉真金白银的上下文。
3. 重资料放第三层，按需读——大块的参考清单、脚本逻辑，不该常驻正文里挤占空间。尤其脚本，它执行就行，压根不用把代码读进上下文。

一个 Skill 的标准结构长这样：

skill-name/ ├── SKILL.md # 必需：YAML 头 + Markdown 正文 ├── scripts/ # 可选：确定性、重复性的活，交给代码 ├── references/ # 可选：按需加载的参考文档 └── assets/ # 可选：产出里要用的模板、图标、字体等

绝大多数 Skill 只需要一个SKILL.md。scripts / references / assets 是「需要了再加」。

二、description：整个 Skill 的命门

如果这篇你只认真读一节，读这节。

description是触发机制本身。模型不会通读你所有 Skill 的正文再挑一个用——它只看每个 Skill 的name+description，然后决定「这个任务，要不要点开某个 Skill」。写不好 description，正文写得再漂亮也白搭：它根本不会被触发。

一条合格的 description 必须同时写清两件事：

• 做什么（What）
• 什么时候该用（When）——具体的触发词、触发场景

而且有个反直觉但极其重要的现实：模型天生倾向「欠触发」——该用 Skill 的时候它常常自己硬扛过去了。所以 description 要写得主动一点、甚至有点「推」。对比一下：

❌ 太含蓄（会欠触发）：

description:生成测试用例的技能。

✅ 主动、带触发词、带兜底场景：

description:>生成软件测试用例的专业技能。当用户提到"生成测试用例"、"写测试用例"、 "帮我测试"、"这个功能怎么测"，或上传了需求文档/PRD/原型图并希望输出用例时， 必须使用此技能。即使用户只是说"帮我测一下这个"、"这个怎么测"，也应触发。

差别不在辞藻，在把触发条件穷举出来、并明确「即使只说 X 也要触发」。这一句「即使……也应触发」，就是专门用来对抗欠触发的。

还有一个必须知道的机制：太简单的一步到位任务，哪怕 description 完美匹配，模型也可能不触发——因为它自己用基础工具就能干（比如「读一下这个 PDF」）。只有复杂、多步、或专门性强的任务，才会稳定触发 Skill。这条给你的启示是：别为琐碎的单步能力写 Skill，写了也用不上；Skill 的价值在于封装「一套模型不那么容易一次做对的流程」。

一句话记住：所有「什么时候用」的信息都放进description，别放正文。正文是给「已经决定用它」的模型看的操作手册。

三、正文：写给模型的操作手册，不是写给人的介绍

这是第二个思维转变：SKILL.md正文的读者是模型，不是人。

新手最常见的写法，是把正文写成一篇「产品介绍」——「本技能旨在帮助用户高效地……」。这是浪费：模型不需要被「介绍」，它需要被指挥。正文应该是一份分步操作手册：拿到输入先做什么、再做什么、按什么格式产出、产出后怎么自查。

几条具体的写法：

1. 用祈使句。「读取需求文档，提取字段约束」，不是「本技能会读取需求文档」。你是在下指令，不是在做旁白。

2. 把输出格式钉死，并配示例。这是保证产出稳定的关键。别指望模型每次自由发挥都对，直接给死模板：

## 输出格式 严格按以下 13 列输出，一列不缺、顺序不乱： | 用例编号 | 用例等级 | 标题 | 前置条件 | 步骤描述 | 预期结果 | ... | **示例：** | ZC-001 | P0 | 正常注册成功 | 邮箱未注册 | 1.打开注册页<br>2.输入合法信息<br>3.提交 | 注册成功，跳转登录页 |

给一个填好的示例，胜过十句「请注意格式」。

3. 给流程，不给愿望。把工作拆成「第一步 / 第二步 / 第三步」，每步说清楚干什么。模糊的「请全面地分析」，远不如「对照维度清单逐项过一遍，每个维度都判断是否适用」来得可执行。

4. 结尾放一份「质量自查清单」。让模型产出后对着 checklist 自检一遍，能显著减少低级遗漏：

## 质量自查 - [ ] 输出字段齐全、顺序正确、无缺列 - [ ] 每条预期结果都可验证，没有"显示正常"这类没法断言的写法 - [ ] 编号连续不重复 - [ ] 边界与异常场景都覆盖了，不是一水儿的正向流程

5. 讲「为什么」，而不是堆一屏「MUST / 禁止」。这是官方指南里我最认同的一条。模型对「解释了原因的要求」执行得更好、更会举一反三。与其写「禁止臆造需求」，不如写「PRD 没写的一律进疑问清单，绝不自己编个验收标准当既定事实——这是 AI 产出最容易翻车的地方」。说清后果，比命令本身更有约束力。

6. 划清边界。明确这个 Skill 管什么、不管什么、和相邻 Skill 怎么分工。一张小表就够：

## 边界：本技能 vs 其他技能 | 你想要的 | 用哪个 | |---|---| | 理清"测什么、风险在哪"（停在分析层） | 本技能 | | 把分析结果写成可执行用例 | test-case-generator |

边界清晰的 Skill，既不会「越界乱抢活」，也方便被别的 Skill 编排——这是能把多个 Skill 串成流水线的前提。

四、什么进正文、什么进脚本、什么进 references

三层加载不是摆设，用好它是写出「精简又强大」Skill 的关键。判断标准很简单：

能被算法唯一确定答案的 → 交给scripts/。
ID 连不连续、覆盖率多少、两条用例像不像、占比够不够——这些别让模型算。模型算十次可能对九次，第十次就是事故；而且它算这些还白烧上下文和 token。写成脚本，一次对、永远对、还不占上下文。让模型只做它擅长的语义判断（「这条用例是不是在测那个点」），把算账留给代码。

大块的参考资料 → 拆到references/。
维度清单、枚举字典、长报告模板这类内容，别一股脑塞进正文把它撑到上千行。放进references/，正文里留一句指路就行：「读references/review-dimensions.md，对照 16 个维度逐项判断」。模型需要时才去读，正文保持轻盈。参考文件超过 300 行，记得在开头放个目录。

多变体场景 → 按变体拆 references。
如果一个 Skill 要支持多个平台/框架（比如部署到 AWS / GCP / Azure），别把三家的细节混在一篇里。拆成references/aws.md、gcp.md、azure.md，正文负责「选哪个」，模型只读相关的那一份。

正文本身保持 < 500 行。逼近这个量就该加层级、往 references 里分流，并在正文里留清楚的指针告诉模型「接下来该去读哪个」。

五、写完 ≠ 写好：像测代码一样测你的 Skill

这一步 90% 的人会跳过，但它恰恰是「能用」和「好用」的分水岭。作为一个做测试的人，我想特别强调：Skill 也需要被测试、被迭代，别凭感觉。

一个务实的迭代循环：

1. 写草稿。先别追求完美，把流程和格式搭出来。
2. 造 2–3 个真实的测试 prompt。关键是「真实」——写用户实际会说的话（「帮我测下这个登录功能」），而不是你精心设计的完美输入。
3. 带 Skill 跑一遍，再不带 Skill 跑一遍（baseline 对比）。这一步是精华：只有对比「有 Skill」和「没 Skill」的结果，你才知道这个 Skill 到底有没有带来价值。如果两者差不多，说明你的 Skill 没做实事，白写了。这是典型的「测量，别假设」。
4. 人来评 + 客观指标一起看。能用脚本客观判定的（格式对不对、字段全不全）就写断言自动判；主观的（措辞、风格）就人工看。
5. 根据反馈改，然后重复。

迭代时守住两条心态，否则容易越改越糟：

• 别过拟合那几个测试例。Skill 是要被用成千上万次的，你却只拿三个例子反复调。如果为了让这三个例子过关，往里加一堆写死的特判和高压 MUST，那它换个需求就废。遇到顽固问题，宁可换个说法、换个思路去引导，也别堆死规矩。
• 保持精简，砍掉不拉动效果的内容。要去读模型的执行过程（不只是最终产出）——如果发现某段指令在让模型做无用功、绕远路，删掉它再看看，往往效果更好。Skill 不是越长越强，是越准越强。

最后，等 Skill 稳定了，还可以单独针对description做触发率优化——毕竟触发是它发挥价值的第一道门。

六、几条踩出来的坑

给你避个雷，这些都是我或身边人真栽过的：

• 把description写成「介绍」而不是「触发条件」→ 欠触发，Skill 成了摆设。触发词要穷举，兜底场景要写「即使……也应触发」。
• 正文写给人看→ 一屏产品介绍、背景铺垫，模型抓不到重点还白占上下文。正文是给模型的操作手册。
• 把能算准的事交给模型→ ID 连续、覆盖率这类客观计算，不稳，该进脚本。
• 什么都往SKILL.md里塞→ 正文膨胀到上千行，上下文吃紧。大块资料拆references/。
• 满屏 MUST / 禁止→ 不如讲清「为什么」，模型执行得更好。
• 不做对比就上线→ 你根本不知道这 Skill 有没有用。跑一次 baseline 对比再说。

七、一个最小起步清单

想现在就动手，照这个来：

1. 建目录your-skill/，里面先只放一个SKILL.md。
2. 写 YAML 头：name一个短标识；description写清「做什么 + 什么时候用」，触发词穷举、加一句「即使……也应触发」。
3. 正文用祈使句写分步流程；把输出格式钉死并配一个填好的示例；结尾加一份质量自查 checklist。
4. 如果流程里有「能算准」的判断，写个脚本丢进scripts/，正文里说明何时调用。
5. 如果有大块参考资料，拆进references/，正文留指针。
6. 造 2–3 个真实 prompt，带 Skill / 不带 Skill 各跑一遍，对比结果，改，重复。
7. 满意了就打包成.skill分享出去，团队里人人可装可用。

结语

写 Skill 的本质，是把你脑子里那套已经跑熟的流程，外化成模型能照着执行的资产。

Prompt 是「这一次，请你这样做」；Skill 是「以后遇到这类事，你就该这样做」。前者随对话消失，后者沉淀成能力、能复用、能被团队共享、能被别的 Skill 编排成流水线。

所以别再满足于收藏 Prompt 了。挑一件你反复在做、又有明确套路的事，按上面这套把它写成一个 Skill。当模型第一次在你没提醒的情况下，自己正确地用起了你写的 Skill——那一刻你会明白，你不是在用 AI，你是在给 AI 造工具。

本文写作原则参考自官方 Skill 创作指南，并结合笔者实际落地经验整理，示例均为演示用途。欢迎在评论区交流你写 Skill 的心得与踩过的坑。