Skill 设计模式¶

Ch07.002 Skill 设计模式¶

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

Overview¶

从 7 个顶级 Skill 仓库（OpenAI/anthropic/Google Labs/Dean Peters/Trail of Bits）中提炼出的 5 种核心设计模式 + 1 种特殊模式。为 Agent Skill 开发提供系统性框架选择指南，告别"怎么写都行"的随意性。 核心价值： Skill 本质是"知识注入"——不生成新工具，而是把指令文本注入 LLM 上下文，让 LLM 用已有工具执行指令。模式选择决定了知识如何组织、触发条件如何声明、执行流程如何控制。

5 种核心设计模式¶

模式 1：线性流程（Linear）¶

适用： 有明确步骤的操作（部署、安装、迁移） 结构： Prerequisites → Quick Start（Step 1→2→3）→ Fallback → Troubleshooting 代表案例： vercel-deploy（77 行） 关键技巧：

• 安全默认值："Always deploy as preview, not production"
• 具体命令：每步给出可直接执行的 bash 命令
• 超时提示："Use a 10 minute (600000ms) timeout"
• 降级方案：CLI 失败有 Fallback 脚本
• 负面指令："Do not curl the deployed URL to verify"

模式 2：决策树 + 按需加载（Decision Tree）¶

适用： 大型平台选型、产品导航、问题诊断 结构： Authentication → Quick Decision Trees（按用户意图分类）→ Product Index 代表案例： cloudflare-deploy（224 行）、cloudflare（211 行，导航型） 关键技巧：

• 用户意图分类："I need to run code" 而非 "Compute products"
• 树形导航：├─ 边缘无服务器函数 → workers/
• 渐进式披露：主文件 7KB，references/ 按需展开到几十万字
• 产品索引表：Product → Reference 映射表 进阶： 导航型（只做选型）和操作型（包含认证+命令+故障排除）可拆分为两个 Skill。

模式 3：循环迭代（Iterative Loop）¶

适用： TDD、代码审查、设计评审等反复执行"做→验证→改进"的流程 结构： Red-Green-Refactor 循环 + 借口反驳表 + 验证清单 代表案例： test-driven-development（371 行，obra/superpowers） 关键技巧：

• 强硬语气："Delete it. Start over." 提高 LLM 遵从率
• Good/Bad 对比：用 <Good> 和 <Bad> 标签包裹代码示例
• 借口反驳表：预判 LLM 的 12 种偷懒借口并逐一反驳
• 验证清单：8 项 checklist 作为循环退出条件
• 人类兜底："ask your human partner"

模式 4：接力棒循环（Baton / Cross-Session Persistence）¶

适用： 跨多个 session 持续推进的长期项目（天~周级别） 结构： 6 步执行协议（读接力棒→查阅上下文→执行→集成→更新文档→写下一个接力棒） 代表案例： stitch-loop（203 行，google-labs-code） 关键技巧：

• 文件即状态：next-prompt.md 作为接力棒，LLM 不需记住"上次做到哪"
• 续命机制：Step 6 标记为 Critical + MUST，忘了写接力棒循环就断了
• 编排无关：CI/CD、人在回路、Agent 链都能驱动 与模式 3 的核心区别： 状态存储在外部文件系统而非 LLM 对话上下文，支持跨 session。 | 维度 | 循环迭代（TDD） | 接力棒循环 | |------|----------------|-----------| | 状态存储 | LLM 对话上下文 | 外部文件系统 | | 跨 session | ❌ | ✅ | | 循环退出 | Checklist 全部打勾 | 路线图清空 | | 适用时长 | 分钟~小时 | 天~周 |

模式 5：多阶段 + 检查点 + Skill 编排（Multi-Phase）¶

适用： 复杂的多周流程，有明确阶段划分和 Go/No-Go 决策点 结构： Phase（Activities → Outputs → Decision Point）× N 阶段 + Complete Workflow + Common Pitfalls 代表案例： discovery-process（502 行，deanpeters/Product-Manager-Skills） 关键技巧：

