从零构建一个生产级 Skill：三种设计模式的选择与实战

这是「Claude Code Skills 完全指南」系列的第三篇。建议先阅读第一篇《Skill 的本质》和第二篇《Description 设计的科学》再继续。

写在前面

前两篇文章解决了两个问题：Skill 是什么（一种通过渐进式披露注入上下文的机制），以及如何让 Skill 被触发（通过精心设计的 description 字段）。

接下来这个问题是不可避免的：

Skill 触发之后，里面的内容应该怎么写？

更准确地说：你面对一个真实的工作任务，决定为它构建一个 Skill。你打开一个空白的 SKILL.md 文件——然后呢？该写什么？该不该带脚本？该不该调 MCP？如何把你脑子里的知识转化为 Claude 能执行的指令？

这篇文章不是理论分析。它是一次从零到一的完整构建记录。

我会带你经历一个真实 Skill 从设计到交付的全过程——用例定义、模式选择、SKILL.md 编写、测试、失败、迭代、再测试——直到它通过评测。在这个过程中，你会自然地理解三种设计模式各自的适用场景，以及选择它们的决策逻辑。

一、不要从 SKILL.md 开始

这是我要传达的第一个、也是最重要的观点。

第一次直接写 SKILL.md 时会遇到问题。 如果 description 设计不好，Skill 甚至不会触发。

但 description 设计不好只是最表层的症状。更深层的问题是：你没有在写代码之前花时间设计。

官方最佳实践的建议是：先创建评测，构建三个测试差距的场景，建立基线，度量没有 Skill 时 Claude 的表现，然后写最少的指令——创建刚好足够弥补差距和通过评测的内容，最后迭代。这种方法确保你解决的是真实问题。

这听起来很"工程化"，但它能让你避免一个极其常见的错误：花三小时写了一个精美的 Skill，结果发现 Claude 不用 Skill 也能把这件事做得差不多好。

正确的起点是三个问题：

问题 1：我到底在解决什么具体问题？

不是"我想做一个有用的 Skill"。而是你在实践中观察到的真实重复性工作。

一位开发者分享了他的起点：他注意到许多同事和他自己在重复做相同的月度和季度业务回顾。在电商和零售行业，分解 KPI 的过程倾向于遵循类似模式。那是起点。他没有构建一个通用的"数据分析 Skill"，而是定义为："一个接收订单 CSV 数据、将 KPI 分解为树状结构、总结发现与优先级并生成具体行动计划的 Skill。"

这里有一个关键的方法：先想象用户实际会怎么说。他列出了几个具体的请求："run a review of my store using this orders.csv"；"analyze last 90 days of sales data, break down why revenue dropped"；"compare Q3 vs Q4, find the top 3 things I should fix"。当你先写出这些具体的提示，Skill 的形状就会变得清晰。

问题 2：没有 Skill 时 Claude 做得多差？

编码代理本身已经是非常好的问题解决者。如果你把任务设计得太对抗性或太复杂，你面临的风险是在测试代理的解决能力而不是你的 Skill。基于你在代理中观察到的真实失败来设定任务会更有效。

具体做法：在没有 Skill 的情况下，让 Claude 跑一遍你定义的 2-3 个用例。 记录它哪里做得好、哪里做得不好。如果它做得足够好——恭喜，你不需要构建这个 Skill。

这是大多数 Skill 创作者从不问的问题：这个 Skill 真的比直接问 Claude 好吗？模型更新后，曾经有用的 Skill 可能变得多余——基础模型现在能够足够好地处理该任务。A/B 基准测试可以发现这一点。

问题 3：Gap 在哪里？

你现在有了"无 Skill 基线"的记录。你观察到的具体差距可能是：

• Claude 缺少你的业务上下文（不知道你的 KPI 定义、公司术语）
• Claude 流程不一致（有时分析深入，有时走过场）
• Claude 缺少某种工具能力（不能做精确计算、不能调 API）

每种差距类型对应不同的设计模式。 这就是选择 Pattern A/B/C 的真正依据。

二、三种设计模式：决策树

选择模式的顺序是：需要与外部 API 实时通信？→ 是 → Pattern C。需要确定性处理如计算、验证或文件转换？→ 是 → Pattern B。Claude 的语言能力和判断力可以独立处理？→ 是 → Pattern A。当犹豫不决时，从 Pattern A 开始。后续很容易添加脚本演进为 Pattern B。但简化一个过于复杂的 Skill 更难。

