Claude Code Skills 完全指南4：Skill 的内容应该怎么组织？

五种架构模式：Skill 的内容应该怎么组织？

这是「Claude Code Skills 完全指南」系列的第四篇。建议先阅读第三篇《从零构建一个生产级 Skill》再继续。

写在前面

前三篇解决了一条完整的链路：Skill 是什么 → 如何让它触发 → 如何从零构建一个。

如果你按照第三篇的 SOP 走了一遍，你现在大概率有了一个能用的 Skill。它有 description、有工作流步骤、通过了 A/B 测试。

但你可能在构建过程中遇到了一种说不清楚的困惑：

我知道该放什么内容，但我不知道该怎么组织它。

该不该让 Claude 先问我问题再执行？审查标准是放在正文里还是外部文件？一个多步骤的流程该怎么设置检查点？如果我需要 Claude 去加载一个库的文档，该怎么安排加载时机？

这些问题指向的不是"放什么"，而是"怎么放"——SKILL.md 内部的结构设计。

现在的挑战是内容设计。规范解释了如何打包一个 Skill，但对如何组织其中的逻辑没有任何指导。例如，一个包装 FastAPI 规范的 Skill 和一个四步骤文档管道的 Skill，运作方式完全不同，即使它们的 SKILL.md 外壳看起来一模一样。

这就是本文要解决的问题。

通过研究跨生态系统的 Skill 构建方式——从 Anthropic 的仓库到 Vercel 和 Google 的内部指南——有五种反复出现的设计模式可以帮助开发者构建 Agent。

这五种模式是 Google Cloud 团队于 2026 年 3 月正式发表的，但它们的原理远比任何单一框架的生命周期更持久。这五种模式在 Google ADK 的语境下呈现，但其原则超越了任何特定框架。按需加载上下文（Tool Wrapper）、分离模板与填充逻辑（Generator）、外部化评审标准（Reviewer）、行动前先收集需求（Inversion）、强制顺序检查点（Pipeline）——这些是基于 LLM 的任何系统都存在的结构性问题的解决方案。

一、为什么需要架构模式？—— Agent 的三个"本能"

在理解五种模式之前，需要先理解它们共同对抗的敌人。

SKILL.md 的 YAML、目录结构，这些已经标准化了，再卷也卷不出花。真正的竞争力在于：你能不能把业务逻辑抽象成合适的设计模式。每种模式都在对抗 Agent 的"本能"。Agent 天生爱猜、爱跳步、爱一次性输出。这五种模式，本质上都是"约束"——约束 Agent 按规矩办事。好的设计，就是好的约束。

这三个"本能"值得展开说明：

本能 1：爱猜。 Agent 天生想要猜测并立即生成。当你说"帮我做一个项目计划"，Claude 的默认行为是立刻开始写——不问你预算、不问你团队规模、不问你时间限制。它不是不知道该问，而是它的训练倾向于"立即给出有用的回应"。

本能 2：爱跳步。 当你给 Claude 一个五步流程，它经常会把第二步和第四步合并、跳过第三步的验证、直接输出最终结果。它不是不理解步骤顺序，而是它"觉得"自己能一步到位。

本能 3：爱一次性输出。 Claude 倾向于生成完整、全面的回答。在聊天中这是优点，但在工作流中这是灾难——它一口气输出 2000 行代码而不是分步骤让你检查。

这五种模式——Tool Wrapper、Generator、Reviewer、Inversion 和 Pipeline——代表了生态系统中原本分散存在的实践的综合，现在被形式化为一个连贯的结构。它们并不解决 Agent 开发的所有问题，但它们优雅地解决了最常见的问题：臃肿的上下文、不一致的输出、僵化的审查、基于假设的规划、以及缺乏控制的流程。

五种模式，五种约束，对抗三个本能。

text

        Agent 的本能              被哪些模式对抗？
       ─────────────             ─────────────────
       爱猜（假设太多）    ←──── Inversion（先问再做）
       爱跳步（省略验证）  ←──── Pipeline（强制检查点）
                                 Reviewer（独立审查）
       爱一次性输出        ←──── Generator（模板化约束）
                                 Tool Wrapper（按需加载）

