第一个 Skill：SKILL.md 到底怎么写

上一篇文章讲了 Skill 是什么：把一套固定做法写成一个文件夹，让 Agent 在合适的任务上自动照着做。这一篇就动手写第一个：不需要装任何工具，不需要写代码，一个文件夹、一个文件就够了。

先把结论放在前面：写 Skill 的难点不在格式，而在描述。 格式只有两项必填，十分钟就能学会；描述写得准不准，决定了这个 Skill 以后会不会在该用的时候被翻出来。

一、最小结构：一个文件夹、一个文件

一个 Skill 最少只需要这样：

publish-checklist/
  SKILL.md

文件夹名就是 Skill 的名字，里面的 SKILL.md 就是全部内容。以后想加脚本、参考资料、模板，再往里面加文件夹，下一篇专门讲怎么分工；但第一版先别加，先把这一个文件写对。

文件夹名有几条实在的规矩：用小写字母、数字和连字符，比如 publish-checklist、code-review，别用空格和中文，也别起一个只有你自己懂的缩写。Agent 和人一样，都是靠名字先猜这个 Skill 是干什么的，名字取得含糊，后面全是麻烦。

二、仅有的两个必填项：name 和 description

打开 SKILL.md，文件分成两部分。上面是一小段元数据，下面是正文。元数据里只有两项是必填的：

---
name: publish-checklist
description: 发文章前的检查流程，在用户说要发布文章、或者要检查一篇文章能不能发时使用。
---
  • name：和文件夹名保持一致，相当于这个 Skill 的身份证，别让文件夹叫一个名、文件里写另一个名。
  • description：这是全文最重要的一句话。它要回答两个问题：这个 Skill 是做什么的，在什么时候用。 Agent 启动时只读这一句，大概 100 个 token，就靠它判断当前任务要不要加载这个 Skill。

所以 description 不是写给人看的简介，而是写给 Agent 看的触发条件。写的时候按这个句式套：“这是一个……流程，在……时使用。”前半句说做什么，后半句说触发场景，两个都有了，才算写完整。

三、描述怎么写才算准：三个反面例子

描述最常见的毛病有三个，对照着改，基本就不会写偏：

  • 太模糊，等于没写。 比如只写“帮你检查东西”。检查什么、在什么时候检查，全没说，Agent 根本不知道该在哪个任务上用它，最后这个 Skill 就一直躺在那里没人翻。
  • 太宽泛，到处乱触发。 比如写“在用户需要帮助时使用”。这句话对什么任务都成立，等于对什么任务都不成立，Agent 要么不敢用，要么在不该用的时候也把它翻出来，干扰正常回答。
  • 只写做法，不写场景。 比如写“核对标题、描述、分类、标签和链接”。步骤列得很全，但没说这是在发文章前用的，Agent 看到用户在聊别的检查任务时，也可能误以为该用它。

改好的样子，是上一节那个例子：做什么说清楚了，触发场景也说清楚了，而且场景窄到一次只对应一类任务。检验方法很简单：把 description 单独拿出来给一个没看过正文的人看，如果他能准确说出“这是在什么情况下用的”，这句描述就合格了。

四、正文写什么：步骤和标准，不是具体内容

元数据下面就是正文。正文只写两样东西：步骤，和每一步做到什么样才算通过。

拿发文章前的检查举例，正文可以这样写：

  1. 核对标题有没有错别字，标题和正文内容是否一致。
  2. 检查描述有没有写，描述是否准确概括了文章内容。
  3. 核对分类和标签是否符合这篇文章的主题。
  4. 逐一打开文中的链接，确认没有死链。
  5. 确认图片都已上传、没有缺失，图片说明没有错位。

每条后面最好再跟一句通过标准，比如“链接全部能打开才算通过，有一条打不开就列出来，不要跳过”。没有标准的步骤，Agent 执行起来全凭感觉，查完也不知道算不算查完。

还有两条正文的纪律。第一，写步骤和标准，不写具体内容。 Skill 里不要出现某一篇文章的标题、某一段代码，它要能反复用在不同的文章、不同的任务上。第二，正文保持简短，一般控制在 500 行以内。 第一版更应该短，三到十步就够了，写得越长，Agent 越难抓住重点，深的资料以后拆出去，下一篇会讲。

五、正文之外，先别急着加的东西

新手写第一个 Skill 时，最容易犯的错不是写得太少，而是第一版就加太多。以下三样，第一版都可以先不写：

  • 脚本。 如果步骤里有一条是每次都要手动跑的命令，比如批量检查链接，那以后可以写成脚本放进 scripts 文件夹；但第一版先用人话把步骤写清楚，确认流程本身是对的，再考虑自动化。
  • 长篇参考资料。 详细的规范、历史背景、例外情况清单，先别塞进正文，也别急着建 references 文件夹。等这个 Skill 真的被用过几次，知道哪条规则总被问起，再把那条规则的详细说明补进去。
  • 模板和素材。 发文章用的固定格式、检查表的表格模板，可以以后放进 assets 文件夹。第一版没有模板也能跑，先跑起来，再补。

记住这个顺序：先有一个能用的 Skill，再有一个好用的 Skill。 第一版的目标不是完美，是跑通一次：Agent 在你说“检查一下这篇文章能不能发”时，真的把这个 Skill 翻出来，并且按步骤查完、把结果一条一条告诉你。

六、一个完整的最小例子

把上面说的拼起来，一个能直接用的 SKILL.md 就是这样：

---
name: publish-checklist
description: 发文章前的检查流程，在用户说要发布文章、或者要检查一篇文章能不能发时使用。
---

# 发文章前检查

按以下步骤逐一检查，每条都要给出通过或不通过的结果，不要跳过任何一条。

1. 核对标题有没有错别字，标题和正文内容是否一致。
2. 检查描述有没有写，描述是否准确概括了文章内容。
3. 核对分类和标签是否符合这篇文章的主题。
4. 逐一打开文中的链接，确认没有死链；有一条打不开就列出来。
5. 确认图片都已上传、没有缺失，图片说明没有错位。

检查完成后，汇总哪条通过、哪条不通过。最后发不发，由用户决定，不要直接发布。

注意最后一句。它和上一篇文章讲的边界是一致的：Skill 管做法，不管判断。发布、对外发送、花钱这些不可逆的动作，Skill 里应该写“停下来等用户确认”，而不是替用户做决定。

练一次：把上一篇的骨架变成文件

上一篇最后留的练习，现在可以直接收尾：

  1. 拿出你上一篇挑的那件每周重复的事，和它的三到五条步骤。
  2. 新建一个文件夹，名字用小写加连字符，再在里面新建 SKILL.md。
  3. 在文件顶部写上 name 和 description，description 按“这是一个……流程，在……时使用”这个句式写。
  4. 正文写下步骤和每一步的通过标准，最后加一句“关键决定由用户确认”。

写完之后，不用急着给它加脚本和资料。下一篇文章，我们讲这个 Skill 写长了之后怎么拆：启动时只读元数据、触发时才读正文、执行时再按需读附件，以及 scripts、references、assets 各自该放什么。