ADK Agent Skills 五大核心设计模式详解解析 Google Agent Development Kit 中

本文基于 Google Cloud Tech 发布的 Agent Skills 设计模式文章整理翻译，介绍 ADK 开发中的五种核心架构模式。

什么是 ADK？

ADK（Agent Development Kit） 是 Google 推出的 Agent 开发工具包，提供了一套规范和工具，帮助开发者构建结构化、可维护的 AI Agent 技能体系。ADK 的核心概念是通过 SKILL.md 文件定义 Agent 的行为模式，使得技能可以被复用、组合和共享。

官网 : google.github.io/adk-docs/
核心理念 : 将 Agent 能力模块化，通过标准化格式实现技能的互操作性

当涉及 SKILL.md 时，开发者往往过于关注格式——把 YAML 写对、目录结构化、遵循规范。但随着超过 30 种 agent 工具（如 Claude Code、Gemini CLI 和 Cursor）统一采用相同的布局，格式问题实际上已经过时。

现在的挑战是 内容设计 。规范解释了如何打包一个 skill，但完全没有指导如何在其中构建逻辑。例如，一个封装 FastAPI 约定的 skill 与一个四步文档管道的运作方式完全不同，即使它们的 SKILL.md 文件在外观上看起来一模一样。

通过研究整个生态系统中 skill 的构建方式——从 Anthropic 的仓库到 Vercel 和 Google 的内部指南——我们发现了五种反复出现的设计模式可以帮助开发者构建 agent。

作者：@Saboo_Shubham_ 和 @lavinigam

本文将用实际可运行的 ADK 代码逐一介绍：

Tool Wrapper（工具包装器） ：让你的 agent 瞬间精通任何库
Generator（生成器） ：从可重用模板生成结构化文档
Reviewer（审查器） ：按严重程度对代码进行清单评分
Inversion（反转） ：agent 在行动前先采访你
Pipeline（管道） ：通过检查点强制执行严格的多步骤工作流

Tool Wrapper 为你的 agent 提供特定库的按需上下文。你无需将 API 约定硬编码到系统提示词（system prompt，给 AI 的初始指令）中，而是将它们打包成一个 skill。你的 agent 只有在实际使用该技术时才会加载这个上下文。

这是最简单的实现模式。 SKILL.md 文件监听用户提示词中的特定库关键词，从 references/ 目录动态加载你的内部文档，并将这些规则作为绝对真理应用。这正是将团队内部编码指南或特定框架最佳实践直接分发到开发者工作流中的机制。

下面是一个教 agent 如何编写 FastAPI 代码的 Tool Wrapper 示例。请注意指令如何明确告诉 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
---

You are an expert in FastAPI development. Apply these conventions to the user's code or question.

## Core Conventions

Load 'references/conventions.md' for the complete list of FastAPI best practices.

## When Reviewing Code
1. Load the conventions reference
2. Check the user's code against each convention
3. For each violation, cite the specific rule and suggest the fix

## When Writing Code
1. Load the conventions reference
2. Follow every convention exactly
3. Add type annotations to all function signatures
4. Use Annotated style for dependency injection

模式 2：Generator（生成器）

Tool Wrapper 应用知识，而 Generator 确保输出始终保持一致。如果你苦恼于 agent 每次运行生成不同的文档结构，Generator 通过编排填空过程来解决这个问题。

它利用两个可选目录： assets/ 保存输出模板， references/ 保存风格指南。指令扮演项目经理的角色。它们告诉 agent 加载模板、阅读风格指南、询问用户缺失的变量，然后填充文档。这对于生成可预测的 API 文档、标准化提交消息（commit message，代码提交时的说明文字）或脚手架项目架构特别实用。

在这个技术报告生成器示例中，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
---

You are a technical report generator. Follow these steps exactly:

Step 1: Load 'references/style-guide.md' for tone and formatting rules.

Step 2: Load 'assets/report-template.md' for the required output structure.

Step 3: Ask the user for any missing information needed to fill the template:
- Topic or subject
- Key findings or data points
- Target audience (technical, executive, general)

Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output.

Step 5: Return the completed report as a single Markdown document.

模式 3：Reviewer（审查器）

Reviewer 模式将 检查什么 与 如何检查 分离开来。你不再编写详述每个代码坏味道（code smell，代码中可疑或不良的迹象）的长系统提示词，而是将模块化评分标准存储在 references/review-checklist.md 文件中。

当用户提交代码时，agent 加载此清单并有条不紊地对提交进行评分，按严重程度分组其发现。如果你将 Python 风格清单换成 OWASP（开放网络应用安全项目）安全清单，你会得到一个完全不同的、专业的审计结果，但使用的是完全相同的 skill 基础设施。这是自动化 PR 审查（Pull Request 审查，代码合并前的同行评审）或在人工查看代码之前发现漏洞的高效方式。

下面的代码审查器 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
---

