Google ADK Agent Skill 5 大设计模式：别再死磕 SKILL.md 格式了

Google ADK Agent Skill 5 大设计模式：别再死磕 SKILL.md 格式了

前两天刷推看到 Google Cloud Tech 发了一篇长文，标题是「5 Agent Skill design patterns every ADK developer should know」。本来以为又是官方文档的复读机，点进去一看，还真有点东西。

我最近一直在用 ADK 的 SkillToolset 做 Agent 开发，踩过不少坑——最典型的就是把所有逻辑塞进系统 prompt，Agent 越来越笨。这篇文章正好把我模糊的经验总结成了 5 个清晰的模式。翻译 + 加了我自己的理解分享出来。

先说结论

模式一句话说明适用场景
Tool Wrapper把库级知识封装成 SkillAgent 需要调用特定 SDK/API
Generator模板填充式生成需要一致的文档/代码输出
Reviewer按 checklist 打分审查代码 review、内容审核
InversionAgent 先采访你再干活需求不明确、怕 Agent 瞎猜
Pipeline多步骤串行 + checkpoint复杂工作流、需要质量门禁

这 5 个模式可以自由组合。比如 Pipeline 里最后一步套个 Reviewer，Generator 开头先走 Inversion 收集变量。

背景：格式已经不是问题了

原文第一个观点很犀利——开发者太纠结 SKILL.md 的格式了。

现实是，超过 30 种 Agent 工具（Claude Code、Gemini CLI、Cursor、Windsurf……）已经在事实上标准化了同一套 SKILL.md 布局：

skill_name/
├── SKILL.md          # 必需：元数据 + 指令
├── references/       # 可选：扩展文档 (*.md)
├── assets/           # 可选：模板、schema、数据
└── scripts/          # 可选：可执行脚本（ADK 暂不支持）

SKILL.md 本身分三层渐进式披露（Progressive Disclosure）：

  • L1 元数据：frontmatter 里的 name 和 description，用于 Skill 发现
  • L2 指令：SKILL.md 正文，Agent 触发 Skill 时才加载
  • L3 资源：references/、assets/ 里的扩展材料，按需引用

格式问题基本解决了。真正的挑战是：Skill 内部的逻辑应该怎么设计？

模式 1：Tool Wrapper —— 让 Agent 秒懂任何库

问题：你让 Agent 调用某个 SDK，它总是写出过时的用法，或者搞混参数顺序。

方案：把库的 API 约定封装成一个 Skill。Agent 只在实际需要用这个库时才加载，不会浪费上下文。

# SKILL.md - Stripe SDK Wrapper

## 使用规则
- 所有金额单位必须是分（cents），不是元
- 创建 Customer 时必须先检查 email 是否已存在
- webhook 验证必须用 stripe.webhooks.constructEvent()