二、模式 1：Tool Wrapper —— 按需知识注入

它解决什么问题？

你的团队有一套内部 API 规范、一种框架的最佳实践、或者一套编码标准。如果把这些放进 CLAUDE.md（始终加载），它们在 Claude 做无关任务时浪费上下文。如果不放——Claude 写代码时又不遵循你的标准。

Tool Wrapper 给你的 Agent 提供按需上下文。不是将 API 约定硬编码到系统提示中，而是打包成一个 Skill。Agent 只在实际使用该技术时才加载此上下文。这是最简单的实现模式。

核心结构

text

tool-wrapper-skill/
├── SKILL.md              # "什么时候加载"和"加载后怎么用"
└── references/
    └── conventions.md    # 实际的规范/文档（按需加载）

注意指令如何明确告诉 Agent 只在开始审查或编写代码时才加载 conventions.md 文件。

以一个 FastAPI 的 Tool Wrapper 为例：

YAML

---
name: api-expert
description: >
  FastAPI development best practices and conventions. 
  Use when building, reviewing, or debugging FastAPI applications.
---

SKILL.md 正文的结构是：You are an expert in FastAPI development.然后分场景引导— `When Reviewing Code:

1. Load the conventions reference
2. Check code against each convention
3. For violations, cite the rule and suggest the fix。 `When Writing Code:
4. Load the conventions reference
5. Follow every convention exactly
6. Add type annotations to all function signatures。

为什么它有效？

这个模式的精妙之处在于加载时机。conventions.md 可能有 3,000 个 token，如果放在 CLAUDE.md 里，每次会话都会消耗这些 token——哪怕你在做前端工作。但作为 Tool Wrapper Skill，只有当 Claude 识别到"用户在做 FastAPI 相关工作"时，才加载那些规范。

参考感知：虽然每个 Skill 只有一个提示，但该提示可以引用其他资产的位置，并提供代理何时应使用这些资产的信息。当这些资产变得相关时，代理知道这些文件存在并按需将它们读入内存以完成任务。这也遵循渐进式披露模式，限制上下文窗口中的信息。

真实案例：Remotion 最佳实践 Skill

Remotion Best Practices Skill 有 117,000+ 周安装量，并通过 Agent Trust Hub 和 Socket 的安全审计。它在 Claude 处理 Remotion 代码时自动激活，按需只加载相关的规则文件以保持上下文效率。

这是一个教科书级的 Tool Wrapper：规则文件分散在多个 reference 文件中，Claude 只在处理特定类型的 Remotion 代码（动画、音频、3D）时才加载对应的规则文件，而不是一次性全部加载。

适用场景

text

✅ 适合 Tool Wrapper 的场景：
  - 编码规范和最佳实践
  - API 文档和使用指南
  - 框架约定和设计模式
  - 内部工具的使用说明
❌ 不适合 Tool Wrapper 的场景：
  - 需要多步骤流程的任务
  - 需要用户输入的交互式工作流
  - 需要结构化输出的文档生成

这是最简单也最实用的模式。如果你团队有内部编码规范，用 Tool Wrapper 分发给每个开发者，比写一万个 Notion 文档都有用——因为 Agent 真的会去读、去执行。

三、模式 2：Generator —— 模板化输出

它解决什么问题？

如果你苦于 Agent 每次运行都生成不同的文档结构，Generator 通过编排一个填空流程来解决这个问题。它利用两个可选目录：assets/ 存放你的输出模板，references/ 存放你的风格指南。

本质上，Generator 对抗的是 Agent 的"一次性输出"本能。没有模板约束时，Claude 每次生成的报告结构可能都不同——有时用表格、有时用列表、有时加了你没要的章节。

核心结构

text

generator-skill/
├── SKILL.md              # 编排指令（项目经理角色）
├── assets/
│   └── report-template.md  # 输出模板
└── references/
    └── style-guide.md      # 风格指南

指令充当项目经理的角色。它们告诉 Agent 加载模板、阅读风格指南、向用户询问缺失的变量，然后填充文档。这适用于生成可预测的 API 文档、标准化提交信息、或脚手架化项目架构。

完整示例：技术报告生成器

