Agent Skill一经推出，便迅速在技术圈走红。更因为使用起来极为简单方便，使得它早已抄超越技术门槛，为越来越多得人所使用。

Skill的大量使用，也催生了一些提示词标准化使用的新范式。比如"把提示词工程做成可复用的技能包（SKILL.md）"这种范式，已在开发者圈里快速升温。

一方面，Gemini CLI 等工具已经把 SKILL.md + YAML 元数据 + references/assets 目录固化成标准化的技能封装方式；另一方面，围绕技能能否跨工具复用、如何渐进加载、怎样避免把一堆脆弱指令塞进系统提示等讨论也在各种社区持续发酵。

甚至有人开始做 SKILL.md 的 lint/校验工具，来解决跨工具不兼容与引用路径失效等问题。

Google Cloud Tech发布的这篇名为《5 Agent Skill design patterns every ADK developer should know》文章，正是从这股热潮切入的。该文指出"格式之争"基本结束，真正的胜负手在内容设计：同样的外壳（SKILL.md），内部逻辑却可能千差万别。

文章作者根据生态实践提炼出 5 种可复用的技能结构模式，并配套 ADK 代码示例，帮助团队把经验沉淀为可执行、可审计、可组合的智能体工作流。

文章要点：

• • 从格式到结构：SKILL.md 的目录与元数据已趋于标准化，难点转为"技能内部逻辑如何组织、何时加载哪些上下文"。
• • 五种模式落地：工具包装器（按需注入库/框架约定）、生成器（模板化稳定输出）、审查器（清单+严重级别评分）、反转（先访谈再行动）、管道（多步检查点防跳步）。
• • 工程化与可治理：把规则放进 references/assets、用渐进式加载控制上下文，并通过校验/审查机制降低"技能引用失效、跨工具不一致"的风险。

以下是正文。

  每个ADK开发者都应该知道的5种Agent Skill设计模式

在 SKILL.md 文件方面，开发者往往过度关注格式问题：确保 YAML 格式正确、合理组织目录结构以及遵循规范。但随着超过 30 种智能体工具（如 Claude Code、Gemini CLI 和 Cursor）都标准化采用相同的布局，格式问题实际上已成历史。

现在的挑战在于内容设计。规范说明了如何打包技能，但对如何构建其内部逻辑却没有提供任何指导。例如，一个封装 FastAPI 约定的技能与一个四步文档管道的运作方式完全不同，尽管它们的 SKILL.md 文件从外部看起来完全相同。

从 Anthropic 的代码库到 Vercel 和 Google 的内部指南，通过研究整个生态系统中技能的构建方式，我们可以发现五种反复出现的设计模式，它们可以帮助开发者构建更可靠的智能体。

作者：@Saboo_Shubham_ 和 @lavinigam

本文通过可运行的 ADK 代码介绍每种模式：

• • 工具包装器 Tool Wrapper：让您的智能体立即成为任何库的专家。
• • 生成器 Generato：从可复用模板生成结构化文档。
• • 审查器 Reviewer：按严重程度根据检查清单对代码评分。
• • 反转模式 Inversion：智能体在行动前先对您进行访谈。
• • 管道模式 Pipeline：通过检查点强制执行严格的多步骤工作流。

模式 1：工具包装器

工具包装器为您的智能体提供特定库的按需上下文。与其将 API 约定硬编码到系统提示中，不如将它们打包成一个技能，您的智能体仅在实际使用该技术时才加载此上下文。

这是最简单的实现模式。SKILL.md 文件监听用户提示中的特定库关键词，从 references/ 目录动态加载内部文档，并将这些规则作为绝对准则应用。这正是将团队内部编码指南或特定框架最佳实践直接分发到开发者工作流中的标准机制。

以下是一个工具包装器示例，用于教导智能体如何编写 FastAPI 代码。注意指令如何明确告知智能体：仅在开始审查或编写代码时，才加载 conventions.md 文件：

# 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 injection

模式 2：生成器

工具包装器负责应用知识，而生成器则负责强制输出一致性。如果您的智能体在每次运行时生成不同的文档结构，生成器通过协调填空式流程来解决这一问题。

生成器利用两个可选目录：assets/ 存放输出模板，references/ 存放样式指南。指令充当项目经理的角色，告知智能体加载模板、阅读样式指南、向用户询问缺失变量并填充文档。这对于生成可预测的 API 文档、标准化提交消息或搭建项目脚手架尤为实用。

