跳转至

Anthropic 官方技能最佳实践：14 个可复用的 Agent Skills 设计模式

Ch04.030 Anthropic 官方技能最佳实践：14 个可复用的 Agent Skills 设计模式

📊 Level ⭐⭐ | 30.1KB | entities/anthropic-14-skill-patterns-best-practices.md

Anthropic 官方技能最佳实践：14 个可复用的 Agent Skills 设计模式

作者： 兔兔AGI / 技术极简主义 来源： 微信公众号 发布时间： 2026-04-22 11:23 江苏 在上一篇文章里，我们从 Claude Code 的源码中提炼了 12 种 Agent Harness 设计模式，主要关注的是智能体在底层是怎么运作的。接下来换个视角，往上看一层：当你真正去写一个扩展 Claude 的技能时，有哪些模式会反复出现？ 在 Agent Skills 的生态中，技能大致可以分为两类。 一类是任务型技能（通常设置 disable-model-invocation: true），对应一整套步骤化流程，比如部署、提交或安全审查，用户一般通过 /skill-name 直接触发。 另一类是参考型技能（用户不可直接调用），更像是背景知识，比如风格指南或领域术语，Claude 会在相关场景下自动应用。 本文基于 Anthropic 官方的技能编写最佳实践，总结了 14 个可以复用的设计模式，分为五类：发现与选择、上下文经济、指令校准、工作流控制和可执行代码。

一、发现与选择

技能写出来没人用，写得好有什么意义？前两个模式要解决的，就是这个「怎么被用到」的问题。

1. 激活元数据模式（Activation Metadata pattern）

当你的技能库里有几十个技能时，Claude 怎么知道该用哪一个？ 答案就在 description。但很多人把它当成「摘要」，写成类似「用于处理文档」这种模糊描述。结果就是：要么选错，要么干脆不用。 description 不是摘要，而是 Claude 做选择时最关键的信号。 在会话开始时，Claude 只能看到每个技能的 name 和 description。如果这一步没选对，后面写得再好也用不上。 一个好的 description，通常要包含三点：

  • 做什么（功能）
  • 什么时候用（触发场景）
  • 遇到哪些词要触发（关键词） Anthropic 的 skill-creator 甚至建议把 description 写得「更主动」一点，因为 Claude 本身有点「触发不够」的倾向。比如：「即使用户没有明确提到仪表盘，只要提到数据可视化或内部指标，就应该触发这个技能」。 适用场景：所有技能都应该用这个模式。入口没做好，后面都没意义。 权衡点：在开放的 Agent Skills 规范中，description 上限是 1024 字符；在 Claude Code 里，description 和可选的 when_to_use 一起最多 1536 字符。空间有限，每句话都要在「触发词、排除条件和领域关键词」之间做取舍。

2. 排除条款模式（Exclusion Clause pattern）

只说「什么时候用」还不够，还要说明「什么时候不用」。 比如你同时有一个「文档处理」和一个「代码生成」技能，如果它们都写成「处理所有文本相关任务」，Claude 很难判断该选哪个。 正向触发是把它拉进来，排除条款是把它推出去。 Ruben Hassid 把排除条款称为「description 里最关键的一行」，甚至比正向触发更重要。 一个好的排除条款，通常会说清楚：

  • 哪些场景不适用
  • 哪些内容更应该交给其他技能
  • 哪些情况直接用 Claude 就够了 比如：「不要用于博客文章、通讯邮件、推文或长篇内容。」 还有一个容易被忽略的点：排除条款不是单独存在的，它需要和整个技能库一起考虑。否则就可能出现两个技能都说「我能做」，或者都说「我不做」。 适用场景：几乎所有技能，尤其是和其他技能有重叠的那些。 权衡点：维护成本。技能一多，排除条款也需要跟着调整，否则很容易出现冲突或空白区。

二、上下文经济

上下文窗口是个共享资源，每个 token 都在和其他技能、对话历史以及当前请求抢空间。

3. 上下文预算模式（Context Budget pattern）