• 统一阶段模板：每个 Phase 都有 Activities → Outputs → Decision Point
• 决策检查点："达到饱和了吗？YES → 下一阶段，NO → +1 周"
• Skill 编排：调度 10+ 个子 Skill 完成各阶段（编排器模式）
• 时间影响：每个 NO 路径标注 "+2-3 days"、"+1 week"

特殊模式：思维框架（Thinking Framework）¶

适用： 安全审计、代码审查、架构分析等需要深度思考而非快速执行的场景 代表案例： audit-context-building（302 行，trailofbits/skills） 核心定位： 控制 LLM"怎么想"而非"做什么"——不生成工具调用，而是建立分析框架。 关键技巧：

• 思维工具：第一性原理、5 Why、5 How 等分析框架
• 量化阈值："每个函数最少 3 个不变量、5 个假设" 强制达到足够分析深度
• 非目标约束："不要识别漏洞、不要提出修复" 先理解再判断
• 反幻觉规则："Never reshape evidence to fit earlier assumptions"

Anthropic 14 种实现模式（5 大类）¶

详细解读参见 Anthropic 官方 14 种设计模式

发现与选择（2 模式）¶

上下文经济（2 模式）¶

指令校准（4 模式）¶

工作流控制（3 模式）¶

可执行代码（2 模式）¶

Anthropic 14 模式与 5+1 框架的对应关系¶

通用写作技巧¶

防止 LLM 偷懒的 4 种武器¶

教学的 3 种有效方式¶

知识组织的 3 层架构¶

模式选择决策树¶

你的 Skill 需要做什么？
│
├─ 执行一个有明确步骤的操作
│  └─ → 模式 1：线性流程
│
├─ 在大量选项中帮用户选择正确的方向
│  └─ → 模式 2：决策树 + 按需加载
│
├─ 在单次会话中反复执行"做→验证→改进"
│  └─ → 模式 3：循环迭代
│
├─ 跨多个 session 持续推进一个长期项目
│  └─ → 模式 4：接力棒循环
│
├─ 跨越多天/多周，有阶段划分和 Go/No-Go 决策
│  └─ → 模式 5：多阶段 + 检查点
│
└─ 需要 LLM 进行深度分析而非快速执行
   └─ → 特殊模式：思维框架

参考 Skill 仓库¶

子页面¶

• — 5 大类 14 种模式详解与写作技巧

深度分析¶

模式演进的内在逻辑¶

从 7 个顶级仓库提炼出的 5+1 种模式，并非随机排列，而是沿着控制粒度和时间跨度两个维度呈阶梯式分布。 控制粒度从「告诉 LLM 做什么」到「告诉 LLM 怎么想」：

• 模式 1-5 都在描述行为（做什么、选哪个、走哪步）

• 特殊模式（思维框架）描述的是思维方式（怎么分析、怎么验证） 时间跨度从瞬时到持久：

• 线性流程：秒~分钟级别

• 循环迭代：分钟~小时级别（单 session）
• 接力棒循环：天~周级别（跨 session）
• 多阶段检查点：周~月级别 这意味着：模式选择的核心依据不是「任务难度」，而是「需要在多长时间跨度内维持一致性」。

为何「线性流程」是入门首选¶

5 种模式里，线性流程是被引用最广的起点（vercel-deploy 仅 77 行），原因有三： 1. 失败成本低：每步有显式输出，错了容易定位 2. 上下文占用低：不需要预设循环退出条件或状态文件 3. 调试友好：TDD、审查等循环模式出问题时，往往先简化为线性步骤来隔离 bug 但线性流程的局限也最明显：它无法处理「需要根据结果调整下一步」的场景——那是循环迭代的领地。

循环迭代与接力棒的本质区别¶

两者都涉及重复，但核心差异不在「重复」本身，而在状态存储位置： | | 循环迭代（模式 3） | 接力棒循环（模式 4） | |--|---|---| | 状态存储 | LLM 对话上下文 | 外部文件系统 | | 适用场景 | 单次会话内的收敛 | 跨 session 的持久推进 | | 退出条件 | checklist 全部打勾 | 路线图清空 | | 本质 | 让 LLM 记住「这次做到哪」 | 让 LLM 继承「上次做到哪」 | 一个关键推论：如果任务本身在单次对话内就能完成，用接力棒就是过度设计；但如果任务会被人为中断（用户关闭窗口、换设备），接力棒就是唯一可靠的选择。

