每个 ADK 开发者都该掌握的 5 种 Agent Skill 设计模式

很多开发者在构建 AI 智能体（Agent）时，花了大量时间在 SKILL.md 的格式上——YAML 写法对不对、目录结构合不合规范。但随着 Claude Code、Gemini CLI、Cursor 等 30 多款主流 Agent 工具都已经标准化到同一套目录规范，格式问题其实已经不是瓶颈。

真正的挑战在于：如何设计 Skill 内部的逻辑结构？

一个封装了 FastAPI 规范的 Skill，和一个四步骤文档生成流水线，从 SKILL.md 外部看起来毫无区别，但内部运作方式截然不同。

本文整理了从 Anthropic、Vercel 到 Google 内部实践中反复出现的 5 种核心设计模式，每种都附带 ADK 代码示例，帮你把 Agent 从”能跑起来”提升到”可靠、可维护”。

为什么 Skill 设计模式很重要？

Agent 的 SKILL.md 文件本质上是给 AI 的”岗位说明书”。格式说明了怎么打包技能，但没有告诉你怎么组织技能内部的逻辑。

没有结构的 Skill 容易导致：

• 每次运行输出格式不一致
• Agent 跳过关键步骤直接给出结果
• 上下文窗口被无关信息填满
• 复杂任务难以维护和扩展

5 种设计模式解决的正是这些问题。

模式一：工具封装（Tool Wrapper）

这个模式解决什么问题？

当你的 Agent 需要处理某个特定库或框架时，通常有两种做法：把所有约定硬编码进系统提示词，或者在用到时动态加载。前者让提示词越来越臃肿，后者就是 Tool Wrapper 的核心思路。

Tool Wrapper 的工作逻辑：

1. 监听用户提示中的特定关键词（如库名、框架名）
2. 触发后动态加载 references/ 目录中的内部文档
3. 将这些规则作为绝对标准应用到当前任务

这个模式特别适合把团队内部的编码规范或框架最佳实践，直接注入到开发者的工作流中，而不是每次都靠口耳相传。

代码示例：FastAPI 专家 Skill

# 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

适用场景

• 封装某个内部框架的使用规范
• 让 Agent 成为特定技术栈的即时专家
• 分发团队编码标准给所有开发者

模式二：生成器（Generator）

这个模式解决什么问题？

你有没有遇到过：同样一个任务，让 Agent 做两次，输出结构完全不一样？Generator 模式专门解决这个问题。

它的核心思路是”填空式生成”：把输出模板放在 assets/ 目录，把写作风格规范放在 references/ 目录，Agent 的指令只负责协调整个流程——加载模板、读取规范、收集缺失变量、填充文档。

Generator 的工作逻辑：

1. 加载 assets/ 中的输出模板
2. 加载 references/ 中的风格指南
3. 向用户询问模板所需的缺失信息
4. 按步骤填充文档
5. 返回完整的结构化输出

代码示例：技术报告生成器

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

注意：Skill 文件本身不包含实际的文档结构或语法规则，它只负责协调资产的检索，并强制 Agent 逐步执行。

适用场景

• 生成格式统一的 API 文档
• 标准化 commit message 写法
• 搭建项目架构脚手架
• 批量生成结构一致的分析报告

模式三：审阅者（Reviewer）

这个模式解决什么问题？

代码审查提示词越写越长，却还是漏掉各种问题？Reviewer 模式把”检查什么”和”怎么检查”分离开来。

不再把所有代码规范塞进系统提示词，而是把审查清单放进 references/review-checklist.md 文件。Agent 的指令保持静态，检查标准动态加载。

这意味着：把 Python 风格检查清单换成 OWASP 安全检查清单，你就得到了一个完全不同的安全审计工具——但用的是完全相同的 Skill 基础设施。

代码示例：Python 代码审阅器

# 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

三级严重度分类

适用场景

• 自动化 PR 代码审查
• 上线前的安全漏洞扫描
• 新人代码质量培训
• 不同标准的模块化审查（性能、安全、风格分开跑）

