原文链接：https://x.com/googlecloudtech/status/2033953579824758855?s=46&t=mPPVh8f99GqMIVi2yREvMQ
原文标题：5 Agent Skill design patterns every ADK developer should know
作者：@Saboo_Shubham_ 和 @lavinigam
当谈到 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 时，开发者往往过于关注格式——如何让 YAML 正确、如何组织目录结构、如何遵循规范。但随着超过 30 种 Agent 工具（如 Claude Code、Gemini CLI 和 Cursor）都在标准化相同的布局，格式化问题实际上已经过时了。
现在的挑战是内容设计。规范解释了如何打包技能，但对于如何构建技能内部的逻辑，却完全没有提供指导。例如，一个封装 FastAPI 规范的技能与一个四步文档流水线的运作方式完全不同，尽管它们的 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件外观看起来一模一样。
通过研究整个生态系统中技能的构建方式——从 Anthropic 的仓库到 Vercel 和 Google 的内部指南——我们发现了五个 recurring 设计模式，可以帮助开发者构建 Agent。
本文将用可运行的 ADK 代码逐一介绍：
- Tool Wrapper：让你的 Agent 瞬间成为任何库的专家
- Generator：从可复用模板生成结构化文档
- Reviewer：根据检查清单按严重程度评分代码
- Inversion：Agent 在行动前先采访你
- Pipeline：通过检查点强制执行严格的多步骤工作流
Tool Wrapper 为你的 Agent 提供按需获取特定库上下文的能力。与其将 API 规范硬编码到系统提示中，不如将它们打包成一个技能。你的 Agent 只有在实际使用该库时才会加载这些上下文。
这是最简的实现模式。 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件监听用户提示中的特定库关键词，从 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 目录动态加载内部文档，并将这些规则作为绝对真理应用。这正是你将团队内部编码规范或特定框架最佳实践直接分发到开发者工作流中的机制。
以下是一个教授 Agent 如何编写 FastAPI 代码的 Tool Wrapper 示例。注意说明如何明确告诉 Agent 只在开始审查或编写代码时才加载 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
| # 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 风格
|
模式 2：Generator（生成器）
Tool Wrapper 应用知识，而 Generator 则强制输出一致性。如果你苦于 Agent 每次运行都生成不同的文档结构，Generator 通过执行一个”填空”流程来解决这个问题。
它利用两个可选目录：𝚊𝚜𝚜𝚎𝚝𝚜/ 存放输出模板，𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 存放风格指南。说明部分充当项目经理角色——告诉 Agent 加载模板、阅读风格指南、询问用户缺失的变量，然后填充文档。这适用于生成可预测的 API 文档、标准化提交信息或搭建项目架构。
在这个技术报告生成器示例中，技能文件不包含实际的布局或语法规则。它只是协调检索这些资源，并强制 Agent 逐步执行：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| # 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 文档返回。
|
模式 3：Reviewer（评审器）
Reviewer 模式将”检查什么”与”如何检查”分离。与其写一个很长的系统提示来详细描述每个代码异味，不如你将模块化的评分标准存储在 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍 文件中。
当用户提交代码时，Agent 加载这个检查清单并系统地评分提交内容，按严重程度分组发现的问题。如果你将 Python 风格检查清单替换为 OWASP 安全检查清单，你就能得到一个完全不同的、专业化的审计，使用完全相同的技能基础设施。这是自动化 PR 审查或在人工检查前发现漏洞的高效方式。
以下代码审查技能演示了这种分离。说明保持静态，但 Agent 从外部检查清单动态加载特定的审查标准，并强制输出基于严重程度的结构化结果：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
| # 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 分并附简要说明
- **三大建议**：最有影响力的改进点
|
模式 4：Inversion（反转）
Agent 天生倾向于猜测并立即生成。Inversion 模式翻转这种动态。不再是用户驱动提示、Agent 执行，而是 Agent 充当采访者。
Inversion 依赖明确的、不可协商的门控指令（如”在所有阶段完成之前不要开始构建”）来强制 Agent 先收集上下文。它按顺序提出结构化问题，并在进入下一阶段前等待你的回答。Agent 拒绝合成最终输出，直到它完全了解你的需求和部署约束。
要看到这个模式的实际应用，看这个项目规划技能。关键要素是严格的阶段划分和明确的守门提示，阻止 Agent 在所有用户回答收集完毕前合成最终计划：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
| # skills/project-planner/SKILL.md
---
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. 询问："这个计划准确捕捉了你的需求吗？需要修改什么？"
5. 根据反馈迭代，直到用户确认
|
模式 5：Pipeline（管道）
对于复杂任务，你不能承受跳过步骤或忽视指令的风险。Pipeline 模式强制执行严格的顺序工作流，带有硬性检查点。
说明本身充当工作流定义。通过实现明确的菱形门条件（如在从文档字符串生成阶段进入最终组装阶段前需要用户批准），Pipeline 确保 Agent 不能绕过复杂任务并呈现未经验证的最终结果。
这个模式利用所有可选目录，仅在特定步骤需要时才拉入不同的参考文件和模板，保持上下文窗口整洁。
在这个文档流水线示例中，注意明确的门条件。Agent 被明确禁止在前一步用户确认生成的文档字符串之前进入组装阶段：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
| # 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' 审查：
- 每个公共符号都有文档
- 每个参数都有类型和描述
- 每个函数至少有一个使用示例
报告结果。在呈现最终文档前修复问题。
|
选择合适的 Agent 技能模式
每个模式回答一个不同的问题。使用以下决策树为你的用例找到合适的模式：
最后，模式可以组合
这些模式不是互斥的。它们可以组合。
Pipeline 技能可以在末尾包含一个 Reviewer 步骤来自查工作。Generator 可以在最开始依赖 Inversion 收集必要变量，然后再填充模板。得益于 ADK 的 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 和渐进式披露，你的 Agent 只在运行时花费上下文 token 加载它确切需要的模式。
停止试图将所有复杂且脆弱的指令塞进单个系统提示。 将工作流拆解，应用正确的结构模式，构建可靠的 Agent。
立即开始
Agent Skills 规范是开源的，并在 ADK 中原生支持。你已经知道如何打包格式了。现在你知道如何设计内容了。使用 Google Agent Development Kit 去构建更智能的 Agent 吧。