## API 速查
### 创建支付意图
\```python
import stripe
stripe.api_key = os.environ["STRIPE_KEY"]

intent = stripe.PaymentIntent.create(
    amount=2000,  # $20.00，单位是分
    currency="usd",
    payment_method_types=["card"],
)
\```

关键在于：这不是文档的复制粘贴，而是提炼出 Agent 最容易犯错的规则。你踩过的坑，都写进 Skill 里。

模式 2：Generator —— 可复现的文档生成

问题：让 Agent 写需求文档，每次格式都不一样。今天有目录，明天没有；今天标记了优先级，明天忘了。

方案：Generator 模式用 assets/ 目录放模板，references/ 放风格指南，SKILL.md 指令当”项目经理”——告诉 Agent 先加载模板、读风格指南、问用户要缺失的变量、然后填充文档。

spec-generator/
├── SKILL.md
├── assets/
│   └── spec-template.md    # 文档模板（带占位符）
└── references/
    └── style-guide.md      # 风格指南

SKILL.md 核心指令：

## 流程
1. 读取 assets/spec-template.md 获取文档结构
2. 读取 references/style-guide.md 获取写作规范
3. 向用户确认以下变量：项目名、目标用户、核心功能列表
4. 按模板填充，严格遵循风格指南
5. 输出完整文档

好处很明显：换个模板就能生成不同类型的文档，Agent 的行为完全可预期。

模式 3：Reviewer —— 按 checklist 逐条审查

问题：让 Agent 做 code review，它要么太啰嗦、要么漏掉关键问题、要么不同 PR 的审查标准不一致。

方案：Reviewer 模式把评审标准拆成 checklist，每条带严重等级。Agent 逐条检查，按格式输出结果。

## 审查清单

### 安全（严重）
- [ ] 是否有 SQL 注入风险？
- [ ] 用户输入是否做了转义？
- [ ] 是否有硬编码的密钥或密码？

### 性能（中等）
- [ ] 是否有 N+1 查询？
- [ ] 大列表是否做了分页？

### 规范（低）
- [ ] 函数命名是否符合项目约定？
- [ ] 是否有未使用的导入？

## 输出格式
对每条不通过的项，输出：
- 严重等级：🔴 严重 / 🟡 中等 / 🟢 低
- 位置：文件名:行号
- 问题描述
- 修复建议

把评审标准从 Agent 的”感觉”变成了可维护的配置。新规则？往 checklist 里加一条就行。

模式 4：Inversion —— 先采访，再执行

问题：你说”帮我写个 API”，Agent 直接开写——用了错误的框架、错误的认证方式、错误的数据库。

方案：Inversion 翻转了控制流。不是用户驱动 prompt + Agent 执行，而是 Agent 先当采访者，按结构化问题收集完所有必要信息，再开始干活。

## 执行规则（不可跳过）

在编写任何代码之前，你必须完成以下采访：

### 第一阶段：技术栈确认
1. 使用什么语言和框架？
2. 目标运行环境？（本地 / Docker / 云服务）
3. 是否有现有的项目结构？

### 第二阶段：需求细化
4. 核心功能列表（按优先级排序）
5. 认证方式？（JWT / OAuth / API Key）
6. 数据存储方案？

### 第三阶段：约束条件
7. 性能要求？（QPS / 响应时间）
8. 是否需要向后兼容？
9. 截止日期？

⚠️ 在所有问题回答完毕之前，禁止生成任何实现代码。

这个模式特别适合需求模糊的场景。Agent 不再猜，而是明确地告诉你”我还缺这些信息”。

模式 5：Pipeline —— 多步骤串行 + 质量门禁

问题：复杂任务（如”分析竞品 → 写 PRD → 生成原型”），Agent 经常跳步骤、漏关键环节。

方案：Pipeline 模式把工作流拆成严格的顺序步骤，每步之间设置 checkpoint。Agent 必须按顺序执行，每个 checkpoint 需要明确通过条件。

## 工作流（严格按顺序执行）

### Step 1: 数据收集
- 搜索竞品的 5 个关键指标
- checkpoint：确认已收集至少 3 个竞品的数据

### Step 2: 分析对比
- 制作对比矩阵
- checkpoint：表格至少包含 5 个维度

### Step 3: 草拟方案
- 基于分析结果写推荐方案
- checkpoint：方案必须包含可行性评估和风险点

### Step 4: 自检（嵌入 Reviewer 模式）
- 按照 references/review-checklist.md 自检
- checkpoint：所有"严重"级别项必须通过

注意最后一步——Pipeline 嵌套了 Reviewer。模式是可组合的，这才是这套体系最有价值的地方。

怎么选？一个决策树

选模式不用纠结，问自己三个问题：

  1. Agent 需要领域知识吗？ → Tool Wrapper
  2. 输出需要一致的结构？ → Generator
  3. 需要检查质量？ → Reviewer
  4. 需求不够明确？ → Inversion
  5. 任务有多个顺序步骤？ → Pipeline

大多数真实场景会组合 2-3 个模式。比如一个”生成技术方案”的 Skill，流程可能是：

Inversion（收集需求）→ Generator（填充方案模板）→ Reviewer（自检方案质量）

这就是一个 Pipeline 包裹了其他三个模式。

ADK 中的实现

在 Google ADK 里，加载和使用 Skill 只需要几行代码：

import pathlib
from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset
from google.adk import Agent

# 加载 Skill
api_skill = load_skill_from_dir(
    pathlib.Path("skills/stripe-wrapper")
)
review_skill = load_skill_from_dir(
    pathlib.Path("skills/code-reviewer")
)

# 组装成工具集
tools = skill_toolset.SkillToolset(
    skills=[api_skill, review_skill]
)

# 创建 Agent
agent = Agent(
    model="gemini-3-pro",
    tools=[tools],
    instruction="你是一个全栈开发助手。"
)

SkillToolset 的好处是渐进式加载——Agent 只在实际触发某个 Skill 时才加载它的 L2 指令，不用的 Skill 只消耗 L1 元数据的几个 token。

我的体会

用了这套模式之后，最大的感受是：从”调 prompt”变成了”设计架构”。

之前的做法是把所有规则、示例、约束全塞进系统 prompt，越改越长、越长越脆弱。现在拆成独立的 Skill，每个 Skill 内部用合适的模式组织逻辑，Agent 的行为变得可预测、可维护。

原文最后一句话说得好：

Stop trying to cram complex and fragile instructions into a single system prompt. Break your workflows down, apply the right structural pattern, and build reliable agents.

别再把复杂脆弱的指令塞进一个系统 prompt 了。把工作流拆开，选对设计模式，才能造出靠谱的 Agent。

参考：Google Cloud Tech 原文 · ADK Skills 文档 · 作者：@Saboo_Shubham_ & @lavinigam

← 返回文章列表