Claude Code Skills：打造你的专属 AI 工作流 · Lesson 4 of 6

第 4 课：测试与调试：确保 Skill 按预期工作

学习目标：

  • 掌握测试 Skill 的基本方法
  • 学会诊断常见问题
  • 理解迭代改进的流程
  • 知道如何验证 Skill 是否真的有用

前置要求：<< 第 3 课 | 下一课 第 5 课 >>

为什么 Skill 第一次不会完美

你写了第一个 Skill，调用它，发现：

  • 有些任务没识别出来
  • 优先级判断错了
  • 输出格式乱了
  • 或者 Claude 根本没加载这个 Skill

这很正常。

Skill 和写代码一样，第一次跑通只是开始。真正有用的 Skill，都是经过多次迭代的。1

这一课教你如何系统地测试和修复问题。

测试方法 1：直接调用测试

最简单的是直接调用测试：用 /skill-name 调用一次，观察输出。2

准备测试用例

在调用之前，先准备 3-5 个测试用例：

正常情况：

完成季度报告审查 PR #234，周五之前明天修复登录 bug

边界情况：

（空输入）

异常情况：

这是一段完全无关的文字，没有任何任务asldfkjasldfj!@#$%

执行测试

在 Claude Code 里，逐个测试：

/task-organizer
完成季度报告审查 PR #234，周五之前明天修复登录 bug

观察三件事：

  1. Claude 是否加载了这个 Skill（如果没加载，是 description 的问题）
  2. 输出的格式是否正确（如果格式乱，是输出格式说明的问题）
  3. 内容是否符合预期（如果分类错了，是处理步骤的问题）

记录结果

用一个简单的表格记录：

输入预期输出实际输出问题
"完成季度报告\n明天修复 bug"应该识别出 2 个任务，bug 是紧急只识别出 1 个任务换行符处理有问题

测试方法 2：观察 Claude 的加载行为

有时候问题不在 instructions，而在 frontmatter。

问题：Claude 没有自动加载 Skill

现象： 你说"帮我整理这些任务"，Claude 没用你的 task-organizer Skill

可能原因：

  1. description 太泛化

    修复： 加上关键词

  2. description 没有触发关键词

    如果你说"帮我整理这些待办"，但 description 里没有"待办"这个词，Claude 可能不会想起这个 Skill。3

    修复： 把用户可能说的词都写进 description

问题：Claude 加载了错误的 Skill

现象： 你想用 task-organizer，但 Claude 加载了另一个 Skill

可能原因： 另一个 Skill 的 description 跟你的输入更匹配

修复： 用 /task-organizer 强制调用，或者改进你的 description 让它更具体

常见问题诊断

问题 1：输出格式不对

现象： Skill 执行了，但输出格式乱

示例：

紧急：修复登录 bug - 明天重要：审查 PR #234 - 周五

你希望的是带 emoji 和标题的分组，但 Claude 输出了纯文本列表。

原因： 输出格式说明不够清楚，或者没有给示例

修复： 在 SKILL.md 的"输出格式"部分，加上完整示例：

加上"必须按以下格式"，然后给完整示例。

问题 2：识别不准确

现象： 有些任务没被识别出来，或者分类错了

示例：

输入：

明天要改那个 bug周五之前准备 demo

输出：

### ⚪ 普通- 明天要改那个 bug - 无明确截止- 周五之前准备 demo - 无明确截止

两个都有明确时间，但都被标记为"无明确截止"。

原因： 处理步骤里的时间识别规则不够全

修复： 补充规则

关键： 把所有可能的表达方式都列出来

问题 3：边界情况未处理

现象： 正常输入没问题，但特殊输入时 Skill 行为异常

示例：

输入：空字符串

输出：Claude 卡住了，或者输出了一堆无意义内容

原因： "注意事项"里没有说明怎么处理空输入

修复：

迭代改进的流程

好的 Skill 不是一次写成的，是测试-修复-测试的循环：1