一个技术报告生成器的 SKILL.md：You are a technical report generator. Follow these steps exactly: Step 1: Load 'references/style-guide.md' for tone and formatting rules. Step 2: Load 'assets/report-template.md' for the required structure. Step 3: Ask the user for missing information: - Topic or subject - Key findings or data points - Target audience. Step 4: Fill the template following the style guide. Step 5: Return the completed report.

为什么这么设计？把"内容"和"结构"分离。模板管结构，Agent 管内容填充。换个模板就能产出完全不同类型的文档，复用性极强。

关键设计原则：模板 ≠ 指令

一个常见的错误是把 Generator 和 Pattern A（纯 Markdown 指令）搞混。两者的区别在于：

• Pattern A 的指令告诉 Claude "怎么做"——流程、判断标准、决策逻辑
• Generator 的模板告诉 Claude "输出长什么样"——结构、字段、格式

在技术报告生成器的例子中，Skill 文件不包含实际的布局或语法规则。它只是协调这些资产的检索，并强制 Agent 逐步执行它们。

SKILL.md 是指挥者，不是内容提供者。实际的内容模板和风格规则都在外部文件里。

适用场景

text

✅ 适合 Generator 的场景：
  - 技术报告、周报、月报
  - API 文档生成
  - 提交信息（commit message）格式化
  - 项目脚手架
  - 标准化邮件/通讯
❌ 不适合 Generator 的场景：
  - 需要自由创意的任务（诗歌、营销文案）
  - 高度上下文相关的分析（每次结构都不同）
  - 不需要结构一致性的一次性任务

四、模式 3：Reviewer —— 可替换的审查引擎

它解决什么问题？

Reviewer 模式将"检查什么"和"如何检查"分离。不是在系统提示中详述每一种代码味道，而是将模块化的评审标准存储在 references/review-checklist.md 文件中。当用户提交代码时，Agent 加载这个清单并系统地评分，按严重程度分组。

Reviewer 的精妙之处在于：它的检查逻辑不变，检查标准可替换。

核心结构

text

reviewer-skill/
├── SKILL.md              # 审查流程（固定的）
└── references/
    └── review-checklist.md  # 审查标准（可替换的）

可替换性：一个 Skill，多个用途

如果你把 Python 代码风格清单换成 OWASP 安全清单，你就得到了一个完全不同的专业审计——使用完全相同的 Skill 基础设施。

这是 Reviewer 模式最强大的特性。同一个 Skill 的"壳"（审查流程），可以通过替换 review-checklist.md 来适配完全不同的审查场景：

text

reviewer-skill/
├── SKILL.md                        # 固定的审查流程
└── references/
    ├── python-style.md              # 用途 1：Python 代码风格审查
    ├── owasp-security.md            # 用途 2：安全漏洞审查
    ├── react-performance.md         # 用途 3：React 性能审查
    └── api-design.md                # 用途 4：API 设计审查

这是自动化 PR 审查或在人工审查之前发现漏洞的高效方式。

SKILL.md 正文示例

审查代码的 Skill 中，指令保持固定，但 Agent 动态加载具体的审查标准，并强制输出结构化的、按严重程度分组的结果。

Markdown

---
name: code-reviewer
description: >
  ALWAYS invoke this skill when the user asks to review code, 
  check a PR, audit code quality, or mentions "review", "audit", 
  "code quality". Do not review code directly — use this skill first.
  Do NOT use for refactoring or performance optimization.
---
# Code Review Skill
## Process
1. Load `references/review-checklist.md`
2. For each rule in the checklist:
   - Check the submitted code against the rule
   - If violation found, record: rule name, severity, location, suggested fix
3. Group findings by severity: 🔴 Critical → 🟡 Warning → 🔵 Info
4. For each finding, cite the specific rule from the checklist
## Output Format
### Summary
- Total issues: [count]
- Critical: [count] | Warning: [count] | Info: [count]
### Findings
[Grouped by severity, each with: rule reference, location, explanation, fix]
### Verdict
PASS / PASS WITH WARNINGS / FAIL

注意这里的核心设计：SKILL.md 中没有任何审查标准——所有标准都在 references/ 中。这意味着同一个 Reviewer Skill 可以在不修改 SKILL.md 的情况下，通过替换 checklist 来适配不同类型的审查。

