SKILL设计模式5种模式让Agent技能从能用变好用你写了不少SKILL但有没有遇到过这些情况Token消耗巨大可输出质量不稳定Agent该问的时候不问不该猜的时候瞎猜输出的格式一次一个样团队根本没法复用这些问题的根源不是你的Prompt写得不好而是SKILL的内部结构没选对。就像写代码有设计模式一样SKILL也有自己的设计模式。Google ADK团队总结了5种经过验证的模式帮你精准解决不同类型的失控点。一、为什么需要SKILL设计模式AI Native开发中Token浪费的核心症结在于两件事让大模型反复猜测本该清晰明确的意图——你不说清楚它就猜猜错了重来Token翻倍消耗用复杂指令表达本可极简表达的逻辑——把结构问题当成Prompt问题来解越写越绕通过结构化的设计模式可以做到减少猜测成本精准触发正确行为标准化Skill编写降低团队协作摩擦渐进式知识加载大幅降低Token消耗Agent在正确时机激活正确技能而非盲目执行关键洞察真正可靠的Skill不依赖越来越复杂的System Prompt而在于选择合适的结构来解决特定的失控点。先诊断问题是知识、结构、审查、澄清还是流程问题再匹配对应的设计模式。二、5种模式总览先看全貌再逐个拆解模式核心定位解决什么问题复杂度Tool Wrapper知识封装器Agent缺少领域专家知识低Generator结构化生成器输出格式不统一中Reviewer标准化审查器检查评估缺乏一致性中Inversion反转提问模式Agent盲目假设信息不足就开工中Pipeline流程流水线多步骤执行顺序失控高三、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 MessageAgent脚手架代码生成周报/月报模板判断标准输出的结构一致性比创造性更重要时选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模式的核心约定级别含义示例Error必须修复影响功能或安全SQL注入漏洞、未处理异常Warning建议修复影响质量缺少类型注解、命名不规范Info可选优化注释不完整、可提取复用逻辑适用场景代码审查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中间可能跳步或遗漏 Pipeline1→[验证]→2→[验证]→3→[验证]→4每步必须有通行证文件结构my-skill/ ├── SKILL.md # 步骤定义 门槛控制逻辑 ├── references/ # 各步骤参考规范 ├── assets/ # 输出模板 └── scripts/ # 自动化脚本可选关键控制指令模板## Step N: [步骤名称] [步骤操作描述] *控制门槛在[条件]之前绝对不要进入Step N1* *如果跳过任何步骤或某一步失败请勿继续。*实际例子代码部署流水线# 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。八、如何选择合适的模式快速决策指南你的问题推荐模式核心特征Agent缺少某个领域的专家知识Tool Wrapper按需注入知识保持上下文干净输出格式一次一个样Generator模板风格指南确保结构一致需要对照标准评估打分Reviewer流程与标准分离灵活替换ChecklistAgent信息不足就开工Inversion先发问后生成禁止信息不全时动手多步骤执行顺序容易乱Pipeline工作流门控防止跳步按复杂度选择低复杂度——只需封装规范→Tool Wrapper中复杂度——需固定输出结构→Generator需评估打分→Reviewer需先收集信息→Inversion高复杂度——多步骤有依赖关系→Pipeline关键洞察如果不确定选哪个模式从最简单的Tool Wrapper开始。先把团队规范封装进去当需要结构化输出时升级为Generator需要评估能力时升级为Reviewer。不要一上来就搞Pipeline。九、模式组合真正的高手是混搭生产系统通常不会只用一种模式而是组合23个模式。常见的有效搭配组合方式典型场景为什么有效Pipeline Reviewer流程末尾的质量控制Pipeline保流程Reviewer保质量Generator Inversion先收集信息再生成定制化报告Inversion避免假设Generator保证格式Pipeline Inversion Generator完整端到端业务流收集→审查→生成全链路可控Tool Wrapper Generator按专家规范生成代码或文档知识注入保证专业度模板保证格式组合实战电商选品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按需消耗加载时机加载内容Token消耗技能激活时SKILL.md描述基础指令约100 Token极低到达对应步骤时references/检查清单或规范文档按需加载避免预先消耗生成阶段时assets/输出模板仅在需要时加载Agent初始只消耗约100 Token加载技能描述。references/的评估清单和assets/的报告模板只有当流程流转到对应步骤时才被加载大幅节省上下文窗口。十、给开发者的切实建议先诊断再开药不要看到问题就堆指令。先判断你的失控点是什么类型知识不够→Tool Wrapper注入专家知识格式不稳→Generator模板锁结构检查不严→Reviewer标准与流程分离信息不全→Inversion先问再做流程混乱→Pipeline门控保顺序从简单模式开始迭代一个常见的错误是上来就写Pipeline——步骤定义、门槛条件、用户确认一整套搞下来发现根本不需要。正确做法是先用Tool Wrapper封装核心知识跑通基本流程发现输出格式不稳定加Generator发现需要质量把关加Reviewer发现步骤顺序出问题再升级为Pipeline模式是用来解决具体问题的工具不是用来展示架构能力的勋章。注意description的精准性所有模式都有一个共同前提Agent必须能正确触发你的Skill。description字段就是触发索引写得越精准Skill被正确调用的概率越高。差的description好的description帮助写代码编写符合FastAPI最佳实践的路由和依赖注入代码做代码审查Python代码类型提示、异常处理、复杂度结构化审查生成报告电商选品分析、市场评估、利润测算标准报告生成