一个好用的 Skill 长什么样：目标、输入、步骤、验收

很多人第一次写 Skill，是把一段很长的提示词存成文件。能用，但效果时好时坏，出了问题也不知道该改哪里。

这篇把一个 Skill 拆成五个部分，每一部分都讲清楚要写什么、为什么这么写。文末有一份完整模板，可以直接复制去改。

Skill 是什么：一份写给 Agent 的岗位说明书

现在很多 Agent 工具都支持 Skill：一个文件夹，里面有一份 SKILL.md，再加上几份参考资料或脚本。Agent 平时只看它的名字和一句描述；等遇到匹配的任务时，才把完整内容读进来照着做。

所以更好的理解方式是，Skill 是一份岗位说明书，而不是一句咒语。一份合格的岗位说明书，至少要回答五个问题：

部分	回答的问题
目标	做完之后，要交出什么？
触发描述	什么时候该用这份说明书？
输入与边界	需要什么材料？缺了怎么办？什么不能碰？
步骤	按什么顺序做？哪一步要停下来等人确认？
验收	怎么判断做对了？

下面一个一个讲。

目标：写清“交出什么”，而不是“做什么”

最常见的写法是：“帮我整理会议纪要。”问题在于，“整理”没有终点。Agent 可能给你一段漂亮的摘要，也可能给你一张表，你们俩想的“完成”根本不是一回事。

更好的写法，是直接写交付物：

读取一份会议记录，输出三个文件：meeting-minutes.md（纪要）、action-items.csv（行动表）、follow-up-draft.md（跟进草稿）。每个决定和行动项都要保留原文编号。

有文件名、有格式、有追溯要求，做没做完一眼就能看出来。

触发描述：决定 Agent 会不会用它

description 这一行最容易被忽略，其实它决定了 Agent 会不会加载这个 Skill。写得太宽，不相关的任务也会用上它；写得太窄，该用的时候反而想不起来。

一个好的触发描述，要同时说清能力和场景：

description: 把会议记录整理成纪要、行动表和跟进草稿。当用户提供会议记录、要求提取决定和待办、或准备会后跟进时使用。

写完之后，再列出至少两句“应该触发”的真实请求，比如“把这份周会记录整理一下”“帮我从会议里拉一个待办表”，用来检查描述有没有覆盖到。

输入与边界：缺什么，就停下来

这一部分要写三件事：

必需的输入：少了哪样就没法开工；
缺失时怎么办：停下来问，而不是自己猜。最典型的就是负责人和截止日期，没写就填“待确认”，绝不能编一个人名；
不能碰的东西：只读哪个目录、只写哪个目录，哪些动作（发邮件、删文件、改原始资料）必须先问人。

AI 最大的风险不是做错，而是把不确定的事写得很确定。边界写得越清楚，这种情况就越少。

步骤：3 到 7 步，每一步都有产物

步骤太少，等于没拆；太多，Agent 容易在中间迷路。我的经验是 3 到 7 步，而且每一步都要有一个能检查的中间结果。

以会议纪要为例：

只读提取：按原文编号列出决定、建议、行动项和风险，不生成文件；
核对数量：数量对不上就回到第 1 步，不往下走；
生成三个文件，只写入 output/ 目录；
自查：逐条对照原文编号，列出无法确定的内容；
人工确认：跟进草稿首行标注“草稿，未发送”，由人决定发不发。

第 5 步很关键。凡是会对外产生影响的动作，比如发消息、改线上数据、删东西，都应该留一个人工确认点。

验收：至少 3 个样例，每个都有通过标准

这是大多数 Skill 缺的部分，也是最值钱的部分。

准备至少 3 份测试材料，每份都写清楚“通过”长什么样。其中最好有一份故意埋了坑：有一条只是建议、没被确认；有一个行动项没写负责人；有一个风险还没结论。好的 Skill 应该把这些都如实标出来，而不是自作主张补全。

样例	埋的坑	通过标准
标准周会记录	无	决定与行动项数量和参考答案一致
缺负责人的记录	1 个行动项没写负责人和日期	两个字段都写“待确认”
混着建议的记录	1 条建议看起来像决定	只能标为“建议”

有了这张表，改 Skill 就有了方向：哪个样例没过，就改哪一段。

一份可以直接改的模板

一个 Skill 文件夹建议这样组织：

meeting-minutes/
├── SKILL.md                    # 岗位说明书本体
└── references/
    ├── task-contract.md        # 任务合同：输入、输出、边界的完整版
    └── test-cases.md           # 测试样例与通过标准

SKILL.md 本体可以这样写：

---
name: meeting-minutes
description: 把会议记录整理成纪要、行动表和跟进草稿。当用户提供会议记录、要求提取决定和待办、或准备会后跟进时使用。
---

# 会议纪要整理

## 目标
读取一份会议记录，输出三个文件，每条决定和行动项都保留原文编号：
- output/meeting-minutes.md：决定、建议、未决风险分区
- output/action-items.csv：ID、类型、内容、负责人、截止日期、依据、状态
- output/follow-up-draft.md：首行标注“草稿，未发送”

## 必需输入
- 一份会议记录（Markdown 或纯文本），每条发言带编号

## 边界
- 只读取 input/，只写入 output/，不修改原始记录
- 负责人或日期没有明确写出时，填“待确认”，不得推断
- 建议不等于决定；未决风险保持未决

## 步骤
1. 只读提取：按编号列出决定、建议、行动项、风险，不生成文件
2. 核对数量，列出无法确定的内容
3. 生成三个文件
4. 逐条对照原文编号自查
5. 停下来，等待人工确认后再做任何对外动作

## 人工确认
- 发送跟进消息、修改任何输入文件之前，必须先问

## 验收
完成前阅读 references/test-cases.md，逐条对照通过标准。
报告实际读取和写入的文件，以及没有执行的检查。

写完之后，对着这张清单检查一遍

名字只用小写字母、数字和连字符
触发描述同时写了能力和使用场景
至少列了 2 句应该触发的真实请求
目标里写的是交付物，而且能检查
必需输入、缺失时的处理、不能碰的东西都写了
步骤在 3 到 7 步之间，每步都有中间结果
对外动作前有人工确认点
至少 3 个测试样例，其中一个埋了坑，每个都有通过标准

这份清单和 AgentClaw 的 Skill 创建器用的是同一套结构检查。那个创建器完全在浏览器本地运行，填完可以直接导出一个标准的 Skill 压缩包。

如果你手上有一段想交给 AI 的重复工作，但不确定该怎么拆，可以把它现在的做法发给我。把一段工作拆清楚、做成可验收的 Skill，正是我提供的第一项服务。