进阶用法：自审查

指示 Agent 在继续之前验证自己的工作。模式是：做工作、运行验证器（脚本、参考清单、或自查）、修复问题、重复直到验证通过。

Reviewer 不只可以用来审查用户提交的代码——它也可以作为其他 Skill 的"内置质检"。比如一个 Generator Skill 生成文档后，可以内嵌一个 Reviewer 步骤来检查自己的输出。

这就是模式组合的起点——稍后会详细展开。

适用场景

text

✅ 适合 Reviewer 的场景：
  - PR 代码审查
  - 安全漏洞扫描
  - 文档质量检查
  - 合同/法律文档审查
  - 设计规范合规检查
❌ 不适合 Reviewer 的场景：
  - 需要生成内容的任务
  - 审查标准不明确/高度主观的场景
  - 一次性的、非标准化的评估

五、模式 4：Inversion —— 先问再做

它解决什么问题？

这是五种模式中最反直觉的一种。它对抗的是 Agent 最根深蒂固的本能——爱猜。

Inversion 模式翻转了常规动态。不是用户驱动提示、Agent 执行，而是 Agent 充当采访者。Inversion 依赖于显式的、不可协商的门控指令（如"在所有阶段完成之前不要开始构建"）来强制 Agent 先收集上下文。它按顺序提出结构化问题，并等待你的回答后才进入下一阶段。Agent 拒绝综合最终输出，直到它对你的需求和部署约束有了完整的画面。

为什么 Agent 需要被"反转"？

想象你对一个建筑师说"帮我设计一个房子"。一个好的建筑师会先问你：几个人住？预算多少？有没有特殊需求（无障碍、宠物）？喜欢什么风格？而一个糟糕的建筑师会立刻开始画图。

Claude 的默认行为更像后者。它接到指令就开始输出——用一堆假设填充你没有提供的信息。这些假设有时对、有时错，但你永远不确定它假设了什么。

Inversion 模式迫使 Claude 在行动前先提问。它把决策权从模型移交给人。

核心结构

text

inversion-skill/
├── SKILL.md              # 面试流程 + 门控指令
└── references/
    └── question-bank.md  # 结构化问题库（可选）

一个完整的 Inversion 示例：项目规划器

要看到 Inversion 的实际效果，可以参考项目规划器 Skill。

Markdown

---
name: project-planner
description: >
  ALWAYS invoke this skill when the user asks to plan a project, 
  create a roadmap, design a system, or architect a solution.
  Do not start planning directly — use this skill first.
---
# Project Planner
## CRITICAL RULE
DO NOT start building or outputting any plan until ALL phases 
below are complete. You are an interviewer first, a planner second.
## Phase 1: Scope
Ask the user:
1. What problem does this project solve?
2. Who are the primary users/stakeholders?
3. What does "done" look like? (Success criteria)
Wait for answers before proceeding.
## Phase 2: Constraints  
Ask the user:
1. Timeline — is there a hard deadline?
2. Team — who is available? What skills?
3. Budget — any resource constraints?
4. Technical — any required technologies or limitations?
Wait for answers before proceeding.
## Phase 3: Risks
Ask the user:
1. What has failed in similar projects before?
2. What are the biggest unknowns?
3. Are there external dependencies?
Wait for answers before proceeding.
## Phase 4: Synthesis
ONLY after Phase 1-3 are complete, create:
1. Project brief (half-page summary)
2. Milestone plan (phased deliverables)
3. Risk mitigation strategies
4. First two weeks: specific tasks with owners

注意每个阶段末尾的 "Wait for answers before proceeding." ——这是 Inversion 的核心机制。没有这句话，Claude 会自行"脑补"答案然后跳到下一个阶段。

真实案例：Elixir 架构师 Skill

一个 Elixir 架构 Skill 的交互示例——用户说"Create architecture docs for a task management system"，Claude 不直接生成，而是先提问：1. 确认技术栈？2. 项目结构偏好？3. 特殊需求：多租户？实时功能？预期用户量？4. 是否使用 Director/Implementor AI 工作流？

