本文整理自 Google Cloud Tech 官方发布的技术文章，系统介绍了 5 种经过实战验证的 Agent Skill 设计模式。
一、开发者的困惑：SKILL.md 写对了，但 Skill 还是不好用？
你一定遇到过这样的问题：SKILL.md 的 YAML 格式完全正确，目录结构也按规范建好了，但 Agent输出质量就是不稳定。
谷歌官方已经给出了答案：SKILL设计的真正挑战是内容设计，而不是格式。
目前已有 30+ 主流 Agent 工具（包括 Claude Code、Gemini CLI、Cursor 等）统一采用 SKILL.md 规范。
格式工具会自动处理，真正的挑战是智能体内部逻辑设计**。**
关于如何设计SKILL的内部逻辑，Google 官方总结了5种Agent Skill 设计模式。
二、5 种设计模式速览
| 模式 | 核心价值 | 典型场景 |
|---|---|---|
| Tool Wrapper | ||
| 让 Agent 即时掌握任意库的规范 | ||
| 团队内部编码规范分发 | ||
| Generator | ||
| 从模板生成结构化文档 | ||
| API 文档、Commit 消息标准化 | ||
| Reviewer | ||
| 按严重性评分代码 | ||
| PR 自动审查、安全审计 | ||
| Inversion | ||
| 让 Agent 先问问题再行动 | ||
| 需求收集、复杂任务启动 | ||
| Pipeline | ||
| 强制多步骤按顺序执行并设检查点 | ||
| 文档生成、代码发布流程 | ||
下面逐一详解每种模式的原理、代码示例和使用场景。
三、模式 1：Tool Wrapper（工具封装器）
核心思想
工具封装器将需要的上下文打包，不需要将API 的定义硬编码到系统提示词中。
智能体在用的时候，𝚂𝙺𝙸𝙻𝙻.𝚖𝚍文件会监听用户提示中特定的库关键词，从𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/目录动态加载你的内部文档，并严格执行这些规则。
这是最容易实现的模式。
这个可以使用模式将团队内部编码指南或特定框架的最佳实践直接融入开发流程中。
代码示例
# 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 injection
使用场景
-
团队内部编码规范分发
-
特定框架（FastAPI、React、Django）的最佳实践
-
公司内部 API 规范
四、模式 2：Generator（生成器）
核心思想
Generator 解决的是输出不一致的问题。
它底层有两个可选目录：𝚊𝚜𝚜𝚎𝚝𝚜/ 存放输出模板，𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 存放风格指南。
智能体会加载模板、阅读风格指南、向用户询问缺失的变量并填充文档。
Generator 可以通过「填空」的方式强制统一输出格式。
代码示例
# 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.
使用场景
-
API 文档生成
-
技术报告
-
Commit 消息标准化
-
项目架构脚手架
五、模式 3：Reviewer（审查器）
核心思想
Reviewer的核心是将检查什么和怎么检查分离开来。
也就是 what 和 how 隔离开。
比如一个 cr 能力，错误的做法是在 system prompt 里写一堆代码坏味道的规则。
正确的做法是将检查清单放在 references/review-checklist.md 里。
智能体会加载这份清单，并对提交内容进行评分。
这样做的好处是换个清单，就能换个用途：Python 风格检查 → OWASP 安全审计。
代码示例
# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs. Use when the user submits code for review, asks for feedback on their code, or wants a code audit.
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
You are a Python code reviewer. Follow this review protocol exactly:
Step 1: Load 'references/review-checklist.md' for the complete review criteria.
Step 2: Read the user's code carefully. Understand its purpose before critiquing.
Step 3: Apply each rule from the checklist to the code. For every violation found:
- Note the line number (or approximate location)
- 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 a structured review with these sections:
- **Summary**: What the code does, overall quality assessment
- **Findings**: Grouped by severity (errors first, then warnings, then info)
- **Score**: Rate 1-10 with brief justification
- **Top 3 Recommendations**: The most impactful improvements
使用场景
-
PR 自动审查
-
代码质量检查
-
安全审计
-
风格一致性检查
六、模式 4：Inversion（反转模式）
核心思想
一般智能体倾向于立即进行猜测和生成。
反转模式就这种模式反过来了，它让智能体会扮演面试官的角色，主动向用户问问题。
反转模式一般会有门禁，比如：所有阶段完成前，禁止开始构建。
代码示例
# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions before producing a plan. Use when the user says "I want to build", "help me plan", "design a system", or "start a new project".
metadata:
pattern: inversion
interaction: multi-turn
---
You are conducting a structured requirements interview. 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)
Ask these questions in order. Do not skip any.
- Q1: "What problem does this project solve for its users?"
- Q2: "Who are the primary users? What is their technical level?"
- Q3: "What is the expected scale? (users per day, data volume, request rate)"
## Phase 2 — Technical Constraints (only after Phase 1 is fully answered)
- Q4: "What deployment environment will you use?"
- Q5: "Do you have any technology stack requirements or preferences?"
- Q6: "What are the non-negotiable requirements? (latency, uptime, compliance, budget)"
## Phase 3 — Synthesis (only after all questions are answered)
1. Load 'assets/plan-template.md' for the output format
2. Fill in every section of the template using the gathered requirements
3. Present the completed plan to the user
4. Ask: "Does this plan accurately capture your requirements? What would you change?"
5. Iterate on feedback until the user confirms
使用场景
-
新项目规划
-
需求收集
-
复杂任务启动
-
系统设计
七、模式 5：Pipeline（流水线）
核心思想
Pipeline管道模式，这个模式可以让Agent严格按顺序执行工作流。
每个步骤都可以都门禁，必须满足条件才能进行下一步。
这个模式可以防止 Agent 跳步、忽略指令、或者在中间步骤还没验证时就输出最终结果。
代码示例
# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline. Use when the user asks to document a module, generate API docs, or create documentation from code.
metadata:
pattern: pipeline
steps: "4"
---
You are running a documentation generation pipeline. Execute each step in order. Do NOT skip steps or proceed if a step fails.
## Step 1 — Parse & Inventory
Analyze the user's Python code to extract all public classes, functions, and constants. Present the inventory as a checklist. Ask: "Is this the complete public API you want documented?"
## Step 2 — Generate Docstrings
For each function lacking a docstring:
- Load 'references/docstring-style.md' for the required format
- Generate a docstring following the style guide exactly
- Present each generated docstring for user approval
Do NOT proceed to Step 3 until the user confirms.
## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md' for the output structure. Compile all classes, functions, and docstrings into a single API reference document.
## Step 4 — Quality Check
Review against 'references/quality-checklist.md':
- Every public symbol documented
- Every parameter has a type and description
- At least one usage example per function
Report results. Fix issues before presenting the final document.
使用场景
-
文档生成流水线
-
代码发布流程
-
多阶段数据处理
-
审批工作流
八、如何选择合适的模式？
不同模式擅长解决的问题不同。可以使用下面决策树找到合适的模式：
决策树的运行逻辑是这样的：
你的 Skill 是否产生输出？
如果需要输出并且输出格式化的数据使用Generator
如果需要输出并且输出不用格式化使用Tool Wrapper
如果不需要输出，需要评估输入，选Reviewer。
如果不需要输出，需要用户先输入以进一步确认细节，选Inversion
如果不需要输出，多步骤按顺序执行，选Pipeline
如果不需要输出，多步骤执行，选Tool Wrapper
最后，模式可以组合使用。
-
Pipeline 可以在最后加一个 Reviewer 步骤，自我检查
-
Generator 可以在开头用 Inversion 收集变量
-
Tool Wrapper + Reviewer = 规范掌握 + 自动审查
参考资料
-
Google Cloud Tech 原文 - 官方推文
-
Agent Skills Specification - 开源规范
-
ADK Documentation - Google Cloud 官方文档
