Agent Skills 的格式很简单，但要做出真正好用的 Skill，并不是把一段 Prompt 放进 SKILL.md 就结束了。
Anthropic 在工程文章里给了几条很实用的建议：从评测开始，为规模做结构拆分，从 Claude 的视角思考，和 Claude 一起迭代，并认真处理安全问题。
这篇文章就按这些建议，整理一套可以落地的 Skill 构建方法。
一、从评测开始，而不是从写说明开始
Anthropic 的第一条建议是：Start with evaluation。
也就是说，不要一上来就凭想象写一个很大的 Skill。更好的方式是先拿真实任务测试 Agent，观察它在哪里失败、哪里需要额外上下文、哪里需要更稳定的工具。
例如你想做一个代码审查 Skill，不要先写“你是资深工程师，请认真审查代码”。你应该先收集几类真实变更：
- 一个容易漏掉边界条件的修复；
- 一个缺少测试的 SEO 变更；
- 一个有潜在性能风险的前端改动；
- 一个涉及部署配置的修改。
然后观察 Claude 的表现：它有没有抓住关键风险？是不是在无关风格问题上花太多篇幅？是否知道项目里哪些文件不能手改？是否按照团队想要的格式输出 review？
这些失败点，才是 Skill 应该补上的内容。
好 Skill 不是“把所有规则都写进去”，而是“针对 Agent 实际会犯的错补充最小有效上下文”。
二、把 Skill 当成可迭代产品
Skill 不是一次写完就永远正确的文档。它更像一个小产品，需要持续评估和迭代。
一个实用流程可以是：
- 选 5 到 10 个代表性任务；
- 不使用 Skill 跑一遍，记录失败点；
- 写最小版本
SKILL.md； - 使用 Skill 再跑一遍；
- 对比输出质量、步骤遗漏、误触发和安全风险；
- 只把确实有帮助的规则沉淀进 Skill。
这样做可以避免两个常见问题。
第一个问题是 Skill 太空。它写了很多正确但无用的原则，实际任务中并不能改善结果。
第二个问题是 Skill 太满。它把所有可能情况都塞进去，导致 Claude 每次触发后负担过重，反而抓不住重点。
三、为规模做结构拆分
Anthropic 的第二条建议是：Structure for scale。
当 SKILL.md 变得臃肿时，应该把内容拆到单独文件里，并在 SKILL.md 中说明什么时候读取它们。
一个常见结构是：
my-skill/
├── SKILL.md
├── reference.md
├── examples.md
├── checklist.md
└── scripts/
└── helper.pySKILL.md 不应该变成所有资料的堆放场。它更适合承担“导航页”的角色：说明这个 Skill 做什么、什么时候用、基本流程是什么、有哪些附加资源。
例如：
## Additional resources
- For complete API fields, read `reference.md`.
- For output examples, read `examples.md`.
- For release risk checks, read `checklist.md`.
- For deterministic validation, run `scripts/validate.py`.这样 Claude 可以根据任务需要继续读取对应资料，而不是每次都加载全部内容。
四、互斥场景要拆开
Anthropic 特别提到，如果某些上下文是互斥的，或者很少一起使用，就应该分开存放，减少 token 使用。
这一点很容易被忽略。
比如一个“文档生成” Skill 里，可能同时有：
- 写 PRD 的模板；
- 写周报的模板；
- 写技术方案的模板；
- 写复盘报告的模板。
这些模板都属于“文档生成”，但在单次任务里通常只会用到一种。如果全部放进 SKILL.md，Claude 每次写周报时也会看到 PRD 和复盘模板，既浪费上下文，也可能混淆输出结构。
更好的方式是把它们拆成独立文件，甚至拆成独立 Skills。
判断是否拆分，可以看三个问题：
- 它们是否经常同时使用？
- 它们是否共享同一套流程？
- Claude 看到其中一个，会不会误用到另一个场景？
如果答案是否定的，就应该拆开。
五、从 Claude 的视角写 description
Anthropic 的第三条建议是：Think from Claude’s perspective。
这句话非常重要，尤其体现在 name 和 description 上。
Claude 会用 Skill 的名称和描述来判断当前任务是否应该触发这个 Skill。所以 description 不是营销文案，而是匹配规则。
一个太泛的 description 可能是：
description: Helps with documents.它的问题是边界太模糊。什么叫 documents？写文档、改文档、读文档、生成 PDF、处理 Word 都算吗？Claude 很可能误触发，也可能该触发时不触发。
更好的 description 应该包含任务、场景和触发信号：
description: Create and revise product requirement documents. Use when the user asks for PRD drafts, feature requirements, user stories, acceptance criteria, or product risk analysis.它告诉 Claude：
- 这个 Skill 做什么；
- 哪些用户表达应该触发；
- 能力边界在哪里。
写 description 时，可以多问一句：如果 Claude 只看到这一行，它能不能正确决定“该不该用”？
六、让 Claude 帮你沉淀 Skill
Anthropic 的第四条建议是：Iterate with Claude。
这听起来有点递归，但很实用。你可以在和 Claude 完成任务后，让它把成功做法和常见错误沉淀进 Skill。
例如一次代码审查结束后，你可以让 Claude 总结：
把这次审查中有效的检查路径，整理成可复用的 Skill 规则。
只保留对未来任务有帮助、非显而易见、可执行的内容。如果 Claude 使用某个 Skill 走偏了，也可以让它反思：
刚才使用这个 Skill 时哪里判断错了？
是 description 误导、流程不清楚、参考资料缺失，还是脚本输出没有被正确解释？
请给出应该修改的 Skill 内容。这样做的好处是，你不必一开始就猜中 Claude 需要什么上下文。你可以从真实交互中发现它实际缺什么，再把经验沉淀进去。
七、脚本既是工具，也是文档
Anthropic 提醒，代码可以同时作为可执行工具和文档，但要写清楚 Claude 应该运行它，还是阅读它。
这点很关键。
如果 Skill 里有一个脚本，SKILL.md 应该明确说明：
- 什么时候运行；
- 从哪个目录运行；
- 输入是什么；
- 输出是什么；
- 失败时怎么处理；
- 是否允许修改文件或访问网络。
例如：
## Validation
Run `python3 ${CLAUDE_SKILL_DIR}/scripts/validate.py <file>` before finalizing.
The script prints JSON with `ok`, `errors`, and `warnings` fields.
Do not modify the target file from this script; it is read-only validation.这样的说明能减少 Agent 的误用。
八、控制副作用：该自动的自动，该手动的手动
Claude Code 文档提到，有些 Skill 可以自动触发，有些应该只允许用户显式调用。
这背后的原则很简单：没有副作用、低风险、强相关的能力适合自动触发；有副作用、高成本、会改变外部状态的能力应该由用户控制。
适合自动触发的例子：
- 根据项目规范解释代码；
- 读取参考文档；
- 生成草稿；
- 做只读检查；
- 总结当前 diff。
更适合手动触发的例子：
- commit；
- deploy；
- 发送消息；
- 调用外部系统写数据；
- 删除、迁移或批量修改文件。
如果一个 Skill 可能产生外部影响，就不要让 Agent 因为“看起来相关”而自动执行它。
九、安全审查：Skill 不是普通文本
Anthropic 在安全部分提醒：Skills 通过指令和代码给 Claude 新能力，也意味着恶意 Skill 可能引入漏洞，或者诱导 Claude 泄露数据、执行非预期操作。
审查 Skill 时，至少要看这些内容：
SKILL.md是否包含诱导泄露数据、绕过权限、忽略用户确认的指令；- 脚本是否读取敏感文件；
- 脚本是否访问不可信网络地址；
- 依赖是否可信；
- 资源文件是否包含隐藏提示或异常内容；
- Skill 是否会修改文件、发送请求、提交代码或部署服务；
- 是否应该限制为手动调用。
对团队来说，Skill 最好像代码一样管理：走版本控制、走 review、走发布流程。
十、一个实用的 Skill 编写清单
写 Skill 前，可以用这份清单快速过一遍。
目标：这个 Skill 解决哪一类重复任务？
触发：用户说什么时应该使用它？什么时候不该用？
输入：它需要读取哪些文件、参数或上下文？
流程：Claude 应该按什么步骤执行？
资料：哪些长文档应该拆到独立文件？
脚本：哪些确定性操作应该交给代码？
输出：最终结果应该是什么格式？
验证：如何判断 Skill 真的改善了任务表现？
安全：它是否有副作用、网络访问或敏感数据风险？
维护：谁负责更新，如何做版本管理？如果这十个问题都能回答清楚，这个 Skill 大概率就不是一段随手写的 Prompt，而是一个可维护的能力模块。
小结
Anthropic 对 Agent Skills 的最佳实践，可以压缩成四句话。
第一，从真实任务和评测开始，不要凭空写大而全的说明。
第二，用渐进式披露组织材料，让 SKILL.md 做导航，把细节拆到独立文件。
第三，从 Claude 的视角写名称、描述和流程，让它知道何时触发、读什么、做什么。
第四，把安全当成设计的一部分，尤其是涉及脚本执行、外部网络和副作用的 Skill。
Agent Skills 的长期价值，不是让我们多写一种配置文件，而是让团队可以把反复验证过的工作方法沉淀下来，让 Agent 在真实任务中稳定复用。