只有在回答完所有问题后，Skill 才启动专家任务代理，执行研究、分析、生成完整的文档包——23 个文件，包含基础文档、5 个 guardrail 文档、8 个架构文档、4 个架构决策记录。

这个案例完美展示了 Inversion 的价值：通过前置 4 个问题，生成的 23 个文件每一个都精确匹配用户的需求。 如果跳过这些问题，Claude 会按默认假设生成——可能选了错误的技术栈、遗漏了多租户需求、或者用了不适合的项目结构。

关键设计原则：门控必须不可协商

Inversion 依赖于显式的、不可协商的门控指令（如"在所有阶段完成之前不要开始构建"）。

"Wait for answers"是建议。"DO NOT proceed until"是命令。在 Inversion 模式中，你需要后者。如果只是"建议"等待，Claude 大概率会自己回答自己的问题然后继续。

门控的最佳实践：

Markdown

## 门控指令的强度梯度
弱（Claude 经常无视）：
  "You may want to ask the user first."
中（偶尔有效）：
  "Wait for answers before proceeding."
强（可靠）：
  "DO NOT start building until all phases are complete.
   If user's answer is unclear, ask a follow-up question.
   NEVER assume or fill in answers yourself."

适用场景

text

✅ 适合 Inversion 的场景：
  - 项目规划和架构设计
  - 需求收集和产品规格编写
  - 复杂配置（部署环境、基础设施）
  - 个性化方案（健身计划、学习路径）
  - 任何"用户不知道自己需要提供什么"的任务
❌ 不适合 Inversion 的场景：
  - 用户已经提供了完整信息的执行任务
  - 紧急的、需要快速响应的操作
  - 有明确标准答案的查询

六、模式 5：Pipeline —— 强制顺序执行

它解决什么问题？

对于复杂任务，你不能容忍跳过步骤或忽略指令。Pipeline 模式通过硬检查点强制执行严格的顺序工作流。指令本身就是工作流定义。通过实施显式的钻石门控条件（如在文档字符串生成到最终组装之间要求用户批准），Pipeline 确保 Agent 不能绕过复杂任务而呈现未经验证的最终结果。

Pipeline 对抗的是 Agent 的"跳步"本能——在多步骤工作流中，确保每一步都被执行、每一个检查点都被经过。

核心结构

text

pipeline-skill/
├── SKILL.md              # 工作流定义 + 门控条件
├── references/
│   ├── docstring-style.md    # Step 2 才加载
│   └── quality-checklist.md  # Step 4 才加载
└── assets/
    └── api-doc-template.md   # Step 3 才加载

这种模式利用所有可选目录，在特定步骤需要时才拉入不同的引用文件和模板，保持上下文窗口干净。

完整示例：文档生成管道

一个文档管道的 SKILL.md：You are running a documentation pipeline. Execute each step in order. Do NOT skip steps. Step 1 解析并清点所有公共类和函数，询问用户确认。Step 2 为每个缺少文档字符串的函数生成文档字符串，加载 references/docstring-style.md 获取格式，逐个展示给用户批准。明确声明：Do NOT proceed to Step 3 until user confirms.

Step 3 组装文档，加载 assets/api-doc-template.md 获取输出结构，编译所有符号为单一 API 参考文档。Step 4 质量检查，针对 references/quality-checklist.md 进行审查：每个公共符号是否有文档、每个参数是否有类型和描述、每个函数是否有至少一个使用示例。报告结果。

注意几个关键设计：

1. 每一步只加载该步需要的文件 → 上下文窗口始终保持精简
2. 步骤之间有人工门控 → "Do NOT proceed until user confirms"
3. 最后一步是质量检查 → Pipeline 内嵌了 Reviewer

Diamond Gate：Pipeline 的核心机制

在这个文档管道示例中，注意显式的门控条件。Agent 被明确禁止在用户确认前一步的生成结果之前进入组装阶段。

"Diamond Gate"（钻石门控）是 Pipeline 的核心概念——在两个步骤之间插入一个需要外部确认的检查点。确认可以来自：

• 用户确认——"Do NOT proceed until user approves"
• 脚本验证——"Run validate.py; if it fails, fix and re-run"
• 自查——"Review your output against the checklist before proceeding"

