别再死磕提示词了！ADK 开发者必学的 5 大 Skill 设计模式，让你的 Agent 从“偶尔靠谱”变成“工业级稳定”

最近刷 Claude Code、Cursor、Gemini CLI 的同学，肯定都有同一个痛：

你把 SKILL.md 写得天花乱坠，YAML 格式完美，目录结构标准，结果跑起来还是“今天神明天鬼”。

你以为问题出在格式？

其实格式早就不是瓶颈了。现在 30+ 个主流 Agent 工具全在用同一套 Skill 规范，包装问题已经彻底解决。

真正的硬核差距，在Skill 内部的内容设计模式。

我把 Anthropic、Vercel、Google 内部的高手实践全部拆开，发现他们反复在用 5 大设计模式。掌握这 5 个，你的 Agent 直接从“高级 autocomplete”进化成“团队专属生产力武器”。

每个模式都配可直接复制的 ADK 代码示例，拿来就用。

Skill 的本质：别再把所有逻辑塞进一个提示词

以前我们最爱干的事，就是把所有规则、模板、检查清单全塞进一个超长系统提示词里。

结果呢？上下文爆炸、Agent 随便跳步、输出格式每次都不一样。

现在高手们的做法完全不同：把复杂工作流拆成结构化的“设计模式”，具体规则、模板、清单全部放在外部文件里，通过 progressive disclosure 按需加载。

金句：Skill 的威力从来不在提示词有多长，而在你给它的认知架构有多清晰。

下面这 5 个模式，就是目前最成熟的 5 种认知架构。

模式 1：Tool Wrapper —— 让 Agent 瞬间变库专家

场景：想让 Agent 严格遵守团队 FastAPI 规范，却不想每次都塞一堆 conventions。

本质：把特定库/团队规范打包成“随叫随到”的专家知识包。只有用户真正提到这个技术栈时，才加载上下文。

代码示例（skills/api-expert/SKILL.md）：

---
name: api-expert
description: FastAPI 开发最佳实践。构建、审查或调试 FastAPI、REST API 时自动调用。
metadata:
  pattern: tool-wrapper
  domain: fastapi
---

你是 FastAPI 专家。严格应用以下约定：

## Core Conventions
加载 references/conventions.md 获取完整最佳实践列表。

## 当审查代码时
1. 先加载 conventions
2. 逐条比对用户代码
3. 每条违规都要引用具体规则并给出修复建议

你以为要靠长提示词教它，其实一个 Tool Wrapper 就够了。省 token，还永远不会忘规范。

模式 2：Generator —— 强制输出结构永远一致

场景：让 Agent 写技术报告、API 文档、Commit Message，每次格式都天差地别。

本质：用模板驱动的“填空”流程，彻底杜绝结构随机性。

代码示例（skills/report-generator/SKILL.md）：

---
name: report-generator
description: 生成结构化技术报告。用户要求写报告、总结、分析时调用。
metadata:
  pattern: generator
  output-format: markdown
---

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

Step 1: 加载 references/style-guide.md 获取语气和格式规则
Step 2: 加载 assets/report-template.md 获取输出结构
Step 3: 向用户询问缺失信息（主题、关键数据、目标受众）
Step 4: 严格填充模板并返回完整 Markdown 文档

本质句：Generator 把“自由发挥”变成了“标准化生产”，特别适合需要一致输出的场景。

模式 3：Reviewer —— 结构化代码审查神器

场景：想自动化 PR Review，却不想每次都手动写一堆检查规则。

本质：把“检查什么”和“怎么检查”彻底分离，检查清单独立维护，可随时换成安全审查、架构审查等。

代码示例（skills/code-reviewer/SKILL.md）：

---
name: code-reviewer
description: Python 代码质量审查。提交代码求反馈或审计时调用。
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---

你是 Python 代码审查员。严格执行以下协议：

Step 1: 加载 references/review-checklist.md 获取完整审查标准
Step 2: 阅读用户代码，理解意图
Step 3: 逐条比对，每条违规记录行号、严重程度、原因、修复建议
Step 4: 输出结构化报告（Summary + Findings + Score + Top 3 Recommendations）

金句：Reviewer 模式让你一句话就能把一个 Skill 变成不同领域的审查专家。

模式 4：Inversion（反转模式）—— 最反直觉却最强的需求收集器

场景：用户说“帮我规划一个新项目”，Agent 一上来就乱猜直接开始设计。

本质：把主动权反转，让 Agent 先变成结构化访谈者，在收集完所有信息前坚决不开始执行。

代码示例（skills/project-planner/SKILL.md）：

---
name: project-planner
description: 新项目规划。通过结构化提问收集需求后再产出计划。
metadata:
  pattern: inversion
  interaction: multi-turn
---

你正在进行结构化需求访谈。**DO NOT 开始设计或构建，直到所有阶段完成**。

## Phase 1 — 问题发现（一次问一个问题）
Q1: 这个项目要解决用户什么问题？
Q2: 主要用户是谁？技术水平如何？
...

## Phase 3 — 合成（只有全部问题回答完毕才执行）
1. 加载 assets/plan-template.md
2. 填充完整计划
3. 询问用户是否准确，迭代直到确认

你以为你要命令 Agent，其实让 Agent 先审问你，效果强 10 倍。彻底解决“需求模糊导致翻车”的顽疾。

模式 5：Pipeline（流水线模式）—— 复杂任务的防跳步神器

场景：多步任务（比如代码生成文档），Agent 总喜欢跳过验证直接给最终结果。

本质：把整个流程拆成硬性步骤 + 用户确认卡点，绝不允许跳步。

代码示例（skills/doc-pipeline/SKILL.md）：

---
name: doc-pipeline
description: 从 Python 源码生成 API 文档的多步流水线。
metadata:
  pattern: pipeline
  steps: "4"
---

你正在运行文档生成流水线。**必须严格按顺序执行，任何步骤失败或未确认都不能继续**。

## Step 1 — 解析库存
分析代码，输出公共 API 检查清单，问用户是否完整
## Step 2 — 生成 Docstring
...（必须用户确认后才能进入 Step 3）
## Step 3 — 组装文档
...
## Step 4 — 质量检查

本质句：Pipeline 是唯一能让复杂任务“零跳步”的结构。

如何选择模式？（一图胜千言决策树）

• 需要特定库/规范专家能力 → Tool Wrapper
• 需要输出结构永远一致 → Generator
• 需要结构化审查打分 → Reviewer
• 需要先充分收集需求 → Inversion
• 需要严格多步不跳步 → Pipeline

高级玩法：模式自由组合

这些模式不是互斥的，而是可以随便叠加的！

• Pipeline 里嵌 Reviewer（最后一步自动审查）
• Generator + Inversion（先收集需求再填充模板）
• Tool Wrapper 嵌入任何模式（随时调用专家知识）

ADK 的 Skill 机制天生支持 progressive disclosure，上下文永远干净高效。

核心认知：别再试图把所有复杂逻辑塞进一个提示词了。把 Skill 当成“结构化系统”来设计，用模式搭骨架，具体内容放外部文件，这才是 2026 年写好 Agent 的正确姿势。

现在就去挑你最常用的 Skill，按照上面 5 个模式重构一次吧。

改完之后你会发现：Agent 终于不再“偶尔靠谱”，而是真正靠谱了。

我是紫微AI，我们下期见。
（完）