这段话来自 Anthropic 的官方指南，但大多数人只是"读过"它，并没有真正理解每种模式为什么适合特定场景。让我深入拆解。

Pattern A：纯 Markdown

它是什么

最简单的模式。仅 Markdown 指令，无脚本。适用于：品牌指南、编码标准、审查清单、提交信息格式化、写作风格规范。使用条件：Claude 的语言能力和判断力足以胜任任务。

一个完整的 Pattern A 示例

官方提供了一个 commit-message-formatter 示例。SKILL.md 的 frontmatter 是 name: commit-message-formatter，description 是 "Format git commit messages using Conventional Commits. Use when user mentions commit, git message, or asks to format/write a commit message."正文是格式规则、规范和输入/输出示例。就这样，没有脚本，没有依赖。

什么时候选 Pattern A？

当你的 Gap 分析显示：Claude 能做每一步，只是做得不够一致。比如它会写提交信息，但有时用过去时、有时漏掉 scope、有时写太长。这种情况下你需要的不是新能力，而是约束和标准——Pattern A 的主场。

示例有助于 Claude 比单纯的描述更清晰地理解你想要的风格和细节。当输出质量依赖于风格一致性时，投资写好示例。

这引出了 Pattern A 设计的一条核心原则：

用输入/输出示例代替抽象描述。 Claude 从具体例子中学到的比从规则陈述中学到的更多。

Pattern A 的陷阱

Pattern A 最常见的失败模式是：你写了一大堆规则，但 Claude 只遵循了其中 60%。这通常不是因为规则写得不好，而是因为规则太多了。

CLAUDE.md 在每个会话都加载，所以只包含广泛适用的内容。对于只在特定时候才相关的领域知识或工作流，改用 Skills——Claude 按需加载它们，不会膨胀每次对话。

同理，SKILL.md 的正文也应该精炼。对于每一行，问自己："删除它会导致 Claude 犯错吗？"如果不会，删掉它。

Pattern B：Markdown + 脚本

它是什么

SKILL.md 包含工作流指令，scripts/ 目录包含可执行脚本。SKILL.md 定义"何时与为何"，脚本处理"如何"。

一个完整的 Pattern B 示例

Skills 可以捆绑和运行任何语言的脚本，赋予 Claude 超越单个提示所能实现的能力。一种强大的模式是生成可视化输出：交互式 HTML 文件可在浏览器中打开，用于探索数据、调试或创建报告。

官方文档提供了一个 codebase-visualizer 的 Pattern B 示例。创建 ~/.claude/skills/codebase-visualizer/SKILL.md。description 告诉 Claude 何时激活，指令告诉 Claude 运行捆绑的脚本：name: codebase-visualizer，description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.

SKILL.md 正文中引用了一个 131 行的 Python 脚本。测试时，在任何项目中打开 Claude Code 并说"Visualize this codebase"。Claude 运行脚本，生成 codebase-map.html 并在浏览器中打开。这种模式适用于任何可视化输出：依赖关系图、测试覆盖率报告、API 文档或数据库 schema 可视化。捆绑脚本处理繁重的工作，Claude 负责编排。

另一个 Pattern B 的实战结构——电商数据分析 Skill 的工作流：

工作流：1. 用户上传 CSV 或 Excel 文件 2. 运行 scripts/validate_schema.js 检查列结构 3. 如果验证通过，用文件路径运行 scripts/analyze.py 4. 展示带可视化的结果 5. 如果验证失败，要求用户澄清列映射。

什么时候选 Pattern B？

当你的 Gap 分析显示：Claude 在某些步骤上需要确定性——精确计算、格式验证、文件解析、数据转换。这些任务不能容忍"差不多对"，必须精确。让 Claude 做加法有时会出错，但一个 Python 脚本永远不会。

保持每个 Skill 聚焦于一个工作。除非你需要确定性行为或外部工具，否则优先使用指令而非脚本。

这条建议的含义是：脚本不是默认选择，而是有明确理由时的升级路径。 只有当你能指出"这一步必须精确"时，才把它放到脚本里。

Pattern B 的关键设计原则

寻找测试用例中的重复工作。阅读测试运行的日志，注意子代理是否都各自独立地编写了类似的辅助脚本或采取了相同的多步骤方法。如果所有 3 个测试用例都导致子代理编写了 create_docx.py 或 build_chart.py，这是一个强信号：Skill 应该捆绑那个脚本。