text

Step 1 ──→ ◇ Gate 1 ──→ Step 2 ──→ ◇ Gate 2 ──→ Step 3 ──→ ◇ Gate 3 ──→ Step 4
           (user OK?)            (script pass?)            (quality OK?)

真实案例：Agile 质量管道

一个生产级的 Claude Code 插件套件使用了 Orchestrator-Worker、prompt chaining、evaluator-optimizer 等模式，核心为四级层次结构（L0→L3），每个 Skill 单一职责。

系统通过自动化审查循环工作：ln-402-task-reviewer 检查每个任务输出，ln-403-task-rework 修复问题并重新提交审查，ln-500-story-quality-gate 运行四级门控（PASS/CONCERNS/REWORK/FAIL），在任何 Story 标记为 Done 之前。代码从不在未通过质量检查的情况下发布。

这是一个完整的生产级 Pipeline：任务执行 → 自动审查 → 修复 → 重新审查 → 质量门控。每一步都有明确的通过/失败标准，而且是机器执行的——不依赖 Agent 的"判断力"。

适用场景

text

✅ 适合 Pipeline 的场景：
  - 文档生成（多步骤，需要中间确认）
  - CI/CD 工作流（构建 → 测试 → 部署）
  - 数据处理管道（验证 → 清洗 → 分析 → 报告）
  - 合规检查流程（多步骤审计）
  - 任何不能跳步的顺序工作流
❌ 不适合 Pipeline 的场景：
  - 不需要顺序的任务
  - 快速迭代的创意工作
  - 步骤之间没有依赖关系的并行任务

七、模式组合 —— 真正的力量

组合才是王道。单一模式能解决的问题有限。真正复杂的生产场景，往往是 Pipeline + Reviewer + Tool Wrapper 的组合拳。

7.1 组合规则

Pipeline Skill 可以在末尾包含 Reviewer 步骤来复查自己的工作。Generator 可以在开头依赖 Inversion 来收集必要的变量，然后再填充模板。

五种模式的组合关系：

text

                    Inversion
                   （前置收集）
                       │
                       ▼
    Tool Wrapper ──→ Pipeline ←── Generator
   （加载知识）     （编排流程）   （模板输出）
                       │
                       ▼
                    Reviewer
                   （后置审查）

组合的逻辑是自然的：

• Pipeline 是骨架 → 定义步骤顺序和检查点
• Inversion 是前奏 → Pipeline 开始前先收集信息
• Tool Wrapper 是补给 → Pipeline 中间步骤需要时才加载知识
• Generator 是产出 → Pipeline 某些步骤的输出需要模板化
• Reviewer 是守卫 → Pipeline 末尾或中间的质量门控

组合遵循问题的逻辑，而非固定层级。

7.2 组合案例 1：Inversion + Generator

场景：生成一份技术方案文档。

text

Phase 1 (Inversion): 收集信息
  → 问题 1：解决什么问题？
  → 问题 2：技术约束？
  → 问题 3：目标受众？
  → 问题 4：交付时间？
Phase 2 (Generator): 基于收集的信息填充模板
  → Load assets/tech-proposal-template.md
  → Load references/writing-guide.md
  → 填充模板，生成文档

这比单独用 Generator 好得多——Generator 单独使用时，Claude 可能会假设错误的技术约束，或者用不匹配目标受众的语调来写。

7.3 组合案例 2：Pipeline + Reviewer + Tool Wrapper

场景：一个完整的代码审查工作流。

text

Step 1 (Tool Wrapper): 加载团队编码规范
  → Load references/team-conventions.md
Step 2 (Pipeline): 执行审查流程
  → 2a. 提取所有变更的文件列表
  → 2b. 对每个文件运行审查
  → 2c. 汇总发现
Step 3 (Reviewer): 用安全清单做二次审查
  → Load references/security-checklist.md
  → 对 Step 2 的输出再做一轮安全审计
Step 4 (Diamond Gate): 用户确认
  → 展示完整审查报告
  → DO NOT approve PR until user confirms

7.4 组合案例 3：完整的研究管道

