Anthropic 官方 14 种 Skill 设计模式¶

Ch01.283 Anthropic 官方 14 种 Skill 设计模式¶

📊 Level ⭐⭐ | 13.0KB | entities/skill-design-patterns-anthropic.md

Anthropic 官方 14 种设计模式（5 大类）¶

来源： Anthropic 官方技能编写最佳实践，原文存档与上面 5+1 种社区模式（提炼自顶级 Skill 仓库）互补，这 14 种模式来自 Anthropic 官方的最佳实践文档，按 技能生命周期组织：从触发到执行到校准。

第一类：发现与选择（Discovery & Selection）¶

决定技能「怎么被用到」。 模式 1：激活元数据（Activation Metadata）

description 不是摘要，是 Claude 做选择时最关键的信号
好 description = 做什么（功能）+ 什么时候用（触发场景）+ 哪些词要触发（关键词）
Anthropic 建议写得「更主动」：Claude 有「触发不够」的倾向
上限：开放规范 1024 字符，Claude Code 中 description + when_to_use 共 1536 字符 模式 2：排除条款（Exclusion Clause）
不说「什么时候用」还要说「什么时候不用」
Ruben Hassid：排除条款是 description 里最关键的一行
排除内容：不适用场景、应交给其他技能的场景、直接用 Claude 就够的场景
维护成本：技能一多，排除条款也要跟着调整

第二类：上下文经济（Context Economy）¶

控制技能对上下文窗口的占用。 模式 3：上下文预算（Context Budget）

默认前提：Claude 是聪明的（不需要从头解释常识）
每一段话都要配得上它占用的 token
术语统一、避免时间敏感表达 模式 4：渐进式披露（Progressive Disclosure）
SKILL.md 是目录不是仓库，主文件控制在 500 行以内
细节拆到不同文件，只在需要时加载
scripts/ 不占上下文
触发点：SKILL.md 超过 ~300 行就该考虑拆分

第三类：指令校准（Instruction Calibration）¶

在「写太死」和「写太松」之间找平衡。 模式 5：控制调优（Control Tuning）

按任务脆弱程度决定指令严格度
三档自由度：高（文本指令「用你的判断」）→ 中（伪代码、参数化步骤）→ 低（精确脚本、强约束）
语气本身是调节手段（如「你是一个更关注正确性而不是风格的资深审查员」）
常见误区：写死更安全 → 实际只是把失败方式从「做错」变成「做不了」 模式 6：解释原因（Explain-the-Why）
先说规则，再说明原因：让 Claude 理解逻辑而非机械执行
Anthropic 把 ALL CAPS 指令视为重构信号
「使用构造器注入。字段注入会破坏可测试性，因为需要依赖 Spring 上下文来模拟字段。」优于「必须使用构造器注入，绝不使用字段注入。」
适用：需要 Claude 自己做判断的地方；不适用于「不能出错」的低自由度步骤 模式 7：模板脚手架（Template Scaffold）
给带占位符的模板，让 Claude 按结构填空
严格模板（数据契约/机器解析）vs 灵活模板（文档类输出）
模板定结构，示例定风格 模式 8：技能内示例（In-Skill Examples）
放 2-3 个输入/输出示例让 Claude 对齐风格
和 few-shot 类似，示例比文字说明更管用
注意：Claude 容易「学例子」，示例要覆盖不同情况 模式 9：已知陷阱（Known Gotchas）
在 SKILL.md 单独加一节列出常见失败情况
往往是技能最有价值的内容（来自真实踩坑）
陷阱会变化：库升级、API 改动后需更新

第四类：工作流控制（Workflow Control）¶

多步骤流程的控制方式。 模式 10：执行清单（Execution Checklist）