换句话说：不要提前预设哪些步骤需要脚本。先用 Pattern A 跑几次，观察 Claude 反复重写什么工具——那就是应该脚本化的部分。

Pattern B 的目录结构

推荐结构是：skill-name/ 下包含 SKILL.md（入口点，必需，< 500 行）、docs/（参考文档，含 CLI-REFERENCE.md、CONCEPTS.md、EXAMPLES.md）、workflows/（操作流程）、scripts/（可执行辅助脚本）和 templates/（可复用模板）。

Pattern C：MCP / 子代理

它是什么

这种模式从 Skill 的工作流中调用 MCP 服务器或子代理。适用于涉及外部服务的工作流——如创建 Issue → 创建分支 → 修复代码 → 打开 PR。更多活动部件意味着更多需要调试的东西，所以建议先熟悉 Pattern A 或 B。

什么时候选 Pattern C？

当你的 Gap 分析显示：工作流需要跨系统协调——读 Gmail、写 Google Sheets、查 Sentry 错误、创建 Linear ticket。这些操作超出了 Claude 的原生能力，需要通过 MCP 连接外部系统。

Skill、MCP 和子代理的定位分别是：Skills 教 Claude 如何行事——分析工作流、编码标准、品牌指南。MCP 服务器给 Claude 新工具——发送 Slack 消息、查询数据库。子代理让 Claude 在独立上下文中运行任务。一个有用的类比：MCP 是厨房——刀、锅、食材。Skill 是告诉你如何使用它们的食谱。两者可以组合。Sentry 的代码审查 Skill 在 Skill 中定义 PR 分析工作流，并通过 MCP 获取错误数据。但很多情况下，单独一个 Skill 就足够开始了。

Pattern C 的风险

随着 MCP 使用规模扩大，工具定义会使上下文窗口过载，中间工具结果会消耗额外 token。工具定义通常直接加载到上下文中。GitHub MCP 服务器为例，有 35 个工具、约 26,000 token 的工具定义。如果工具有重叠功能，还可能让模型困惑。

这就是为什么 Anthropic 反复强调"从 Pattern A 开始"。Pattern C 引入的复杂度不是线性增长，而是指数增长——每多一个外部依赖，调试和维护的成本都会翻倍。

三种模式的选择总结

text

你的 Skill 需要什么？              →  选择
─────────────────────────────────────────────
Claude 做得到，只是不够一致         →  Pattern A（纯 Markdown）
某些步骤必须精确/确定性处理          →  Pattern B（Markdown + 脚本）
需要连接外部系统                   →  Pattern C（MCP / 子代理）

模式的演化路径（单向的）：
A → B → C（容易添加复杂度）
C → B → A（很难移除复杂度）

所以：永远从 A 开始。

三、实战：从零构建一个电商 KPI 分析 Skill

接下来，我将用一个完整的案例来展示从设计到交付的全过程。

3.1 第一步：用例定义

还记得那位电商开发者的起点吗？他注意到每月的业务回顾是重复性工作。我用同样的方法论来定义我的 Skill。

我的观察：我和团队每月都要用 CSV 订单数据做业务复盘。每次都重复同样的步骤：导入数据 → 计算 KPI → 拆解变化原因 → 写行动建议。

用例定义（2-3 个具体场景）：

text

用例 1："用这个 orders.csv 做一次月度业务回顾"
  → 输入：CSV 文件
  → 输出：KPI 树状图 + 关键发现 + 行动计划

用例 2："分析过去 90 天的销售数据，拆解为什么收入下降了"
  → 输入：CSV 文件 + 时间范围
  → 输出：归因分析 + 根因 + 优先级建议

用例 3："对比 Q3 和 Q4，找出需要改进的前 3 件事"
  → 输入：两个时间段的数据
  → 输出：对比报告 + Top 3 行动项

3.2 第二步：基线测试（无 Skill）

在构建任何东西之前，我先让 Claude 不用 Skill 来完成用例 1。

我观察到的具体问题：

text

✅ Claude 能读取 CSV 文件
✅ Claude 能计算基础 KPI（收入、订单量、客单价）
❌ KPI 拆解不一致——有时做到二级，有时只做一级
❌ 数值计算偶尔出错（百分比变化计算不精确）
❌ 输出格式每次不一样——有时用表格，有时用列表
❌ 没有行动建议的优先级排序
❌ 不了解电商特有的 KPI 定义（如 AOV、复购率、LTV）

3.3 第三步：Gap 分析与模式选择

