原文来源： Google Cloud Tech (@GoogleCloudTech) · X Article · 2026年3月18日 作者： Shubham Saboo (@Saboo_Shubham_)、Lavi Nigam (@lavinigam) 原文链接： https://x.com/googlecloudtech/status/2033953579824758855 整理日期： 2026年3月20日
文章背景
当谈到 SKILL.md 时，开发者往往纠结于格式——YAML 写对没有、目录结构对不对、是否符合规范。但随着 30 多种 Agent 工具（如 Claude Code、Gemini CLI、Cursor）已经在同一套文件布局上达成标准化，格式问题基本已经解决了。
现在真正的挑战是内容设计。规范告诉你怎么打包一个 Skill，但对如何组织 Skill 内部的逻辑完全没有指导。比如，一个封装 FastAPI 规范的 Skill 和一个四步文档生成流水线，运作方式完全不同，但它们的 SKILL.md 文件从外面看长得一模一样。
通过研究整个生态中 Skill 的构建方式——从 Anthropic 的代码库到 Vercel 和 Google 内部的指南——作者发现了 5 种反复出现的设计模式，可以帮助开发者构建更好的 Agent。
模式 1：Tool Wrapper（工具包装器）
原文翻译
Tool Wrapper 为你的 Agent 提供针对特定库的按需上下文。与其把 API 规范硬编码到系统 prompt 里，不如把它们打包成一个 Skill。Agent 只在实际使用该技术时才加载这些上下文。
这是最简单的实现模式。SKILL.md 文件监听用户 prompt 中的特定库关键词，从 references/ 目录动态加载你的内部文档，并将这些规则视为绝对真理。这正是你向开发者工作流中分发团队内部编码规范或特定框架最佳实践的机制。
示例： 一个教 Agent 写 FastAPI 代码的 Tool Wrapper。指令明确告诉 Agent 只有在开始审查或编写代码时才加载 conventions.md 文件。
# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions.
metadata:
pattern: tool-wrapper
domain: fastapi
---
核心指令： - 审查代码时： 加载规范参考 → 逐条检查 → 引用具体规则并建议修复 - 编写代码时： 加载规范参考 → 严格遵循每条规范 → 添加类型注解 → 使用 Annotated 风格依赖注入
精读点评
Tool Wrapper 解决的是上下文膨胀问题。如果你的 Agent 需要和 20 种技术打交道，把所有规范塞进系统 prompt 会导致上下文窗口浪费和行为泛化。Tool Wrapper 的核心价值是"按需加载"——只在需要时才占用 token。
适用场景： 测试框架规范、ORM 库规范、云服务 SDK 规范、私有代码库编码标准。
模式 2：Generator（生成器）
原文翻译
Tool Wrapper 用于应用知识，Generator 则用于确保输出一致。如果你的 Agent 每次运行都生成不同结构的文档，Generator 通过编排一个"填空"过程来解决这个问题。
它利用两个可选目录：assets/ 存放输出模板，references/ 存放风格指南。指令充当项目经理的角色——告诉 Agent 加载模板、阅读风格指南、向用户询问缺失的变量，然后填充文档。这对生成可预测的 API 文档、标准化 commit 消息或搭建项目架构非常实用。
示例： 技术报告生成器。Skill 文件本身不包含实际的布局或语法规则，它只负责协调获取这些资源并强制 Agent 逐步执行。
# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown.
metadata:
pattern: generator
output-format: markdown
---
核心流程：
1. 加载 references/style-guide.md（语气和格式规则）
2. 加载 assets/report-template.md（输出结构）
3. 向用户收集缺失信息（主题、关键发现、目标受众）
4. 按风格指南填充模板，确保所有必填部分都存在
5. 返回完整的 Markdown 文档
精读点评
Generator 解决的是输出一致性问题。同一个 Agent 执行同一个任务，两次生成完全不同的文档结构——这是 LLM 的天然倾向。Generator 通过"模板 + 风格指南 + 变量收集"三件套强制输出结构化。
适用场景： API 文档、标准化 commit 消息、事故报告、架构设计文档、Changelog。
模式 3：Reviewer（审查员）
原文翻译
Reviewer 模式把"查什么"和"怎么查"分开。与其在系统 prompt 里写一大段详述每种代码问题的说明，不如把模块化的评审标准存储在 references/review-checklist.md 文件中。
当用户提交代码时，Agent 加载这份 checklist 并有条不紊地评分，按严重度分组报告。如果你把 Python 风格 checklist 换成 OWASP 安全 checklist，使用完全相同的 Skill 基础设施就能得到一次完全不同的专业审计。这是自动化 PR 审查或在人工审查前捕获漏洞的高效方式。
示例： Python 代码审查 Skill。指令保持不变，但 Agent 从外部 checklist 动态加载具体审查标准，并强制生成按严重度分级的结构化输出。
# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs.
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
核心流程：
1. 加载 references/review-checklist.md
2. 仔细阅读代码，先理解意图再批评
3. 逐条对照 checklist，每发现一条违规就记录：行号、严重度、原因解释、具体修复建议
4. 输出结构化审查报告：摘要 → 按严重度分组的发现 → 1-10 评分 → Top 3 建议
精读点评
Reviewer 的精髓在于关注点分离——审查逻辑和审查标准解耦。换一份 checklist 就能完全改变审查范围，而 Skill 的"引擎"不用动。这和软件工程中"策略模式"的思想如出一辙。
适用场景： 自动 PR 审查、OWASP 安全审计、合规检查清单、内部架构标准评估。
模式 4：Inversion（反转）
原文翻译
Agent 天然倾向于猜测并立即生成。Inversion 模式翻转了这种动态。不是用户驱动 prompt、Agent 执行，而是 Agent 充当采访者。
Inversion 依赖明确的、不可协商的门控指令（如"在所有阶段完成之前，不要开始构建"）来强制 Agent 先收集上下文。它按顺序提出结构化问题，等待你的回答后才进入下一阶段。Agent 拒绝在完整掌握你的需求和部署约束之前综合输出最终结果。
示例： 项目规划 Skill。关键在于严格的阶段划分和明确的门控 prompt，阻止 Agent 在收集完所有用户回答之前综合最终计划。
# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements through structured interview.
metadata:
pattern: inversion
interaction: multi-turn
---
核心流程： - 阶段 1 — 问题发现： Q1 项目解决什么问题？Q2 主要用户是谁？Q3 预期规模？ - 阶段 2 — 技术约束（仅在阶段 1 全部回答后）： Q4 部署环境？Q5 技术栈偏好？Q6 不可妥协的要求？ - 阶段 3 — 综合（仅在所有问题回答后）： 加载模板 → 填充 → 呈现 → 迭代反馈直到用户确认
精读点评
Inversion 是 5 个模式中对企业场景价值最大的。大多数内部 AI 工具的失败不是模型不够好，而是用户给的输入太模糊，Agent 靠猜就开始干活。Inversion 强制 Agent 先做"需求调研"再动手——这对审计、咨询、项目规划等场景天然适用。
适用场景： 产品需求收集、Sprint 规划、数据项目配置、新系统上线。
模式 5：Pipeline（流水线）
原文翻译
对于复杂任务，你不能容忍步骤被跳过或指令被忽略。Pipeline 模式用硬性检查点来强制执行严格的顺序工作流。
指令本身就是工作流定义。通过实施明确的菱形门控条件（如要求用户在从 docstring 生成阶段推进到最终组装之前必须批准），Pipeline 确保 Agent 无法绕过复杂任务直接呈现未验证的最终结果。
这个模式使用所有可选目录，只在需要的特定步骤才引入不同的参考文件和模板，保持上下文窗口干净。
示例： 文档生成流水线。注意明确的门控条件——Agent 被明确禁止在用户确认上一步生成的 docstring 之前进入组装阶段。
# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline.
metadata:
pattern: pipeline
steps: "4"
---
核心流程： 1. 解析与清单： 分析代码，提取所有公共类、函数和方法 2. 生成 Docstring： 按风格指南为每个函数生成 docstring → 呈现给用户审批 → 用户未确认前不得继续 3. 组装文档： 加载文档模板，将所有类和函数编译为完整 API 参考 4. 质量检查： 对照质量清单审查 → 修复问题 → 呈现最终文档
精读点评
Pipeline 和我们之前固化的晨报信息图流程（analysis → structured-content → prompt → image → 门禁验收）在思想上完全一致。文章把这种实践上升为了通用设计模式。核心思想是：当 Agent 要做的事情超过 3 步，且每一步都依赖前一步的结果时，你必须用结构化的检查点来防止 Agent "抄近路"。
适用场景： 带安全检查清单的部署流程、带编辑审批的内容生产流水线、需要逐步确认的合规工作流。
模式选择决策指南
| 你的问题是什么 | 推荐模式 | 常见组合 |
|---|---|---|
| 需要按技术切换专家身份，不污染全局上下文 | Tool Wrapper | + Reviewer |
| 需要结构化、可预测、跨次一致的输出 | Generator | + Inversion |
| 需要可插拔的评审标准，同一套引擎不同 checklist | Reviewer | Pipeline + Reviewer |
| 需要先收集完整信息再行动，避免基于猜测的规划 | Inversion | + Generator |
| 需要强制多步骤顺序执行，禁止跳步 | Pipeline | + Reviewer |
模式可以组合
这 5 种模式不是互斥的，而是可组合的：
- 一个 Pipeline 可以在最后一步嵌入 Reviewer 来复核自己的工作
- 一个 Generator 可以在开头嵌入 Inversion 来收集必要的变量再填模板
- 得益于 ADK 的
SkillToolset和渐进式披露机制，Agent 在运行时只为实际需要的模式花费上下文 token
核心建议： 不要试图把复杂而脆弱的指令塞进一个系统 prompt。把工作流拆解开，应用正确的结构模式，构建可靠的 Agent。
精读核心洞察
1. 从"格式标准化"到"设计模式标准化"
文章开篇点明：SKILL.md 的文件格式已经被 30+ 工具统一了，格式战争结束了。下一个战场是 Skill 内部的逻辑设计。这意味着 Agent 开发正在从"怎么写 prompt"进化到"怎么架构 prompt"。
2. 本质是"反 prompt 膨胀"
每个模式的核心价值都是同一件事：让 Agent 在正确的时间加载正确的上下文，而不是一次性塞进所有东西。这和软件工程中"单一职责原则"如出一辙。
3. Inversion 对企业场景价值最大
大多数企业内部 AI 工具的失败不是模型不够好，而是用户给的输入太模糊，Agent 靠猜就开始干活。Inversion 强制 Agent 先做"需求调研"再动手。
4. Pipeline 就是我们已经在做的事情
回顾此前固化的晨报信息图流程（analysis → structured-content → prompt → image → 门禁验收），本质上就是 Pipeline 模式 + Diamond Gate Conditions。文章把这种实践上升为了通用设计模式。
5. 组合能力才是真正的架构能力
模式不是互斥的，而是可组合的。一个 Pipeline 可以在最后一步嵌入 Reviewer；一个 Generator 可以在开头嵌入 Inversion。这种组合能力才是把"prompt 工程"变成"Agent 架构"的关键。
6. 对德勤 AI 平台建设的实际意义
- Tool Wrapper → 各团队的技术规范可以模块化分发，不用塞进全局 prompt
- Generator → 审计报告、合规文档等高频输出场景可以模板化、结构化
- Reviewer → 代码审查、合规检查可以用可插拔的 checklist 驱动
- Inversion → 咨询类场景（需求调研、风险评估）天然适用
- Pipeline → 多步骤审批流程、文档生产流水线可以强制执行