Google 最近在 ADK（Agent Development Kit）上推了一篇硬核文章，不讲框架怎么用，专门讲 Skill 怎么设计。
这事儿挺关键。现在 30 多个 agent 工具（Claude Code、Gemini CLI、Cursor 等）都统一用 SKILL.md 这个格式了，文件结构大家都一样——但写出来的 skill 质量天差地别。问题不在格式，在内容设计。
Google 团队研究了生态里各种 skill 的实现方式，从 Anthropic 的仓库到 Vercel 和 Google 内部指南，总结了 5 种反复出现的设计模式。每种都对应一类典型问题，直接给你解题套路。
Pattern 1：Tool Wrapper——给 agent 装个"技能包"
核心逻辑：让 agent 在需要时才加载特定领域的知识，而不是把所有东西塞进 system prompt。
传统的做法是：把 FastAPI 规范、代码风格、最佳实践全写进一个超长的 system prompt 里。agent 每次启动都带着这个"万能工具箱"，但大部分时候用不上。
Tool Wrapper 换了个思路：把某个技术栈的规范封装成一个 skill，只有当用户提到"FastAPI"、"REST API"、"Pydantic"这些关键词时，agent 才动态加载这个 skill 的 references/ 目录，读取里面的规范文档。
优势：
- 上下文窗口干净，不加载无关内容
- 规范更新只需改 skill 文件，不动 agent 核心代码
- 团队规范可以直接打包成 skill 分发
适用场景：
- 封装某个框架/库的编码规范
- 团队内部代码风格指南
- 特定技术栈的最佳实践
代码示例（FastAPI skill）：
💡 PROMPT
提示词参考：
```yaml
---
name: api-expert
description: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models.
metadata:
pattern: tool-wrapper
domain: fastapi
---
You are an expert in FastAPI development.
## Core Conventions
Load 'references/conventions.md' for the complete list of FastAPI best practices.
## When Reviewing Code
1. Load the conventions reference
2. Check the user's code against each convention
3. For each violation, cite the specific rule and suggest the fix
## When Writing Code
1. Load the conventions reference
2. Follow every convention exactly
3. Add type annotations to all function signatures
4. Use Annotated style for dependency injection
```
关键点：SKILL.md 文件本身不包含完整规范，而是告诉 agent 去哪里加载规范。这样 skill 文件保持简洁，规范文档单独维护。
Pattern 2：Generator——填空题式文档生成
核心逻辑：用模板 + 风格指南强制输出一致性，解决"每次生成的文档结构都不一样"的问题。
Generator 模式像是一个项目经理。它不自己写内容，而是：
- 1加载模板（
assets/report-template.md） - 2加载风格指南（
references/style-guide.md） - 3问用户要缺失的变量（主题、关键数据、目标受众）
- 4按模板结构填充内容
优势：
- 输出格式完全可控（由模板决定）
- 多人协作时风格统一（由风格指南保证）
- 支持复杂文档结构（API 文档、技术报告、项目架构）
适用场景：
- 生成标准化的技术文档
- API 文档自动生成
- 提交信息规范化
- 项目脚手架
代码示例（技术报告生成器）：
💡 PROMPT
提示词参考：
```yaml
---
name: report-generator
description: Generates structured technical reports in Markdown.
metadata:
pattern: generator
output-format: markdown
---
Step 1: Load 'references/style-guide.md' for tone and formatting rules.
Step 2: Load 'assets/report-template.md' for the required output structure.
Step 3: Ask the user for missing information:
- Topic or subject
- Key findings or data points
- Target audience
Step 4: Fill the template following the style guide rules.
Step 5: Return the completed report.
```
关键是 Step 3 的主动提问——agent 不会瞎猜，缺什么直接问，保证最终输出有足够信息支撑。
Pattern 3：Reviewer——代码审查自动化
核心逻辑：把"查什么"和"怎么查"分离。检查清单独立维护，agent 只负责执行打分。
传统做法是在 system prompt 里写一长串"检查这个、检查那个"。问题：
- 检查项多了 prompt 臃肿
- 不同项目要用不同检查标准，得改 prompt
- 检查逻辑和规范混在一起，难维护
Reviewer 模式把检查清单抽离到 references/review-checklist.md，agent 按清单逐项打分，并按严重性分组（error/warning/info）。
优势：
- 检查标准模块化（换个清单就是另一套审查规则）
- 输出结构化（按严重性分组，优先修复高严重性问题）
- 可扩展（OWASP 安全检查、Python 风格检查、团队规范检查，都是同一套基础设施）
适用场景：
- 自动化 PR 代码审查
- 安全漏洞扫描
- 代码风格检查
- PR 提交前钩子
代码示例（Python 代码审查器）：
💡 PROMPT
提示词参考：
```yaml
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs.
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
Step 1: Load 'references/review-checklist.md'.
Step 2: Read the user's code carefully.
Step 3: Apply each rule from the checklist. For every violation:
- Note the line number
- Classify severity: error (must fix), warning (should fix), info (consider)
- Explain WHY it's a problem, not just WHAT is wrong
- Suggest a specific fix with corrected code
Step 4: Produce structured review:
- **Summary**: What the code does, overall quality
- **Findings**: Grouped by severity
- **Score**: Rate 1-10 with justification
- **Top 3 Recommendations**: Most impactful improvements
```
这里最关键的是 Step 3 的"WHY not WHAT"——不只是指出问题，还要解释为什么是问题，让开发者真正理解规范背后的逻辑。
Pattern 4：Inversion——让 agent 先问你
核心逻辑：翻转传统交互模式。不是用户驱动 prompt、agent 执行，而是 agent 先采访用户，收集完整需求后再动手。
Agent 的天性是想"立刻生成"。给个模糊需求，它就开始输出——结果往往是方向偏了、细节不对、反复返工。
Inversion 模式强制 agent 先提问，按阶段收集信息：
- Phase 1：问题发现（要解决什么问题？用户是谁？规模多大？）
- Phase 2：技术约束（部署环境？技术栈偏好？不可妥协的要求？）
- Phase 3：综合方案（所有信息收集完才开始设计）
核心技巧：在 SKILL.md 里写死 "DO NOT start building until all phases are complete"。这是硬性 gate，agent 不能跳过。
适用场景：
- 新项目规划
- 系统架构设计
- 需求不明确时的需求澄清
- 复杂任务的方案设计
代码示例（项目规划器）：
💡 PROMPT
提示词参考：
```yaml
---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions.
metadata:
pattern: inversion
interaction: multi-turn
---
DO NOT start building or designing until all phases are complete.
## Phase 1 — Problem Discovery
Ask one question at a time, wait for each answer:
- Q1: "What problem does this project solve?"
- Q2: "Who are the primary users?"
- Q3: "What is the expected scale?"
## Phase 2 — Technical Constraints
Only after Phase 1 is fully answered:
- Q4: "What deployment environment?"
- Q5: "Any technology stack preferences?"
- Q6: "What are non-negotiable requirements?"
## Phase 3 — Synthesis
1. Load 'assets/plan-template.md'
2. Fill in every section using gathered requirements
3. Present the completed plan
4. Ask: "Does this capture your requirements?"
5. Iterate on feedback until user confirms
```
重点是 Phase 1 和 Phase 2 必须串行完成，不能跳。用户回答完一个问题，agent 才能问下一个，避免信息遗漏。
Pattern 5：Pipeline——带检查点的多步工作流
核心逻辑：把复杂任务拆成严格顺序的步骤，每步都有明确的输入/输出和通过条件，agent 不能跳步。
对于复杂任务（比如从代码生成 API 文档），单次 prompt 容易丢三落四——有的函数忘了加 docstring，有的参数没写类型，最后拼出来的文档质量不稳定。
Pipeline 模式把任务拆成固定步骤，每步完成后要用户确认才能进入下一步：
- 1Parse & Inventory：解析代码，列出所有公开 API，用户确认列表完整性
- 2Generate Docstrings：为每个缺 docstring 的函数生成文档字符串，逐个让用户审核
- 3Assemble Documentation：把所有 API 和 docstrings 按模板组装成完整文档
- 4Quality Check：按清单检查（每个公开符号都有文档？参数都有类型和说明？至少一个使用示例？）
关键设计：步骤之间有 diamond gate——比如 Step 2 → Step 3 必须用户确认 "Do NOT proceed to Step 3 until user confirms"。
适用场景：
- 从代码生成文档
- 多阶段内容生产（大纲 → 初稿 → 审核 → 定稿）
- 需要人工检查点的自动化流程
- 复杂的数据处理管道
代码示例（API 文档生成管道）：
💡 PROMPT
提示词参考：
```yaml
---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline.
metadata:
pattern: pipeline
steps: "4"
---
Execute each step in order. Do NOT skip steps.
## Step 1 — Parse & Inventory
Analyze code to extract all public classes, functions, constants.
Present inventory as checklist.
Ask: "Is this the complete public API?"
## Step 2 — Generate Docstrings
For each function lacking docstring:
- Load 'references/docstring-style.md'
- Generate docstring following style guide
- Present for user approval
Do NOT proceed to Step 3 until user confirms.
## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md'.
Compile all classes, functions, docstrings into single API reference.
## Step 4 — Quality Check
Review against 'references/quality-checklist.md':
- Every public symbol documented
- Every parameter has type and description
- At least one usage example per function
Report results. Fix issues before presenting final document.
```
这里 Step 2 → Step 3 的 "Do NOT proceed" 是硬性约束——用户不点头，agent 不能往下走，强制人工质量控制。
5 种模式怎么选？
直接看决策树：
| 需求 | 推荐模式 |
|---|---|
| 让 agent 掌握某个技术栈的规范 | Tool Wrapper |
| 生成格式统一的文档/代码 | Generator |
| 自动化代码审查/安全扫描 | Reviewer |
| 需求不明确，先收集信息再设计 | Inversion |
| 复杂任务需要分步执行+人工检查 | Pipeline |
进阶技巧：模式组合
这 5 种模式不是互斥的，可以组合使用：
- Pipeline + Reviewer：文档生成管道的最后一步加自动审查
- Generator + Inversion：文档生成前先采访用户收集变量
- Tool Wrapper + Reviewer：代码审查时加载团队规范作为检查标准
ADK 的 SkillToolset 支持按需加载——agent 只在特定步骤加载特定 skill，上下文窗口不会爆炸。
总结
Agent Skill 不是"写个 YAML 配置文件就完事了"。格式标准化只是第一步，真正决定 skill 好不好用的是内容设计：
- Tool Wrapper 解决"知识太多塞不进 prompt"——按需加载，用的时候再读
- Generator 解决"每次输出格式都不一样"——模板 + 风格指南强制一致
- Reviewer 解决"审查标准不统一"——检查清单独立维护，输出结构化
- Inversion 解决"需求不明确就开干"——先采访，后执行，避免返工
- Pipeline 解决"复杂任务容易丢三落四"——分步执行，每步有检查点
现在 SKILL.md 格式 30 多个工具都支持了，格式不再是瓶颈。该想想怎么设计内容，让 agent 真正"懂行"了。