在以下技术报告生成器示例中，技能文件本身不包含实际的布局规则或语法规则，而是仅负责协调各类资产的调取，并强制智能体逐步执行：

# 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.

模式 3：审查器

审查器模式将"检查什么"与"如何检查"分离开来。与其在冗长的系统提示中逐一列举每种代码坏味道，不如将模块化的评审标准存储在 references/review-checklist.md 文件中。

当用户提交代码时，智能体加载此检查清单并系统地对提交内容评分，按严重程度对发现结果进行分组。只需将 Python 风格检查清单替换为 OWASP 安全检查清单，使用完全相同的技能基础设施，即可获得一套截然不同的专项安全审计。这是自动化 PR 审查或在人工介入之前主动捕获漏洞的高效方法。

以下代码审查器技能展示了这种分离架构。指令部分保持静态不变，但智能体从外部检查清单动态加载具体的审查标准，并强制输出按严重程度分类的结构化审查结果：

# skills/code-reviewer/SKILL.md
---
name:code-reviewer
description:审查Python代码的质量、
风格和常见缺陷。当用户提交代码供
审查、请求对其代码的反馈或需要代码
审计时使用。
metadata:
pattern:reviewer
severity-levels:error,warning,info
---

您是Python代码审查员。严格遵循以下
审查协议：

步骤1：加载'references/review-checklist.md'
以获取完整的审查标准。

步骤2：仔细阅读用户的代码。在提出批评
之前，先理解其用途。

步骤3：将检查清单中的每条规则应用于代
码。对于发现的每个违规：
-记录行号（或大致位置）
-分类严重程度：error（必须修复）、
warning（应该修复）、info（建议考虑）
-解释问题存在的原因（WHY），而不仅仅
是问题所在（WHAT）
-提供包含修正代码的具体修复建议

步骤4：生成包含以下部分的结构化审查
报告：
-**摘要**：代码的功能描述及整体质量
评估
-**发现**：按严重程度分组（错误优先，
其次是警告，最后是信息）
-**评分**：1-10分制，附简要说明
-**前3条建议**：最具影响力的改进
措施

# 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

模式 4：反转模式

智能体天然倾向于立即猜测并生成结果。反转模式颠覆了这一动态：智能体不再被动地等待用户驱动提示并执行，而是主动充当访谈者的角色。

反转模式依赖于明确且不可逾越的门控指令（例如"在所有阶段完成之前，不得开始构建"），强制智能体优先收集上下文。它按顺序提出结构化问题，并在进入下一阶段前等待用户答复。在对需求和部署约束形成完整认知之前，智能体拒绝输出任何综合结果。

以下项目规划器技能展示了这一模式的具体运作。关键要素在于严格的阶段划分，以及在收集完所有用户答复之前阻止智能体综合最终计划的明确门控提示：

# skills/project-planner/SKILL.md
---
name:project-planner
description:在生成计划之前，通过结构
化提问收集需求，从而规划新软件项目。
当用户说"我想构建"、"帮我规划"、"设计
一个系统"或"开始一个新项目"时使用。
metadata:
pattern:inversion
interaction:multi-turn
---

您正在进行结构化需求访谈。在所有阶段完成
之前，不得开始构建或设计。

## 阶段 1 — 问题发现（每次提问一个问题，等待每个答复）

按顺序提出以下问题，不得跳过任何问题。

-Q1："这个项目为用户解决什么问题？"
-Q2："主要用户是谁？他们的技术水平
如何？"
-Q3："预期规模是多少？（每日用户数、
数据量、请求速率）"

## 阶段 2 — 技术约束（仅在阶段 1 完整作答后进行）

-Q4："您将使用什么部署环境？"
-Q5："您有任何技术栈要求或偏好吗？"
-Q6："有哪些不可妥协的需求？（延迟、
可用性、合规性、预算）"

## 阶段 3 — 综合（仅在所有问题均已作答后进行）

1.加载'assets/plan-template.md'
以获取输出格式
2.使用收集的需求填充模板的每个部分
3.向用户展示已完成的计划
4.询问："这份计划是否准确反映了您的
需求？您希望更改什么？"
5. 根据反馈进行迭代，直至用户确认

# 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：管道模式

对于复杂任务，步骤被跳过或指令被忽视的代价难以承受。管道模式通过硬检查点强制执行严格的顺序工作流。

