SKILL设计模式：5种模式让Agent技能从能用变好用

你写了不少SKILL，但有没有遇到过这些情况：Token消耗巨大可输出质量不稳定？Agent该问的时候不问，不该猜的时候瞎猜？输出的格式一次一个样，团队根本没法复用？

这些问题的根源不是你的Prompt写得不好，而是SKILL的内部结构没选对。就像写代码有设计模式一样，SKILL也有自己的设计模式。Google ADK团队总结了5种经过验证的模式，帮你精准解决不同类型的"失控点"。

一、为什么需要SKILL设计模式？

AI Native开发中，Token浪费的核心症结在于两件事：

1. 让大模型反复猜测本该清晰明确的意图——你不说清楚，它就猜，猜错了重来，Token翻倍消耗
2. 用复杂指令表达本可极简表达的逻辑——把结构问题当成Prompt问题来解，越写越绕

通过结构化的设计模式，可以做到：

• 减少猜测成本，精准触发正确行为
• 标准化Skill编写，降低团队协作摩擦
• 渐进式知识加载，大幅降低Token消耗
• Agent在正确时机激活正确技能，而非盲目执行

💡关键洞察：真正可靠的Skill不依赖越来越复杂的System Prompt，而在于选择合适的结构来解决特定的失控点。先诊断问题是知识、结构、审查、澄清还是流程问题，再匹配对应的设计模式。

二、5种模式总览

先看全貌，再逐个拆解：

三、Tool Wrapper：给Agent装上专家大脑

核心理念

SKILL.md只放触发关键词和加载指令，真正的专业知识放在references/里按需加载。Agent需要时才读取，不需要时零消耗。无脚本、无模板——纯知识封装。

工作原理

工作流程： 1. Agent识别到用户意图匹配Skill描述 2. 仅加载SKILL.md（约100 Token） 3. 按需加载references/中的规范文件 4. 将领域知识应用于当前任务 关键机制： 激活时消耗极低（~100 Token） 知识文件只在需要时加载 替换references/即可切换领域

文件结构

my-skill/ ├── SKILL.md # 触发关键词 + 加载指令（无脚本、无模板） └── references/ └── conventions.md # 规范、约定、最佳实践

实际例子

比如你要让Agent写FastAPI代码，但每次生成的路由风格、依赖注入方式都不一样：

# SKILL.md --- name: fastapi-expert description: 帮助编写符合FastAPI最佳实践的代码。当用户需要编写FastAPI相关代码、路由、依赖注入时触发。 --- # FastAPI专家模式 ## 激活规则 加载参考文档：`references/fastapi-conventions.md` 按照文档中的约定，确保所有生成的FastAPI代码符合规范。

references/fastapi-conventions.md里放什么？你团队的FastAPI路由命名约定、响应模型规范、依赖注入最佳实践。Agent读取后，瞬间"掌握"你团队的经验。

💡关键洞察：description字段是Agent的搜索索引，必须包含具体的业务关键词。"帮助写代码"这种宽泛描述会导致技能无法被正确触发，"编写FastAPI路由、依赖注入"这种才精准。

适用场景

• 框架编码规范（FastAPI路由约定、React组件规范）
• 基础设施模式（Terraform资源命名与模块化）
• 数据库优化实践（PostgreSQL查询优化）
• 公司内部API设计规范

判断标准：只需要封装约定和最佳实践，无需生成固定格式输出时，选Tool Wrapper。

四、Generator：让输出格式不再一次一个样

核心理念

assets/模板决定"输出什么结构"，references/风格指南控制"怎么写"。模板强制结构，风格指南保证质量。

工作原理

双控机制： 模板（assets/） → 控制结构：必须包含哪些章节、每个章节放什么内容 指南（references/） → 控制风格：语气、术语、格式规范 两者分离的好处： 换模板不换风格 → 同一风格适配不同文档类型 换风格不换模板 → 同一结构适配不同受众

文件结构

my-skill/ ├── SKILL.md ├── assets/ │ └── report-template.md # 输出结构模板（必须包含哪些章节） └── references/ └── style-guide.md # 语气、格式风格指南

实际例子

技术分析报告是典型场景——你要的不是一个随意发挥的文档，而是每次都包含"背景-分析-结论-建议"四个固定章节，且术语一致、语气专业的标准格式。

# assets/report-template.md 示例 # [项目名称] 技术分析报告 ## 1. 背景 [问题描述与上下文] ## 2. 分析 [技术分析过程，需要包含数据支撑] ## 3. 结论 [核心发现，不超过3条] ## 4. 建议 [可执行的下一步行动，每条标注优先级] # references/style-guide.md 示例 - 语气：客观、简洁，避免主观评价 - 术语：使用项目内统一术语表 - 数据：所有结论必须有数据支撑，标注数据来源 - 长度：单段不超过5行