很多技能喜欢从头解释一遍：什么是 PDF、什么是库、JSON 是怎么工作的——但这些 Claude 本来就知道。这种冗余一旦在几十个技能里重复出现，上下文窗口在用户开口之前就已经被占掉一大半。 默认前提：Claude 是聪明的。 这个模式的核心是：每一段话都要配得上它占用的 token。如果删掉一句话不会让一个「足够聪明的读者」困惑，那它大概率就是多余的。 另外还有两个容易忽略的点：

  • 术语要统一：选一个说法就一直用，比如只用 field，不要来回切换 field / box / element
  • 避免时间敏感表达：像「2025 年 8 月之前」这种描述，很快就会过时。更好的做法是把这类信息放到「旧模式」的附录里 适用场景：所有技能的基础要求，可以当作默认纪律。 权衡点：如果你的技能要兼容多个模型，就要按最弱模型来决定细节程度——对 Sonnet 来说刚好的简洁，对 Haiku 可能就偏简略了。

4. 渐进式披露模式（Progressive Disclosure pattern）

很多人会把所有内容一股脑塞进 SKILL.md：不管用户问什么，几百行甚至上千行内容一次性全加载。表格、API 文档、示例代码——不管用不用，都占着上下文。 核心思路是：把 SKILL.md 当成目录，而不是仓库。 具体做法一般是：

  • 主文件尽量控制在 500 行以内
  • 把细节拆到不同文件（比如 FORMS.md、REFERENCE.md、reference/finance.md）

  • 只在需要的时候再加载这些文件 还有两个实用技巧：

  • scripts/ 里的脚本可以执行，但不会被加载进上下文，所以里面的实现细节通常不会占 token

  • 对于特别长的参考文件，在顶部加目录（TOC），这样即使读取被截断，Claude 也能知道整体结构 适用场景：当 SKILL.md 超过 ~300 行时，基本就该考虑拆分了。 权衡点：拆分带来的复杂度。文件多了之后，不仅作者更难把控全局，Claude 也需要做「下一步该加载哪个文件」的判断，一旦选错，就会多走几轮。

三、指令校准

指令到底该写多细？写得太死，会限制发挥；写得太松，又容易跑偏。下面这几个模式，主要就是在这两者之间找平衡。

5. 控制调优模式（Control Tuning pattern）

有些技能会把每一步都写死，结果一遇到需要灵活处理的情况，Claude 反而被卡住。反过来，如果指令太模糊，在那些「错一步就全错」的场景里，又很容易出问题。 这个模式的核心是：根据任务的脆弱程度来决定指令该有多严格。 可以一直问自己一个问题：这里能接受多大的偏差？

  • 高自由度（文本指令，比如「用你的判断」）：适合开放型任务，比如代码审查
  • 中自由度（伪代码、参数化步骤）：适合有流程但需要灵活调整的任务，比如部署
  • 低自由度（精确脚本、强约束，比如「不要修改」）：适合高风险操作，比如数据库迁移 语气本身也是一个调节手段。比如在开头设定角色：「你是一个更关注正确性而不是风格的资深代码审查员」。这种设定会直接影响后面的判断标准，在参考型技能里很常见。 适用场景：对每个步骤都问一句——这里允许多少偏差？ 权衡点：很多人会倾向于「写死一点更安全」，但其实只是把失败方式换了一种：从「做错」，变成「做不了」。

6. 解释原因模式（Explain-the-Why pattern）

把规则写成一串 ALWAYS / NEVER / MUST，看起来很清晰，但其实缺少上下文。Claude 可能会按字面执行，却在边界情况里用错，或者在不该严格执行的时候也机械套用。 Anthropic 的 skill-creator 甚至把这种全大写指令当作需要重构的信号。 这个模式的核心是：先说规则，再说明原因。 这样 Claude 不只是「照做」，而是能理解背后的逻辑，在规则没覆盖到的情况里也能自己做判断。 比如：「使用构造器注入。字段注入会破坏可测试性，因为需要依赖 Spring 上下文来模拟字段。」就比：「必须使用构造器注入，绝不使用字段注入。」更稳一些。前者提供了推理依据，后者只是限制行为。 适用场景：当你开始写 MUST / ALWAYS / NEVER 这类强制性规则时，就应该考虑换成这种结构。 权衡点：解释会消耗 token——对于那些真正「不能出错」的步骤（比如前面说的低自由度场景），直接命令式反而更合适；带原因的写法，更适合需要 Claude 自己做判断的地方。