把流程变成可勾选的清单，未完成项始终「可见」
解决的核心问题：不是做错，而是没做完
每轮出现在对话中，让用户也能看到进度 模式 11：自纠正循环（Self-Correcting Loop）
生成 → 验证 → 失败则修复 → 再验证
验证可以是脚本或规则检查
需要设重试上限，避免不收敛 模式 12：计划-验证-执行（Plan-Validate-Execute）
在理解任务和执行操作之间加一层可验证的中间产物（如 JSON 计划）
所有验证发生在副作用之前（与自纠正循环的核心区别）
适合批量操作、不可逆、代价高的任务

第五类：可执行代码（Executable Code）¶

把确定性工作交给脚本。 模式 13：实用工具包（Utility Bundle）

把反复「重新写」的辅助逻辑提前做成脚本，放到 scripts/
脚本要求：自处理错误、合理默认或快速失败、常量有用途说明
判断标准：翻翻日志——哪些辅助逻辑反复被「重新写」 模式 14：自主校准（Autonomy Calibration）
在 YAML 里用 allowed-tools 明确技能仅需的能力
注意：allowed-tools 是「预批准」不是「硬限制」，真正约束要靠权限策略
容易被误用：写太宽 = 放大权限

与社区模式的关系¶

维度	社区模式（5+1 种）	Anthropic 官方模式（14 种）
来源	7 个顶级 Skill 仓库	Anthropic 官方最佳实践文档
组织方式	按流程结构（线性/决策树/循环等）	按生命周期阶段（触发→上下文→指令→流程→代码）
覆盖	宏观流程决策	微观编写决策 + 宏观流程
互补	偏「选哪种」	偏「怎么写好」
重叠	循环迭代 ↔ 自纠正循环（类似）	渐进式披露两者都有
最佳实践：用社区模式的决策树选型，用 Anthropic 模式的编写原则指导具体实现。
→ 返回总览

深度分析¶

系统性视角：5 类模式的内在逻辑¶

Anthropic 的 14 种模式并非孤立的技巧，而是一条从「触发」到「执行」再到「校准」的完整链路。

发现与选择（模式 1-2）：解决技能「何时被调用」的问题。description 和排除条款是最早影响 Claude 决策的两个信号，写好它们等于给技能装了正确的「入口过滤器」。
上下文经济（模式 3-4）：解决技能「占用多少上下文」的问题。Claude 的上下文窗口是共享资源，预算思维和渐进式披露能防止技能在大型对话中成为负担。
指令校准（模式 5-9）：解决「指令怎么写才有效」的问题。这是 Anthropic 模式中最密集的一类，涵盖自由度控制、原因解释、模板、示例和已知陷阱——本质上是把人类的隐性知识转化为显性的工程约束。
工作流控制（模式 10-12）：解决多步骤任务的「过程可信度」问题。执行清单让进度透明，自纠正循环处理反馈驱动的不稳定过程，计划-验证-执行则预防不可逆错误的代价在事后才显现。
可执行代码（模式 13-14）：解决「确定性工作谁来干」的问题。工具包把反复「重新写」的辅助逻辑提前固化，权限校准则在 YAML 层控制技能的能力边界。

核心张力：自由度 vs 确定性¶

Anthropic 模式在「写太死」和「写太松」之间的张力贯穿始终，这体现在： 控制调优（模式 5）本身是矛盾的：它要求按任务脆弱程度决定指令严格度，但紧接着解释原因（模式 6）又说「先说规则再说原因」。两者并不冲突——模式 6 是「如何写规则」的方法论，模式 5 是「写多严」的裁量权。真正的张力在于：当一个规则无法用原因说服 Claude 时，强制执行（低自由度）可能是唯一选择，但此时恰恰违背了「先说 Why」的原则。实践中，这个张力在「低风险高判断」场景（如文本编辑风格）最容易被化解：规则写宽松，理由写清晰。 ALL CAPS 作为重构信号：Anthropic 把大写指令视为重构信号，这个洞察很实用——大写往往说明作者在传递规则而非解释原因。当规则能够被理解时，强制执行就不必要了。

渐进式披露 vs 上下文预算：一个优化两个方向¶

渐进式披露（模式 4）和上下文预算（模式 3）看似都在「省上下文」，实则针对不同问题：

