Agent Skill 设计模式完全指南

本文深入解析 Google ADK 团队总结的五种 Skill 设计模式，帮助你根据不同场景选择最合适的 Skill 内部逻辑组织方式。

前言

规范告诉我们"Skill 长什么样"，但没告诉我们"Skill 内部的逻辑该怎么设计"。

一个封装 FastAPI 规范的 Skill 和一个分 4 步执行的文档流水线 Skill，虽然外表都叫 SKILL.md，但内部结构完全不是一回事。

Google ADK 团队研究了生态中各种 Skill 的实现方式，从 Anthropic 仓库到 Vercel 和 Google 内部指南，总结出 5 种反复出现的设计模式。

五种 Skill 设计模式总览

模式	核心问题	适用场景
Tool Wrapper	如何让 Agent 调用特定工具？	封装框架规范、技术栈最佳实践
Generator	如何生成一致的文档/代码？	标准化输出、模板填充
Reviewer	如何自动化审查代码或内容？	代码审查、质量检查
Inversion	如何先收集信息再执行？	需求不明确、需要结构化提问
Pipeline	如何组织多步骤工作流？	复杂任务分解、流水线处理

模式一：Tool Wrapper --- 给 Agent 装"技能包"

核心逻辑

让 Agent 在需要时才加载特定领域的知识，而不是把所有东西塞进 system prompt。

objectivec 复制代码

┌─────────────────────────────────────────────────────────────┐
│                    Tool Wrapper 模式                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   SKILL.md ────── 告诉 Agent ──────→ references/规范文件   │
│                         │                    │              │
│                         │ 去哪里找知识          │ 按需加载       │
│                         ▼                    ▼              │
│                   Agent 执行任务         Agent 获得完整指导   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

适用场景

封装框架/库的编码规范
团队内部代码风格指南
特定技术栈的最佳实践

模式结构

yaml 复制代码

---
name: api-expert
description: FastAPI 开发最佳实践与规范。适用于构建、审查或调试 FastAPI 应用程序时使用。
---

## 核心规范
加载 'references/conventions.md' 获取完整规范列表。

## 审查代码时
1. 加载规范参考文件
2. 对照每条规范逐一检查用户代码
3. 针对每处违规，引用具体规则并给出修改建议

关键设计点

SKILL.md 本身不包含完整规范，而是告诉 Agent 去哪里加载规范。

这种设计的优势：

规范可以独立维护和更新
Agent 只在需要时加载相关知识
避免上下文膨胀

进阶变体：多层 Tool Wrapper

yaml 复制代码

---
name: fullstack-expert
description: Full-stack web development guidance for React, Node.js, and PostgreSQL applications.
---

## 当你需要前端指导时
加载 'references/frontend-conventions.md'

## 当你需要后端指导时
加载 'references/backend-conventions.md'

## 当你需要数据库指导时
加载 'references/database-conventions.md'

模式二：Generator --- 填空题式文档生成

核心逻辑

用模板 + 风格指南强制输出一致性。

vbnet 复制代码

┌─────────────────────────────────────────────────────────────┐
│                      Generator 模式                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Step 1: 加载风格指南（references/style-guide.md）          │
│              ↓                                              │
│   Step 2: 加载模板（assets/report-template.md）              │
│              ↓                                              │
│   Step 3: 向用户询问缺失信息（主动提问）                       │
│              ↓                                              │
│   Step 4: 按规范填充模板                                     │
│              ↓                                              │
│   Step 5: 返回成品                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

适用场景

标准化技术文档生成
API 文档自动生成
项目脚手架

模式结构

yaml 复制代码

---
name: report-generator
description: 以 Markdown 格式生成结构化技术报告。
---

第一步：加载 'references/style-guide.md'，获取语气和格式规范。

第二步：加载 'assets/report-template.md'，获取所需的输出结构。