模式 2 的两个陷阱¶

决策树 + 按需加载（模式 2）是，看起来简单但实际上最容易踩坑的模式： 陷阱一：用户意图分类不准确 cloudflare 的导航型 Skill 把「用户意图」作为顶级分类键（「I need to run code」），这要求对用户语言有高度敏感——同一需求可能有十几种表达方式。如果分类颗粒度不够，LLM 会选错分支。 陷阱二：渐进式披露过头 主文件 7KB、references/ 按需展开到几十万字的设计，依赖 LLM 能准确判断「该加载哪个文件」。一旦判断错误，LLM 会在错误的上下文中工作，输出质量不可预测。 解决方式在 Anthropic 的渐进式披露模式里：主文件尽量控制在 500 行以内，给长参考文件加 TOC，这样即使读取被截断，LLM 也能知道整体结构。

Anthropic 14 模式的降维映射¶

Anthropic 的 14 种模式可以映射到本文的 5+1 框架： | Anthropic 分类 | 对应模式 | 核心贡献 | |---|---|---| | 发现与选择 | 模式 1 前置 | description 决定 Skill 是否被加载 | | 上下文经济 | 模式 2 按需加载 | 渐进式披露、主文件<500行 | | 指令校准 | 全部模式 | 控制调优、解释原因、模板脚手架 | | 工作流控制 | 模式 3/5 | 执行清单、自纠正循环、计划-验证-执行 | | 可执行代码 | 全部模式 | scripts/ 工具包、allowed-tools 权限控制 | 这说明：Anthropic 的 14 种模式是更细粒度的实现技巧，而 5+1 框架是更高层次的结构选择。两者不是替代关系，而是不同抽象级别的工具。

模式与上下文字节数的关系¶

知识组织的 3 层架构（Frontmatter ~100、主文件 2K-5K、references/ 每个 1K-3K、总上下文 <10K）背后有一个隐含约束： 当主文件超过 300 行时，就应该考虑拆分了（Anthropic 的渐进式披露模式建议）。这与「主文件 2K-5K tokens」的预算并不矛盾——300 行 Markdown 约等于 3K-4K tokens，正好在上限附近。 实际编写中，一个 Skill 好不好，从上下文占用就能大致判断：超过 15K tokens 的 Skill，LLM 的遵从率会显著下降。

控制粒度与 Skill 类型的关系¶

Skill 通常分为两类： 1. 任务型技能：对应整套步骤化流程，用户通过 /skill-name 直接触发，通常设置 disable-model-invocation: true 2. 参考型技能：更像背景知识，用户不可直接调用，Claude 在相关场景下自动应用 | 类型 | 典型模式 | description 要求 | |------|---------|-----------------| | 任务型 | 模式 1/3/4/5 | 清晰的动作 + 触发时机 + 关键词 | | 参考型 | 模式 2/特殊模式 | 领域边界 + 适用场景 + 排除条款 | 参考型技能对 description 的要求反而更高——因为它不能被直接调用，全靠 description 里的触发词来决定何时加载。

实践启示¶

写 Skill 前的第一问¶

在动笔之前，先问自己一个问题：这个 Skill 解决的是「不知道怎么做」，还是「容易做错」？

• 如果是「不知道怎么做」→ 优先用模式 1 或 2（线性流程或决策树）
• 如果是「容易做错」→ 优先用模式 3 或特殊模式（循环迭代或思维框架） 这个判断决定了 Skill 的整体基调：前者偏向指引，后者偏向约束。

从最小可用开始¶

快速上手模板（线性模式）只需 4 个 Section：Prerequisites → Steps → Troubleshooting。不用一上来就设计循环迭代或接力棒——先用最少的结构验证需求是否真实存在。 如果同一个 Skill 被反复使用，而且每次都是「做一半、中断、继续做」，那时再引入模式 4（接力棒循环）。 如果发现每次都在重复相同的修正（比如总是漏掉某个验证步骤），那时再引入模式 3（循环迭代）的退出清单。

description 的三个必含要素¶

