Google官方出品：每个开发者都该知道的5种Skill设计模式

原文作者：Google Cloud Tech (@GoogleCloudTech)，
原文链接：https://x.com/GoogleCloudTech/status/2033953579824758855

真正难的，是内容设计。

规范告诉你怎么打包一个 Skill，但对里面的逻辑怎么组织，一个字没说。比如，一个封装了 FastAPI 规范的 Skill，和一个四步文档生成流水线，从外面看 SKILL.md 长得一模一样，但里面的运作方式完全不同。

我研究了整个生态里 Skill 的构建方式——从 Anthropic 的仓库到 Vercel、Google 的内部指南——总结出了五种反复出现的设计模式，能帮开发者把 Agent 真正做好。

这篇文章覆盖了每种模式，并配了能跑的 ADK 代码：

1. 1. Tool Wrapper（工具包装器）：让你的 Agent 瞬间成为某个库的专家
2. 2. Generator（生成器）：用可复用模板输出结构化文档
3. 3. Reviewer（审查器）：按严重程度对代码逐条打分
4. 4. Inversion（反转模式）：Agent 先来采访你，再动手做
5. 5. Pipeline（流水线）：带检查点的严格多步工作流

模式一：Tool Wrapper（工具包装器）

Tool Wrapper 给你的 Agent 装上了”按需加载的专业知识”。与其把 API 规范死写进系统 Prompt，不如打包成一个 Skill。Agent 只在真正用到那个技术的时候，才把这些上下文加载进来。

这是五种模式里最好实现的。SKILL.md 监听用户 Prompt 里的特定关键词，动态从 references/ 目录加载你的内部文档，然后把这些规则当作绝对真理来执行。这正是你把团队内部编码规范、特定框架最佳实践直接推进开发者工作流的方式。

下面是一个 Tool Wrapper 的例子，教 Agent 怎么写 FastAPI 代码。注意这里的指令明确告诉 Agent：只有在开始审查或编写代码的时候，才去加载 conventions.md：

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models.
metadata:
  pattern: tool-wrapper
  domain: fastapi
---

你是 FastAPI 开发专家。请将这些约定应用到用户的代码或问题中。

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

## 审查代码时
1. 加载约定参考文档
2. 用每一条约定检查用户的代码
3. 对于每一处违规，引用具体规则并给出修复建议

## 编写代码时
1. 加载约定参考文档
2. 严格遵循每一条约定
3. 为所有函数签名添加类型注解
4. 使用 Annotated 风格进行依赖注入

模式二：Generator（生成器）

Tool Wrapper 是在”应用知识”，Generator 是在”强制输出一致性”。如果你头疼 Agent 每次生成的文档结构都不一样，Generator 就是救星——它通过”填空游戏”来解决这个问题。

它用到两个可选目录：assets/ 放输出模板，references/ 放风格指南。指令扮演的是项目经理的角色，让 Agent 先加载模板，读风格指南，问用户缺了哪些变量，然后填进去。用来生成可预期的 API 文档、标准化 Commit 消息、或者项目架构脚手架，都很好使。

下面这个技术报告生成器的例子里，Skill 文件本身不包含任何实际的布局或语法规则。它只是协调这些资产的调取，强制 Agent 一步一步执行：

# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document.
metadata:
  pattern: generator
  output-format: markdown
---

你是一个技术报告生成器。请严格按照以下步骤执行：

Step 1: 加载 'references/style-guide.md' 获取语气和格式规则。
Step 2: 加载 'assets/report-template.md' 获取所需的输出结构。
Step 3: 向用户询问填充模板所需但缺失的信息：
  - 主题或话题
  - 关键发现或数据点
  - 目标读者（技术、管理层、普通读者）
Step 4: 按照风格指南规则填写模板。模板中的每个部分都必须出现在输出中。
Step 5: 将完成后的报告作为一份单独的 Markdown 文档返回。

模式三：Reviewer（审查器）

Reviewer 模式把”查什么”和”怎么查”分开了。与其在系统 Prompt 里把每个代码坏味道都列一遍，不如把模块化的评审标准存到 references/review-checklist.md 里。

用户提交代码，Agent 加载这个清单，逐条打分，按严重程度归类输出结果。如果你把 Python 风格清单换成 OWASP 安全清单，用完全相同的 Skill 基础设施，就能得到一个完全不同的专项审计工具。用来自动化 PR Review、在人工审阅前先抓漏洞，效果很好。

下面这个代码审查 Skill 展示了这种分离。指令本身是静态的，但 Agent 会动态加载外部清单里的具体评审标准，强制输出结构化的、按严重程度分级的结果：

# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs. Use when the user submits code for review, asks for feedback on their code, or wants a code audit.
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---

你是一名 Python 代码审查员。请严格遵循以下审查协议：