7. 模板脚手架模式（Template Scaffold pattern）

像报告、提交信息、API 请求、发布说明这类输出，只要结构很重要，Claude 每次生成的「形状」往往都不太一样。 问题在于：结构其实藏在示例里，但技能本身没说清楚，所以每次都在重新「猜」。 这个模式的做法很直接：给一个带占位符的模板，让它按结构填空。 模板一般分两种：

  • 严格模板（「必须按这个结构来」）：适合数据契约、需要机器解析的场景
  • 灵活模板（「这是推荐结构，可以调整」）：适合需要一定发挥空间的文档类输出 可以简单理解为：模板定结构，示例定风格。 适用场景：只要输出有固定结构，或者后面还要被解析（不管是人还是程序），就应该用模板。 权衡点：模板越严格，越容易限制表达。在一些边缘情况里，反而可能不够用。所以如果不是给机器用，优先用灵活模板。

8. 技能内示例模式（In-Skill Examples pattern）

光靠描述，很难把语气、格式和细节说清楚。常见情况是：结构对了，但风格不对——比如提交信息用了正确的 conventional commit 前缀，但语气跟团队不一致。 这个模式的做法是：在技能里放几个输入/输出示例，让它照着对齐。 Input: [用户输入示例] Output: [期望输出示例] 和 few-shot 类似，给两到三个例子，通常比一大段说明更管用。Claude 会优先对齐示例，而不是从文字里自己猜。 可以这么理解：模板（上一个模式）解决的是结构问题；示例解决的是风格问题。两者配合使用时效果最好：模板定结构，示例定风格。 适用场景：既有结构要求、又有表达风格要求的输出，比如提交信息、发布说明、changelog、审查摘要等。 权衡点：Claude 很容易「学例子」。如果示例里带了某种习惯，它会在所有输出里复现。所以示例要尽量覆盖不同情况，而不是只给一种写法。

9. 已知陷阱模式（Known Gotchas pattern）

很多技能只覆盖「正常流程」，告诉 Claude 该怎么做，却没说哪些地方容易出错。 一旦遇到真实环境里的边缘情况——字段不存在、命令在 macOS 能跑但在 Linux 失败、库悄悄返回空结果——Claude 没有参考，就容易自己「编一个修复」。 这个模式的做法是：专门列出已知的陷阱。 在 SKILL.md 里单独加一节，把常见失败情况写清楚，比如：

  • 「扫描 PDF 可能返回空数组，需要先检查页码类型」
  • 「页面旋转必须在列提取前设置 page.rotation = 0」 在实战里，这一部分往往是一个技能最有价值的内容，因为它直接来自踩过的坑。 适用场景：已经在真实环境跑过一段时间的技能，可以根据实际问题不断补充。 权衡点：这些「陷阱」是会变化的。库升级、API 改动之后，旧问题可能已经不存在，如果不更新，反而会误导 Claude 去排查一个已经不存在的错误。

四、工作流控制

多步骤流程该怎么控制？从简单的线性步骤，到带校验的执行，再到基于计划的流程控制，复杂度是逐步增加的。

10. 执行清单模式（Execution Checklist pattern）

在多步骤流程里，常见问题不是做错，而是没做完：跳过验证、忘了当前进度，甚至提前宣布完成——「应该已经好了」，但其实只做到一半。 这个模式的做法是：把流程变成一份可勾选的清单。 让 Claude 在对话中直接使用，比如：

  • 步骤1：...
  • 步骤2：...
  • 步骤3：... 每完成一步就勾掉，没完成的会一直留在那。 关键点在于：未完成的项是「可见的」。 清单会一直出现在对话里，不只是 Claude 自己知道，也让用户一眼就能看出进度。每一轮都要面对「还有哪些没做」，自然就更难提前收工。 适用场景：超过三步的流程，尤其是那些「少一步就可能出问题」的场景。 权衡点：清单每轮都会完整出现，长对话里 token 会明显增加。对于很短的流程，用这个模式反而有点重了。