模式四：反转式（Inversion）

这个模式解决什么问题？

Agent 天生想要立刻猜测并生成结果。用户说”帮我设计一个系统”，Agent 就开始输出架构图——但往往缺少关键上下文，最终结果偏差很大。

Inversion 模式翻转了这个动态：不是用户驱动提示词然后 Agent 执行，而是 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

为什么”逐一提问”很重要？

注意指令里特别说明了”一次只问一个问题，等待每个回答”。这不是多余的细节——如果 Agent 一次性抛出六个问题，用户往往只会回答其中几个，剩下的信息就丢失了。逐步收集才能确保信息完整。

适用场景

• 软件项目需求收集
• 复杂方案设计前的信息整理
• 任何”需要充分了解背景才能给出好答案”的场景

模式五：流水线（Pipeline）

这个模式解决什么问题？

对于复杂任务，你不能接受任何步骤被跳过或指令被忽略。Pipeline 模式通过硬性检查点强制执行严格的顺序工作流。

指令本身就是工作流定义。通过实现明确的”钻石门”条件（比如要求用户在生成文档字符串后确认，才能进入最终组装阶段），Pipeline 确保 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"
---

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.

注意 Step 2 末尾的那条指令：Do NOT proceed to Step 3 until the user confirms。这就是”钻石门”——一个显式的人工确认节点，是整个流水线可靠性的核心。

适用场景

• 从源代码生成 API 文档
• 多步骤数据处理工作流
• 需要人工确认节点的内容生成任务
• 任何”顺序不能乱、步骤不能跳”的复杂场景

如何选择合适的模式？

每种模式回答的是不同的问题：

快速判断流程：

1. 任务涉及特定技术领域知识？→ Tool Wrapper
2. 需要统一的输出结构？→ Generator
3. 需要评分或评审现有内容？→ Reviewer
4. 需要先问清楚再做？→ Inversion
5. 任务有多个强依赖步骤？→ Pipeline

模式可以组合使用

这五种模式并不互斥，它们可以组合：

• Pipeline + Reviewer：流水线的最后一步加入 Reviewer，让 Agent 自我检查输出质量
• Generator + Inversion：在填充模板之前，先用 Inversion 收集所有必要的变量
• Tool Wrapper + Pipeline：在流水线的特定步骤动态加载领域知识

ADK 的 SkillToolset 和渐进式上下文加载机制，让 Agent 只在真正需要某个模式时才消耗对应的上下文 token，保持整体运行效率。

常见问题

问：SKILL.md 的格式已经标准化，还需要学这些模式吗？

格式只解决了”怎么打包 Skill”的问题，设计模式解决的是”怎么组织 Skill 内部逻辑”。两者解决不同层面的问题，都需要掌握。

问：Inversion 模式会不会让 Agent 显得太啰嗦？

只在合适的场景使用 Inversion——当任务复杂到需要充分上下文才能给出有效结果时。如果任务足够简单，直接用 Tool Wrapper 或 Generator 即可。

问：Pipeline 中的用户确认节点会不会影响自动化程度？

会。但这正是 Pipeline 的价值所在——它牺牲一部分自动化换取可靠性。如果你的场景可以完全自动化，不需要人工确认，可以去掉确认节点，但要接受潜在的错误传播风险。

问：这些模式在不同 Agent 工具（Claude Code、Cursor、Gemini CLI）之间通用吗？

通用。Agent Skills 规范是开源的，并被上述工具原生支持。模式是内容层面的设计，不依赖特定工具的实现。

小结

停止把复杂、脆弱的指令全部塞进一个系统提示词。

5 种设计模式给了你一套分解工作流的方法：

• Tool Wrapper：让 Agent 按需成为某领域专家
• Generator：保证每次输出结构一致
• Reviewer：把评审标准和评审流程分离
• Inversion：先问清楚，再开始做
• Pipeline：用检查点保障复杂任务的可靠执行

Agent Skills 规范是开源的，ADK 原生支持所有这些模式。格式问题你已经解决了，现在可以把精力放在真正重要的地方：内容设计。