适用场景

• 技术分析报告、API参考文档
• 规范化Git Commit Message
• Agent脚手架代码生成
• 周报/月报模板

判断标准：输出的结构一致性比创造性更重要时，选Generator。

五、Reviewer：检查什么和怎么查，分开管

核心理念

将"检查什么"（checklist）与"如何检查"（审查协议）分离。替换references/中的检查清单，就能用同一个SKILL结构实现完全不同类型的审查。

这个解耦思路很实用——你不用为每种审查写一套新SKILL，只需要换checklist文件。

工作原理

解耦逻辑： SKILL.md（怎么查）： - 定义审查流程：加载清单 → 逐条检查 → 按严重程度分组 → 输出报告 - 不包含任何具体的检查项 references/review-checklist.md（查什么）： - 列出所有检查项和判定标准 - 可以独立替换、更新、版本管理 好处： 审查Python代码 → 替换为python-checklist.md 审查安全漏洞 → 替换为security-checklist.md 审查API文档 → 替换为api-doc-checklist.md SKILL.md本身不需要修改

文件结构

my-skill/ ├── SKILL.md # 审查协议（如何检查：加载、应用、报告） └── references/ └── review-checklist.md # 检查清单（检查什么：按严重程度列举规则）

输出格式规范

审查结果按严重程度分组，这是Reviewer模式的核心约定：

适用场景

• 代码审查：Python类型提示检查、异常处理完整性、函数复杂度评估
• 安全审计：OWASP Top 10检查、密钥硬编码检测、SQL注入风险扫描
• 内容审查：技术文档排版规范、语气一致性检查、术语使用规范
• API文档审查：参数说明完整性、示例代码正确性、错误码覆盖度

判断标准：任务类似"根据标准评分"，需按严重程度分类输出时，选Reviewer。

六、Inversion：先问再做，别替用户做主

核心理念

翻转Agent交互主导权——Agent先提问、用户回答。防止Agent信息不足就开工，凭空假设导致无效输出。

这是解决"AI一上来就一顿操作猛如虎，结果完全偏离用户意图"的最直接方法。

三阶段流程

Inversion模式的三阶段： Phase 1: 收集（Collect） Agent主动提问，收集所有必要的上下文信息 问题必须具体、结构化，不是笼统的"你想要什么" Phase 2: 确认（Confirm） Agent复述收集到的信息 用户核对是否理解正确 Phase 3: 执行（Generate） 确认无误后才开始生成 基于完整信息，输出质量显著提升

关键控制指令

必须在SKILL.md中明确写出控制指令，这是Inversion模式生效的核心：

# 必须写在SKILL.md中的约束 在完成所有阶段前，绝对不要开始构建！ DO NOT start building until all phases are complete.

这不是建议，是硬性约束。没有这句话，Agent大概率会在用户回答第一个问题后就开始输出，完全违背模式意图。

实际例子

设计基础设施配置向导，Agent必须先搞清楚你的环境、规模、安全要求，再给出配置方案：

# SKILL.md 片段 ## Phase 1: 收集需求 请依次询问以下信息（每条等待用户回答后再问下一条）： 1. 部署环境（开发/测试/生产）？ 2. 预期并发量级？ 3. 是否有合规要求（如等保、PCI-DSS）？ 4. 现有基础设施（云厂商、VPC配置）？ **必须在所有问题回答完毕后，才进入Phase 2。** ## Phase 2: 确认 将用户的回答整理成需求摘要，请用户确认。 **必须等待用户明确说"确认"后，才进入Phase 3。** ## Phase 3: 生成配置 基于确认的需求，输出完整的配置方案。

适用场景

• 项目需求文档收集
• 系统故障诊断引导
• 基础设施配置向导
• 定制化报告生成前的信息采集

判断标准：Agent必须了解用户具体情况才能开始工作时，选Inversion。

七、Pipeline：多步骤有序执行，一步都不能跳

核心理念

定义严格有序的多步骤工作流，步骤间设置明确的验证门槛（Gate Conditions）。门槛条件防止跳步——不满足条件，绝对不进入下一步。

工作原理

Pipeline的核心机制： Step 1 → [Gate] → Step 2 → [Gate] → Step 3 → [Gate] → 完成 Gate（门槛）的作用： - 验证上一步的输出是否满足要求 - 用户确认后才能继续 - 任何一步失败，流程终止 与普通多步骤的区别： 普通步骤：1→2→3→4，中间可能跳步或遗漏 Pipeline：1→[验证]→2→[验证]→3→[验证]→4，每步必须有"通行证"

文件结构