第三步：向用户询问缺失信息：
  - 主题或议题
  - 关键发现或数据要点
  - 目标受众

第四步：按照风格指南规范填写模板。

第五步：返回已完成的报告。

关键设计点

Step 3 的主动提问 ------ Agent 不会瞎猜，缺什么直接问。

这是一个非常重要的设计哲学：

与其让 Agent 猜测缺失的信息，不如让它主动询问用户。

模板文件示例

markdown 复制代码

<!-- assets/report-template.md -->

# 技术报告：{{title}}

## 执行摘要
{{executive_summary}}

## 背景
{{background}}

## 详细分析

### {{section_1_title}}
{{section_1_content}}

### {{section_2_title}}
{{section_2_content}}

## 结论与建议
{{conclusions}}

## 附录
{{appendix}}

模式三：Reviewer --- 代码审查自动化

核心逻辑

把"查什么"和"怎么查"分离。检查清单独立维护，Agent 只负责执行打分。

scss 复制代码

┌─────────────────────────────────────────────────────────────┐
│                      Reviewer 模式                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────────┐                                       │
│   │ Review Checklist │  ← 独立维护的检查清单                   │
│   │ (references/)    │                                       │
│   └────────┬────────┘                                       │
│            │ 按需加载                                          │
│            ▼                                                  │
│   ┌─────────────────┐     ┌─────────────────┐               │
│   │  Agent 执行审查   │ ──→ │  结构化审查报告   │               │
│   └─────────────────┘     └─────────────────┘               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

适用场景

自动化 PR 审查
安全漏洞扫描
代码风格检查

模式结构

yaml 复制代码

---
name: code-reviewer
description: 审查 Python 代码的质量、风格与常见错误。
---

第一步：加载 'references/review-checklist.md'。

第二步：仔细阅读用户的代码。

第三步：逐一应用清单中的每条规则。针对每处违规：
  - 记录行号
  - 划分严重等级：错误 / 警告 / 提示
  - 解释问题的原因，而不仅仅是描述问题本身
  - 给出具体的修改建议

第四步：按严重等级分组，输出结构化的审查报告。

关键设计点

Step 3 的 "WHY not WHAT" ------ 不只指出问题，还要解释为什么是问题。

检查清单文件示例

markdown 复制代码

<!-- references/review-checklist.md -->

# Python 代码审查清单

## 错误处理
- [ ] 是否捕获了所有必要的异常？
- [ ] 异常信息是否足够具体？
- [ ] 是否有裸露的 `except:` 捕获所有异常？

## 性能
- [ ] 是否有 N+1 查询问题？
- [ ] 是否有不必要的循环？
- [ ] 大文件处理是否使用了流式处理？

## 安全
- [ ] 是否有 SQL 注入风险？
- [ ] 是否有 XSS 风险？
- [ ] 敏感信息是否硬编码？

## 代码风格
- [ ] 函数命名是否清晰？
- [ ] 是否有适当的文档字符串？
- [ ] 代码复杂度是否过高？

模式四：Inversion --- 让 Agent 先问你

核心逻辑

翻转传统交互模式。不是用户驱动 prompt → Agent 执行，而是 Agent 先采访用户，收集完整需求后再动手。

复制代码

┌─────────────────────────────────────────────────────────────┐
│                     Inversion 模式                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   传统模式:                                                    │
│   用户 → Agent → 执行（信息不足时猜测）                            │
│                                                             │
│   Inversion 模式:                                             │
│   Agent 采访用户 → 收集信息 → 确认理解 → 执行                    │
│                                                             │
│   ┌──────────────────────────────────────────┐              │
│   │  第一阶段：问题探索（一次问一个问题）           │              │
│   │  第二阶段：技术约束（前提：问题已明确）           │              │
│   │  第三阶段：综合整理（加载模板 → 填充 → 呈现）     │              │
│   └──────────────────────────────────────────┘              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

适用场景

