当谈到 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 时，开发者往往过于关注格式——正确编写 YAML、组织目录结构、遵循规范。但随着超过 30 种 Agent 工具（如 Claude Code、Gemini CLI 和 Cursor）统一采用相同的布局，格式问题实际上已经不再是障碍。
现在的挑战在于内容设计。规范说明了如何打包一个技能，但完全没提如何组织其内部的逻辑。例如，一个封装 FastAPI 惯例的技能，与一个四步文档生成管道的技能，尽管它们的 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件从外部看一模一样，运行方式却完全不同。
通过研究整个生态中技能的构建方式——从 Anthropic 的代码仓库到 Vercel 和 Google 的内部指引——我们发现有五种反复出现的模式，可以帮助开发者构建更好的 Agent。
作者：@Saboo_Shubham_ 和 @lavinigam
本文将通过可运行的 ADK 代码逐一介绍每种模式：
- 工具包装器：让你的 Agent 瞬间成为任何库的专家
- 生成器：基于可复用模板生成结构化文档
- 评审器：按严重级别对照清单评审代码
- 反转式：Agent 先对你进行访谈，然后再执行操作
- 管道式：强制执行带有检查点的严格多步骤工作流
模式一：工具包装器
工具包装器为你的 Agent 提供特定库的按需上下文。你无需将 API 惯例硬编码到系统提示中，而是将它们打包成一个技能。只有当 Agent 实际使用该技术时，它才会加载这个上下文。
这是实现起来最简单的模式。𝕊𝕂𝕀𝕃𝕃.𝕞𝕕 文件监听用户提示中的特定库关键词，动态地从 references/ 目录加载你的内部文档，并将这些规则作为绝对真理应用。这正是你将团队内部编码规范或特定框架最佳实践直接分发到开发者工作流中的机制。
下面是一个工具包装器的示例，它教会 Agent 如何编写 FastAPI 代码。注意指令中明确告诉 Agent，只有在开始审查或编写代码时才加载 conventions.md 文件：
1# skills/api-expert/SKILL.md2---3name: api-expert4description: FastAPI 开发最佳实践和惯例。在构建、审查或调试 FastAPI 应用、REST API 或 Pydantic 模型时使用。5metadata:6 pattern: tool-wrapper7 domain: fastapi8---910你是 FastAPI 开发的专家。请将这些惯例应用到用户的代码或问题中。1112## 核心惯例1314加载 'references/conventions.md' 以获取完整的 FastAPI 最佳实践列表。1516## 审查代码时171. 加载惯例参考文件182. 对照每条惯例检查用户代码193. 对于每条违规，指出具体规则并建议修复2021## 编写代码时221. 加载惯例参考文件232. 严格遵循每条惯例243. 为所有函数签名添加类型注解254. 使用 Annotated 风格进行依赖注入
模式二：生成器
工具包装器应用知识，而生成器则强制生成一致的输出。如果你经常遇到 Agent 每次运行都生成不同文档结构的问题，生成器通过组织一个填空流程来解决这个问题。
它利用了两个可选目录：assets/ 存放输出模板，references/ 存放风格指南。指令充当项目经理的角色，告诉 Agent 加载模板、阅读风格指南、向用户询问缺失的变量，然后填充文档。这对于生成可预测的 API 文档、标准化提交信息或搭建项目架构非常实用。
在这个技术报告生成器示例中，技能文件本身并不包含实际布局或语法规则。它只是协调这些资产的检索，并强制 Agent 一步一步地执行它们：
1# skills/report-generator/SKILL.md2---3name: report-generator4description: 生成 Markdown 格式的结构化技术报告。当用户要求撰写、创建或起草报告、摘要或分析文档时使用。5metadata:6 pattern: generator7 output-format: markdown8---910你是一个技术报告生成器。请严格按照以下步骤操作：1112第一步：加载 'references/style-guide.md' 以获取语气和格式规则。1314第二步：加载 'assets/report-template.md' 以获取所需的输出结构。1516第三步：询问用户任何填写模板所需的缺失信息：17- 主题或话题18- 关键发现或数据点19- 目标受众（技术人员、高管、普通用户）2021第四步：按照风格指南规则填充模板。输出中必须包含模板的每个部分。2223第五步：将完成的报告作为一个 Markdown 文档返回。
模式三：评审器
评审器模式将“检查什么”与“怎么检查”分离开来。你无需编写冗长的系统提示来列举每种代码坏味道，而是将模块化的评审标准存储在 references/review-checklist.md 文件中。
当用户提交代码时，Agent 加载这份清单，并逐条对提交的代码进行评分，按严重程度对发现的问题进行分组。如果你把 Python 风格清单换成 OWASP 安全清单，使用完全相同的技能基础架构，就能得到一个完全不同、专业化的审计。这是自动化 PR 审查或在人工查看代码之前捕获漏洞的高效方法。
下面的代码评审技能展示了这种分离。指令保持静态，但 Agent 从外部清单动态加载具体的评审标准，并强制输出结构化的、按严重级别分类的结果：
1# skills/code-reviewer/SKILL.md2---3name: code-reviewer4description: 审查 Python 代码的质量、风格和常见错误。当用户提交代码进行审查、寻求代码反馈或要求代码审计时使用。5metadata:6 pattern: reviewer7 severity-levels: error,warning,info8---910你是一个 Python 代码评审员。请严格按照以下评审协议操作：1112第一步：加载 'references/review-checklist.md' 以获取完整的评审标准。1314第二步：仔细阅读用户代码。在批评之前先理解其目的。1516第三步：将清单中的每条规则应用到代码上。对于每一条违规：17- 标注行号（或近似位置）18- 分类严重级别：error（必须修复）、warning（应该修复）、info（可以考虑）19- 解释为什么存在问题，而不仅仅是哪里有问题20- 提供具体的修复建议和修正后的代码2122第四步：输出结构化的评审结果，包含以下部分：23- **摘要**：代码的功能、整体质量评估24- **发现的问题**：按严重级别分组（先 errors，再 warnings，最后 info）25- **评分**：1-10 分，附简要理由26- **前 3 条建议**：最具影响力的改进点
模式四：反转式
Agent 天生倾向于直接猜测并立即生成。反转式模式颠覆了这种动态。不再是用户驱动提示、Agent 执行，而是 Agent 扮演访谈者的角色。
反转式依赖于明确的、不可协商的门控指令（例如“在所有阶段完成之前不要开始构建”），强制 Agent 先收集上下文。它按顺序提出结构化问题，等待你的回答后再进入下一个阶段。Agent 只有在完整了解你的需求和部署约束之后，才会综合最终输出。
来看这个项目规划技能的例子。这里的关键在于严格的阶段划分和明确的门控提示，防止 Agent 在收集完所有用户回答之前就合成最终计划：
1# skills/project-planner/SKILL.md2---3name: project-planner4description: 通过结构化问题收集需求，然后制定新软件项目计划。当用户说“我想构建”、“帮我规划”、“设计一个系统”或“开始一个新项目”时使用。5metadata:6 pattern: inversion7 interaction: multi-turn8---910你正在主持一场结构化需求访谈。在所有阶段完成之前，不要开始构建或设计。1112## 阶段一 —— 问题发现（一次问一个问题，等待每个答案）1314按顺序提问。不要跳过任何一个。1516- Q1: “这个项目要为用户解决什么问题？”17- Q2: “主要用户是谁？他们的技术水平如何？”18- Q3: “预期规模是多少？（每日用户数、数据量、请求速率）”1920## 阶段二 —— 技术约束（只有在阶段一完全回答后才开始）2122- Q4: “你将使用什么部署环境？”23- Q5: “你对技术栈有什么要求或偏好？”24- Q6: “哪些是不可妥协的要求？（延迟、可用性、合规性、预算）”2526## 阶段三 —— 综合（只有在所有问题都回答后才开始）27281. 加载 'assets/plan-template.md' 以获取输出格式292. 使用收集到的需求填充模板的每个部分303. 将完成的计划呈现给用户314. 询问：“这个计划是否准确捕捉了你的需求？你想改什么？”325. 根据反馈进行迭代，直到用户确认
模式五：管道式
对于复杂任务，你不能允许跳过步骤或忽略指令。管道式模式通过硬性检查点强制执行严格的顺序工作流。
指令本身充当工作流定义。通过实现显式的菱形门控条件（例如要求在从文档字符串生成进入最终组装之前获得用户批准），管道式确保 Agent 不能绕过复杂任务而直接呈现未经验证的最终结果。
该模式利用了所有可选目录，只在需要时的特定步骤拉入不同的参考文件和模板，从而保持上下文窗口的整洁。
在这个文档管道示例中，注意显式的门控条件。Agent 被明确禁止进入组装阶段，直到用户确认上一步生成的文档字符串：
1# skills/doc-pipeline/SKILL.md2---3name: doc-pipeline4description: 通过多步管道从 Python 源代码生成 API 文档。当用户要求记录模块、生成 API 文档或从代码创建文档时使用。5metadata:6 pattern: pipeline7 steps: "4"8---910你正在运行一个文档生成管道。请按顺序执行每个步骤。不要跳过步骤，如果某一步失败则不要继续。1112## 第一步 —— 解析与清单13分析用户的 Python 代码，提取所有公共类、函数和常量。将清单呈现为复选框列表。询问：“这是你希望记录的完整公共 API 吗？”1415## 第二步 —— 生成文档字符串16对于每个缺少文档字符串的函数：17- 加载 'references/docstring-style.md' 以获取所需格式18- 严格按风格指南生成文档字符串19- 呈现每个生成的文档字符串供用户批准20在用户确认之前，不要进行第三步。2122## 第三步 —— 组装文档23加载 'assets/api-doc-template.md' 以获取输出结构。将所有类、函数和文档字符串编译成一个 API 参考文档。2425## 第四步 —— 质量检查26对照 'references/quality-checklist.md' 进行审查：27- 每个公共符号都有文档28- 每个参数都有类型和描述29- 每个函数至少有一个使用示例30报告结果。在提交最终文档之前修复问题。
选择合适的 Agent 技能模式
每种模式回答不同的问题。使用这个决策树找到适合你场景的模式：
最后，模式可以组合
这些模式并不互斥。它们可以组合使用。
一个管道式技能可以在最后包含一个评审器步骤，来自我检查工作质量。一个生成器可以在最开始依赖反转式模式来收集填充模板所需的变量。得益于 ADK 的 SkillToolset 和渐进式披露，你的 Agent 在运行时只会消耗与所需模式精确对应的上下文 token。
不要再试图把所有复杂且脆弱的指令塞进一个系统提示里。分解你的工作流，应用正确的结构模式，构建可靠的 Agent。
今天就开始吧
Agent 技能规范是开源的，并且在 ADK 中原生支持。你已经知道如何打包格式，现在你知道如何设计内容了。用 Google Agent Development Kit 构建更智能的 Agent 吧。