基于上述观察，我的 Gap 分为三类：

结论：Pattern B——核心是 Markdown 指令保证流程一致性，加一个 Python 脚本保证数值计算精确。

为什么不是 Pattern A？因为百分比计算、同环比分析这类操作需要确定性——Claude 做数学偶尔会出错，而 Python 永远不会。

为什么不是 Pattern C？因为数据来自用户上传的本地 CSV 文件，不需要连接外部系统。

3.4 第四步：编写 SKILL.md

Frontmatter

基于第 2 篇的五层框架设计 description：

YAML

---
name: ecommerce-review
description: >
  ALWAYS invoke this skill when the user asks to analyze e-commerce 
  order data, run a monthly/quarterly business review, or break down 
  sales KPIs from CSV or Excel files. 
  Triggers include: "business review", "revenue analysis", "KPI breakdown",
  "orders.csv", "sales data", "why revenue dropped", "compare Q3 vs Q4",
  "GMV", "AOV", "conversion rate", "retention", "churn".
  Do not analyze sales data directly — use this skill first.
  Do NOT use for general data analysis unrelated to e-commerce orders.
---

分解一下：

• 指令式语态 → "ALWAYS invoke"
• 具体触发词 → 从用例定义中提取的用户实际措辞
• 负面约束 → "Do not analyze sales data directly"
• 边界排除 → "Do NOT use for general data analysis"

正文结构

在描述工作流之前，先给模型做定位。识别你产品中的核心对象、关键配置文件或主要入口点。这给了代理一个系统的心智地图，然后再开始行动。LLM 在先理解结构、再执行动作时表现更好。

基于这条原则，SKILL.md 正文按以下顺序组织：

Markdown

# E-commerce Business Review Skill

## Domain Context

E-commerce KPI definitions for this skill:
- **GMV** (Gross Merchandise Volume): Total transaction value before returns
- **AOV** (Average Order Value): GMV / number of orders
- **Repeat Rate**: Orders from returning customers / total orders
- **Revenue = GMV × (1 - Return Rate) × (1 - Discount Rate)**

## Workflow

### Step 1: Data Validation
Run `scripts/validate_and_compute.py --validate <file_path>` to verify:
- Required columns exist: order_id, date, customer_id, amount
- No critical null values in required columns
- Date range is parseable

If validation fails, ask user to clarify column mapping.

### Step 2: KPI Computation
Run `scripts/validate_and_compute.py --analyze <file_path>` to compute:
- All KPI metrics with exact decimal precision
- Period-over-period changes (MoM, QoQ, YoY)
- Statistical summaries

**IMPORTANT**: Use ONLY the script output for numerical values. 
Do not recalculate or estimate any numbers yourself.

### Step 3: KPI Tree Decomposition
Using the computed values from Step 2, build a KPI tree:

Revenue ├── Order Volume │ ├── New Customer Orders │ └── Returning Customer Orders (→ Repeat Rate) ├── Average Order Value │ ├── Items per Order │ └── Average Item Price └── Return Rate

text

For each node, annotate: current value, change vs prior period, 
and whether the change is positive/negative for the business.

### Step 4: Root Cause Analysis
Identify the top 3 KPIs with the largest negative change.
For each, explain:
1. What happened (data-driven observation)
2. Likely causes (business context reasoning)
3. Potential actions

### Step 5: Action Plan
Present exactly 3 prioritized recommendations:
- Priority 1 (Quick Win): Lowest effort, highest impact
- Priority 2 (Strategic): Medium effort, high impact
- Priority 3 (Foundation): High effort, long-term impact

For each, specify: what to do, expected impact, timeline.

## Output Format

Always use this exact structure:
1. **Executive Summary** (3 sentences max)
2. **KPI Dashboard** (table format)
3. **KPI Tree** (ASCII art, annotated)
4. **Root Cause Analysis** (top 3 issues)
5. **Action Plan** (3 prioritized recommendations)

## Gotchas
- If date column has mixed formats, validate_and_compute.py 
  will normalize them. Trust its output.
- If the dataset has < 100 orders, warn the user that statistical 
  significance is limited.
- Never round percentages yourself. The script provides exact values.

关于 Gotchas 部分

你的 Skill 文件不应只描述能做什么——还应该定义限制。包含一个简短的部分来说明不支持的操作、配置冲突、环境约束或已知的失败模式。负面约束对 LLM 非常有力，可以减少那些需要人工审查才能发现的细微错误。