1. 写第一个版本（核心功能）2. 用 3-5 个测试用例测试3. 记录哪里不对4. 修改 SKILL.md5. 再测试6. 重复 3-5，直到通过所有测试用例7. 实际使用一周8. 发现新问题9. 回到第 4 步

不要期望第一个版本就完美。 先让它能跑，再让它跑对，最后让它跑好。

验证 Skill 是否真的有用

技术上能跑通了，但还要验证一个更重要的问题：这个 Skill 是否真的节省了时间？1

对比测试

对比测试的做法很直接：同一个任务，用和不用 Skill 各跑几次，计时比较。

不用 Skill 的情况：

计时：你每次手动解释流程，Claude 执行，平均需要多久？

用 Skill 的情况：

计时：你调用 Skill，Claude 执行，平均需要多久？

如果 Skill 版本没有更快，或者质量更差，说明这个 Skill 还需要改进。

实际使用一周

真正的测试是实际使用。4

记录这些指标：

  • 调用了多少次
  • 有多少次结果直接可用（不需要手动修改）
  • 有多少次需要重新调用或手动改
  • 节省了多少时间

如果一周内调用次数少于 3 次，说明这个任务本身可能不够"重复"，不值得写成 Skill。

调试技巧汇总

遇到 Skill 用不起来的情况，先做一次加载失败诊断——按下表逐项排查文件路径、frontmatter 格式和触发关键词。

问题诊断方法修复方向
Claude 没自动加载 Skill检查 description 是否包含你说的关键词补充触发词、说明使用场景
输出格式乱检查是否给了完整的输出示例加示例、加"必须按以下格式"
识别不准确检查处理步骤是否列出了所有情况补充规则、给更多判断条件
边界情况错误检查"注意事项"是否覆盖这个情况加特殊情况处理
Skill 存在但调不出来检查文件路径、检查 frontmatter 格式确认 --- 在正确位置、YAML 缩进正确

小结

  • 第一次写的 Skill 不会完美，需要测试-修复-测试的迭代
  • 测试方法：直接调用、观察加载行为、准备测试用例
  • 常见问题：description 太泛化、输出格式说明不清、识别规则不全、边界情况未处理
  • 调试流程：记录预期和实际输出、诊断问题、修改 SKILL.md、重新测试
  • 验证有用性：对比用和不用 Skill 的时间、质量、稳定性，实际使用一周看调用频率

下一课，我们通过一个完整的代码审查 Skill 案例，学习如何处理更复杂的工作流。

>> 第 5 课：实战案例：构建代码审查 Skill

Footnotes

  1. Claude Code Skills：.NET 工作流与可复用提示 — https://codewithmukesh.com/blog/skills-claude-code/ ↩ ↩2 ↩3

  2. Claude Code 官方文档：Skills 扩展指南 — https://code.claude.com/docs/en/skills ↩

  3. 构建 Claude Skill 实战教程：YAML Frontmatter 与测试 — https://sjramblings.io/building-skills-for-claude-part-2/ ↩

  4. Claude Skills 作为自文档化的 Runbook — https://zackproser.com/blog/claude-skills-internal-training ↩

Exercises

01

用第 3 课创建的 Skill，执行完整的测试流程：

Level 1：调试你的 Skill
  1. 准备 3 个测试用例（1 个正常、1 个边界、1 个异常）
  2. 记录每个用例的预期输出和实际输出
  3. 找出至少 1 个问题
  4. 修改 SKILL.md
  5. 重新测试，验证问题是否修复
Done criteria · checked locally
02

用你的 Skill 和"不用 Skill、直接跟 Claude 说"两种方式，分别完成同一个任务，对比：

Level 2：对比测试
  1. 哪个更快
  2. 哪个结果质量更好
  3. 哪个更稳定（多次调用结果一致）
Done criteria · checked locally

My note

Jot down thoughts, sticking points, things you didn't get. Written to this course's appendix only — the lesson file is never touched.