一个研究项目不是瀑布流——它是依赖图。有些阶段可以并行，有些严格顺序。例如：/research-ideation 和 /interview-me 可以并行运行，结果汇入 /lit-review，然后顺序执行 /data-analysis，最后到 /review-paper。用户可以从中间进入管道。

这个案例展示了一个关键洞察：Pipeline 不一定是完全线性的。 它可以有并行分支和多个入口点。关键是每一步的依赖关系是明确的，检查点是强制的。

7.5 反模式：过度组合

一个常见的错误是在简单任务上堆砌模式。

如果你的 Skill 只是"按照团队规范审查代码"，一个 Reviewer 就够了。不需要在前面加 Inversion（审查什么很明确）、不需要 Pipeline（只有一步）、不需要 Generator（输出格式简单）。

判断标准很简单：每增加一种模式，都应该是因为你能指出它解决的具体问题。 如果你说不出"加这个模式是为了防止 Claude 做 X"，那就不要加。

八、选择框架：一张决策表

当你面对一个新的 Skill 设计任务时，用以下表格快速定位：

text

你的核心需求是什么？                          选择哪种模式？
────────────────────────────────────────────────────────
Claude 需要某个库/框架的知识                 → Tool Wrapper
输出必须遵循固定结构                         → Generator
需要按标准评审输入                           → Reviewer
用户的需求信息不完整                         → Inversion
任务有多步骤且不能跳步                       → Pipeline
────────────────────────────────────────────────────────
以上多个都需要？                             → 组合模式（以 Pipeline 为骨架）
不确定？                                    → 从 Tool Wrapper 开始（最简单）

每种模式回答一个不同的问题：

九、进阶原则：灵活指令 vs 严格指令

在五种模式的基础上，还有一个贯穿所有模式的设计决策：每一条指令应该是灵活的还是严格的？

在多种方法都有效且任务容许变化时，给 Agent 自由度。对于灵活指令，解释"为什么"可能比严格指令更有效——理解指令背后目的的 Agent 能做出更好的上下文相关决策。

一个代码审查 Skill 可以描述要查找什么，而不规定精确步骤：

Markdown

## Code review process
1. Check all database queries for SQL injection
2. Verify authentication checks on every endpoint
3. Look for race conditions in concurrent code paths
4. Confirm error messages don't leak internal details

但在操作脆弱、一致性重要、或必须遵循特定顺序时，要使用严格指令：Run exactly this sequence: python scripts/migrate.py --verify --backup. Do not modify the command or add additional flags.

判断标准：

text

灵活指令：
  - Claude 的判断力可以带来更好的结果
  - 任务允许多种有效方法
  - 解释"为什么"比规定"怎么做"更有效
严格指令：
  - 操作有副作用（删除、部署、发送）
  - 输出必须精确一致（数值计算、格式化）
  - 步骤顺序不可更改（数据库迁移、CI/CD）

每种模式中都可以混合使用灵活和严格指令。比如一个 Pipeline 中，分析步骤可以灵活（Claude 自行决定怎么分析），但验证步骤必须严格（运行指定的脚本，不可修改参数）。

十、常见误区

误区 1：「每个 Skill 都需要一种模式」

不是。很多简单的 Skill——比如"提交信息格式化"——不需要任何架构模式。它只需要一些格式规则和几个输入/输出示例。示例帮助 Claude 比单纯的描述更清晰地理解你想要的风格和细节。当输出质量依赖于风格一致性时，投资写好示例。

模式是工具，不是义务。只在面对特定的结构性问题（上下文膨胀、输出不一致、跳步、瞎猜）时才使用。

误区 2：「Pipeline 就是把所有步骤列出来」

Pipeline 的核心不是步骤列表——是门控条件。没有门控的 Pipeline 和普通的步骤列表没有区别，Claude 照样会跳步。

每两个步骤之间，问自己：Claude 有没有可能跳过或合并这两步？ 如果有——加门控。如果没有（两步之间有真实依赖，比如 Step 2 需要 Step 1 的输出文件）——可以不加。

误区 3：「Inversion 就是加几个问题」

Inversion 不是"在前面加几个问题"——是翻转控制权。如果你的 SKILL.md 写了"Ask the user about X"但没有门控，Claude 可能会问完问题后不等回答就继续，或者干脆自己回答自己的问题。