You are a Python code reviewer. Follow this review protocol exactly:

Step 1: Load 'references/review-checklist.md' for the complete review criteria.

Step 2: Read the user's code carefully. Understand its purpose before critiquing.

Step 3: Apply each rule from the checklist to the code. For every violation found:
- Note the line number (or approximate location)
- Classify severity: error (must fix), warning (should fix), info (consider)
- Explain WHY it's a problem, not just WHAT is wrong
- Suggest a specific fix with corrected code

Step 4: Produce a structured review with these sections:
- **Summary**: What the code does, overall quality assessment
- **Findings**: Grouped by severity (errors first, then warnings, then info)
- **Score**: Rate 1-10 with brief justification
- **Top 3 Recommendations**: The most impactful improvements

模式 4：Inversion（反转）

Agent 本性倾向于立即猜测和生成。Inversion 模式颠覆了这种动态。不再是用户驱动提示词和 agent 执行，而是 agent 充当面试官的角色。

Inversion 依赖明确的、不可协商的门控指令（如”在所有阶段完成之前不要开始构建”）来强制 agent 首先收集上下文。它按顺序提出结构化问题，并等待你的答案后再进入下一阶段。在拥有需求和部署约束的完整图景之前，agent 拒绝综合最终输出。

要看到实际效果，请看这个项目规划器 skill。这里的关键元素是严格的阶段划分和明确的门控提示词，它阻止 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
---

You are conducting a structured requirements interview. DO NOT start building or designing until all phases are complete.

## Phase 1 — Problem Discovery (ask one question at a time, wait for each answer)

Ask these questions in order. Do not skip any.

- Q1: "What problem does this project solve for its users?"
- Q2: "Who are the primary users? What is their technical level?"
- Q3: "What is the expected scale? (users per day, data volume, request rate)"

## Phase 2 — Technical Constraints (only after Phase 1 is fully answered)

- Q4: "What deployment environment will you use?"
- Q5: "Do you have any technology stack requirements or preferences?"
- Q6: "What are the non-negotiable requirements? (latency, uptime, compliance, budget)"

## Phase 3 — Synthesis (only after all questions are answered)

1. Load 'assets/plan-template.md' for the output format
2. Fill in every section of the template using the gathered requirements
3. Present the completed plan to the user
4. Ask: "Does this plan accurately capture your requirements? What would you change?"
5. Iterate on feedback until the user confirms

模式 5：Pipeline（管道）

对于复杂任务，你不能允许跳过步骤或忽略指令。Pipeline 模式强制执行严格的、顺序的工作流，并带有硬检查点。

指令本身充当工作流定义。通过实现明确的菱形门控条件（例如在从 docstring 生成进入最终组装之前需要用户批准），Pipeline 确保 agent 不能绕过复杂任务并呈现未经验证的最终结果。

该模式利用所有可选目录，仅在需要的特定步骤中提取不同的参考文件和模板，保持上下文窗口（context window，LLM 一次能处理的最大文本量）干净。

在这个文档管道示例中，请注意明确的门控条件。agent 被明确禁止进入组装阶段，直到用户确认上一步生成的 docstring：

# 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"
---

You are running a documentation generation pipeline. Execute each step in order. Do NOT skip steps or proceed if a step fails.

## Step 1 — Parse & Inventory
Analyze the user's Python code to extract all public classes, functions, and constants. Present the inventory as a checklist. Ask: "Is this the complete public API you want documented?"

## Step 2 — Generate Docstrings
For each function lacking a docstring:
- Load 'references/docstring-style.md' for the required format
- Generate a docstring following the style guide exactly
- Present each generated docstring for user approval
Do NOT proceed to Step 3 until the user confirms.

## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md' for the output structure. Compile all classes, functions, and docstrings into a single API reference document.

## Step 4 — Quality Check
Review against 'references/quality-checklist.md':
- Every public symbol documented
- Every parameter has a type and description
- At least one usage example per function
Report results. Fix issues before presenting the final document.

选择正确的 agent skill 模式

每种模式回答不同的问题。使用此决策树为你的用例找到合适的模式：

最后，模式可以组合

这些模式并不互斥。它们可以组合。

Pipeline skill 可以在最后包含一个 Reviewer 步骤来复查自己的工作。Generator 可以在最开始依赖 Inversion 来收集必要的变量，然后再填充其模板。多亏了 ADK 的 SkillToolset 和渐进式披露（progressive disclosure，按需加载信息的设计理念），你的 agent 只在运行时在它需要的确切模式上花费上下文 token。

不要再试图将复杂而脆弱的指令塞进单个系统提示词中。分解你的工作流，应用正确的结构模式，构建可靠的 agent。

今天就开始

Agent Skills 规范是开源的，并在整个 ADK 中得到原生支持。你已经知道如何打包格式。现在你知道如何设计内容。使用 Google Agent Development Kit 构建更智能的 agent 吧。