我要投稿

Google 官方总结的 5 种 Agent Skill 设计模式

发布日期：2026-03-22 09:12:37 浏览次数： 1612

作者：石臻说AI

微信搜一搜，关注“石臻说AI”

⭐ 设为星标 · 第一时间收到推送

石臻说AI 编辑：石臻

导读： Agent Skill 不是写个 YAML 配置文件就完事了。Google 官方总结了 5 种设计模式，帮你从"能用"到"好用"——从 Tool Wrapper 到 Pipeline，每种都解决了特定场景下的痛点。

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 真正"懂行"了。

Google ADK 官方总结的 5 种 Agent Skill 设计模式，帮你从"能用"到"好用"。每种模式都针对特定痛点：Tool Wrapper 按需加载知识，Generator 强制输出一致性，Reviewer 模块化代码审查，Inversion 先问后做避免返工，Pipeline 分步执行加检查点。代码示例全部来自官方推文，可直接复用。

参考链接