如果你用过 Claude Code、Gemini CLI 或者 Cursor，大概已经见过 SKILL.md 这个东西。它是一种把 AI 能力打包成可复用模块的文件格式，现在已经成了 Agent 技能的事实标准——不只是这几个工具，OpenAI Codex、GitHub Copilot、VS Code Insiders、Trae，还有更多工具都在用同一套规范。有人把这个时刻比作 AI Agent 领域的 npm 时刻：写一次技能，部署到整个生态。

但格式标准化只解决了"怎么打包"的问题，没解决"里面的逻辑该怎么组织"。

一个教 Agent 写 FastAPI 代码的技能，和一个四步文档生成管道，从 SKILL.md 的外壳看起来没什么区别——都是 YAML 元数据加一段指令文本。区别在内部：它们的工作方式完全不同，适用场景也完全不同。如果你把管道逻辑写成了工具包装器的风格，Agent 会乱套；如果你把简单的知识注入写成了复杂的多阶段管道，就是在给自己找麻烦。

通过研究 Anthropic、Vercel 和 Google 内部的技能设计实践，有 5 种反复出现的模式值得认识。它们不是什么高深理论，更像是一套命名好的直觉——一旦你知道它们的名字，就会开始在各处认出它们。

---

先理解一个底层机制：渐进式披露

在介绍 5 个模式之前，有个机制值得先说清楚，因为它是整套设计的基础。

Agent Skills 的加载不是一次性的。它分三层：启动时只加载元数据（name + description，大约 50 个 token）；当用户的请求和技能描述匹配时，才加载完整的 SKILL.md 指令（2000-5000 token）；执行过程中，references/ 和 assets/ 目录下的文件按需读取，不用的步骤根本不占上下文窗口。

这意味着你可以把大量知识分散存放，Agent 只在真正需要的时候才去取。这是 5 个模式里很多设计决策的来源——“为什么要把检查清单放到 references/ 而不是直接写在指令里”，答案就是这个。

---

模式一：工具包装器

这是最简单的模式，也是最常见的起点。

核心思路是：把某个领域的知识或约定封装进技能，让 Agent 在处理相关任务时自动调用这些知识，就像给它装了一个专家大脑。

最典型的用法是把团队内部的编码规范塞进工作流。比如你有一套 FastAPI 的最佳实践文档，以前每次 Code Review 都要手动对照，现在可以这样写：

---
name: api-expert
description: FastAPI development best practices and conventions.
metadata:
  pattern: tool-wrapper
  domain: fastapi
---

你是FastAPI开发专家。把这些约定应用到用户的代码中。

## 核心约定
加载 'references/conventions.md' 获取完整的最佳实践列表。

## 代码审查时
1. 加载约定参考文档
2. 检查用户代码是否符合每条约定
3. 每次违规，引用具体规则并建议修复方式

注意"加载 references/conventions.md"这个指令——这就是渐进式披露在起作用。完整的约定文档只在 Agent 真正需要审查代码时才进入上下文，平时不占位置。

工具包装器适合的场景：某个库或框架的最佳实践、团队内部规范、特定领域的专业知识。判断标准很简单：如果你的技能本质上是在回答"怎么正确地做 X"，那它就是工具包装器。

---

模式二：生成器

工具包装器是"应用知识"，生成器是"强制输出结构"。

如果你有这样的痛点——每次让 Agent 生成文档，结构都不一样，有时候有摘要有时候没有，有时候用一级标题有时候用二级标题——生成器模式能根治这个问题。

它的工作方式是：把输出模板放在 assets/ 目录，把风格指南放在 references/ 目录，然后指令扮演一个项目经理的角色，让 Agent 先读模板、再读风格指南、然后向用户收集缺失的变量、最后填空。

---
name: report-generator
description: 生成结构化技术报告
metadata:
  pattern: generator
  output-format: markdown
---

你是技术报告生成器。严格按步骤执行：

第一步：加载 'references/style-guide.md' 获取语气和格式规则
第二步：加载 'assets/report-template.md' 获取输出结构
第三步：问用户获取填充模板所需的缺失信息：
- 主题
- 关键发现或数据点
- 目标受众（技术/执行/普通）
第四步：按风格指南规则填充模板。模板中每个章节都必须出现在输出中。
第五步：返回完整的Markdown文档

这里有个细节值得注意：第三步是主动问用户要信息，而不是让 Agent 自己猜。这个设计防止了 Agent 用假设填充模板，生成看起来完整但实际上是编造的内容。

生成器的适用场景很广：API 文档、标准化的 commit message、项目 README、周报模板……任何"格式比内容更重要"的场景都适合。

---

模式三：审查员

审查员模式做了一件很聪明的事：把"检查什么"和"怎么检查"分开。

传统的做法是把所有检查规则直接写在系统提示词里，结果是一个又长又脆弱的指令块——规则一多就容易互相干扰，更新一条规则要小心翼翼地不破坏其他的。审查员模式把评估标准模块化，放到 references/review-checklist.md，指令只负责描述检查流程。

---
name: code-reviewer
description: 审查Python代码质量、风格和常见bug
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---

你是Python代码审查员。严格按协议执行：

第一步：加载 'references/review-checklist.md' 获取完整审查标准
第二步：仔细读用户代码。理解它的目的再批评
第三步：把清单上的每条规则应用到代码上。每次违规：
- 标注行号或大概位置
- 分类严重程度：error（必须修）、warning（应该修）、info（可以考虑）
- 解释WHY，不只是WHAT
- 给出具体修复建议和正确代码

第四步：生成结构化审查报告，包含摘要、发现列表、评分和前3条建议

