谈到 SKILL.md 文件时，开发者往往纠结于格式——如何正确编写YAML、如何组织目录结构、如何遵循规范。但随着超过30种智能体工具（如Claude Code、Gemini CLI和Cursor）都开始标准化采用相同的布局结构，格式问题实际上已经不再是难题。

现在的挑战在于内容设计。规范文档解释了如何打包一个技能，但对于如何构建技能内部的逻辑却完全没有提供任何指导。例如，一个封装了FastAPI规范的技能，与一个四步流程的文档生成技能，尽管它们的SKILL.md文件在外观上看起来一模一样，但内部运作方式却完全不同。

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

作者：@SabooShubham 和 @lavinigam

本文将逐一介绍这些模式，并提供可运行的ADK代码示例：

工具包装器 (Tool Wrapper)：让你的智能体瞬间成为任何库的专家
生成器 (Generator)：基于可复用模板生成结构化文档
审查器 (Reviewer)：按照严重程度对照检查清单为代码评分
反转模式 (Inversion)：智能体在行动前先对你进行访谈
流水线 (Pipeline)：强制执行带有检查点的严格多步骤工作流

模式一：工具包装器 (Tool Wrapper)

工具包装器能为你的智能体提供针对特定库的按需上下文。与其将API规范硬编码到系统提示词中，不如将它们打包成一个技能。只有当智能体实际需要使用该技术时，才会加载这部分上下文。

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

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

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI开发最佳实践与规范。在构建、审查或调试FastAPI应用、REST API或Pydantic模型时使用。
metadata:
  pattern: tool-wrapper
  domain: fastapi
---

你是一位FastAPI开发专家。请将这些规范应用到用户的代码或问题中。

## 核心规范

加载'references/conventions.md'获取完整的FastAPI最佳实践列表。

## 审查代码时
1. 加载规范参考文档
2. 根据每条规范检查用户的代码
3. 对于每个违规点，引用具体规则并提出修改建议

## 编写代码时
1. 加载规范参考文档
2. 严格遵守每条规范
3. 为所有函数签名添加类型注解
4. 使用Annotated风格进行依赖注入

模式二：生成器 (Generator)

工具包装器侧重于应用知识，而生成器则侧重于强制输出的一致性。如果你经常遇到智能体每次运行生成的文档结构都不同的问题，生成器模式通过编排一个“填空”流程来解决这个问题。

它利用了两个可选的目录：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文档返回。

模式三：审查器 (Reviewer)

审查器模式将审查什么与如何审查分离开来。你无需编写冗长的系统提示词来详述每一种代码坏味道，而是将模块化的评分标准存储在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：将检查清单中的每条规则应用于代码。对于发现的每个违规点：
- 注明行号（或大致位置）
- 分类严重程度：错误（必须修复）、警告（应该修复）、信息（可以考虑）
- 解释为什么这是个问题，而不仅仅是指出错误是什么
- 提供具体的修改建议，包括修正后的代码

步骤 4：生成结构化的审查报告，包含以下部分：
- **总结**：代码的功能、整体质量评估
- **发现**：按严重程度分组（先列出错误，然后是警告，最后是信息）
- **评分**：给出1-10分并简要说明理由
- **三大建议**：最具影响力的改进点

模式四：反转模式 (Inversion)

智能体天生倾向于猜测并立即生成结果。反转模式颠覆了这一动态。不再是用户主导提示词、智能体执行操作，而是由智能体扮演访谈者的角色。

反转模式依赖于明确的、不可协商的门控指令（例如“在所有阶段完成之前，不要开始构建”），强制智能体首先收集上下文信息。它会按顺序提出结构化的问题，并在进入下一阶段之前等待你的回答。只有在全面了解你的需求和部署约束之后，智能体才会综合输出最终结果。

要了解其实际应用，请看这个项目规划技能。关键要素在于严格的阶段划分和明确的门控提示，这阻止了智能体在收集完所有用户答案之前综合生成最终计划：

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

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

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

按顺序询问以下问题。不要跳过任何一个。

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

## 阶段 2 — 技术约束（仅在阶段1完全回答后开始）

- 问题4：“你将使用什么部署环境？”
- 问题5：“你对技术栈有什么要求或偏好吗？”
- 问题6：“有哪些不可妥协的需求？（延迟、正常运行时间、合规性、预算）”

## 阶段 3 — 综合（仅在所有问题都回答后开始）

1. 加载'assets/plan-template.md'获取输出格式
2. 使用收集到的需求填写模板的每个部分
3. 向用户展示完整的计划
4. 询问：“这个计划是否准确反映了你的需求？你有什么要修改的吗？”
5. 根据反馈进行迭代，直到用户确认

模式五：流水线 (Pipeline)

对于复杂的任务，不能容忍跳过步骤或忽略指令。流水线模式通过设置严格的检查点，强制执行一个顺序的工作流。

指令本身作为工作流的定义。通过实现明确的“菱形门控”条件（例如，在从生成文档字符串到最终汇编之前，需要获得用户批准），流水线确保了智能体无法绕过复杂任务而直接给出一个未经验证的最终结果。

这种模式会用到所有可选的目录，仅在特定的步骤中拉取所需的参考文件或模板，从而保持上下文窗口的整洁。

在这个文档生成流水线示例中，请注意那些明确的门控条件。智能体被明确禁止在用户确认上一步生成的文档字符串之前，进入汇编阶段：

# 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'进行检查：
- 所有公共符号都有文档
- 每个参数都有类型和描述
- 每个函数至少有一个使用示例
报告检查结果。在呈现最终文档之前修复发现的问题。

如何选择合适的智能体技能模式

每种模式都回答了不同的问题。使用这个决策树来为你自己的用例找到最合适的模式：

[此处为决策树图示]

最后，模式可以组合使用

这些模式并不是互斥的。它们可以组合使用。

一个流水线技能可以在最后包含一个审查器步骤来复核自身的工作。一个生成器可以在最开始依赖反转模式来收集填充模板所需的变量。得益于ADK的SkillToolset和渐进式信息暴露机制，你的智能体仅在运行时为其所需的确切模式消耗上下文令牌。

别再试图将复杂且脆弱的指令塞进单个系统提示词里了。将你的工作流拆解开来，应用正确的结构模式，构建出真正可靠的智能体。

每位ADK开发者都应掌握的5种智能体技能设计模式

POPULAR POSTS

CATEGORIES