11. 自纠正循环模式（Self-Correcting Loop pattern）

在生成代码、编辑 XML、或者按规范写文档时，单次输出很容易留下问题——而这些问题，本来是技能可以发现的。 问题不在于「怎么写对」，而在于：没有人检查它写得对不对。 这个模式的做法是：引入一个显式的循环。 流程很简单：生成 → 验证 → 失败则修复 → 再验证 验证可以是：

  • 脚本（比如 python validate.py fields.json）
  • 或规则检查（比如重新对照 STYLE_GUIDE.md 一条条过） 只有通过验证，流程才结束。 适用场景：对质量要求高、且可以验证的任务，比如代码生成、配置文件、结构化输出等。 权衡点：可能不收敛。如果验证不够严格，或者 Claude 一直在同一个地方出错，就会反复循环。实际使用中需要设置重试上限，并在失败时回退给用户处理。

12. 计划-验证-执行模式（Plan-Validate-Execute pattern）

对于批量或高风险操作——比如批量改表结构、数据迁移、整篇文档重写——如果直接「上来就做」，一旦出错，很容易一路错到底。 等你发现问题时，修改可能已经应用完了，回滚成本很高。 这个模式的做法是：在「理解任务」和「执行操作」之间，加一层可验证的中间产物。 通常是一个结构化的计划（比如 JSON），流程变成：计划 → 验证 → 通过后再执行 关键点是：所有验证都发生在副作用之前。 这和前面的自纠正循环不一样——那是在结果出来之后反复修，这里是在真正动手之前，把问题提前挡住。Claude 可以在「计划」阶段反复调整；只有当计划通过验证后，才允许执行真实操作。 适用场景：批量操作、不可逆操作，或者一旦出错代价很高的任务。 权衡点：流程更重。对于简单任务（比如改两个字段），这套流程本身的成本可能比任务还高。所以更适合那些「做错了很难补救」的场景。

五、可执行代码

把一部分工作从 Claude 的推理里拿出来，交给确定性的脚本去做：运行、返回结果——要么成功，要么失败。

13. 实用工具包模式（Utility Bundle pattern）

如果每次都让 Claude 临时写验证脚本、PDF 解析器或者数据处理逻辑，不仅慢，还不太稳定，而且这些「临时代码」也在白白消耗 token。 很多时候，其实是在反复写同一套逻辑，只是细节有点不一样。 这个模式的做法是：把这些确定性的能力提前做成脚本，放到 scripts/ 里。 之后让 Claude 通过 bash 调用，而不是每次都现写一遍。好处是：进入上下文的只有脚本输出，而不是实现过程。 这些脚本本身也有几个基本要求：

  • 能自己处理常见错误，而不是把问题再丢回给 Claude
  • 要么给出合理默认（比如自动创建缺失文件），要么快速失败并说明原因
  • 常量要写清楚用途（比如「30s 超时是为了覆盖慢连接」），避免魔法数字 如果不确定哪些逻辑值得抽出来，可以简单看一下：跑几次技能，翻翻日志——哪些辅助逻辑反复被「重新写」，就应该提到 scripts/。 适用场景：确定性强、经常重复、值得单独测试的操作。 权衡点：环境依赖。脚本是在用户环境里跑的，不同机器、不同系统可能表现不一样。所以需要在 SKILL.md 里写清依赖，并尽量避免平台相关问题（比如路径写法）。

14. 自主校准模式（Autonomy Calibration pattern）