Inversion 的核心是那句不可协商的门控指令。没有它，Inversion 就退化成了一个"建议性"的提问列表。

误区 4：「模式选择是一次性决策」

模式应该随 Skill 的演进而调整。你可能从 Tool Wrapper 开始，发现需要更一致的输出后加入 Generator，发现需要质量检查后加入 Reviewer。这是正常的演进路径，不是设计失败。

但记住第三篇的核心原则：加复杂度容易，减复杂度难。 所以永远从最简单的模式开始。

十一、你今天就应该做的 3 件事

✅ 行动 1：给你现有的 Skill 归类

打开你已经构建或安装的每一个 Skill，用以下检查表归类：

text

这个 Skill 主要是…
□ 给 Claude 加载某种知识/规范？ → Tool Wrapper
□ 让 Claude 按模板生成文档？   → Generator
□ 让 Claude 按标准审查输入？   → Reviewer
□ 让 Claude 先问再做？         → Inversion
□ 让 Claude 按顺序执行多步骤？ → Pipeline
□ 以上都不是 / 太简单不需要    → 无模式（纯 Pattern A）

如果你发现一个 Skill 混合了多种模式但效果不好，考虑拆分。

✅ 行动 2：为一个现有 Skill 添加 Reviewer 步骤

选一个你最常用的 Skill，在末尾添加一个"自审查"步骤：

Markdown

## Final Check
Before presenting the output:
1. Load `references/quality-checklist.md`
2. Check your output against each criterion
3. If any criterion fails, fix and re-check
4. Only present the output when all criteria pass

创建对应的 quality-checklist.md，列出 3-5 条你最关心的质量标准。

✅ 行动 3：在你下一个 Skill 中尝试 Inversion

下次你要构建一个新 Skill 时，先问自己：Claude 开始执行前，是否有可能做出错误的假设？ 如果是——在 Skill 的开头加入一个 Inversion 阶段。只需要 3-5 个结构化问题 + 一句"DO NOT proceed until all questions are answered"。

然后对比：有 Inversion 和没有 Inversion 时，输出质量的差距。大多数情况下，这个差距会让你惊讶。

本文的知识框架总结

text

五种架构模式
│
├── 共同对抗的敌人：Agent 的三个本能
│   ├── 爱猜 → Inversion
│   ├── 爱跳步 → Pipeline + Reviewer
│   └── 爱一次性输出 → Generator + Tool Wrapper
│
├── 五种模式
│   ├── Tool Wrapper：按需加载知识（最简单）
│   ├── Generator：模板化输出（结构一致性）
│   ├── Reviewer：可替换的审查引擎（质量保证）
│   ├── Inversion：先问再做（翻转控制权）
│   └── Pipeline：强制顺序执行（门控检查点）
│
├── 组合原则
│   ├── Pipeline 是骨架
│   ├── Inversion 是前奏
│   ├── Tool Wrapper 是补给
│   ├── Generator 是产出
│   ├── Reviewer 是守卫
│   └── 组合遵循问题的逻辑，非固定层级
│
├── 灵活 vs 严格
│   ├── 灵活：解释"为什么"，给 Agent 判断空间
│   └── 严格：规定"怎么做"，用于脆弱/精确操作
│
└── 核心原则
    ├── 格式已死，设计永生
    ├── 好的设计 = 好的约束
    ├── 每增加一种模式都要有明确理由
    └── 从最简单的模式开始

下一篇预告

四篇文章走下来，你已经掌握了 Skill 的设计和构建。但有一个贯穿所有篇章的隐含主题还没有被正面回答：

Claude 的上下文窗口是最稀缺的资源——你到底应该怎么管理它？

第 5 篇将深入 Context Engineering，从理论框架到实操方法，回答一个核心问题：如何在有限的上下文空间中放入最高信号的信息，让 Claude 的每一个 token 都发挥最大价值。这不只是 Skill 的话题——它是整个 AI 工程的核心学科。

本文是「Claude Code Skills 完全指南」系列的第 4 篇，共 10 篇。全系列目录：

请点击了解详情 →