这个设计的扩展性很好。你把 references/review-checklist.md 里的 Python 风格清单换成 OWASP 安全清单，就得到了一个安全审计工具——SKILL.md 的指令部分一个字不用改。这就是把"检查逻辑"和"检查标准"解耦的好处。

实际应用场景：自动化 PR 审查、在人工 Review 之前先过一遍机器检查、安全漏洞扫描、文档质量评估。

---

模式四：反转

前三个模式都是 Agent 收到任务就开始干活。反转模式把这个动态倒过来——Agent 先变成面试官。

这个模式的核心洞察是：Agent 天生喜欢猜、喜欢立刻生成。给它一个模糊的需求，它会用假设填满所有空白，然后交给你一个看起来完整但其实偏差很大的结果。反转模式用明确的、不可协商的门槛指令来对抗这个倾向。

---
name: project-planner
description: 通过结构化问题收集需求后再生成计划
metadata:
  pattern: inversion
  interaction: multi-turn
---

你正在进行结构化需求访谈。在所有阶段完成前不要开始构建或设计。

## 阶段1——问题发现（一次问一个问题，等每个回答）
- Q1: "这个项目为用户解决什么问题？"
- Q2: "主要用户是谁？技术水平如何？"
- Q3: "预期规模是多少？"

## 阶段2——技术约束（只有在阶段1完全回答后才问）
- Q4: "你会用什么部署环境？"
- Q5: "有什么技术栈要求或偏好吗？"
- Q6: "有什么不可妥协的需求？"

## 阶段3——合成（只有在所有问题都回答后才执行）
1. 加载 'assets/plan-template.md' 获取输出格式
2. 用收集到的需求填充模板
3. 展示完成的计划，问用户是否准确
4. 根据反馈迭代，直到用户确认

关键是那句"在所有阶段完成前不要开始构建或设计"——这是一个硬性禁令，不是建议。没有这句话，Agent 很可能在阶段 1 结束后就迫不及待地开始生成计划了。

反转模式适合需求模糊、上下文复杂的任务：项目规划、架构设计、需求分析。任何"如果信息不完整，结果会差很多"的场景都值得考虑用这个模式。

---

模式五：管道

管道是这 5 个模式里最复杂的，也是最适合处理复杂任务的。

它的核心理念是：指令本身就是工作流定义。通过明确的顺序步骤和硬性检查点，管道确保 Agent 不会跳过步骤、不会在前一步没完成的情况下进入下一步。

---
name: doc-pipeline
description: 通过多步管道从Python源码生成API文档
metadata:
  pattern: pipeline
  steps: "4"
---

你在运行文档生成管道。按顺序执行每一步。不要跳过步骤，也不要在步骤失败后继续。

## 步骤1——解析和清点
分析用户的Python代码，提取所有公开的类、函数和常量。
把清单以检查列表形式呈现。问："这是你想文档化的完整公开API吗？"

## 步骤2——生成Docstring
对每个缺少docstring的函数：
- 加载 'references/docstring-style.md' 获取所需格式
- 严格按照风格指南生成docstring
- 展示每个生成的docstring，等待用户确认
只有在用户确认后才能进入步骤3。

## 步骤3——组装文档
加载 'assets/api-doc-template.md' 获取输出结构。
把所有类、函数和docstring编译成单个API参考文档。

## 步骤4——质量检查
对照 'references/quality-checklist.md' 检查完整性。
报告结果，在展示最终文档前修复问题。

注意步骤 2 末尾那句"只有在用户确认后才能进入步骤 3"——这是一个明确的门条件，也叫菱形门。它强制在关键节点引入人工确认，防止 Agent 用一个有问题的中间结果继续往下走，最后交出一个表面完整但内部错误的输出。

管道模式还有一个上下文管理上的好处：每个步骤只在需要时才加载对应的参考文件，整个执行过程中上下文窗口保持干净。这对于长流程任务尤其重要。

---

怎么选

5 个模式各自回答一个不同的问题：

• 你的任务是"把某个领域的知识应用到用户输入上"？→ 工具包装器
• 你的任务是"生成格式一致的输出"？→ 生成器
• 你的任务是"系统性地评估某个输入"？→ 审查员
• 你的任务需要大量上下文才能做好，但用户通常不会主动提供？→ 反转
• 你的任务有多个必须按顺序执行的步骤，中间需要人工确认？→ 管道

如果你的任务同时符合多个描述，那就组合使用。这 5 个模式不是互斥的。管道的最后一步可以嵌入一个审查员来 double-check 自己的输出；生成器可以在开头依赖反转来收集填充模板所需的变量。组合是常态，不是例外。

---

这套模式解决的真正问题

回到最开始的问题：为什么不直接把所有指令塞进系统提示词？

技术上当然可以。但系统提示词是一个平面结构，所有内容同时存在于上下文里，相互干扰，难以维护，更新一个地方容易破坏其他地方。更重要的是，它不可复用——你为一个项目写的 FastAPI 约定，没法直接拿到另一个项目用。

SKILL.md 加上这 5 个模式，本质上是在给 Agent 的能力做模块化设计：关注点分离（指令、知识、模板各放各处）、按需加载（渐进式披露）、可复用（跨工具、跨项目）。

这不只是工程上的整洁，它影响的是 Agent 的可靠性。一个结构清晰的技能，Agent 更不容易跑偏；一个把知识分层存放的技能，Agent 更不容易因为上下文过长而遗忘关键指令。

从这个角度看，选择正确的设计模式，其实是在选择你愿意为 Agent 的行为承担多少不确定性。

---

本文基于 Shubham Saboo 和 Lavini Gam 在 Google Cloud Tech 发布的文章，参考了 Anthropic、Vercel 和 Google 内部的技能设计实践。相关资源可在 awesome-agent-skills 仓库找到。