Step 1: 加载 'references/review-checklist.md' 获取完整的审查标准。
Step 2: 仔细阅读用户的代码。在提出批评前先理解它的用途。
Step 3: 将清单中的每条规则应用到代码上。对发现的每一处违规：
  - 记录行号（或大致位置）
  - 标注严重程度：error（必须修复）、warning（建议修复）、info（可考虑）
  - 解释为什么这是个问题，而不只是指出哪里错了
  - 给出带修正代码的具体修复建议
Step 4: 输出一份结构化审查，包含以下部分：
  - **Summary**：代码做了什么，整体质量评估
  - **Findings**：按严重程度分组（先 errors，再 warnings，最后 info）
  - **Score**：按 1-10 打分，并给出简短理由
  - **Top 3 Recommendations**：最有影响力的 3 条改进建议

模式四：Inversion（反转模式）

Agent 天生就想马上猜测、马上生成。Inversion 模式把这个动态翻转了。不是用户驱动 Prompt、Agent 执行，而是 Agent 来当采访者。

Inversion 靠的是明确的、不可绕过的”门控指令”（比如”在所有阶段完成之前，不许开始动手”），强制 Agent 先收集上下文。它按顺序提问，等你回答了才问下一个。在得到你完整的需求和部署约束之前，Agent 拒绝输出任何最终结果。

看看这个项目规划 Skill。关键在于严格的分阶段设计和明确的”门控 Prompt”——它阻止 Agent 在收集完用户所有答案之前合成最终方案：

# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions before producing a plan. Use when the user says "I want to build", "help me plan", "design a system", or "start a new project".
metadata:
  pattern: inversion
  interaction: multi-turn
---

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

## Phase 1 — Problem Discovery（一次问一个问题，等回答）
按顺序问，一个都不能跳过：
- Q1: "这个项目为用户解决什么问题？"
- Q2: "主要用户是谁？他们的技术水平如何？"
- Q3: "预期规模是多少？（每天用户量、数据量、请求量）"

## Phase 2 — Technical Constraints（Phase 1 全部回答完之后）
- Q4: "你用什么部署环境？"
- Q5: "有没有技术栈要求或偏好？"
- Q6: "有哪些不可妥协的要求？（延迟、可用性、合规、预算）"

## Phase 3 — Synthesis（所有问题都回答完之后）
1. 加载 'assets/plan-template.md' 获取输出格式
2. 用收集到的需求填写模板的每个部分
3. 把完成的方案呈现给用户
4. 问："这个方案准确反映了你的需求吗？你想改哪里？"
5. 根据反馈迭代，直到用户确认

模式五：Pipeline（流水线）

处理复杂任务，你不能接受跳步骤或忽略指令。Pipeline 模式强制执行严格的顺序工作流，带硬检查点。

指令本身就是工作流定义。通过实现明确的”钻石门控条件”（比如要求用户在进入最终组装阶段之前必须确认），Pipeline 确保 Agent 不能绕过复杂任务、直接扔出一个没验证过的最终结果。

这个模式用到了所有可选目录，在每个步骤需要的时候才引入对应的参考文件和模板，保持上下文窗口干净。

看这个文档生成流水线的例子，注意明确的门控条件——Agent 被明令禁止在用户确认上一步生成的文档注释之前，进入组装阶段：

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline. Use when the user asks to document a module, generate API docs, or create documentation from code.
metadata:
  pattern: pipeline
  steps: "4"
---

你正在运行一个文档生成流水线。请按顺序执行每一步。不要跳过步骤，也不要在某一步失败时继续进行。

## Step 1 — Parse & Inventory
分析用户的 Python 代码，提取所有公开的类、函数和常量。以清单形式呈现。问："这是你要文档化的完整公开 API 吗？"

## Step 2 — Generate Docstrings
对每个缺少文档注释的函数：
- 加载 'references/docstring-style.md' 获取所需格式
- 按风格指南逐字生成文档注释
- 逐条呈现给用户确认

**在用户确认之前，不得进入 Step 3。**

## Step 3 — Assemble Documentation
加载 'assets/api-doc-template.md' 获取输出结构。把所有类、函数和文档注释编译成一份完整的 API 参考文档。

## Step 4 — Quality Check
对照 'references/quality-checklist.md' 审查：
- 每个公开符号都有文档
- 每个参数都有类型和描述
- 每个函数至少有一个使用示例

报告结果，修完问题再呈现最终文档。

怎么选对模式？

每种模式回答的是不同的问题。用这个决策树找到适合你场景的那个：

最后：这些模式可以组合

这五种模式不是互斥的，它们可以叠加。

Pipeline Skill 可以在最后加一个 Reviewer 步骤来自我审查。Generator 可以在开头套一层 Inversion 来先收集必要的变量，再填模板。得益于 ADK 的 SkillToolset 和渐进式披露机制，你的 Agent 在运行时只会把上下文 token 花在它真正需要的模式上。

别再把复杂又脆弱的指令塞进一个大系统 Prompt 了。把你的工作流拆开，用对结构模式，构建可靠的 Agent。