如果一个技能默认拿到一整套工具，它理论上什么都能做：写文件、跑 shell、调外部服务——哪怕它的任务其实只是读点数据。 比如一个带 Write 和 Bash 权限的安全审计技能，就算 SKILL.md 写得再严格，本身也是个隐患。 这个模式的做法是：在 YAML 里把 allowed-tools 写清楚，只给它真正需要的能力。 比如：

  • 安全审计：Read, Grep, Glob
  • 文档生成：Read, Write
  • 部署任务：只开放受限命令的 Bash 但有个容易被忽略的点：allowed-tools 更像是「预批准」，不是「硬限制」。 它可以减少审批，但不等同于沙箱。在 Claude Code 里，真正的约束还是要靠权限策略，而不是只靠这里的声明。 适用场景：只需要少量能力的技能，尤其是安全、审计、分析这类任务。 权衡点：很容易误用。如果 allowed-tools 写得太宽，其实是在放大权限；而且很多人会把「预批准」当成「已经限制」。需要严格控制时，一定要配合权限策略一起用。

总结

这 14 个模式，基本覆盖了技能设计里最容易出问题的几个关键点。 description 决定技能会不会被用到；渐进式披露决定它会占多少上下文；解释原因和已知陷阱，决定 Claude 在边界情况下能不能做出正确判断；计划-验证-执行和自主校准，则是在出问题时，把风险控制在可接受范围内。 每一个模式，背后其实都对应着一种常见的失败方式。 就像上一篇深度拆解 Claude Code：12 个可复用的 Agentic Harness 设计模式提到的，这些并不是某个产品里的技巧，而是一套正在逐渐稳定下来的方法。 无论底层模型或工具怎么变，这些原则大概率都会继续适用。

参考资源

  • Skill authoring best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
  • The Complete Guide to Building Skills for Claude: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
  • Skill Authoring Patterns from Anthropic's Best Practices: https://generativeprogrammer.com/p/skill-authoring-patterns-from-anthropics

深度分析

模式分类的认知架构

14 个模式并非散乱分布，而是围绕技能生命周期的三个核心问题组织：技能如何被选中（发现与选择）→ 技能如何传递信息（上下文经济）→ 技能如何指导行动（指令校准）→ 行动如何被控制（工作流控制）→ 行动如何执行（可执行代码）。这是一个从「入口」到「出口」的完整链路，每一类模式解决的其实是不同阶段的信息损耗问题。

触发机制的本质

激活元数据模式和排除条款模式看似在描述技能选择机制，实际上在解决一个问题：LLM 的技能调用本质上是一个「软匹配」而非「精确路由」。description 的三个组成部分（功能、触发场景、关键词）中，最容易被忽视的是「排除条件」——Ruben Hassid 将其重要性置于正向触发之上，原因在于：当多个技能都声称能处理同一类请求时，排除条款才是消除歧义的关键。这种设计哲学映射到传统的 API 设计中，类似于「白名单」思维：不仅要说明你支持什么，更要明确你不支持什么。

上下文经济的深层矛盾

渐进式披露模式解决了一个根本矛盾：模型的上下文窗口虽然大，但并非无限——更重要的是，上下文越长，推理质量往往会下降（注意力分散问题）。将 SKILL.md 视为目录而非仓库的思路，本质上是将信息检索的责任从「全量加载」转变为「按需获取」。这里有一个隐含假设：模型能够根据任务动态决定加载哪些子文件。这个假设成立的前提是主文件的 TOC 设计足够清晰，且子文件的命名与组织符合模型的认知习惯。

指令粒度的控制论

控制调优模式的核心洞察是：指令的严格程度应该与任务的容错空间成正比。这引出了一个重要的设计原则——「自由度梯度」。对于开放性任务（如代码审查），高自由度允许模型调用其内在能力；对于高风险操作（如数据库迁移），低自由度确保行为可预测。中间地带的「伪代码化步骤」实际上是一种结构性约束：它告诉模型「有哪些步骤」但不规定「每步怎么做」，从而在结构保证和灵活执行之间取得平衡。

模板与示例的双重功能

模板脚手架模式和技能内示例模式分别解决输出的「结构一致性」和「风格一致性」。这两者的区别在于：模板解决的问题是「输出格式对不对」（机器可读性），示例解决的问题是「输出风格对不对」（人可读性）。当模板和示例结合使用时，模板提供骨架，示例提供血肉。但这里有一个微妙的陷阱：Claude 容易过度拟合示例中的风格特征，即使这些特征是任务无关的（比如提交信息中的语气偏好）。