指令本身即充当工作流定义。通过实施明确的菱形判定门控（例如，要求用户在从文档字符串生成步骤转入最终组装阶段之前给予确认），管道模式确保智能体不能绕过复杂任务、直接呈现未经验证的最终结果。

该模式充分利用所有可选目录，仅在特定步骤需要时才引入相应的参考文件和模板，从而保持上下文窗口的整洁高效。

以下文档管道示例中，门控条件一目了然：智能体被明确禁止进入组装阶段，直至用户确认上一步骤中已生成的文档字符串：

# skills/doc-pipeline/SKILL.md
---
name:doc-pipeline
description:通过多步骤管道从Python
源代码生成API文档。当用户要求为模
块编写文档、生成API文档或从代码创
建文档时使用。
metadata:
pattern:pipeline
steps:"4"
---

您正在运行文档生成管道。按顺序执行
每个步骤。如果某个步骤失败，不得跳
过步骤或继续执行。

## 步骤 1 — 解析与清单
分析用户的Python代码，提取所有公共
类、函数和常量。以检查清单的形式呈
现清单。询问："这是您想要记录的完整
公共API吗？"

## 步骤 2 — 生成文档字符串
对于每个缺少文档字符串的函数：
-加载'references/docstring-style.md'
以获取所需格式
-严格按照样式指南生成文档字符串
-提交每个生成的文档字符串供用户审批
在用户确认之前，不得继续执行步骤3。

## 步骤 3 — 组装文档
加载'assets/api-doc-template.md'以
获取输出结构。将所有类、函数和文档
字符串编译为单个API参考文档。

## 步骤 4 — 质量检查
对照'references/quality-checklist.md'
进行审查：
-每个公共符号均已记录
-每个参数均有类型和描述
-每个函数至少有一个使用示例
报告结果。在呈现最终文档之前修复
所有问题。

# 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.

选择正确的智能体技能模式

每种模式回答一个不同的问题。参考以下对照，找到适合您用例的模式：

• 需要向智能体注入特定库或框架的专业知识 → 工具包装器；

• 需要智能体始终输出结构一致的文档 → 生成器；

• 需要对代码进行可量化的结构化质量评审 → 审查器；

• 任务在执行前须完整收集用户需求 → 反转模式；

• 任务步骤严格有序、不允许跳步或遗漏 → 管道模式。

最后：模式可组合

这些模式并非互斥，它们可以自由组合。

管道技能可以在末尾嵌入一个审查器步骤，对自身的输出结果进行双重校验；生成器可以在最开始引入反转模式，在填充模板之前先收集必要的变量。借助 ADK 的 SkillToolset 和渐进式加载机制，智能体在运行时仅为实际调用的特定模式消耗上下文 token。

停止将复杂而脆弱的指令一股脑塞进单个系统提示。分解工作流，应用正确的结构化模式，构建真正可靠的智能体。

立即开始

Agent Skills 规范已开源，并在 ADK 中获得原生支持。您已掌握技能的打包方式，现在也掌握了内容的设计方法。使用 Google 智能体开发工具包，构建更智能的智能体。

写在最后

提示词工程正在经历一场深刻的范式迁移：从"如何写出一段好提示词"，演进为"如何将提示词逻辑工程化、模块化、可复用"。

SKILL.md 格式的标准化，不过是这场迁移的起点；真正的挑战，在于内容的结构设计。

这篇文章所提炼的五种模式：工具包装器、生成器、审查器、反转模式、管道模式，也不是非凭空而来，而是从 Anthropic、Vercel、Google 等头部机构的工程实践中归纳出的共性解法。

如果仔细阅读，你会发现其实它们各自回答了一个具体的工程问题：何时按需加载上下文、如何保证输出结构一致、如何把评审标准与执行逻辑解耦、何时应当先问后做，以及如何防止智能体在复杂任务中跳步乱序。

重要的是，这五种模式并不孤立，且是可以自由组合的工程构件。一个成熟的Agent工作流，往往是多种模式的有机叠加：管道保证执行顺序，审查器把守质量关口，反转模式在入口处收集完整上下文。这种模块化、可组合的设计理念，正是 SKILL.md 生态最核心的工程价值所在。

对于开发团队来说，已经是时候以架构师的视角重新审视智能体工作流：

• • 哪些逻辑应封装为可复用的技能？
• • 哪种模式最契合当前任务的语义特征？
• • 如何通过合理组合，让整体效果大于部分之和？
  ……

格式只是起点，结构才是终点。