新项目规划
系统架构设计
需求不明确时的需求澄清

模式结构

yaml 复制代码

---
name: project-planner
description: 通过结构化提问收集需求，为新软件项目制定规划。
---

在所有阶段完成之前，请勿开始构建。

## 第一阶段 --- 问题探索
每次只提一个问题：
- 问题1："这个项目解决什么问题？"
- 问题2："主要用户群体是哪些？"
- 问题3："预期的使用规模是多少？"

## 第二阶段 --- 技术约束
仅在第一阶段全部回答完毕后进行：
- 问题4："部署环境是什么？"
- 问题5："是否有技术栈偏好？"
- 问题6："哪些是不可妥协的硬性需求？"

## 第三阶段 --- 综合整理
收集所有信息 → 加载模板 → 填写内容 → 呈现结果 → 迭代优化

关键设计点

阶段性门控 ------ 后续阶段必须在前置阶段完成后才能开始。

变体：分页式信息收集

yaml 复制代码

---
name: requirements-collector
description: 通过多轮对话系统性地收集项目需求。
---

## 规则
- 每个回复只问最多 3 个问题
- 用编号列出待回答的问题
- 等待用户回答后再继续
- 回答不全不开始开发

## 信息类别
1. 业务目标（必须回答）
2. 用户故事（必须回答）
3. 技术约束（可选）
4. 成功指标（可选）

模式五：Pipeline --- 带检查点的多步工作流

核心逻辑

把复杂任务拆成严格顺序的步骤，每步都有明确的输入/输出和通过条件，Agent 不能跳步。

vbnet 复制代码

┌─────────────────────────────────────────────────────────────┐
│                      Pipeline 模式                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐         │
│   │ Step 1│ ──→ │ Step 2│ ──→ │ Step 3│ ──→ │ Step 4│         │
│   │ 解析   │    │ 生成   │    │ 组装   │    │ 质量检查│         │
│   └──┬────┘    └──┬────┘    └──┬────┘    └──┬────┘         │
│      │           │           │           │                │
│      ▼           ▼           ▼           ▼                │
│   输入确认     用户确认      用户确认      最终检查           │
│      │           │           │           │                │
│      └───────────┴───────────┴───────────┘                │
│                    ↑                                       │
│              【确认前不得继续】硬性约束                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

适用场景

从代码生成文档
多阶段内容生产
需要人工检查点的自动化流程

模式结构

yaml 复制代码

---
name: doc-pipeline
description: 通过多步骤流水线，从 Python 源代码生成 API 文档。
---

按顺序执行每个步骤，不得跳过任何步骤。

## 第一步 --- 解析与清点
分析代码，提取所有公开 API，以清单形式呈现。
询问："这是完整的公开 API 列表吗？"

## 第二步 --- 生成文档字符串
针对每个缺少文档字符串的函数，生成内容并提交用户确认。
在用户确认之前，不得进入第三步。

## 第三步 --- 组装文档
加载模板，将所有内容汇编为统一的 API 参考文档。

## 第四步 --- 质量检查
对照清单进行审查，在呈现最终文档之前修复所有问题。

关键设计点

Step 2 → Step 3 的【确认前不得继续】是硬性约束 ------ 用户不点头，Agent 不能往下走。

变体：带自动验证的 Pipeline

yaml 复制代码

---
name: deployment-pipeline
description: 通过验证步骤部署应用到 Kubernetes 集群。
---

## 第一步 --- 预检查
验证所有配置：
- kubectl 配置正确
- Docker 镜像已构建
- 所有 secrets 已配置

## 第二步 --- 语法验证
运行：kubectl --dry-run=client -f manifests/
仅在无错误时继续。

## 第三步 --- 部署
应用清单到目标集群。
立即运行健康检查。

## 第四步 --- 验证
执行冒烟测试套件。
检查关键指标（延迟、错误率）。