Gotchas 部分是区分"能用的 Skill"和"好用的 Skill"的关键。它编码了你的踩坑经验——每一条都是你（或你的用户）曾经真实遇到过的问题。

关于脚本

scripts/validate_and_compute.py 是一个约 80 行的 Python 脚本，做两件事：

1. --validate 模式：检查 CSV 列结构和数据完整性
2. --analyze 模式：用 pandas 计算所有 KPI 指标，输出 JSON

为什么用脚本而不是让 Claude 自己算？因为 SKILL.md 中有一条关键指令："Use ONLY the script output for numerical values. Do not recalculate or estimate any numbers yourself." 这确保了数值的确定性。

3.5 第五步：测试与迭代

评测体系

构建 Skill 时有两个不同的东西要做对：1. 输出质量——假设 Skill 被激活了，它给出的答案好吗？2. 触发精度——Claude 真的在该激活时激活了 Skill 吗？

这意味着你需要两套测试，而不是一套。

触发精度测试（应触发 / 不应触发）：

text

✅ 应触发：
  "用这个 orders.csv 做月度回顾"         → 触发  ✅
  "revenue dropped 15%, analyze why"      → 触发  ✅
  "compare Q3 vs Q4 sales"               → 触发  ✅
  "算一下我的 GMV 和 AOV"                → 触发  ✅

❌ 不应触发：
  "分析这个用户行为 CSV"                  → 未触发 ✅
  "帮我写一个 Python 数据分析脚本"         → 未触发 ✅
  "这个 JSON 数据有什么规律"              → 未触发 ✅

输出质量测试：

用真实测试数据运行完整工作流。检查输出质量、API 错误率和 token 消耗，与基线对比。将相同任务在有 Skill 和无 Skill 的条件下分别运行。统计消息数、API 调用数、token 数以及用户需要纠正或重新引导 Claude 的频率。

第一轮测试的失败

我的第一版 Skill 在测试中暴露了三个问题：

问题 1：Claude 跳过了脚本，自己算

尽管 SKILL.md 中写了"Use ONLY the script output"，Claude 在第一轮测试中有 2/5 的概率跳过脚本，直接用自己的推理来估算数字。

修复：在 Step 2 中加入更强的约束——"You MUST run the script. Do NOT proceed to Step 3 until you have the script's JSON output. If the script fails, report the error to the user instead of estimating."

来自 skill-creator 的智慧——如果你发现自己在用全大写写 ALWAYS 或 NEVER，或使用超级僵硬的结构，那是一个黄旗。如果可能的话，重新组织并解释推理，让模型理解为什么你要求的东西很重要。这是一种更人性化、强大和有效的方法。

这条建议很有道理——理想情况下应该解释"为什么"而非命令。但在这个具体场景中，数值精确性是不可协商的，所以保留了强约束。关键是为约束提供理由：我在指令后加了一句"Reason: LLM arithmetic is occasionally imprecise; the script guarantees exact values."

问题 2：KPI 树的深度不一致

有时 Claude 拆解到三级（Revenue → Order Volume → New vs Returning），有时只到一级（Revenue → 各组成部分）。

修复：在 Step 3 中，把 KPI 树的结构从"示例"改为"必须遵循的模板"。用 ASCII 图完整画出每一级的节点，不留模糊空间。

问题 3：行动计划太泛

Claude 的建议经常是"提升用户体验"、"优化营销策略"这种正确但无用的废话。

修复：在 Step 5 中加入约束——"Each recommendation must reference a SPECIFIC KPI from the analysis. Bad: 'Improve customer experience.' Good: 'Increase repeat rate from 23% to 30% by implementing a post-purchase email sequence targeting first-time buyers.'"

迭代方法论

最有效的 Skill 开发过程涉及 Claude 本身。与一个 Claude 实例（"Claude A"）合作创建 Skill，然后由另一个实例（"Claude B"）来使用。Claude A 帮助你设计和精炼指令，而 Claude B 在真实任务中测试它们。这之所以有效，是因为 Claude 模型既理解如何编写有效的代理指令，也理解代理需要什么信息。

具体的迭代流程：

text

第 1 轮：写初稿 → Claude B 测试 → 发现 3 个问题
第 2 轮：用 Claude A 讨论修复方案 → 更新 SKILL.md → Claude B 再测试
                                                    → 问题 1 修复 ✅
                                                    → 问题 2 修复 ✅
                                                    → 问题 3 部分修复 ⚠️