工作流控制的层次

执行清单模式、自纠正循环模式和计划-验证-执行模式构成了一个控制粒度的递增序列。执行清单解决的是「漏做」问题（确保步骤完整性），自纠正循环解决的是「做错」问题（通过验证修复结果），计划-验证-执行解决的是「做坏」问题（在副作用发生前拦截高风险操作）。三者的共同特点是：通过引入外部记忆（对话中的清单、验证脚本、结构化计划）来补偿模型单次推理的局限性。

工具权限的最小化原则

自主校准模式指向了一个在传统软件开发中也经常被忽视的原则：最小权限原则。在 LLM Agent 的语境中，「预批准」不等于「硬限制」这一洞察非常重要——它提醒我们，allowed-tools 的限制是信息层面的，而不是执行层面的。真正的安全边界需要通过基础设施层面的权限策略来实现，而非仅仅依赖技能描述中的字段声明。

实践启示

设计优先级

在从头设计一个新技能时，应该按以下顺序考虑：先确保技能会被正确触发（description 的三元结构 + 排除条款），再确保上下文消耗合理（渐进式披露），然后才是指令的具体写法。这个优先级反映了信息流动的方向：入口选错，后续优化毫无意义。

Description 写作的检查清单

撰写 description 时，应该逐一检查：是否说了「做什么」（不是模糊的「处理文档」而是具体的「从 PDF 中提取结构化数据并转换为 JSON」）、是否说了「何时触发」（「当用户提到数据分析或可视化时」）、是否说了「关键词」（「包括仪表盘、图表、KPI」）、是否说了「何时不用」（「不适用于纯文本编辑或博客写作」）。一个检测标准：如果 description 不能让一个不了解该技能的人判断出「这个场景该不该用」，那就是不够清晰。

渐进式披露的实施步骤

当 SKILL.md 接近 300 行时，应该开始拆分。具体做法：第一步，识别哪些是「默认需要」的（基础指令、角色设定），哪些是「按需加载」的（API 文档、参考示例、工具脚本）；第二步，将按需加载的内容移到独立文件，主文件只保留目录（TOC）和必要的说明；第三步，在主文件中使用清晰的锚点标记，如 <!-- 参考资料：见 FORMS.md -->。对于超过 500 行的主文件，拆分几乎是必须的。

指令校准的梯度实践

对于每个指令步骤，在编写时应该明确回答：这个步骤能接受多大偏差？如果偏差是不可接受的（如数据迁移中的字段类型），用精确脚本；如果偏差是可接受的（如报告的撰写风格），用文字描述加示例。检查自己是否过度使用 MUST/ALWAYS/NEVER这类强制指令——如果一个规则没有解释原因，它很可能缺少必要的上下文边界。

模板和示例的配置建议

模板配置优先选择灵活模板而非严格模板，除非输出需要机器解析。示例配置应该覆盖不同输入类型，而不仅仅是一种典型情况——两到三个示例比一个详细示例更有效。对于高度格式化的输出（如 JSON），考虑同时提供模板（结构）和示例（具体值），让模型既能理解格式约束，也能理解语义约束。

工具包的维护策略

将 scripts/ 理解为技能的「确定性子系统」——这里存放的是经过测试、不会因调用方式不同而变化的逻辑。脚本应该具备：自动处理常见错误（而非让错误向上传播）、快速失败并提供清晰错误信息、无魔法数字（所有阈值都有注释说明）。建议为每个脚本编写简单的测试用例，并在 SKILL.md 中注明依赖环境。

权限配置的防御性思维

allowed-tools 的配置应该遵循「功能最小化」而非「先用后收紧」——后者容易导致权限蔓延。配置完成后，应该模拟一个恶意或者误用的场景，思考：如果这个技能被用于超出其设计目标的任务，现有的工具权限会造成多大风险？这个思维实验能够帮助发现潜在的安全盲点。

相关实体