Google 官方总结的 5 种 Agent Skill 设计模式
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 文件保持简洁,规范文档单独维护。
补充:Tool Wrapper 的完整双语模板与另一种图示
原始模板来自另一译本,保留代码块原样;本轮未运行。
# skills/api-expert/SKILL.md
---
name:api-expert
description:FastAPI开发最佳实践和约
定。在构建、审查或调试FastAPI应用
程序、RESTAPI或Pydantic模型时使用。
metadata:
pattern:tool-wrapper
domain:fastapi
---
您是FastAPI开发专家。将这些约定应用
于用户的代码或问题。
## 核心约定
加载'references/conventions.md'以
获取完整的FastAPI最佳实践列表。
## 审查代码时
1.加载约定参考文档
2.根据每个约定检查用户的代码
3.对于每个违规,引用具体规则并建议修
复方案
## 编写代码时
1.加载约定参考文档
2.严格遵循每个约定
3.为所有函数签名添加类型注解
4.使用Annotated 风格进行依赖注入# skills/api-expert/SKILL.md
---
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. Apply these conventions to the user's code or question.
## 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 injectionPattern 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 不会瞎猜,缺什么直接问,保证最终输出有足够信息支撑。
补充:Generator 的完整双语模板与另一种图示
原始模板来自另一译本,保留代码块原样;本轮未运行。
# skills/report-generator/SKILL.md
---
name:report-generator
description:生成结构化的Markdown技
术报告。当用户要求编写、创建或起草报
告、摘要或分析文档时使用。
metadata:
pattern:generator
output-format:markdown
---
您是技术报告生成器。严格按照以下步骤
执行:
步骤1:加载'references/style-guide.md'以
获取语气和格式规则。
步骤2:加载'assets/report-template.md'以
获取所需的输出结构。
步骤3:向用户询问填充模板所需的任何缺
失信息:
-主题或主旨
-关键发现或数据点
-目标受众(技术人员、管理层、普通用户)
步骤4:按照样式指南规则填充模板。模板
中的每个部分都必须出现在输出中。
步骤5:以单个Markdown 文档的形式返回已完成的报告。# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document.
metadata:
pattern: generator
output-format: markdown
---
You are a technical report generator. Follow these steps exactly:
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 any missing information needed to fill the template:
- Topic or subject
- Key findings or data points
- Target audience (technical, executive, general)
Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output.
Step 5: Return the completed report as a single Markdown document.
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"——不只是指出问题,还要解释为什么是问题,让开发者真正理解规范背后的逻辑。
补充:Reviewer 的完整双语模板与另一种图示
原始模板来自另一译本,保留代码块原样;本轮未运行。
# skill…