装了一堆技能不好使？你缺的不是格式，是设计模式 Google 官方总结的5 种技能设计模式

模式一：Tool Wrapper（工具包装器）

痛点：你希望 Claude 用某个框架或库的时候，遵守特定的规范和最佳实践。但每次都要在对话里重复提醒"用 Pydantic V2 不要用 V1""路由要按这个结构组织"，烦。

类比：想象你新来一个实习生，每次写代码都要口头叮嘱一遍"我们公司用 ESLint 这套规则、命名用驼峰、API 路径用复数"。说了三遍你就烦了。Tool Wrapper 就是把这些叮嘱写成一本员工手册，新人来了翻手册就行，不用你每次口述。

为什么要单独做成技能，而不是写在系统提示词里？ 因为上下文窗口是有限的。你把 FastAPI 规范、React 规范、数据库规范全塞进系统提示词，Claude 还没开始干活，窗口就满了一大半。Tool Wrapper 的核心思路是按需加载：你写 React 的时候，FastAPI 的规范根本不需要出现。Claude 检测到你在聊 FastAPI，才把那份规范拉进来。

核心结构：

my-fastapi-skill/
├── SKILL.md          # 触发条件 + 核心指令
└── references/
    ├── routing.md    # 路由最佳实践
    ├── models.md     # 数据模型规范
    └── gotchas.md    # 常见坑点

SKILL.md 里的关键写法：

---
name: api-expert
description: FastAPI 开发最佳实践。在构建、审查或调试
  FastAPI 应用时使用。
---

你是 FastAPI 开发专家。

## 核心规范
加载 'references/conventions.md' 获取完整最佳实践列表。

## 审查代码时
1. 加载规范参考
2. 对照每条规范检查用户代码
3. 对每个违规项，引用具体规则并建议修复

适用场景：团队有一套技术规范，希望 Claude 自动遵守。框架封装、代码规范、写作风格指南，都适合这个模式。

一句话总结：把散落在团队 wiki 和口口相传里的"我们是这么用的"，打包喂给 Claude，让它自动变成老员工。

模式二：Generator（生成器）

痛点：你要反复产出结构相似的内容。每次写 API 文档、每次出周报、每次写产品动态，格式都一样，但 Claude 每次跑出来的结构都不一样。上次有摘要这次没有，上次有来源标注这次忘了。

类比：你去打印店做名片，不会每次都从头设计。你选一个模板，填上名字、电话、职位就行了。Generator 就是给 Claude 一个模板，它的工作不是"创作"，是"填空"。但比打印店高级的地方在于，它还有一本《品牌视觉规范手册》，填空的时候要按手册里的规矩来。

为什么 Agent 需要被强制"按模板填"？ 因为 AI 的天性是创造性地生成。你给它一个需求，它每次都想"更好地表达"，结果每次表达方式都不一样。Generator 模式用模板把 AI 的创造力框住：骨架是固定的，你只管往里面填肉。

Google 原文说得很准确：SKILL.md 本身不包含任何布局规则或内容，它只负责协调。读模板、读样式指南、问你缺什么信息、填充、输出。像一个项目经理，自己不写一个字，但控制整个流程。

核心结构：

doc-generator/
├── SKILL.md            # 生成流程 + 质量标准
├── assets/
│   └── template.md     # 文档模板（带占位符）
└── references/
    └── style-guide.md  # 风格指南

SKILL.md 里的关键写法：

---
name: report-generator
description: 生成结构化技术报告。当用户要求撰写报告时使用。
---

你是技术报告生成器。严格按以下步骤执行：

步骤 1：加载 'references/style-guide.md' 获取语调和格式规则
步骤 2：加载 'assets/report-template.md' 获取输出结构
步骤 3：向用户询问缺失信息（主题、数据、目标读者）
步骤 4：按样式指南填充模板，每个章节都必须保留
步骤 5：返回完整文档

适用场景：任何需要"统一输出格式"的场景。文档生成、报告模板、邮件模板、代码脚手架。

一句话总结：SKILL.md 当项目经理，模板当骨架，风格指南当质检员。三件套配齐，产出就稳定了。

模式三：Reviewer（审查器）

痛点：你需要 Claude 按一套标准评估代码或内容。不是让它写东西，是让它挑毛病。但每次要重新描述"你帮我看看有没有安全问题""你帮我检查一下代码风格"，标准不统一，漏检是常事。

类比：餐厅的卫生检查员不需要会做菜。他手里有一张检查表：厨房温度达标吗？食材过期了吗？操作台干净吗？逐条打勾就行。Reviewer 就是这个检查员，手里的检查表决定了它是食品安全审查还是消防安全审查。同一个人，换张表，就能查不同的东西。