第 3 轮：针对问题 3 加入更具体的示例 → Claude B 再测试
                                    → 全部通过 ✅

迭代时注意 Claude 实际如何使用 Skill。观察：意外的探索路径——Claude 读取文件的顺序是否出乎你的预料？这可能表明你的结构不如你想的那么直观。遗漏的关联——Claude 是否没能跟随对重要文件的引用？你的链接可能需要更明确。对某些部分的过度依赖——如果 Claude 反复读取同一个文件，考虑是否应将该内容放到主 SKILL.md 中。

A/B 基准测试

最后的验证：Skill 版本 vs 无 Skill 基线的对比。

判断标准：Skill 版本赢 70% 以上——Skill 明显有帮助，保留。Skill 赢 50-70%——改进有限，Skill 可能需要完善或在最新模型更新后已不必要。Skill 赢不到 50%——Skill 在损害性能，原始 Claude 做得更好。移除或重写。

我的结果：在 5 个测试场景中，Skill 版本在 4 个上明显更好（KPI 拆解更完整、数值更准确、行动建议更具体），1 个持平。通过率 80%——保留。

四、SKILL.md 正文的编写原则

通过上述实战，我提炼出 SKILL.md 正文编写的六条核心原则。

原则 1：先结构，后行动

在描述工作流之前，先给模型做定位。识别你系统中的核心对象、关键配置文件或主要入口点。这给了代理一个心智地图，然后再开始行动。LLM 在先理解结构、再执行动作时表现更好。

在电商 Skill 中，"Domain Context"部分就是做这件事——先教 Claude 什么是 GMV、AOV、复购率，再告诉它怎么分析。

原则 2：避免抽象描述，用具体步骤

避免抽象的功能描述。而是描述如何一步步完成真实任务。如果工作流需要特定顺序，直接声明顺序。如果需要权限、前置条件或环境设置，明确列出。

坏写法：

Markdown

## Analysis
Analyze the data and provide insights.

好写法：

Markdown

## Step 3: KPI Tree Decomposition
Using the computed values from Step 2, build a KPI tree:
[完整的 ASCII 模板]
For each node, annotate: current value, change vs prior period,
and whether the change is positive/negative for the business.

原则 3：用 if/then 代替模糊判断

简短的"如果/那么"指导可以显著提高一致性。例如：如果任务需要顺序步骤，遵循有序流程；如果存在替代方案，清晰地呈现选项。这些轻量级规则帮助 LLM 正确选择而非猜测。

在 Skill 中：

Markdown

If dataset has < 100 orders → warn user about statistical significance
If date column has mixed formats → trust script normalization output
If script returns error → report error to user, do not estimate values

原则 4：输入/输出示例胜过千言万语

在 SKILL.md 中包含：何时使用、如何运行、预期输出和 Gotchas。添加明确的路由指导："Use when…" vs "Don't use when…"以及几个关键边界案例。包含负面示例（何时不应触发）和正面示例一起使用，以提高路由准确性。

原则 5：保持 SKILL.md 精炼，详细内容放 references/

SKILL.md 应控制在 500 行以内，详细文档放在 references/ 目录中。

如果你的电商 KPI 定义需要两页来解释，不要全塞进 SKILL.md。创建 references/kpi-definitions.md，在 SKILL.md 中用一句话引用："See references/kpi-definitions.md for detailed KPI calculation formulas."

Claude 只在需要时才会读取引用文件，这正是渐进式披露的价值。

原则 6：编写 Gotchas——最高信号内容

Gotchas 部分记录 Claude 的已知失败点。不是写显而易见的内容，而是聚焦于那些推动 Claude 偏离默认行为的信息。

每次测试中发现的问题，都应该进入 Gotchas。它是一个随时间增长的"踩坑记录"：

Markdown

## Gotchas
- Claude will sometimes skip the validation script and estimate values.
  → ALWAYS run the script first.
- If the CSV has a "revenue" column, Claude may use it directly instead 
  of computing Revenue = GMV × (1 - Return Rate) × (1 - Discount Rate).
  → Ignore any pre-computed "revenue" column; calculate from components.
- Action plans tend toward vague recommendations when data is ambiguous.
  → Every recommendation MUST reference a specific KPI number.

五、完整的 Skill 构建 SOP

将上述所有步骤凝练为一个可复用的 SOP：

text

