每位 ADK（Agent Development Kit）开发者都应掌握的 5 大智能体技能设计模式
在 SKILL.md 的实际应用中，开发者往往过于关注格式——如 YAML 的正确性、目录结构以及规范的遵循。但随着超过 30 款智能体工具（如 Claude Code、Gemini CLI 和 Cursor）统一采用相同布局，格式问题基本已解决，不再是主要难题。
如今的挑战在于内容设计。规范只说明了如何打包技能，却没有任何关于内部逻辑结构的指导。例如，一个封装 FastAPI 约定的技能，其运行方式与一个四步文档流水线完全不同，尽管它们的 SKILL.md 文件在外观上看起来完全一致。
通过研究整个生态系统中技能的构建方式——从 Anthropic 的开源库到 Vercel 和 Google 的内部规范——我们总结出五种反复出现的设计模式，可帮助开发者构建更强大的智能体。
作者：@Saboo_Shubham_ 和 @lavinigam
本文将结合实际 ADK 代码，逐一讲解这五种模式：
- 工具封装器（Tool Wrapper）：让智能体瞬间精通任意库
- 生成器（Generator）：基于可复用模板生成结构化文档
- 代码审查器（Reviewer）：按严重级别用检查清单对代码评分
- 反转模式（Inversion）：智能体在执行前先采访你
- 流水线模式（Pipeline）：通过检查点强制执行多步工作流
模式一：工具封装器（Tool Wrapper）
工具封装器为智能体按需提供某个库的上下文信息。你无需将 API 约定硬编码到系统提示词中，而是将其打包为一个技能。智能体只有在实际需要处理该技术时才会加载相关上下文。
这是最易实现的设计模式。SKILL.md 文件会监听用户提示中的特定库关键词，动态从 references/ 目录加载内部文档，并将这些规则视为绝对准则。这正是将团队内部编码规范或特定框架最佳实践直接注入开发者工作流的机制。
下面是一个教会智能体如何编写 FastAPI 代码的工具封装器示例。请注意，指令明确要求智能体仅在开始审查或编写代码时才加载 conventions.md 文件：
# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI 开发最佳实践与约定。用于构建、审查或调试 FastAPI 应用、REST API 或 Pydantic 模型时。
metadata:
pattern: tool-wrapper
domain: fastapi
---你是一位 FastAPI 开发领域的专家。请将这些规范应用到用户的代码或问题中。
## 核心规范
加载 `references/conventions.md` 以查看 FastAPI 最佳实践的完整列表。
## 审查代码时
1. 加载 conventions 参考文档
2. 按照每条规范逐项检查用户代码
3. 对每一处违规，引用具体规则并提出修正建议
## 编写代码时
1. 加载 conventions 参考文档
2. 严格遵循每一条规范
3. 为所有函数签名添加类型注解
4. 使用 Annotated 风格进行依赖注入 模式二：生成器
工具封装器用于应用知识，而生成器则确保输出的一致性。如果你遇到智能体每次生成的文档结构都不一致，生成器会通过“填空式”流程解决这一问题。
它利用两个可选目录：assets/ 用于存放输出模板，references/ 用于存放风格指南。指令扮演项目经理的角色，指导智能体加载模板、阅读风格指南、向用户询问缺失变量，并填充文档内容。这种方式非常适合生成可预测的 API 文档、规范化提交信息或搭建项目架构。
在这个技术报告生成器示例中，技能文件并不包含实际的布局或语法规则，而是协调这些资源的获取，并强制智能体按步骤执行：
# skills/report-generator/SKILL.md
---
name: report-generator
description: 以 Markdown 格式生成结构化技术报告。当用户请求撰写、创建或草拟报告、摘要或分析文档时使用。
metadata:
pattern: generator
output-format: markdown
---你是一名技术报告生成器。请严格按照以下步骤执行：
步骤 1：加载 'references/style-guide.md' 以获取语气和格式规则。
第2步：加载 'assets/report-template.md' 以获取所需的输出结构。
步骤 3：向用户询问填充模板所需的缺失信息：
- 主题或题材
- 关键发现或数据点
- 目标受众（技术类、管理层、普通大众）
步骤4：按照风格指南填写模板。模板中的每个部分都必须在输出中完整呈现。
步骤 5：将完整报告作为单一 Markdown 文档返回。模式 3：代码审查器
代码审查器模式将“检查什么”与“如何检查”分离。与其编写冗长的系统提示逐一列出每个代码异味，不如将模块化的评分标准存储在 references/review-checklist.md 文件中。
当用户提交代码时，智能体会加载这份检查清单，系统地对提交内容进行评分，并按严重级别分组发现结果。如果将 Python 风格检查清单替换为 OWASP 安全检查清单，依然可以在同一技能基础设施下获得完全不同且专业化的审计。这种方式非常适合自动化 PR 审查，或在人工审查代码前捕获潜在漏洞。
下面的代码审查技能展示了这种分离。指令保持静态，但智能体会动态加载外部检查清单中的具体审查标准，并强制输出结构化、基于严重级别的结果：
# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: 审查 Python 代码的质量、风格和常见漏洞。用于用户提交代码进行审查、请求代码反馈或希望进行代码审计的场景。
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
你是一名 Python 代码审查器。请严格遵循以下审查流程执行：
步骤 1：加载 `references/review-checklist.md`，查看完整的审查标准。
步骤2：仔细阅读用户代码，并在评审前先明确其用途。
步骤 3：将检查清单中的每条规则应用到代码中。对于发现的每个违规项：
- 标注行号（或大致位置）
- 分类严重级别：error（必须修复）、warning（建议修复）、info（可考虑）
- 说明为什么这是问题，而不仅仅指出错误所在
- 提出具体的修复建议，并附上修正后的代码
步骤4：生成结构化审查报告，包含以下部分：
- **摘要**：代码功能说明及整体质量评估
- **发现**：按严重级别分组（先列错误，其次警告，最后信息）
- **评分**：1-10分，并简要说明理由
- **三大建议**：最具影响力的改进措施模式4：反转模式
智能体通常倾向于立即猜测并生成内容。反转模式则颠倒这一流程——由智能体担任“面试官”主动发问，而不是由用户主导提示并由智能体执行。
反转模式依赖明确且不可协商的门控指令（如“在所有阶段完成之前，禁止开始构建”），强制智能体先收集上下文。它会按顺序提出结构化问题，并在收到你的回答后才进入下一阶段。在未完全掌握你的需求和部署约束之前，智能体不会生成最终输出。
要了解实际应用，请参考以下项目规划技能。关键要素在于严格的阶段划分，以及明确的门控提示，确保智能体在收集完所有用户答案之前不会生成最终方案：
# skills/project-planner/SKILL.md
---
name: project-planner
description: 通过结构化提问收集需求，规划新软件项目，最终生成方案。当用户说“我想开发”、“帮我规划”、“设计系统”或“启动新项目”时使用。
metadata:
pattern: inversion
interaction: multi-turn
---
你正在进行结构化需求访谈。在所有阶段完成之前，务必不要开始构建或设计。
## 第一阶段 — 问题发现（一次只提一个问题，等待每个答案）
请按顺序提出这些问题，任何一个都不得跳过。
- 问题1：“该项目为用户解决了哪些问题？”
- 问题2：“主要用户是谁？他们的技术水平如何？”
- 问题3：“预期规模是多少？（每日用户数、数据量、请求频率）”
## 阶段二 — 技术限制（仅在阶段一全部回答后进行）
- 问题4：“您将使用什么部署环境？”
- 问题5：“您是否有技术栈方面的要求或偏好？”
- 问题6：“有哪些不可妥协的需求？（延迟、在线率、合规性、预算）”
## 阶段 3 — 综合（仅在所有问题全部回答后进行）
1. 加载 `assets/plan-template.md`，作为输出格式
2. 使用收集到的需求填写模板的每个部分
3. 向用户展示完整计划
4. 提问：“此计划是否准确反映您的需求？您会做哪些修改？”
5. 根据反馈迭代，直到用户确认 模式五：流水线模式
对于复杂任务，绝不能跳过步骤或忽略指令。流水线模式会强制执行严格的顺序流程，并设置不可绕过的硬性门控条件。
指令本身即是工作流程的定义。通过明确的门控条件（例如必须在用户批准后才能从文档字符串生成阶段进入最终组装），流水线模式确保智能体无法绕过复杂任务，直接输出未经验证的最终结果。
该模式充分利用所有可选目录，仅在具体步骤需要时加载不同的参考文件和模板，从而保持上下文窗口的整洁。
在此文档流水线示例中，请注意显式的门控条件：智能体被明确禁止在用户确认前一步生成的文档字符串之前进入组装阶段。
# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: 通过多步流水线从 Python 源代码生成 API 文档。适用于用户请求模块文档、生成 API 文档或从代码创建文档的场景。
metadata:
pattern: pipeline
steps: "4"
---您正在运行文档生成流水线。请按顺序执行每一步，切勿跳过，也不要在某一步失败时继续。
## 第一步 — 解析与清单整理
分析用户的 Python 代码，提取所有公开类、函数和常量，并将其整理为检查清单。询问用户：“这就是您希望文档化的全部公开 API 吗？”
## 步骤 2 — 生成文档字符串
针对每个缺少文档字符串的函数：
- 加载 `references/docstring-style.md` 获取所需格式
- 严格按照风格指南生成文档字符串
- 将每个生成的文档字符串展示给用户审核
在用户确认之前，**不得**进入步骤 3。
## 步骤 3 — 汇编文档
加载 `assets/api-doc-template.md` 获取输出结构，将所有类、函数及其文档字符串整合为一份完整的 API 参考文档。
## 第4步 — 质量检查
请根据 `references/quality-checklist.md` 进行审查：
- 每个公开符号均有文档说明
- 每个参数都有类型和描述
- 每个函数至少有一个使用示例
报告检查结果，并在提交最终文档前修复所有问题。
选择合适的智能体技能模式
每种模式都针对不同的问题。请参考下方决策树，找到适合你用例的模式：
最后，模式可以组合使用
这些模式并非互斥，而是可以组合。
例如，流水线模式的技能可以在最后加入代码审查器步骤，对自身输出进行二次检查；生成器模式可以在流程最初借助反转模式，先收集所需变量，再填充模板。借助 ADK 的 SkillToolset 和渐进式披露（按需加载上下文），你的智能体只会在运行时为所需模式消耗上下文令牌。
不要再试图将复杂且脆弱的指令塞进单一系统提示中。请拆分工作流程，应用合适的结构化模式，构建可靠的智能体。
立即开始实践
Agent Skills 规范是开源的，并已在 ADK 中原生支持。你已经掌握了格式打包的方法，现在也了解了内容设计的原则。用 Google Agent Development Kit 构建更智能的智能体吧。
作者：@Saboo_Shubham_ 和 @lavinigam
讨论
登录后可评论、点赞、引用回复。