为什么要把检查标准单独存文件，而不是写在指令里？ 因为你会经常更新标准。发现一个新的安全漏洞模式，往 checklist 里加一条就行，不需要重写整个技能。而且同一个 Reviewer 骨架，换一份 checklist 就变成完全不同的审查工具。Google 原文举了个很好的例子：把 Python 风格检查清单换成 OWASP 安全检查清单，瞬间就变成了安全审计技能。代码一行不用改。

核心结构：

code-reviewer/
├── SKILL.md              # 审查流程 + 评分规则
└── references/
    └── checklist.md      # 检查清单（按严重度分级）

checklist.md 举例（Python 风格审查）：

## Critical（必须修）
- 硬编码密钥或密码
- SQL 拼接（注入风险）
- 未处理的异常吞掉错误信息

## Warning（建议修）
- 函数超过 50 行
- 变量命名不符合 PEP 8

## Info（可以考虑）
- 可以用列表推导式简化的循环
- 重复的 import

SKILL.md 里的关键写法：

---
name: code-reviewer
description: 审查 Python 代码的质量和安全性。当用户提交代码审查时使用。
---

你是代码审查员。严格按以下流程执行：

步骤 1：加载 'references/checklist.md' 获取审查标准
步骤 2：仔细阅读代码，先理解目的再评判
步骤 3：逐条检查，每个发现标注严重程度（Critical/Warning/Info）
步骤 4：输出审查报告，按严重度分组，Critical 优先

适用场景：代码审查、安全审计、内容质量检查、合规检查。任何"打分评估"的场景。

一句话总结：骨架固定，清单可换。一个 Reviewer 技能，换份清单就是另一个领域的专家。

模式四：Inversion（反转控制）

痛点：你给 Claude 一个需求，它二话不说就开始写代码了。你还没说完呢，它已经写了 200 行，方向还是错的。

Agent 天生就想猜、想立刻动手。大部分情况这是优点，但在需求不明确的复杂任务里，这是灾难。

类比：你去看医生。好医生不会你刚说"头疼"就开药，他会先问：疼了多久？哪个位置？有没有其他症状？吃过什么药？最近压力大吗？问完一圈，才下诊断开药。Inversion 模式就是让 Claude 像好医生一样，先问诊，再开方。如果 Claude 是个"头疼就给你开止痛片"的医生，你敢吃吗？

为什么 Agent 需要被硬性拦住？ 因为"猜测并立即生成"是大语言模型的本能。原文说得很到位："Agents inherently want to guess and generate immediately." 这个本能在简单任务上是效率，在复杂任务上是灾难。你不能指望 Claude "自觉"去问你问题，你得在 SKILL.md 里用最强硬的指令把它按住："在所有阶段完成之前，禁止开始构建。"不写这句话，它问了两个问题就会忍不住开始写代码。

核心结构：

project-planner/
├── SKILL.md              # 访谈流程 + 启动条件
└── references/
    └── question-bank.md  # 问题库

SKILL.md 里的关键写法：

---
name: project-planner
description: 通过结构化提问收集需求后再制定计划。
  当用户说"帮我规划""设计一个系统"时使用。
---

你正在进行结构化需求采访。
DO NOT start building until all phases are complete.

## 阶段 1：目标确认（每次问一个，等回答）
- 这个项目要解决什么问题？
- 目标用户是谁？
- 成功标准是什么？

## 阶段 2：技术约束（阶段 1 全部回答后才进入）
- 必须用哪些技术栈？
- 部署环境是什么？
- 不可妥协的需求？（延迟、合规、预算）

## 阶段 3：综合（所有问题回答后才进入）
1. 加载 'assets/plan-template.md' 获取输出格式
2. 用收集到的需求填充模板
3. 向用户确认："这个方案准确吗？想改什么？"

适用场景：新项目启动、复杂需求拆解、任何"别急，先搞清楚再动手"的场景。

一句话总结：Agent 的本能是猜了就干。Inversion 把这个本能反过来：先问清楚，再动手。

模式五：Pipeline（流水线）

痛点：多步骤任务，Claude 经常跳步。你让它"先调研、再设计、再编码、最后测试"，它调研到一半觉得自己懂了就开始写代码，跳过了设计环节。或者在编码阶段突然开始重新调研，前后反复。

