Agent 技能的五种设计模式

1. 技能（SKill）的规范

为了能让Skill 在不同的 Agent 中都很很好的运行， Claude Code、Gemini CLI、GitHub Copilot、Cursor、JetBrains Junie 等都开始使用同一个 Agent 技能标准：https://agentskills.io/specification。在这里规定了技能的目录结构格式，SKILL.md字段的约定，以及技能的扩展方式。

每个技能都遵循相同的目录布局：

复制代码

skill-name/
├── SKILL.md          ← YAML前言 + markdown指令（必需）
├── references/       ← 风格指南、检查列表、约定（可选）
├── assets/           ← 模板和输出格式（可选）
└── scripts/          ← 可执行脚本（可选）

2. Google 技能的五种设计模式

Google 在此基础上在今年的三月又提出了 5 种模式《5 Agent Skill Design Patterns Every ADK Developer Should Know》，其中的ADK是

是 Google Agent Development Kit（谷歌智能体开发工具包）。这是一个由 Google 在 2025 年推出的开源框架，旨在帮助开发者快速构建、管理和部署生产级的 AI 智能体（AI Agents）。其中包含了：Python、Java、Go，以及Typescript 的版本。

SKill 的五种设计模式
- 工具包装器（Tool Wrapper）：使您的代理立即成为任何库或框架的专家
- 生成器（Generator）：从可重用模板中产生结构一致的文档
- 审阅者（Reviewer）：让您的代理根据清单按严重程度评分代码
- 反转（Inversion）：翻转对话------代理在操作之前向您提问
- 流水线（Pipeline） ：强制执行严格的逐步工作流程，并在各阶段之间设置检查点

2.1. 模式1：工具包装器（Tool Wrapper） -- 教Agent工具/库

工具包装器（Tool Wrapper）: 是一种将库或工具的约定、最佳实践和编码标准打包成代理可按需获取的知识的代理技能，当使用该技术时，代理成为领域专家。

这是最简单的SKILL.md模式，只有指令加上参考文件，没有模板或脚本。

工具包装器技能将库或工具的约定打包成按需的知识，代理在加载技能时成为专家。

工具包装器模式：SKILL.md在库关键字上触发，从references/加载约定，并且代理将其作为领域专业知识应用。

2.1.1. 何时使用工具包装器

当您希望您的代理为特定库、SDK或内部系统应用一致的专家级约定时，这是最广泛采用的模式。

举例：
编写一个google-adk-conventions技能来编码您的团队的ADK模式------默认使用哪个模型、如何命名代理、如何布线工具集、如何处理错误------您团队构建的每个ADK代理都会自动遵循相同的约定，无需在每个系统提示中重复它们。

yaml 复制代码

# skills/google-adk-conventions/SKILL.md
---
name: google-adk-conventions
description: Google ADK编码约定和最佳实践。在构建、审查或调试任何ADK代理、工具或多代理系统时使用。
metadata:
  pattern: tool-wrapper
  domain: google-adk
---

您是ADK专家。在编写或审查ADK代码时应用这些约定。

