话不多说，先上干货。本文梳理自 Google ADK 智能体工程专家 La vi Nigam 关于 Agent Skill 设计的一些核心心得，重点总结了 5 种可落地、能直接用的 SKILL.md 设计模式。核心目标就一个：帮开发者把 Token 浪费降下来，把 Skill 编写质量提上去。

背景：为什么需要 Skill 设计模式？

如果仔细复盘过 AI Native 产品的开发过程，你会发现一个很扎心的现实：大量 Token 都浪费在了无关紧要的“猜测”上。大模型需要反复揣摩一个本来很明确的用户意图，或者被迫用一套臃肿的指令去理解一个本可以简单表达的逻辑。

使用结构化的 SKILL.md 设计模式，能直接解决这个痛点：

• 减少模型的“瞎猜”成本，让它在正确的时机精准触发正确的行为
• 让 Skill 的编写方式标准化，团队协作时少些“我以为，你以为”的摩擦
• 巧妙利用渐进式知识加载，把 Token 消耗降下来
• 核心目的：让 Agent 在正确的时间，激活正确的技能

5 种模式总览

Pattern 1：Tool Wrapper（工具包装器）

这个模式的思路很直接：SKILL.md 通过 load_skill_resource 加载 references/ 目录下的规范文件，Agent 应用这些规则后，瞬间就能变成某个领域的专家。没有脚本，没有模板——本质上就是一个知识封装的过程。

工作原理

（图片位置：此处应插入 Tool Wrapper 工作原理示意图）

文件结构

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

适用场景

• FastAPI 路由约定、响应模型规范
• Terraform 资源命名与模块化模式
• PostgreSQL 查询优化最佳实践
• 公司内部 API 设计规范

SKILL.md 示例

---
name: fastapi-expert
description: 帮助编写符合 FastAPI 最佳实践的代码。当用户需要编写 FastAPI 相关代码、路由、依赖注入时触发。
---
# FastAPI 专家模式

## 激活规则
- 加载参考文档：`references/fastapi-conventions.md`
- 按照文档中的约定，确保所有生成的 FastAPI 代码符合规范。

Pattern 2：Generator（生成器）

核心思想是：assets/ 里的模板决定了“输出什么结构”，而 references/ 里的风格指南则控制“怎么输出”。模板负责强制结构，风格指南负责保证质量。

工作原理

（图片位置：此处应插入 Generator 工作原理示意图）

文件结构

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

适用场景

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

Pattern 3：Reviewer（审查员）

这个模式的核心在于“分离”：把“检查什么”（checklist）与“如何检查”（审查协议）拆开。你只需要替换 references/ 中的检查清单文件，就能用同一个技能结构，完成完全不同类型的审查任务。

工作原理

（图片位置：此处应插入 Reviewer 工作原理示意图）

文件结构

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

输出格式规范

审查结果按严重程度分组，一目了然：

适用场景

代码审查

• Python 类型提示检查
• 异常处理完整性
• 函数复杂度评估

安全审计

• OWASP Top 10 检查
• 密钥硬编码检测
• SQL 注入风险

内容审查

• 技术文档排版规范
• 语气一致性检查
• 术语使用规范

API 文档审查

• 参数说明完整性
• 示例代码正确性
• 错误码文档覆盖

Pattern 4：Inversion（反转/提问模式）

这个模式的思路很有意思：把 Agent 和用户的交互主导权翻转过来。不再是用户提问、Agent 回答，而是 Agent 先提问、用户回答——让技能本身来驱动对话。这能有效防止 Agent 凭空胡乱假设，减少大量无效输出。

三阶段流程

（图片位置：此处应插入 Inversion 三阶段流程示意图）

关键控制指令

必须在 SKILL.md 中明确写出：

在完成所有阶段前，绝对不要开始构建！
DO NOT start building until all phases are complete.

适用场景

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

Pattern 5：Pipeline（流水线）

这套模式定义了一个严格有序的多步骤工作流，步骤之间设置了明确的“门槛”（Gate Conditions）。门槛条件的作用就是防止跳过任何验证步骤。

工作原理

（图片位置：此处应插入 Pipeline 工作原理示意图）

文件结构

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

关键控制指令模板

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

适用场景

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

如何选择合适的模式？

话说回来，面对这 5 种模式，到底该怎么选？这里整理了一份快速决策指南：

快速决策指南

决策树

（图片位置：此处应插入模式选择决策树示意图）

实战案例：电商选品 Pipeline

场景描述

设计一个结合了 Inversion + Reviewer + Generator 三种模式的电商选品 Pipeline，实现从需求收集到最终选品报告的完整闭环。

目录结构

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）、市场分析、利润测算并生成标准选品报告。当用户需要寻找或评估电商商品时触发。
metadata:
  pattern: Pipeline
  domain: E-commerce
---
# 电商选品工作流

你是一个专业的电商选品专家。请严格按照以下顺序执行选品工作流。
**核心规则：在完成所有阶段前，绝对不要开始生成选品方案！**
如果跳过任何步骤或某一步失败，请勿继续。

## Step 1: 收集需求（Inversion Pattern）
主动向用户提问以收集选品上下文：
1. 目标受众是谁？
2. 预算和预期利润率是多少？
3. 是否有特定的类目偏好或供应链优势？
*控制门槛：必须等待用户回答完所有问题后，才能进入 Step 2。*

## Step 2: 评估商品（Reviewer Pattern）
加载并应用评估标准：
- 加载检查清单：`references/product-evaluation-checklist.md`
- 按清单标准对商品进行打分（❌ 致命缺陷 / ⚠️ 潜在风险 / ✅ 优势）

## Step 3: 用户确认（Pipeline Gate）
向用户展示 Step 2 的初步审查结果。
*控制门槛：在用户明确确认之前，绝对不要进入第四步！*

## Step 4: 生成最终报告（Generator Pattern）
在用户确认后，综合输出正式报告：
- 加载报告模板：`assets/selection-report-template.md`
- 将收集到的需求和评估结果填入模板，严格遵守模板定义的章节结构

关键设计解析

精准的 Description 触发

description 字段是 Agent 的“搜索索引”。它必须包含具体业务关键词（如“电商选品”、“利润测算”），才能确保 Agent 在正确时机激活该技能，避免误触发或漏触发。

渐进式知识加载

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

进阶建议

从简单开始

如果不确定该从哪个模式下手，最简单的 Tool Wrapper 绝对是不错的选择。先把团队规范封装进去，后续如果需要结构化输出，再升级为 Generator；需要评估能力，再升级为 Reviewer。一步步来。

模式组合最佳实践

生产系统中往往不是单一模式打天下，组合 2～3 个模式是常态。以下是一些常见搭配：

渐进式知识加载机制