每个 ADK 开发者都应该知道的 5 种智能体技能设计模式

Tldr

随着 30+ 智能体工具标准化了 SKILL.md 格式，格式问题已解决，真正的挑战是内容设计。本文从 Anthropic、Vercel、Google 的实践中归纳出五种设计模式：Tool Wrapper（按需加载库上下文）、Generator（模板化一致输出）、Reviewer（清单式评分审查）、Inversion（先采访再行动）、Pipeline（带检查点的多步工作流）。模式可组合，复杂度递增。

说到 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍，开发者们往往纠结于格式——把 YAML 写对、目录结构搞好、遵循规范。但随着 Claude Code、Gemini CLI、Cursor 等超过 30 种智能体工具在同一套布局上达成标准化，格式问题几乎已经过时了。

现在真正的挑战是内容设计。规范告诉你如何打包一个技能，却对如何组织其内部逻辑只字未提。举个例子，一个封装 FastAPI 约定的技能和一个四步文档流水线，运作方式截然不同，尽管它们的 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件看起来一模一样。

通过研究整个生态中技能的构建方式——从 Anthropic 的代码仓库到 Vercel 和 Google 的内部规范——可以归纳出五种反复出现的设计模式（Design Pattern），帮助开发者构建智能体。

作者：@Saboo_Shubham_ 和 @lavinigam

本文逐一介绍每种模式，并附带可运行的 ADK（Agent Development Kit，智能体开发套件）代码：

模式	核心能力	复杂度
Tool Wrapper 工具包装器	让智能体即时成为任何库的专家	⭐
Generator 生成器	基于可复用模板生成结构化文档	⭐⭐
Reviewer 审查器	按严重级别对代码进行清单评分	⭐⭐
Inversion 反转模式	智能体先采访你，再行动	⭐⭐⭐
Pipeline 流水线	强制执行带检查点的严格多步工作流	⭐⭐⭐⭐

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

核心思想

按需加载库上下文，而非硬编码到系统提示词中。

Tool Wrapper 为你的智能体提供针对特定库的按需上下文。它不是把 API 约定硬编码到系统提示词（System Prompt）里，而是将其打包成一个技能。智能体只在实际使用该技术时才加载这些上下文。

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

下面是一个 Tool Wrapper 的示例，教智能体如何编写 FastAPI 代码。注意指令明确告诉智能体：只在开始审查或编写代码时才加载 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 负责强制输出一致性。如果你苦恼于智能体每次运行都生成不同的文档结构，Generator 通过编排一个填空式流程来解决这个问题。

Generator 利用两个可选目录：assets/ 存放输出模板，references/ 存放风格指南。指令充当项目经理——告诉智能体加载模板、阅读风格指南、向用户询问缺失的变量，然后填充文档。这对于生成可预测的 API 文档、标准化提交信息，或搭建项目架构的脚手架都非常实用。

下面这个技术报告生成器的例子中，技能文件本身不包含实际的布局或语法规则，只负责协调资源加载，强制智能体逐步执行：

# 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 模式将”检查什么”和”如何检查”分离开来。与其在系统提示词里写一长串代码异味的描述，不如把一份模块化的评分标准存放在 references/review-checklist.md 文件中。

当用户提交代码时，智能体加载这份清单，系统地审查提交内容，并按严重级别对问题分组。只要把 Python 风格清单换成 OWASP 安全清单，同一套技能基础设施就能产出一份截然不同的专项安全审计。这是自动化 PR 审查或在人工介入前捕获漏洞的高效手段。

下面这个代码审查器技能展示了这种分离。指令本身是静态的，但智能体从外部清单动态加载具体的审查标准，并强制输出结构化结果：

# 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（反转模式）

核心思想

颠覆控制流：智能体先采访用户，收集完整上下文后再行动。

智能体天生倾向于猜测和立即生成。Inversion 模式颠覆了这种互动方式——不再是用户驱动提示词、智能体负责执行，而是让智能体充当采访者。

Inversion 依赖于明确的、不可妥协的门控指令（比如”在所有阶段完成之前，不要开始构建”）来强制智能体先收集上下文。它按顺序提出结构化问题，等你回答后再进入下一阶段。在完整掌握你的需求和部署约束之前，智能体会拒绝生成最终输出。

来看这个项目规划器技能。关键要素在于严格的阶段划分和明确的门控提示词——智能体在收集完所有回答之前，绝不会开始生成最终计划：

# 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 模式通过硬性检查点强制执行严格的顺序工作流。

指令本身就是工作流定义。通过设置明确的菱形门控条件（Diamond Gate Conditions，即流程图中菱形判断节点所代表的前置条件检查）——比如要求用户在文档字符串生成阶段完成后批准，才能进入最终组装阶段——Pipeline 确保智能体无法绕过复杂任务、直接呈现未经验证的最终结果。

这种模式会用到所有可选目录，在特定步骤需要时才拉取对应的参考文件和模板，从而保持上下文窗口的整洁。

在下面这个文档流水线的例子中，注意明确的门控条件——智能体被明确禁止在用户确认前一步生成的文档字符串之前进入组装阶段：

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

选择合适的智能体技能模式

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

最后：模式可以组合

模式并非互斥

Pipeline 可以在末尾加入 Reviewer 步骤来复查自身的工作。Generator 可以在开头借助 Inversion 收集填充模板所需的变量。模式的真正威力在于组合。

借助 ADK 的 SkillToolset（技能管理 API）和渐进式加载（Progressive Disclosure，即按需加载技能上下文），智能体只在运行时消耗实际需要的上下文 token。

核心建议

别再把复杂而脆弱的指令硬塞进一个系统提示词里了。把工作流拆开，应用正确的结构模式，构建可靠的智能体。

立即开始

Agent Skills 规范是开源的，并在 ADK 中得到原生支持。格式你已经会了，现在你也掌握了内容设计。去用 Google Agent Development Kit 构建更强大的智能体吧。