my-skill/ ├── SKILL.md # 步骤定义 + 门槛控制逻辑 ├── references/ # 各步骤参考规范 ├── assets/ # 输出模板 └── scripts/ # 自动化脚本（可选）

关键控制指令模板

## Step N: [步骤名称] [步骤操作描述] *控制门槛：在[条件]之前，绝对不要进入Step N+1！* *如果跳过任何步骤或某一步失败，请勿继续。*

实际例子：代码部署流水线

# SKILL.md 片段 ## Step 1: 代码审查 加载审查清单：`references/review-checklist.md` 按Error/Warning/Info三级输出审查结果。 *控制门槛：存在Error级别问题时，绝对不要进入Step 2！* ## Step 2: 测试执行 运行相关测试套件，收集测试报告。 *控制门槛：所有测试通过后，才能进入Step 3。测试失败则回到Step 1修复。* ## Step 3: 发布确认 向用户展示变更摘要和测试结果，请用户确认发布。 *控制门槛：用户明确说"发布"后，才进入Step 4。* ## Step 4: 发布与验证 执行发布操作，验证线上服务状态。

适用场景

• 代码文档化（解析→用户确认→生成→质量检查）
• 数据清洗与处理流水线
• 代码部署工作流（审查→测试→发布→验证）
• 多步骤审批流程

判断标准：步骤有依赖关系，顺序不能乱，需要用户中途确认时，选Pipeline。

八、如何选择合适的模式？

快速决策指南

按复杂度选择

1. 低复杂度——只需封装规范→Tool Wrapper
2. 中复杂度——需固定输出结构→Generator；需评估打分→Reviewer；需先收集信息→Inversion
3. 高复杂度——多步骤有依赖关系→Pipeline

💡关键洞察：如果不确定选哪个模式，从最简单的Tool Wrapper开始。先把团队规范封装进去，当需要结构化输出时升级为Generator，需要评估能力时升级为Reviewer。不要一上来就搞Pipeline。

九、模式组合：真正的高手是混搭

生产系统通常不会只用一种模式，而是组合2～3个模式。常见的有效搭配：

组合实战：电商选品SKILL

一个电商选品场景，组合Inversion + Reviewer + Generator三种模式：

# 目录结构 ecommerce-product-selector/ ├── SKILL.md # Pipeline主控制 ├── references/ │ └── product-evaluation-checklist.md # Reviewer模式的评估标准 └── assets/ └── selection-report-template.md # Generator模式的报告模板 # SKILL.md 核心逻辑 --- name: ecommerce-product-selector description: 帮助进行电商选品（Product Selection）、市场分析、利润测算并生成标准选品报告。 --- 核心规则：在完成所有阶段前，绝对不要开始生成选品方案！ 如果跳过任何步骤或某一步失败，请勿继续。 ## Step 1: 收集需求（Inversion） 主动向用户提问： 1. 目标受众是谁？ 2. 预算和预期利润率是多少？ 3. 是否有特定的类目偏好或供应链优势？ 控制门槛：必须等待用户回答完所有问题后，才能进入Step 2。 ## Step 2: 评估商品（Reviewer） 加载检查清单：`references/product-evaluation-checklist.md` 按清单标准对商品打分（Error/Warning/优势） ## Step 3: 用户确认（Gate） 向用户展示Step 2的审查结果。 控制门槛：用户明确确认后，才能进入Step 4。 ## Step 4: 生成报告（Generator） 加载报告模板：`assets/selection-report-template.md` 将需求和评估结果填入模板，严格遵循模板结构。

渐进式知识加载

组合模式的一个重要优势是Token按需消耗：

Agent初始只消耗约100 Token加载技能描述。references/的评估清单和assets/的报告模板，只有当流程流转到对应步骤时才被加载，大幅节省上下文窗口。

十、给开发者的切实建议

先诊断，再开药

不要看到问题就堆指令。先判断你的"失控点"是什么类型：

• 知识不够→Tool Wrapper，注入专家知识
• 格式不稳→Generator，模板锁结构
• 检查不严→Reviewer，标准与流程分离
• 信息不全→Inversion，先问再做
• 流程混乱→Pipeline，门控保顺序

从简单模式开始迭代

一个常见的错误是上来就写Pipeline——步骤定义、门槛条件、用户确认，一整套搞下来发现根本不需要。正确做法是：

1. 先用Tool Wrapper封装核心知识，跑通基本流程
2. 发现输出格式不稳定，加Generator
3. 发现需要质量把关，加Reviewer
4. 发现步骤顺序出问题，再升级为Pipeline

模式是用来解决具体问题的工具，不是用来展示架构能力的勋章。

注意description的精准性

所有模式都有一个共同前提：Agent必须能正确触发你的Skill。description字段就是触发索引，写得越精准，Skill被正确调用的概率越高。