阶段 1：定义（占总时间 30%）
┌──────────────────────────────────────────────┐
│ 1a. 观察重复任务，定义 2-3 个具体用例          │
│ 1b. 为每个用例写出用户可能说的话               │
│ 1c. 无 Skill 基线测试，记录 Claude 的具体差距  │
│ 1d. Gap 分析 → 选择 Pattern（A / B / C）      │
└──────────────────────────────────────────────┘
            ↓
阶段 2：构建（占总时间 30%）
┌──────────────────────────────────────────────┐
│ 2a. 用五层框架写 description                  │
│ 2b. 正文按：Domain Context → Workflow →       │
│     Output Format → Gotchas 顺序组织          │
│ 2c. 如选 Pattern B，编写脚本处理确定性步骤     │
│ 2d. SKILL.md 控制在 500 行以内                │
└──────────────────────────────────────────────┘
            ↓
阶段 3：测试（占总时间 30%）
┌──────────────────────────────────────────────┐
│ 3a. 触发精度测试：10 个应触发 + 5 个不应触发   │
│ 3b. 输出质量测试：用真实数据跑完整流程          │
│ 3c. A/B 对比：Skill vs 无 Skill 基线          │
│ 3d. 目标：触发率 ≥ 90%，A/B 胜率 ≥ 70%        │
└──────────────────────────────────────────────┘
            ↓
阶段 4：迭代（占总时间 10%，但会反复进行）
┌──────────────────────────────────────────────┐
│ 4a. 分析失败案例，归类到三种问题：              │
│     不触发 / 输出质量差 / 误触发               │
│ 4b. Claude A 讨论修复方案 → 更新 SKILL.md     │
│ 4c. Claude B 重新测试 → 记录改进               │
│ 4d. 更新 Gotchas 部分                         │
└──────────────────────────────────────────────┘

最有效的 Skill 构建者在一个具有挑战性的任务上反复迭代直到 Claude 成功，然后将获胜的方法提取为 Skill。

这是一个反直觉但极其实用的策略：不是先写 Skill 再测试，而是先在无 Skill 的条件下与 Claude 反复调试同一个任务，找到让它成功的提示模式，然后把这些模式固化为 Skill。

六、Skill 的生命周期管理

构建完成不是终点。Skills 是活文档。从发布开始计算，一个 Skill 还需要经历三个生命阶段。

阶段 1：观察期（发布后 1-2 周）

在真实使用中密切观察 Skill 的表现。关注以下信号：

• Claude 是否按预期触发？（还是经常需要手动 /skill-name？）
• 用户是否需要额外的纠正或补充提示？
• 有没有新的边界案例暴露出来？

每个新发现的问题都进入 Gotchas 部分。

阶段 2：稳定期

Skill 进入日常使用。定期做两件事：

这可以防止 Skill 退化——随着基础模型改进，Skills 逐渐变得过时的现象。

定期验证：每次 Claude 模型大版本更新后，重新跑一遍 A/B 基准测试。如果基线已经赶上或超过了 Skill 的表现，这个 Skill 可能需要更新或退役了。

能力提升型 Skill 帮助 Claude 做基础模型做不到或做不一致的事情。但随着模型进步，这些 Skill 可能变得不必要。编码偏好型 Skill 更持久，但其价值取决于它对你实际工作流的忠实程度。评测验证的就是这种忠实度。

阶段 3：演进或退役

Skill 有三种可能的结局：

• 演进：从 Pattern A 升级到 B（添加脚本处理新的确定性需求）
• 拆分：一个 Skill 变得太大，拆成多个聚焦的 Skill
• 退役：基础模型已经内化了这个能力，Skill 不再提供增量价值

这是大多数 Skill 创作者从不问的问题：这个 Skill 真的比直接问 Claude 好吗？模型更新后，曾经有用的 Skill 可能变得多余。

不要舍不得。一个过时的 Skill 留在环境中不是零成本——它占据 description 预算，可能干扰其他 Skill 的触发。

七、常见误区

误区 1：「先写脚本再想 Skill」

很多有编程背景的人会本能地从脚本开始。但 Skill 的核心不是脚本，是编排——告诉 Claude 什么时候做什么、以什么顺序、用什么标准判断。脚本只是编排中某些步骤的"执行工具"。

正确的顺序永远是：先定义工作流 → 再决定哪些步骤需要脚本 → 最后写脚本。

误区 2：「一个 Skill 解决所有问题」

保持每个 Skill 聚焦于一个工作。

如果你发现一个 Skill 的正文超过 300 行，或者它处理的用例超过 3 个，几乎可以肯定应该拆分。

