ADK 开发者必知的 5 种 Agent 技能设计模式
发布于 • 作者: Ethan
概述
本文是5 Agent Skill design patterns every ADK developer should know的笔记。
引言
在开发 Agent 技能（处理 SKILL.md 文件）时，开发者往往过于关注格式问题——例如确保 YAML 语法正确、构建合理的目录结构以及遵循规范。然而，随着 Claude Code、Gemini CLI 和 Cursor 等 30 多种 Agent 工具都在采用相同的布局标准，格式问题实际上已被解决。
如今的真正挑战在于内容设计。虽然规范说明了如何打包技能，但并没有就如何构建其内部逻辑提供指导。例如，一个封装 FastAPI 约定的技能与一个包含四个步骤的文档生成流水线，其内部运行机制截然不同，即便它们的 SKILL.md 文件在外部看起来毫无二致。
通过研究整个生态系统（从 Anthropic 的代码库到 Vercel 以及 Google 的内部指南）中技能的构建方式，可以总结出 5 种反复出现的 Agent 核心设计模式。
模式 1：工具包装器 (The Tool Wrapper)
工具包装器模式能够为 Agent 提供针对特定库的按需上下文。相较于将 API 约定硬编码到系统提示词中，更好的做法是将它们打包成一个独立的技能。Agent 只有在实际使用该特定技术时，才会加载这些上下文。
这是最容易实现的一种模式。SKILL.md 文件会监听用户提示词中特定的库关键字，动态加载位于 references/ 目录下的内部文档，并将这些规则作为绝对准则加以应用。这种机制非常适合将团队的内部编码规范或特定框架的最佳实践直接分发到开发者的工作流中。
以下是一个教授 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
---
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：生成器 (The Generator)
如果说工具包装器用于应用知识，那么生成器模式则用于强制执行一致的输出。如果面临 Agent 每次运行生成的文档结构都不一致的困境，生成器模式可以通过协调一个“填空”过程来解决此问题。
该模式利用了两个可选目录：assets/ 用于存放输出模板，references/ 用于存放样式指南。指令在这里充当项目经理的角色，指示 Agent 加载模板、阅读样式指南、向用户询问缺失的变量，并最终填充文档。这种模式在生成可预测的 API 文档、标准化提交信息 (commit messages) 或搭建项目架构时非常实用。
在下面的技术报告生成器示例中，技能文件本身并不包含实际的布局或语法规则。它仅仅负责协调这些资产的检索，并强制 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：审查员 (The Reviewer)
审查员模式将“审查什么”与“如何审查”分离开来。与其编写冗长的系统提示词来详细说明每一种代码异味 (code smell)，不如将模块化的评分标准存储在 references/review-checklist.md 文件中。
当用户提交代码时，Agent 会加载此检查表，并系统地对提交的内容进行评分，按严重程度对发现的问题进行分类。如果将 Python 样式检查表替换为 OWASP 安全检查表，就可以使用完全相同的技能基础设施获得一个截然不同且专业的安全审计。这是一种自动化 PR（拉取请求）审查或在人工介入前捕获漏洞的高效方法。
以下代码审查技能展示了这种分离机制。指令保持静态，但 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 天生倾向于立即进行猜测和生成。反转模式颠覆了这种动态。该模式下，不再由用户主导提示词并由 Agent 执行，而是让 Agent 扮演面试官的角色。
反转模式依赖于明确且不可协商的门控指令（例如“在所有阶段完成之前，不要开始构建”），以强制 Agent 首先收集上下文。它会按顺序提出结构化问题，并等待答案后再进入下一个阶段。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
模式 5：流水线 (The 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"
---
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 技能模式
每种模式都解决了不同的问题。通常可以通过决策树来为特定用例找到合适的模式。
模式的组合应用
这些模式相互之间并不是排斥的，它们可以组合使用。
一个流水线 (Pipeline) 技能可以在最后包含一个审查员 (Reviewer) 步骤，以复查其自身的工作。一个生成器 (Generator) 可以依赖反转 (Inversion) 模式在最开始收集必要的变量，然后再填充其模板。得益于 ADK 的 SkillToolset 机制和渐进式披露，Agent 只会在运行时将上下文 Token 花费在它确切需要的模式上。
避免试图将复杂和脆弱的指令塞进一个单一的系统提示词中。将工作流分解，应用正确的结构模式，可以构建出更可靠的 Agent。