写好 Skill 的几个原则！

近日Anthropic分享他们内部使用Claude Code中的各种skill实践经验，从基本概念，到 skill 的定义。

原文：https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

阅读完成后，我总结了关于如何写好skill几条原则。如下：

1、不要写模型已经知道的废话

Claude 已经会写代码，也能读代码仓库。如果 Skill 只是写“先理解需求，再实现，再测试”，那样价值是很低的。

高质量 Skill 应该补充模型默认不知道的信息，栗如：

• 公司内部约定

• 常见错误

• 特定系统的真实行为

• 工具链的限制

• 团队希望坚持的判断标准

Skill 核心其实就是给 Agent 的高信号工作指南，而不是写冗余的介绍。

2、一定要有 Gotchas

Anthropic 特别强调这一点，踩坑记录往往是一份 Skill 里含金量最高的部分。

所谓踩坑记录，不是那种放之四海而皆准的"注意事项"，而是 Agent 真实用坏过、出过问题的地方，每一条都有血有肉。

同时，你的 Skill 要跟着用跟着更新，Agent 哪里犯了错，就往踩坑记录里加一条，久了就是一份真正值钱的经验库。

3、使用渐进式披露

一个 Skill 不应该把所有内容都塞进 SKILL.md。更好的做法是把它设计成一个可探索的文件夹。

如：

my-skill/
  SKILL.md
  references/
    api.md
    schema.md
    examples.md
  scripts/
    verify_checkout.py
    fetch_metrics.py
  assets/
    report-template.md

SKILL.md 只放入口信息：什么时候用、总体流程是什么、遇到具体情况该看哪个文件。详细 API、长示例、模板和脚本放到其他文件里。这样可以减少上下文压力，也让 Agent 在真正需要时再读取细节。

4、不要把 Claude 绑得太死

Skill 应该给 Agent 足够的信息和边界，但不要规定每一步都必须机械执行。

过度具体的指令会让 Agent 在面对新情况时失去灵活性。好的写法是：

• 明确目标。

• 明确约束。

• 明确必须避免的坑。

• 明确验证标准。

• 允许 Agent 根据实际上下文选择实现路径。

这个和写工程规范有点像：原则要清楚，细节要能适应现实。

5、Description 是写给模型看的触发条件

Skill 的 frontmatter 里有 description 字段。这个字段不是给人类看的宣传语，而是给模型判断“什么时候应该使用这个 Skill”的触发条件。

比如：

---
name: checkout-verifier
description: Verify checkout flows, Stripe test-card payments, invoice states, and payment webhook processing.
---

这个 description 应该包含用户可能会说出的关键词、任务场景和适用边界。它写得越清楚，Agent 越容易在正确时机调用它。

6、让 Skill 记住历史

有些 Skill 需要记忆。比如 standup 生成器，如果能读取昨天写过什么，就可以只输出变化部分，而不是每天重复相同内容。

记忆可以很简单，append-only 文本日志、JSON 文件，以及 SQLite 数据库。

7、把稳定操作写成脚本

脚本会比自然语言更稳定，比如你让 Agent 每次都重新写一段数据拉取代码，既浪费上下文，也容易出错。

更好的方式是把稳定部分封装成脚本或库，让 Agent 负责组合和判断。