误区 3：「正文里什么都写」

一个常见错误是把所有领域知识、所有规则、所有案例都塞进 SKILL.md 正文。臃肿的文件会导致 Claude 忽略你的实际指令。如果 Claude 在有规则的情况下仍然做你不想要的事，文件可能太长了，规则被淹没了。

正文只放过程（步骤），知识放 references/，示例放 examples/。

误区 4：「不做评测就发布」

自从去年 10 月发布 Agent Skills 以来，Anthropic 注意到大多数作者是领域专家而非工程师。他们了解自己的工作流，但没有工具来判断 Skill 是否仍然适用于新模型、是否在该触发时触发、或者编辑后是否真的有改进。

无论如何，测试将一个"看起来能用"的 Skill 变成一个你"知道能用"的 Skill。

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

✅ 行动 1：选择你的第一个 Skill 候选任务

回顾过去一周，找到一个你在 Claude Code 中重复做了至少 3 次的任务。问自己：

• 我能定义 2-3 个具体用例吗？
• 我能写出用户实际会说的话吗？
• 没有 Skill 时 Claude 的表现差在哪里？

如果三个问题都有清晰的答案，这就是你的第一个 Skill 候选。

✅ 行动 2：做一次无 Skill 基线测试

不要急着动手写。先在没有 Skill 的条件下让 Claude 完成你定义的用例。详细记录：

text

✅ Claude 做得好的部分：_________
❌ Claude 做得差的部分：_________
🔍 差距类型：
  □ 一致性问题（做得到但不稳定）→ Pattern A
  □ 精确性问题（计算/验证需要确定性）→ Pattern B
  □ 外部连接需求（需要调 API/服务）→ Pattern C

✅ 行动 3：写一个最简 Pattern A 版本

即使你最终需要 Pattern B，也从 A 开始。写一个只有 frontmatter + 50 行正文的最简 Skill，用 2-3 个测试提示跑一遍。

当犹豫不决时，从 Pattern A 开始。后续很容易添加脚本演进为 Pattern B。但简化一个过于复杂的 Skill 更难。

如果 Pattern A 已经让 A/B 胜率达到 70%——停下来，你不需要 Pattern B。 只有当你能明确指出"这一步必须精确"时，才升级。

本文的知识框架总结

text

从零构建一个生产级 Skill
│
├── 构建流程（不要从 SKILL.md 开始）
│   ├── 第 1 步：定义 2-3 个具体用例
│   ├── 第 2 步：无 Skill 基线测试
│   ├── 第 3 步：Gap 分析 → 模式选择
│   ├── 第 4 步：编写 SKILL.md（description + 正文 + 脚本）
│   └── 第 5 步：双维测试（触发精度 + 输出质量）+ A/B 对比
│
├── 三种设计模式
│   ├── Pattern A：纯 Markdown → Claude 能做但不一致
│   ├── Pattern B：Markdown + 脚本 → 某些步骤需要确定性
│   └── Pattern C：MCP / 子代理 → 需要连接外部系统
│   └── 演化方向：A → B → C（单向，容易加复杂度，难以减）
│
├── SKILL.md 正文六原则
│   ├── 1. 先结构后行动（Domain Context → Workflow）
│   ├── 2. 具体步骤代替抽象描述
│   ├── 3. if/then 代替模糊判断
│   ├── 4. 输入/输出示例胜过千言万语
│   ├── 5. 正文精炼，详细内容放 references/
│   └── 6. Gotchas 是最高信号内容
│
├── 迭代方法论
│   ├── Claude A（设计者）+ Claude B（测试者）
│   ├── 观察 Claude B 的真实行为，不猜测
│   └── 每个发现的问题 → Gotchas 部分
│
└── 生命周期管理
    ├── 观察期（发布后 1-2 周）
    ├── 稳定期（定期 A/B 验证）
    └── 演进或退役（模型更新后重新评估）

下一篇预告

你现在知道了三种模式怎么选、SKILL.md 怎么写。下一个问题更精细：SKILL.md 正文的"内容"应该按什么架构组织？

第 4 篇将介绍从 Anthropic、Vercel、Google 等公司的实践中提炼的五种架构模式——Tool Wrapper、Reviewer、Pipeline、Inversion、Generator。每种模式解决不同类型的任务，而且它们可以组合。理解这五种模式，你就能为任何类型的工作任务设计出合适的 Skill 架构。

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