类比：工厂流水线为什么效率高？因为每个工位只干一件事，干完了传给下一个工位。不会出现"装轮胎的工人突然跑去喷漆"的情况。Pipeline 模式就是给 Claude 造一条流水线：每个阶段有明确的任务，有明确的完成标准，达标了才能传给下一阶段。更关键的是，每个阶段只加载那个阶段需要的参考资料，不会被其他阶段的信息干扰。

为什么需要"门控"（Gate）？ 因为 Agent 不像流水线工人有物理约束，它随时可以"跳到任何一步"。你得用指令把它钉在当前阶段。门控就是那道铁门：所有条件都满足了，门才开。条件可以是"用户确认了"，也可以是"文件生成成功了"，也可以是"质量检查通过了"。

Google 原文管这叫"diamond gate conditions"（菱形门控条件），来自流程图里表示判断的菱形框。每个门控都是一个 Yes/No 判断，No 就打回去重做。

核心结构：

feature-pipeline/
├── SKILL.md                  # 流水线定义 + 门控条件
└── references/
    ├── research-guide.md     # 阶段 1 参考
    ├── design-patterns.md    # 阶段 2 参考
    ├── coding-standards.md   # 阶段 3 参考
    └── test-checklist.md     # 阶段 4 参考

SKILL.md 里的关键写法：

---
name: doc-pipeline
description: 通过多步骤管线从源代码生成 API 文档。
---

你正在运行文档生成管线。按顺序执行，禁止跳步。

## 步骤 1：解析与清点
分析代码，提取所有公开类和函数。
询问："这是你想要文档化的完整 API 吗？"

## 步骤 2：生成文档注释
- 加载 'references/docstring-style.md'
- 逐个生成文档注释，向用户展示
- ⛔ 用户确认之前，禁止进入步骤 3

## 步骤 3：组装文档
加载 'assets/api-doc-template.md'，编译成完整 API 参考文档

## 步骤 4：质量检查
对照 'references/quality-checklist.md' 审查
- 每个公开符号都有文档？
- 每个参数都有类型和描述？
- 修复所有问题后再提交最终文档

注意每个阶段只加载那个阶段需要的参考文档。阶段 1 不需要看编码规范，阶段 3 不需要看调研指南。好处有两个：省 token，减少干扰。Claude 不会在编码阶段突然跑去做调研。

适用场景：任何超过三步的复杂工作流。功能开发、内容生产线、数据处理管道。

一句话总结：流水线不是建议，是强制。门控条件把 Claude 钉在当前阶段，不达标不放行。

怎么选模式？一张表搞定

实际场景对号入座：

高级用法：模式组合

单个模式覆盖单个场景，但真实工作流往往需要组合。两种最常见的：

Pipeline + Reviewer：流水线的某个阶段内嵌一个审查步骤。比如内容生产线里，写完初稿后有一个质量审查阶段，用 Reviewer 的检查清单打分，不通过就打回重写，通过了才进入排版。就像工厂流水线上的质检工位，不是生产线外面单独的质检部门。

Generator + Inversion：生成内容之前，先收集所有必要信息。比如生成项目提案，先用 Inversion 问清楚背景、目标、约束，然后再用 Generator 按模板生成。就像医生先问诊（Inversion），再按处方模板开药（Generator）。

Google 原文总结得好："These patterns are not mutually exclusive. They compose." 先把单个模式用熟，组合是自然而然的事。

从哪个模式开始

如果你现在只会"写一段提示词丢进 SKILL.md"，按这个顺序上手：

第一步：Tool Wrapper。 最简单，也最实用。挑你最常用的一个框架或库，把你每次都要提醒 Claude 的那些规范写进去，把常见坑点整理到 references/ 下面。十分钟就能搞定，立刻能感受到效果。

第二步：Reviewer。 找一个你经常需要 Claude "帮我检查一下"的场景，把检查标准写成清单，按严重度分级。写完你会发现，这个模式的复用性极高，换份清单就是新技能。

第三步：Generator 或 Inversion，看你的需求。 经常需要统一格式产出的，先搞 Generator。经常被 Claude 抢跑、需求没说清就开始写的，先搞 Inversion。

最后才碰 Pipeline。 它是最复杂的模式，但也是天花板最高的。等前面几个模式用熟了，你自然会遇到"我需要把多个阶段串起来"的场景，那时候上 Pipeline 水到渠成。

技能写得好不好，不看格式对不对，看你选的设计模式对不对。格式是入场券，模式才是手艺。

Agent Skills 规范是开源的，在 ADK 中得到原生支持。您已经了解如何打包该格式。现在您知道如何设计内容了。使用 Google Agent Development Kit 构建更智能的代理。

GitHub：https://google.github.io/adk-docs/

来源：Google Cloud Tech 的 X Article