## 第五步 --- 回滚（如需要）
如果验证失败，自动回滚到上一版本。

设计模式选择指南

按需求类型选择

你需要什么？	选择哪种模式
特定技术栈的专家知识	Tool Wrapper
一致的结构化输出	Generator
自动化代码/内容审查	Reviewer
需求不明确，需先收集信息	Inversion
复杂的多步骤任务	Pipeline
不确定？	从 Tool Wrapper 开始

按复杂度选择

javascript 复制代码

低复杂度 ────────────────────────────────────────────── 高复杂度

┌─────────┐     ┌──────────┐     ┌───────────┐     ┌────────────┐
│Tool     │ ──→ │Generator │ ──→ │Reviewer   │ ──→ │Inversion   │
│Wrapper  │     │          │     │           │     │            │
└─────────┘     └──────────┘     └───────────┘     └─────┬──────┘
                                                         │
                                                         ▼
                                                   ┌────────────┐
                                                   │ Pipeline   │
                                                   │(可选组合以上) │
                                                   └────────────┘

模式组合推荐

在实际项目中，模式组合往往能发挥更大威力：

组合	说明	场景
Pipeline + Reviewer	管道最后一步加自动审查	文档生成后自动质量检查
Generator + Inversion	先收集信息再填充模板	需用户输入的结构化文档生成
Pipeline + Tool Wrapper	管道某些步骤加载专家知识	多步骤代码生成（每步有特定规范）
Inversion + Pipeline	先完成需求收集再进入执行流水线	复杂项目全流程（需求→设计→实现→验证）

组合示例：Inversion + Pipeline + Reviewer

yaml 复制代码

---
name: full-project-scaffolder
description: 通过结构化流程引导用户完成项目脚手架生成。
---

## Phase 1: 需求收集（Inversion）
... [收集项目需求] ...

## Phase 2: 项目生成（Pipeline）
### 步骤 1: 生成项目结构
### 步骤 2: 生成配置文件
### 步骤 3: 生成入口文件
... [等待用户确认] ...

## Phase 3: 代码审查（Reviewer）
加载 'references/best-practices.md'
逐一检查生成的文件...

最佳实践

1. 选择合适的自由度

自由度	适用场景	示例
高	多种方法都有效	代码审查流程
中	有首选模式但允许变化	带参数的脚本模板
低	操作脆弱、一致性关键	数据库迁移命令

2. 设置检查点和反馈循环

对于复杂任务，在关键步骤后设置验证点：

yaml 复制代码

## 第三步 --- 验证
运行验证器：python validate.py output/
如果验证失败：
  - 仔细阅读错误信息
  - 修复问题
  - 再次验证
仅在验证通过后才继续。

3. 保持 Skill 精简

建议正文控制在 500 行以内。如果内容较多，把详细资料拆分到单独的文件中。

4. Description 只描述触发条件

yaml 复制代码

# ❌ 总结了工作流
description: Use when executing plans - dispatches subagent per task with code review

# ✅ 只有触发条件
description: Use when executing implementation plans with independent tasks

总结

模式	核心价值	关键设计点
Tool Wrapper	知识封装，按需加载	SKILL.md 指向 references/
Generator	一致性输出	模板 + 主动询问缺失信息
Reviewer	标准化审查	检查清单独立，Agent 执行打分
Inversion	需求优先	分阶段门控，不满足条件不执行
Pipeline	步骤控制	【确认前不得继续】硬性约束

记住：没有最好的模式，只有最适合当前场景的模式。从 Tool Wrapper 开始，逐步探索更复杂的模式组合。

参考资料

描述	链接
Agent Skills 开放规范	agentskills.io/specificati...
Google ADK Skill 设计模式	x.com/GoogleCloud...
Anthropic 官方 Skills 仓库	github.com/anthropics/...
Awesome Agent Skills	github.com/VoltAgent/a...
Superpowers 框架	github.com/obra/superp...