渐进式披露解决的是初始加载成本：SKILL.md 太大导致首次激活慢
上下文预算解决的是持续消耗成本：每一段话占用 token 影响对话质量两者的边界都在于：拆得太碎破坏上下文连贯性，卡得太紧损失必要的背景知识。Anthropic 给的锚点是：SKILL.md 超过 ~300 行考虑拆分，主文件控制在 500 行以内。

Anthropic 模式 vs 社区模式：互补而非竞争¶

维度	社区模式（5+1 种）	Anthropic 官方模式（14 种）
组织方式	按流程结构（线性/决策树/循环等）	按生命周期阶段（触发→上下文→指令→流程→代码）
抽象层次	具体可复用的模板	设计原则和权衡框架
优势	决策有路径、可直接套用	系统性覆盖、有量化指标
劣势	依赖案例积累、难以上升到方法论	缺少决策树、缺乏踩坑案例
两种模式的最佳结合方式：用社区模式的决策树选型（选哪种流程结构），用 Anthropic 模式的编写原则指导具体实现（怎么写好每一步）。

实践启示¶

1. 按问题域对号入座¶

写技能之前先问：我的技能最可能失败在哪个环节？

失败在「选错了」→ 先优化 description（模式 1）和排除条款（模式 2）
失败在「上下文爆了」→ 先检查是否违反预算原则（模式 3）和是否需要拆分（模式 4）
失败在「不听指令」→ 检查自由度选择（模式 5）和是否该用原因解释替代强制（模式 6）
失败在「做了一半」→ 清单模式（模式 10）可能最有效
失败在「不可逆错误」→ 计划-验证-执行（模式 12）而非自纠正循环

2. description 的三层结构¶

Anthropic 强调 description 是「最关键的信号」，实践中最有效的三层结构： 1. 做什么：一句话功能描述（10-15 词） 2. 什么时候用：触发场景描述（20-30 词） 3. 什么词触发：关键词/排除词好 description 的反面不是「没有 description」，而是「把 description 写成说明书」——把功能拆解写成操作手册是 SKILL.md 的任务，不是 description 的任务。

3. ALL CAPS 检查表¶

每次写完 SKILL.md，都做一次 ALL CAPS 扫描：对每个大写指令问——

这个规则能「先说 Why」吗？
如果说了 Why，Claude 还能做对吗？
如果能，这个大写指令就是重构候选把「必须」「禁止」「只能」翻译成原因说明，往往会发现规则本身可以更优雅。

4. 渐进式披露的执行信号¶

什么时候该拆文件？Anthropic 给了两个锚点：

SKILL.md 超过 ~300 行：考虑拆分
SKILL.md 接近 500 行：必须拆分拆分的单位不是「任意分段」，而是「相对独立的子主题」。每次拆分后检查：新文件是否能在不读其他文件的情况下理解大意？如果不能，拆分粒度可能太细了。

5. 工具包反推法¶

「实用工具包（模式 13）」的判断标准是「哪些辅助逻辑反复被重新写」。实操方式：翻技能的使用日志，找那些「每次都要查一下上次怎么写的」的模式——那些就是工具化的候选。好工具的标准：自处理错误、合理默认或快速失败、常量有用途说明。

6. 权限校准的最小化原则¶

「自主校准（模式 14）」容易被误用：allowed-tools 写得比实际需要的宽，等于给技能开了多余的权限门。原则：只写实际需要的最小权限集，定期审计「上次用是什么时候」。

7. 模式组合清单¶

以下是典型场景的模式组合推荐： | 场景 | 推荐模式组合 | |------|-------------| | 新技能启动 | 模式 1、2、3、7、8 | | 多步骤复杂任务 | 模式 10、11 或 12 | | 高风险不可逆操作 | 模式 12（Plan-Validate-Execute） | | 高频使用的技能 | 模式 13（工具包）+ 模式 9（已知陷阱） | | 调试/修复已有技能 | 模式 6（解释 Why）+ ALL CAPS 扫描 |