Agent 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。

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

适用场景

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

模式结构

---
name: api-expert
description: FastAPI 开发最佳实践与规范。适用于构建、审查或调试 FastAPI 应用程序时使用。
---
## 核心规范
加载 'references/conventions.md' 获取完整规范列表。
## 审查代码时
1. 加载规范参考文件
2. 对照每条规范逐一检查用户代码
3. 针对每处违规，引用具体规则并给出修改建议

关键设计点

SKILL.md 本身不包含完整规范，而是告诉 Agent 去哪里加载规范。这种设计的优势：

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

进阶变体：多层 Tool Wrapper

---
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 — 填空题式文档生成

核心逻辑

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

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

适用场景

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

模式结构

---
name: report-generator
description: 以 Markdown 格式生成结构化技术报告。
---
第一步：加载 'references/style-guide.md'，获取语气和格式规范。
第二步：加载 'assets/report-template.md'，获取所需的输出结构。
第三步：向用户询问缺失信息：
- 主题或议题
- 关键发现或数据要点
- 目标受众
第四步：按照风格指南规范填写模板。
第五步：返回已完成的报告。

关键设计点

Step 3 的主动提问 —— Agent 不会瞎猜，缺什么直接问。这是一个非常重要的设计哲学。

模板文件示例


# 技术报告：{{title}}
## 执行摘要
{{executive_summary}}
## 背景
{{background}}
## 详细分析
### {{section_1_title}}{{section_1_content}}
### {{section_2_title}}{{section_2_content}}
## 结论与建议
{{conclusions}}
## 附录
{{appendix}}

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

核心逻辑

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

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

适用场景

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

模式结构

---
name: code-reviewer
description: 审查 Python 代码的质量、风格与常见错误。
---
第一步：加载 'references/review-checklist.md'。
第二步：仔细阅读用户的代码。
第三步：逐一应用清单中的每条规则。针对每处违规：
- 记录行号
- 划分严重等级：错误 / 警告 / 提示
- 解释问题的原因，而不仅仅是描述问题本身
- 给出具体的修改建议
第四步：按严重等级分组，输出结构化的审查报告。

关键设计点

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

检查清单文件示例


# Python 代码审查清单
## 错误处理
- [ ] 是否捕获了所有必要的异常？
- [ ] 异常信息是否足够具体？
- [ ] 是否有裸露的 `except:` 捕获所有异常？
## 性能
- [ ] 是否有 N+1 查询问题？
- [ ] 是否有不必要的循环？
- [ ] 大文件处理是否使用了流式处理？
## 安全
- [ ] 是否有 SQL 注入风险？
- [ ] 是否有 XSS 风险？
- [ ] 敏感信息是否硬编码？
## 代码风格
- [ ] 函数命名是否清晰？
- [ ] 是否有适当的文档字符串？
- [ ] 代码复杂度是否过高？

模式四：Inversion — 让 Agent 先问你

核心逻辑

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

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

适用场景

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

模式结构

---
name: project-planner
description: 通过结构化提问收集需求，为新软件项目制定规划。
---
在所有阶段完成之前，请勿开始构建。
## 第一阶段 — 问题探索
每次只提一个问题：
- 问题1："这个项目解决什么问题？"
- 问题2："主要用户群体是哪些？"
- 问题3："预期的使用规模是多少？"
## 第二阶段 — 技术约束
仅在第一阶段全部回答完毕后进行：
- 问题4："部署环境是什么？"
- 问题5："是否有技术栈偏好？"
- 问题6："哪些是不可妥协的硬性需求？"
## 第三阶段 — 综合整理
收集所有信息 → 加载模板 → 填写内容 → 呈现结果 → 迭代优化

关键设计点

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

变体：分页式信息收集

---
name: requirements-collector
description: 通过多轮对话系统性地收集项目需求。
---
## 规则
- 每个回复只问最多 3 个问题
- 用编号列出待回答的问题
- 等待用户回答后再继续
- 回答不全不开始开发
## 信息类别
1. 业务目标（必须回答）
2. 用户故事（必须回答）
3. 技术约束（可选）
4. 成功指标（可选）

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

核心逻辑

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

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

适用场景

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

模式结构

---
name: doc-pipeline
description: 通过多步骤流水线，从 Python 源代码生成 API 文档。
---
按顺序执行每个步骤，不得跳过任何步骤。
## 第一步 — 解析与清点
分析代码，提取所有公开 API，以清单形式呈现。
询问："这是完整的公开 API 列表吗？"
## 第二步 — 生成文档字符串
针对每个缺少文档字符串的函数，生成内容并提交用户确认。
在用户确认之前，不得进入第三步。
## 第三步 — 组装文档
加载模板，将所有内容汇编为统一的 API 参考文档。
## 第四步 — 质量检查
对照清单进行审查，在呈现最终文档之前修复所有问题。

关键设计点

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

变体：带自动验证的 Pipeline

---
name: deployment-pipeline
description: 通过验证步骤部署应用到 Kubernetes 集群。
---
## 第一步 — 预检查
验证所有配置：
- kubectl 配置正确
- Docker 镜像已构建
- 所有 secrets 已配置
## 第二步 — 语法验证
运行：kubectl --dry-run=client -f manifests/
仅在无错误时继续。
## 第三步 — 部署
应用清单到目标集群。
立即运行健康检查。
## 第四步 — 验证
执行冒烟测试套件。
检查关键指标（延迟、错误率）。
## 第五步 — 回滚（如需要）
如果验证失败，自动回滚到上一版本。

设计模式选择指南

按需求类型选择

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

按复杂度选择

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

模式组合推荐

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

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

组合示例：Inversion + Pipeline + Reviewer

---
name: full-project-scaffolder
description: 通过结构化流程引导用户完成项目脚手架生成。
---
## Phase 1: 需求收集（Inversion）
... [收集项目需求] ...
## Phase 2: 项目生成（Pipeline）
### 步骤 1: 生成项目结构
### 步骤 2: 生成配置文件
### 步骤 3: 生成入口文件
... [等待用户确认] ...
## Phase 3: 代码审查（Reviewer）
加载 'references/best-practices.md'
逐一检查生成的文件...

最佳实践

1. 选择合适的自由度

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

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

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

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

3. 保持 Skill 精简

4. Description 只描述触发条件

# ❌ 总结了工作流
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…