Anthropic 的 Activation Metadata 模式指出：一个好的 description 必须同时包含： 1. 做什么（功能） 2. 什么时候用（触发场景） 3. 遇到哪些词要触发（关键词） 缺任何一个，Skill 被加载的概率就会下降。尤其是在 skill 库较大的情况下，description 决定了「这个 Skill 会不会被用到」。

防止 LLM 偷懒的四种武器可以组合使用¶

强硬语气、借口反驳表、量化阈值、负面指令，这四种武器并非孤立，而是可以叠加：

• 在技能开头用强硬语气（「Delete it. Start over.」）
• 在循环体内用借口反驳表堵死逃避路径
• 在验证清单里用量化阈值（最少 3 个不变量、5 个假设）
• 在边界场景用负面指令（「Do not curl the URL」） 组合效果远大于单用其一——因为 LLM 的偷懒路径是多元的，单一武器无法覆盖所有情况。

渐进式披露的实施检查¶

如果 SKILL.md 超过 300 行，按渐进式披露原则应该拆分。检查步骤： 1. 主文件是否在 500 行以内？ 2. 参考文档是否有 TOC（目录）？ 3. scripts/ 里的脚本是否不会加载到上下文？ 4. 拆分后主文件是否仍然可以独立提供核心价值？ 如果第四点不满足（即拆开后每个文件都没法单独提供价值），说明拆分粒度有问题，需要重新设计结构。

模式选择的修正时机¶

模式选择不是一锤子买卖。随着 Skill 使用的深入，需要根据实际情况修正： | 信号 | 修正方向 | |------|---------| | 每次都要手动提醒 LLM 某个步骤 | 线性流程 → 加入执行清单（模式 10） | | LLM 经常跳过验证步骤 | 线性流程 → 自纠正循环（模式 11） | | 任务需要跨越多次会话 | → 引入接力棒循环（模式 4） | | 状态文件越来越复杂 | 接力棒 → 考虑多阶段检查点（模式 5） | | LLM 在边界情况总是判断错误 | → 引入思维框架（特殊模式） | 不要试图一步到位设计最复杂的模式。从最小可用开始，根据实际使用中的失败模式逐步迭代。

工具包模式的价值实现¶

实用工具包模式（Anthropic 模式 13）的核心价值不在「写脚本」，而在「让确定性的事情不要消耗 LLM 的推理资源」。 实施检查：

• 脚本是否能自己处理常见错误，而不是把问题抛回给 LLM？
• 常量是否有注释说明用途（避免魔法数字）？
• 脚本在不同系统环境下是否能正常工作（路径、权限）？ 如果一个脚本每次运行都要 LLM 盯着看日志，它就不是一个合格的工具包。

指令校准的灵活性判断¶

控制调优模式（Anthropic 模式 5）的核心问题是：这里能接受多大的偏差？

• 高自由度（文本指令，如「用你的判断」）：适合开放型任务，如代码审查
• 中自由度（伪代码、参数化步骤）：适合有流程但需灵活调整的任务，如部署
• 低自由度（精确脚本、强约束，如「不要修改」）：适合高风险操作，如数据库迁移 很多人会倾向于「写死一点更安全」，但其实只是把失败方式换了一种：从「做错」，变成「做不了」。

解释原因 vs 直接命令的选择¶

解释原因模式（Anthropic 模式 6）的核心是：先说规则，再说明原因。 比如：「使用构造器注入。字段注入会破坏可测试性，因为需要依赖 Spring 上下文来模拟字段。」就比：「必须使用构造器注入，绝不使用字段注入。」更稳一些。 但不是所有场景都适合解释原因：

• 带原因的写法更适合需要 LLM 自己做判断的地方
• 对于真正「不能出错」的低自由度场景，直接命令式反而更合适

Related¶

• Agent Skill 编写指南 — Skill 格式、渐进式披露、编写规范、评估迭代的基础知识
• Hermes Agent — 支持 Skill 机制的核心开源 Agent
• OpenClaw 架构解析 — 内置 Skill 系统实现
• Anthropic 14 模式原始文章
• 社区模式原始文章存档

相关实体¶

• MOC
• MOC