每个 ADK 开发者都该知道的 5 种 Agent Skill 设计模式
看到谷歌官方发布的一篇文章《每个 ADK 开发者都该知道的 5 种 Agent Skill 设计模式》，我就给大家翻译了一下，真的是干货啊。
说到 Agent Skill，开发者往往把注意力放在格式上：YAML 写对了没有、目录结构对不对、有没有符合规范。但现在已经有超过 30 种 Agent 工具（比如 Claude Code、Gemini CLI、Cursor）都在用同一套格式标准，格式问题基本上已经不是问题了。
真正的难点在于内容设计。规范告诉你怎么打包一个 Skill，但对于里面的逻辑该怎么组织，一个字的指导都没有。举个例子，一个封装 FastAPI 开发规范的 Skill，和一个四步走的文档生成流水线，运作方式完全不同，但它们的配置文件从外面看长得一模一样。
通过研究整个生态里 Skill 的构建方式，从 Anthropic 的开源仓库到 Vercel 和 Google 的内部规范，可以总结出五种反复出现的设计模式，能帮开发者把 Agent 搭得更好。
这篇文章会逐一讲解每种模式，并附上可运行的 ADK 代码：
-
工具封装（Tool Wrapper）：让你的 Agent 瞬间精通任何一个库
-
生成器（Generator）：用可复用的模板生成结构化文档
-
审查器（Reviewer）：按严重程度对代码进行清单式打分
-
反转模式（Inversion）：让 Agent 先采访你，再动手
-
流水线（Pipeline）：强制执行带检查点的多步骤工作流
工具封装模式（Tool Wrapper）
工具封装的作用是给你的 Agent 提供针对特定库的按需上下文。与其把 API 的使用规范硬编码到系统提示词里，不如把它们打包成一个 Skill。Agent 只在真正用到这个技术的时候才加载这些上下文。
这是最容易实现的一种模式。Skill 文件监听用户提示词里的特定库关键词，动态加载你内部文档目录里的资料，然后把这些规则当作绝对准则来执行。这个机制特别适合把团队内部的编码规范或特定框架的最佳实践，直接注入到开发者的工作流里。
下面是一个工具封装的例子，教 Agent 怎么写 FastAPI 代码。注意看，指令里明确告诉 Agent，只有在开始审查或编写代码时才加载规范文件：
# skills/api-expert/ SKILL.md
---
name: api-expert
description: FastAPI 开发最佳实践和规范。在构建、审查或调试 FastAPI 应用、REST API 或 Pydantic 模型时使用。
metadata:
pattern: tool-wrapper
domain: fastapi
---
你是 FastAPI 开发专家。将以下规范应用到用户的代码或问题上。
## 核心规范
加载 'references/ conventions.md' 获取完整的 FastAPI 最佳实践列表。
## 审查代码时
1. 加载规范参考文件
2. 逐条对照规范检查用户的代码
3. 每发现一处违规，引用具体规则并给出修复建议
## 编写代码时
1. 加载规范参考文件
2. 严格遵循每一条规范
3. 所有函数签名都加上类型注解
4. 使用 Annotated 风格进行依赖注入 生成器模式（Generator）
工具封装是"用知识"，生成器则是"控输出"。如果你苦恼于 Agent 每次生成的文档结构都不一样，生成器模式就是来解决这个问题的，它把整个过程变成了一个填空题。
生成器用到两个可选目录：一个放输出模板，一个放风格指南。指令充当项目经理的角色，告诉 Agent 去加载模板、读取风格指南、向用户询问缺失的变量，然后填充文档。这种模式非常适合生成格式统一的 API 文档、标准化提交信息，或者搭建项目脚手架。
下面这个技术报告生成器的例子里，Skill 文件本身不包含实际的排版布局或语法规则，它只是协调这些资源的调取，然后强制 Agent 一步一步执行：
c
# skills/report-generator/ SKILL.md
---
name: report-generator
description: 生成 Markdown 格式的结构化技术报告。当用户要求撰写、创建或起草报告、摘要或分析文档时使用。
metadata:
pattern: generator
output-format: markdown
---
你是一个技术报告生成器。严格按以下步骤执行：
第 1 步：加载 'references/ style-guide.md' 获取语气和格式规则。
第 2 步：加载 'assets/ report-template.md' 获取要求的输出结构。
第 3 步：向用户询问填充模板所需的缺失信息：
- 主题或对象
- 关键发现或数据点
- 目标读者（技术人员、管理层、普通读者）
第 4 步：按照风格指南的规则填充模板。模板中的每个章节都必须出现在输出中。
第 5 步：将完成的报告作为单个 Markdown 文档返回。 审查器模式（Reviewer）
审查器模式把"查什么"和"怎么查"分开了。与其在系统提示词里写一大段代码异味清单，不如把一份模块化的评分标准存到单独的参考文件里。
当用户提交代码时，Agent 加载这份检查清单，逐条打分，然后按严重程度分组输出结果。如果你把 Python 风格检查清单换成 OWASP 安全检查清单，用同一套 Skill 基础设施就能得到一个完全不同的专项审计。这种模式非常适合自动化 PR 审查，或者在人工介入之前先把漏洞抓出来。
下面这个代码审查 Skill 展示了这种分离。指令本身是固定的，但 Agent 会动态加载外部检查清单里的具体审查标准，并强制输出按严重程度分级的结构化结果：
# skills/code-reviewer/ SKILL.md
---
name: code-reviewer
description: 审查 Python 代码的质量、风格和常见 bug。当用户提交代码要求审查、请求反馈或需要代码审计时使用。
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
你是一个 Python 代码审查员。严格按以下审查流程执行：
第 1 步：加载 'references/ review-checklist.md' 获取完整的审查标准。
第 2 步：仔细阅读用户的代码。先理解它的用途，再开始挑问题。
第 3 步：将检查清单中的每条规则逐一应用到代码上。每发现一处违规：
- 标注行号（或大致位置）
- 划分严重程度：error（必须修）、warning（建议修）、info（可以考虑）
- 解释"为什么"有问题，而不只是说"哪里"有问题
- 给出具体的修复建议和修正后的代码
第 4 步：输出结构化的审查报告，包含以下部分：
- **概要**：代码功能说明、整体质量评估
- **发现**：按严重程度分组（先 error，再 warning，最后 info）
- **评分**：1-10 分，附简要理由
- **三条核心建议**：影响最大的改进方向 反转模式（Inversion）
Agent 天生就想猜你的意思然后立刻开干。反转模式把这个动态翻转过来：不再是用户驱动提示、Agent 执行，而是让 Agent 变成采访者。
反转模式依赖明确的、不可跳过的门控指令（比如"在所有阶段完成之前，不许开始构建"），强制 Agent 先收集上下文。它按顺序提出结构化的问题，等你回答完一个再问下一个。在拿到你的完整需求和部署约束之前，Agent 拒绝生成最终输出。
来看这个项目规划 Skill。关键在于严格的阶段划分和明确的门控提示，它会阻止 Agent 在收集完所有用户回答之前就急着生成最终方案：
# skills/project-planner/ SKILL.md
---
name: project-planner
description: 通过结构化提问收集需求，然后规划新的软件项目。当用户说"我想做一个""帮我规划""设计一个系统"或"启动新项目"时使用。
metadata:
pattern: inversion
interaction: multi-turn
---
你正在进行一次结构化的需求访谈。在所有阶段完成之前，不许开始构建或设计。
## 第一阶段 --- 问题发现（逐个提问，等待每个回答）
按顺序提出以下问题，不许跳过任何一个。
- Q1："这个项目为用户解决什么问题？"
- Q2："主要用户是谁？他们的技术水平如何？"
- Q3："预期规模是多少？（日活用户数、数据量、请求频率）"
## 第二阶段 --- 技术约束（第一阶段全部回答完毕后才进入）
- Q4："你打算用什么部署环境？"
- Q5："有没有技术栈方面的要求或偏好？"
- Q6："有哪些不可妥协的硬性要求？（延迟、可用性、合规、预算）"
## 第三阶段 --- 综合输出（所有问题都回答完毕后才进入）
1. 加载 'assets/ plan-template.md' 获取输出格式
2. 用收集到的需求填充模板的每个部分
3. 将完成的方案展示给用户
4. 询问："这份方案是否准确反映了你的需求？你想改哪里？"
5. 根据反馈迭代，直到用户确认 流水线模式（Pipeline）
对于复杂任务，你承受不起步骤被跳过或指令被忽略的后果。流水线模式强制执行一个严格的、顺序推进的工作流，并设置硬性检查点。
指令本身就是工作流的定义。通过设置明确的菱形门控条件（比如要求用户确认之后才能从文档字符串生成阶段进入最终组装阶段），流水线确保 Agent 不能跳过复杂任务的中间环节，直接甩出一个未经验证的最终结果。
这种模式会用到所有可选目录，在特定步骤才拉取对应的参考文件和模板，保持上下文窗口的干净。
下面这个文档生成流水线的例子里，注意看那些明确的门控条件。Agent 被明确禁止在用户确认上一步生成的文档字符串之前进入组装阶段：
# skills/doc-pipeline/ SKILL.md
---
name: doc-pipeline
description: 通过多步骤流水线从 Python 源代码生成 API 文档。当用户要求为模块生成文档、创建 API 文档或从代码生成文档时使用。
metadata:
pattern: pipeline
steps: "4"
---
你正在运行一个文档生成流水线。严格按顺序执行每个步骤。不许跳步，某步失败也不许继续。
## 第 1 步 --- 解析与盘点
分析用户的 Python 代码，提取所有公开的类、函数和常量。以清单形式展示盘点结果。询问："这是你想要文档化的完整公开 API 吗？"
## 第 2 步 --- 生成文档字符串
对每个缺少文档字符串的函数：
- 加载 'references/ docstring-style.md' 获取要求的格式
- 严格按照风格指南生成文档字符串
- 将每个生成的文档字符串展示给用户确认
用户确认之前，不许进入第 3 步。
## 第 3 步 --- 组装文档
加载 'assets/ api-doc-template.md' 获取输出结构。将所有类、函数和文档字符串编排成一份完整的 API 参考文档。
## 第 4 步 --- 质量检查
对照 'references/ quality-checklist.md' 进行审查：
- 每个公开符号都有文档
- 每个参数都有类型和描述
- 每个函数至少有一个使用示例
输出检查结果。在呈现最终文档之前修复所有问题。 怎么选？
每种模式回答的是不同的问题。用下面这棵决策树来找到适合你场景的那个。
这些模式之间并不互斥，它们可以组合。
一个流水线 Skill 可以在最后加一个审查步骤来自查。一个生成器可以在最开头用反转模式来收集必要的变量，然后再填充模板。得益于 ADK 的渐进式披露机制，你的 Agent 在运行时只会把上下文 token 花在它真正需要的模式上。
别再试图把复杂又脆弱的指令全塞进一条系统提示词里了。把你的工作流拆开，用对结构化模式，去构建靠谱的 Agent。
Agent Skills 规范是开源的，ADK 原生支持。格式怎么打包你已经会了，现在内容怎么设计你也知道了。去用 Google Agent Development Kit 构建更聪明的 Agent 吧。