写好一个 Skill
触发描述、步骤粒度、示例、验证与迭代。
一句话理解：好 Skill = 能被准确触发的描述 + 只写 Agent 不知道的内容 + 自带验证的步骤 + 用评测驱动的迭代。
让模型“帮我写一个销售分析 Skill”，几秒钟就能得到一份看起来很专业的文档：“确保数据准确”“遵循最佳实践”“注意异常值”。问题是这些话 Agent 本来就知道，真正会让它出错的东西（退款单还留在订单表里、华东区口径包含哪些城市、测试账号怎么识别）一条都没写。
写 Skill 的难点不在格式，而在内容取舍。这一课按写作顺序，讲清楚每一步的要点。
五个步骤不是走一遍就结束，而是一个闭环：
第一步：从真实经验出发
agentskills.io 的最佳实践指出，一个常见的失败模式是：不提供任何领域材料，只让模型凭通用知识生成 Skill，结果得到的都是空泛的步骤。有效的 Skill 来自真实经验，主要有两种提炼方式：
- 从一次真实任务里提炼：先和 Agent 一起完整做一遍任务，过程中你会不断补充背景、纠正做法、说明偏好。做完后回头看：哪些步骤是有效的？你纠正过它什么？提供了哪些它原本不知道的事实？这些就是 Skill 的原材料。
- 从已有资料中综合：内部 Runbook、故障复盘、Code Review 意见、历史工单的处理记录。基于你们团队真实处理记录写成的工单排查 Skill，一定比基于“客服最佳实践”文章写成的好用。
Anthropic 的文档推荐一种 “Claude A / Claude B” 的迭代方式：用一个会话（A）和你一起设计、修改 Skill，再用一个装了该 Skill 的全新会话（B）去做真实任务。观察 B 在哪里卡住，再带着具体现象回到 A 修改。一定要用全新会话测试，否则写 Skill 时留下的上下文会掩盖指令里的缺口。
这个迭代方式可以画成一个循环：
第二步：写好 description
描述承担了全部触发责任。好描述要同时回答两个问题：做什么，以及什么时候用。
对比两个版本：
# 差：太宽泛，触发时机不明
description: 帮助处理销售数据。
# 好：能力具体，场景覆盖到用户的日常说法，也划清了边界
description: 分析销售数据的变化原因：按区域、渠道、SKU 逐层下钻，对照库存与促销记录定位下降或增长的驱动因素，并输出带数据证据的结论。当用户询问业绩为什么变化、某区域或产品表现异常、需要解释周报或月报中的波动时使用，即使用户没有提到“分析”二字。只做原因分析，不负责生成常规周报。几条写法要点：
- 写用户意图，不写内部实现。 Agent 拿用户的话去和描述比对，“业绩为什么掉了”比“执行多维下钻算法”更容易匹配。
- 主动覆盖不含术语的说法。 agentskills.io 甚至建议写得“积极”一点，明确列出用户没有点名领域时也适用的情况。
- 写清边界。 最后一句“不负责生成常规周报”能减少和相邻 Skill 的误触发。
- 人称保持一致。 Anthropic 建议用第三人称描述（“分析……”而不是“我可以帮你……”），因为描述会被注入系统提示词；agentskills.io 则建议用“当……时使用此 Skill”的祈使句式。两种都可以，关键是不要写成“我能帮你做 XX”。
- 关键场景放在最前面。 规范上限是 1024 个字符，某些产品在 Skill 很多时还会截短描述。
看一个真实案例。本站作者的 Search Router 的 SKILL.md 在描述里直接写进了“搜索 XXX”“帮我查一下”“网络查询”这些口语化触发说法，这是对的。它还额外写了一个 triggers 列表字段，但 triggers 不在 Agent Skills 规范的字段里。在遵循规范的产品中，能保证起作用的是 description，所以触发说法一定要写进描述本身。
第三步：正文只写 Agent 不知道的
每写一段，都问自己一句：“没有这句话，Agent 会做错吗？” 不会，就删掉。不确定，就去测试。
最有价值的部分：踩坑清单
agentskills.io 认为，很多 Skill 里价值最高的内容是一份“踩坑清单”：违反常识、只有在你们的环境里才成立的事实。例如销售分析 Skill：
## 注意事项
- 退款订单不会从 orders 表删除，而是 status = 'refunded'。计算 GMV 时必须排除，否则会高估。
- “华东区”在销售口径里包含上海、江苏、浙江、安徽，但在市场活动口径里不含安徽。
- 测试账号的 user_id 以 9999 开头，任何统计都要先过滤。
- 大促当周的环比没有参考意义，改用去年同期对比，并在结论里说明。每当你在使用中纠正了 Agent 一次，就把这条纠正补进清单。这是迭代 Skill 最直接的方法。
给默认选项，不给菜单
“可以用 A、B、C 或 D 方法”会让 Agent 反复尝试。更好的写法是：给一个默认方案，再说明例外情况下用什么。
教方法，不教某一题的答案
“把 orders 表和 customers 表按 customer_id 关联，筛选华东区求和”只对一个问题有用。“先读 references/schema.md 找到相关表，用 _id 外键关联，按用户问题加筛选条件，结果用 Markdown 表格输出”适用于一类问题。
按任务的脆弱程度决定约束强度
| 自由度 | 适用情况 | 写法 | 例子 |
|---|---|---|---|
| 高 | 多种做法都可以，取决于具体情况 | 给检查要点和判断原则，解释原因 | 代码评审、竞品调研 |
| 中 | 有推荐做法，允许适度变化 | 给模板或带参数的脚本 | 销售周报、SEO 报告 |
| 低 | 操作脆弱、必须严格一致 | 给确切命令，并写明“不要修改参数” | 数据库迁移、批量更新线上配置 |
第四步：步骤、清单与验证回路
多步骤任务最常见的失败是跳步和“自以为完成”。三个模式可以显著改善：
进度清单：让 Agent 把清单复制到回复里，逐项勾选。
复制以下清单并随进度更新：
- [ ] 1. 对每个页面运行 check_page.py
- [ ] 2. 按 references/rules.md 判定每一项
- [ ] 3. 汇总问题并按严重程度排序
- [ ] 4. 按模板输出报告
- [ ] 5. 核对报告中每个问题都有脚本输出作为证据验证回路：做完 → 运行校验 → 修正 → 再校验，直到通过才继续。校验器可以是脚本，也可以是一份对照清单。
验证回路的结构如下，关键是“通过才继续”：
先计划、再校验、后执行：批量或不可逆的操作，先让 Agent 生成结构化的变更计划，用脚本对照真实数据校验，通过后再执行。比如批量修改 50 个页面的 meta description：先生成 changes.json，脚本检查每个 URL 是否存在、长度是否合规，全部通过才真正写入。
写脚本时还有一条原则：脚本自己处理错误，不要把问题甩给模型。 报错信息要具体到能指导修正，比如“字段 signature_date 不存在，可用字段：customer_name、order_total”。
第五步：用评测驱动迭代
Anthropic 建议先建评测，再写大量内容：先让 Agent 在没有 Skill 的情况下做几个代表性任务，记录它具体错在哪里；针对这些缺口设计至少三个测试场景，测出基线；然后只写刚好能弥补缺口的内容。
评测分两类，要分开做：
| 评测什么 | 怎么做 | 通过标准 |
|---|---|---|
| 触发是否准确 | 准备约 20 条真实风格的提问：8–10 条应该触发，8–10 条不应该触发；负例优先选“近似但不该触发”的说法；每条运行 3 次，计算触发率 | 应触发的触发率高于阈值（agentskills.io 给的默认值是 0.5），不应触发的低于阈值 |
| 效果是否更好 | 同一批任务，分别在装了 Skill 和没装 Skill 的全新会话中运行，对比结果 | 装了 Skill 后质量明显提升，Token 与耗时的增加可以接受 |
优化描述时，为了避免“只对这 20 句话有效”，可以把提问按约 60% / 40% 分成训练集和验证集，只根据训练集的失败修改描述，用验证集判断改动是否真的有效。Claude Code 用户可以安装官方的 skill-creator 插件，自动完成测试用例管理、有无 Skill 对比和描述调优。评测集的更多方法见「构建评测集」。
常见误区
- 写成百科全书。 过度详尽的 Skill 反而有害：Agent 难以找到与当前任务相关的部分，还可能去执行根本不适用的指令。
- 只测“应该触发”。 不测负例，就发现不了描述太宽导致的误触发。最有价值的负例是共享关键词但需求不同的说法，比如“帮我写个脚本把 CSV 导入数据库”对 CSV 分析 Skill 来说就是一个近似负例。
- 写完就不管。 业务口径会变，系统会升级。Skill 需要负责人，随着踩坑清单和评测结果持续更新。
- 把时效性信息写死。 “2025 年 8 月之前用旧接口”这类内容迟早会过期。当前做法写在正文，历史做法单独放到“旧版本说明”里。
Skill 评审清单
- 描述同时写了“做什么”和“什么时候用”，覆盖用户的口语说法，并写清边界
- 正文的每一段都通过了“没有它会做错吗”的检验
- 有一份来自真实纠错的踩坑清单
- 多步骤任务有进度清单，关键步骤有验证回路
- 确定性操作交给脚本，脚本的报错信息可以直接指导修正
- 至少有三个测试场景，并有无 Skill 时的基线对比
- 触发测试包含近似负例，并且多次运行
- 明确了 Skill 的负责人和更新机制
练习
改写一个“坏 Skill”（约 50 分钟）。下面是一份典型的初稿：
---
name: support-helper
description: 客服相关的帮助。
---
# 客服助手
客服是连接产品与用户的重要环节。处理客服问题时要认真细致，
确保信息准确，遵循最佳实践，必要时可以查询各种系统。- 找出它的问题：名字太泛、描述没有触发时机、正文全是 Agent 本来就知道的内容。
- 基于「客服工单处理 Agent」的场景重写：新名字、完整描述、排查步骤、至少 3 条踩坑清单、输出格式。
- 写出 6 条触发测试提问（3 条应触发、3 条近似负例），并说明每条负例“近似”在哪里。
延伸阅读
- Skill authoring best practices：Anthropic 的 Skill 写作指南与检查清单。
- Best practices for skill creators：从真实经验出发、踩坑清单、校准约束强度等写作模式。
- Optimizing skill descriptions：触发测试集的设计与描述优化流程。
下一步
下一课「实操：把一个 SOP 做成 Skill」会带你把 SEO 诊断流程从零做成一个 Skill，并在 Claude Code 中验证触发和效果。