近期，Anthropic 公开了他们在内部使用 Claude Code 编写 Skill 的实战经验与最佳实践。梳理这些内容后，有几个核心原则非常值得深入探讨——毕竟，要让 AI 助手精准理解你的需求，关键在于如何写好 Skill。以下思路来自他们的真实踩坑与经验提炼，也是目前较为成熟的 Agent 开发方向。

1、不要写入模型已知的冗余信息

Claude 本身具备代码编写能力，也能读取仓库结构。如果 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 仅作为入口文件，说明何时使用该 Skill、整体流程是什么、遇到具体场景应查阅哪个文件。详细的 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 越容易在正确时机自动调用该 Skill。

6、让 Skill 具备记忆能力

部分 Skill 需要记住历史上下文。例如，一个 standup 生成器如果能读取昨天写过的内容，就可以只输出变化部分，避免每天重复相同信息。记忆的实现方式可以很简单：追加式文本日志、JSON 文件，或者 SQLite 数据库。

7、将稳定操作封装为脚本

脚本比自然语言指令更稳定可靠。如果让 Agent 每次重新编写数据拉取代码，既浪费上下文 token，也容易出错。更好的做法是将稳定部分封装成脚本或库，让 Agent 专注于组合与判断。