## 代理命名
- \`name\`字段必须与代理的目录名称完全匹配（\`search-agent/\` → \`name="search-agent"\`）
- 使用小写、连字符分隔的名称：\`search-agent\`，而不是\`SearchAgent\`

## 模型选择
- 大多数任务默认使用\`gemini-2.5-flash\`（快速、成本效益高）
- 仅在复杂多步推理时使用\`gemini-2.5-pro\`
- 将模型定义为常量，永远不要内联硬编码：\`MODEL = "gemini-2.5-flash"\`

## 工具定义
加载\`references/tool-conventions.md\`以获取完整规则。要点：
- 命名：动词-名词，snake_case --- \`get_weather\`，\`search_documents\`，而不是\`run\`或\`doStuff\`
- 始终添加类型提示：\`city: str\`，\`user_id: int\`
- 不要使用默认参数值------LLM必须推导或请求所有输入
- 文档字符串是LLM的主要手册------精确描述，不要描述\`ToolContext\`

## 多代理系统
- 子代理上的\`description\`字段是您的路由API------具体一点，不要泛泛而谈
- 每个根代理只使用一个内置工具（Google搜索、代码执行）
- 当代理有5个以上工具时，将相关工具分组到\`BaseToolset\`子类中

2.2. 模式2：生成器（Generator） -- 生成结构化输出

生成器（Generator）: 通过这个模式填充可重用模板生成文档、报告或配置。

与工具包装器不同，它使用两个可选目录：

assets: 保存输出模板（要填充的结构），
references: 保存样式指南（要遵循的质量规则）。

指令协调整个过程，加载样式指南，加载模板，收集输入，填充内容。

生成器模式：指令协调整个过程，references/定义质量规则，assets/提供输出模板。

2.2.1. 何时使用生成器

当输出需要每次都遵循固定结构时，一致性比创造力更重要。常见的实际用途：

技术报告------执行摘要、背景、方法论、发现、建议，无论主题如何，总是在相同的顺序下
API文档------每个端点都使用相同的部分进行文档化：描述、参数、请求/响应示例、错误代码
提交消息 ------从模板执行Conventional Commits格式（feat:、fix:、docs:），以便存储库中的每个提交都读取一致
ADK代理脚手架 ------从模板生成新的ADK项目的标准agent.py + __init__.py + .env结构，预配置了您团队的模型常量和指令样式
示例

yaml 复制代码

# 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文档。

assets/report-template.md中的模板定义了每次报告必须具备的确切部分------执行摘要、背景、方法论、发现、总结表、建议、下一步。
references/style-guide.md中的样式指南控制语调（"第三人称，主动语态"）、格式（"章节用H2，子章节用H3"）和质量（"执行摘要不超过150字，无模糊的下一步"）。

代理在激活技能时通过load_skill_resource加载这两个文件。模板强制执行结构，样式指南强制执行质量。交换任一文件即可更改输出，而无需修改指令。

2.3. 模式3：审阅者（Reviewer） -- 根据标准评估

审阅者（Reviewer） : 技能根据存储在references/中的检查表评估代码、内容或工件，生成按严重性分组的评分结果报告。

关键设计思路：分离检查表文件和指令中的评估协议。将references/review-checklist.md替换为references/security-checklist.md，您可以从相同的技能结构获得完全不同的评估。

审阅者模式：用户提交代码，技能从references/加载其检查表，应用审阅协议，并生成按严重性分组的结果报告。

2.3.1. 何时使用审阅者

任何人类审阅者使用检查表的地方------审阅者技能可以对其进行编码并一致地应用。常见的实际用途：

代码审阅 ------根据团队的样式规则捕获可变默认值、缺少类型提示、裸露的except:块；
安全审计------针对提交的代码运行OWASP Top 10检查，将发现按严重性分类，然后再进行人工审查
编辑审阅------根据房屋样式指南（语调、标题结构、字数、禁用短语）检查博客文章或文档
ADK代理审阅 ------根据团队的google-adk-conventions验证新代理：命名、模型常量、工具文档字符串、描述字段质量
示例

yaml 复制代码

# 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并简要说明理由
- **前三项建议**：最具影响力的改进

references/review-checklist.md:包含按类别组织的实际规则------正确性（严重性：错误）、样式（严重性：警告）、文档（严重性：信息）、安全性（严重性：错误）、性能（严重性：信息）。每个类别都有具体、可检查的项目："无可变默认参数"、"函数少于30行"、"无通配符导入"。

当我使用三个故意的错误测试它时------<PascalCase>命名、可变默认参数和裸露的except:------代理加载了技能，获取了检查表，并捕获了所有三个错误。它将可变默认值分类为错误（正确------这是一个bug），将命名分类为警告（正确------这是样式问题），并生成了评分报告。检查表驱动了行为，而不是代理的预训练。

2.4. 模式4：反转（Inversion） -- 技能采访您

反转（Inversion）: 这种模式翻转了典型的代理交互：不是用户推动对话，而是技能指示代理通过定义的阶段提出结构化问题，然后才产生任何输出。代理在收集到所需的所有信息之前不会行动。

不需要特殊框架支持, 反转纯粹是指令创作模式，依赖于明确的门控，如DO NOT start building until all phases are complete来阻止代理前进。

阶段性结构是使反转有效的关键。第一阶段完成后才能开始第二阶段。第三阶段仅在所有问题都回答后才会触发。顶部的DO NOT start building or designing until all phases are complete指令是关键的门控------没有它，代理往往会在第一个答案后就急于得出结论。

反转模式：技能通过阶段性问题驱动对话，仅在收集完所有答案后才综合输出。

2.4.1. 何时使用反转

代理在能够做有用工作之前需要来自用户的情境的任何地方------它可以防止最常见的代理故障模式：基于假设而非询问来生成详细计划。常见的实际用途：

需求收集------在生成技术设计之前，就项目对用户进行访谈，确保计划反映实际约束而非猜测
诊断访谈------逐步进行结构化故障排除检查表（环境、版本、错误消息、重现步骤），然后提出修复方案
配置向导------收集部署首选项（云提供商、区域、扩展要求），然后生成基础架构配置
ADK代理设计------在搭建新的ADK代理之前，对用户进行访谈：它需要什么工具、使用哪种模型、是否是多代理系统的一部分、路由约束是什么？
示例

yaml 复制代码

# skills/project-planner/SKILL.md
---
name: project-planner
description: 通过结构化问题收集需求来规划新软件项目，然后生成计划。当用户说"我想构建"、"帮我规划"、"设计一个系统"或"开始一个新项目"时使用。
metadata:
  pattern: inversion
  interaction: multi-turn
---

您正在进行结构化的需求访谈。在所有阶段完成之前不要开始构建或设计。

## 第一阶段------问题发现（一次问一个问题，等待每个答案）

按顺序提出这些问题。不要跳过任何问题。

- Q1："这个项目为用户解决了什么问题？"
- Q2："主要用户是谁？他们的技术水平如何？"
- Q3："预期规模是多少？（每日用户数、数据量、请求率）"

## 第二阶段------技术约束（仅在第一阶段完全回答后）

- Q4："您将使用什么部署环境？"
- Q5："您有任何技术栈要求或偏好吗？"
- Q6："不可协商的要求是什么？（延迟、正常运行时间、合规性、预算）"

## 第三阶段------综合（仅在所有问题回答后）

1. 加载'assets/plan-template.md'以获取输出格式
2. 使用收集到的需求填写模板的每个部分
3. 向用户呈现完成的计划
4. 询问："此计划是否准确反映了您的需求？您会改变什么？"
5. 根据反馈迭代，直到用户确认

assets/plan-template.md
锚定了综合步骤。它定义了问题陈述、目标用户、规模要求、技术架构、不可协商要求、提议的里程碑、风险与缓解措施以及决策日志的部分。代理使用访谈答案填写此模板，无论对话如何进行，都产生一致的输出。

2.5. 模式5：流水线（Pipeline）-- 执行多步骤工作流程

流水线（Pipeline）：技能定义了一个顺序工作流，其中每个步骤必须在下一个步骤开始之前完成，并具有显式的门控条件，以防止代理跳过验证。

这是最复杂的模式，与仅加载参考文献的工具包装器不同，流水线使用所有三个可选目录（references/、assets/、scripts/）并在步骤之间添加控制流。指令本身即为工作流定义。

流水线模式：步骤按顺序执行，带有菱形门控条件。"用户确认？"门控防止代理跳过验证。

2.5.1. 何时使用流水线

任何多步骤过程中，步骤之间有依赖关系且顺序很重要的情况------如果跳过一个步骤会产生不正确或未经验证的输出，请使用流水线。常见的实际用途：

文档生成------解析代码→生成文档字符串（经用户批准）→汇编文档→质量检查，各阶段之间设有门控
数据处理------验证输入→转换→丰富→写入输出，每个步骤必须在下一阶段运行前成功完成
部署工作流------运行测试→构建构件→部署到暂存环境→烟雾测试→提升到生产环境，带有人工确认门控
ADK代理入职------采访用户（反转）→搭建文件（生成器）→根据约定验证（审阅者），将三种模式组合成一个流水线
示例

yaml 复制代码

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: 通过多步骤流水线从Python源代码生成API文档。当用户要求记录模块、生成API文档或从代码创建文档时使用。
metadata:
  pattern: pipeline
  steps: "4"
---

您正在运行文档生成流水线。按顺序执行每个步骤。如果步骤失败，则不要跳过步骤或继续。

## 步骤1------解析和清点
分析用户的Python代码，提取所有公共类、函数和常量。将库存作为检查列表呈现。询问："这是您想要文档化的完整公共API吗？"

## 步骤2------生成文档字符串
对于缺少文档字符串的每个函数：
- 加载'references/docstring-style.md'以获取所需格式
- 精确遵循样式指南生成文档字符串
- 向用户展示每个生成的文档字符串以供批准
在用户确认之前，请勿进入步骤3。

## 步骤3------组装文档
加载'assets/api-doc-template.md'以获取输出结构。将所有类、函数和文档字符串汇编成单个API参考文档。

## 步骤4------质量检查
根据'references/quality-checklist.md'进行审查：
- 每个公共符号都已记录
- 每个参数都有类型和描述
- 每个函数至少有一个使用示例
报告结果。在提交最终文档之前修复问题。

门控条件是定义特征。"在用户确认之前请勿进入步骤3"可防止代理在未审查文档字符串的情况下组装文档。顶部的"不要跳过步骤或在步骤失败时继续"可执行顺序约束。没有这些门控，代理往往会一路冲过所有步骤并提交跳过了验证的最终结果。

每个步骤加载不同的资源。

步骤2加载references/docstring-style.md, Google样式的文档字符串格式。

步骤3加载assets/api-doc-template.md, 输出结构，包含目录、类、函数、常量部分。

步骤4加载references/quality-checklist.md, 完整性和质量规则。

代理只为每个步骤需要的资源支付上下文token。

3. 选择正确的技能模式

每种模式回答一个不同的问题。使用此表找到合适的模式，如果您仍然不确定，请使用下面的决策树。

模式	使用场景	使用的目录	复杂性
工具包装器	代理需要有关特定库或工具的专业知识	`references/`	低
生成器	输出必须每次都遵循固定模板	`assets/` + `references/`	中
审阅者	代码或内容需要根据清单进行评估	`references/`	中
反转	代理必须在操作之前从用户那里收集上下文	`assets/`	中 - 多轮
流水线	工作流有带验证门控的有序步骤	`references/` + `assets/` + `scripts/`	高

模式可以组合：

流水线可以包含审阅者步骤：------doc-pipeline的步骤4加载quality-checklist.md并根据其评估汇编的文档，这是嵌入流水线中的审阅者模式。
生成器可以使用反转在生成输出之前收集输入。
工具包装器可以作为参考文件嵌入到流水线技能中。

生产系统通常结合2-3种模式，最常见的组合是元数据驱动的披露（我们的工具包装器）加市场分发。

如果您不确定哪种模式适合，请从以下决策树开始：

决策指南：遵循yes/no分支以找到适合您用例的正确模式。大多数技能明显映射到一种模式。

Agent 技能的五种设计模式

1. 技能（SKill） 的规范

2. Google 技能的五种设计模式

2.1. 模式1：工具包装器（Tool Wrapper） -- 教Agent工具/库

2.1.1. 何时使用工具包装器

2.2. 模式2：生成器（Generator） -- 生成结构化输出

2.2.1. 何时使用生成器

2.3. 模式3：审阅者（Reviewer） -- 根据标准评估

2.3.1. 何时使用审阅者

2.4. 模式4：反转（Inversion） -- 技能采访您

2.4.1. 何时使用反转

2.5. 模式5：流水线（Pipeline）-- 执行多步骤工作流程

2.5.1. 何时使用流水线

3. 选择正确的技能模式

1. 技能（SKill）的规范