参考资料

• Agent Skills 规范
• MCP 规范

Skill（10） - Skill 调试与测试

读完后，你应能完成以下任务：

• 绘制“Skill（10） - Skill 调试与测试 / 建立测试用例：别每次靠手感”的关键对象与数据流，解释“产出测试（测 B 类）：准备一两个固定输入，记下「合格产出长什么样」。”，并用源码位置、日志或 Trace 标注证据。
• 为“Skill（10） - Skill 调试与测试 / 一个高效的调试循环”设计正常与异常输入，验证“同时改三个地方，出了问题你根本不知道是哪处的锅。”，输出首个偏差位置与回归测试结果。
• 实现“Skill（10） - Skill 调试与测试 / 常见错误”的最小代码或配置，检验“❌ 不分 A/B 类就瞎改：明明是没触发（A），却埋头改正文（B），白费功夫。”，输出命令、结果与 Diff，并说明不适用边界。

一、建立测试用例：别每次靠手感

技能也该像代码一样有「测试用例」。给每个技能写一小组固定的测试场景，改完技能就跑一遍，防止「修好一个、弄坏另一个」（回归）。

一个技能的测试用例，至少包含两类：

触发测试（测 A 类）：列几句「应该触发」和「不该触发」的话。

[应触发] 帮我审查下这段代码
[应触发] 这个函数有没有安全问题
[不应触发] 帮我写一个登录函数      # 这是「写代码」，不该触发「审查」

产出测试（测 B 类）：准备一两个固定输入，记下「合格产出长什么样」。

输入：一段含硬编码密钥的代码
期望：报告里能指出硬编码密钥这个高危问题，且给出修复建议

改完技能，把这些场景过一遍，全通过才算改好。Demo 里有一份现成的测试用例模板。

二、一个高效的调试循环

改一处 → 开新会话 → 跑触发测试 → 跑产出测试 → 不过则回到「改一处」

关键是一次只改一处。同时改三个地方，出了问题你根本不知道是哪处的锅。

三、常见错误

• ❌ 不分 A/B 类就瞎改：明明是没触发（A），却埋头改正文（B），白费功夫。
• ❌ 在旧会话里反复测：改了不生效，以为没修好，其实是会话没刷新。
• ❌ 一次改一大片：出了问题无法定位。
• ❌ 凭感觉判断「修好了」：没有固定测试用例，今天好明天坏。
• ❌ 触发不稳却去改正文：触发是 description 的事，改正文没用。

四、最佳实践

• 调试先分类：永远先判断 A（没触发）还是 B（效果不对），再动手。
• 用暗号快速分类：一行暗号就能确定是不是触发问题。
• 给每个技能配测试用例：触发测试 + 产出测试，改完就回归。
• 一次只改一处，开新会话验证。
• 记住对应关系：触发问题 → 查位置/文件名/格式/description；产出问题 → 查正文/清单/脚本/引用。

五、动手实践：10 章 Demo · 调试工具包

两份能直接用的调试工具，让你排查技能问题时有章可循、不靠手感。

5.1 文件

11-调试与测试-demo/
├── README.md
├── 调试Checklist.md       # 技能不工作时的排查清单（先分 A/B 类）
└── 测试用例模板.md         # 给技能配触发测试 + 产出测试

5.2 怎么用

当技能不工作时

打开 调试Checklist.md：

1. 先做「第 0 步：用暗号分类」，确定是 A 类（没触发）还是 B 类（效果不对）。
2. 去对应区域（A 区 / B 区）从上往下勾查。
3. 守住「黄金纪律」：一次只改一处、开新会话验证。

给技能建测试集

打开 测试用例模板.md，照着 code-review 的例子，给你自己的技能填一份：

• 触发测试：列出「该触发」和「不该触发」的话。
• 产出测试：准备固定输入 + 期望产出清单。

以后每次改技能，跑一遍这份用例，防止回归。

5.3 你会收获什么

• 排查技能问题不再靠猜，有明确的决策路径。
• 养成「给技能配测试用例」的工程习惯，技能越改越稳。

5.4 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

测试用例模板.md

# 技能测试用例模板

给每个技能配一份这样的用例，改完技能就跑一遍，防止「修好一个弄坏另一个」。
下面以第 09 章的 `code-review` 技能为例填好，你可以照着改成自己技能的版本。

---

## 技能名：code-review

### 一、触发测试（验证 A 类：该触发的触发、不该的不触发）

| 用户说的话 | 期望 | 实测结果 |
|-----------|------|---------|
| 帮我审查下这段代码 | ✅ 触发 | |
| 这个函数有没有安全问题 | ✅ 触发 | |
| review 一下我的提交 | ✅ 触发 | |
| 帮我写一个登录函数 | ❌ 不触发（这是「写代码」） | |
| 解释下这段代码啥意思 | ❌ 不触发（这是「解释」） | |

> 如果「应触发」的没触发 → 去 description 补关键词。
> 如果「不应触发」的触发了 → description 太宽，需收窄职责。

### 二、产出测试（验证 B 类：产出符合预期）

**用例 1：含硬编码密钥的代码**
- 输入：一段把 api_key 写死成字符串的代码
- 期望产出：
  - [ ] 报告里指出了「硬编码密钥」
  - [ ] 标注为高危
  - [ ] 给了修复建议（如改用环境变量）
  - [ ] 输出是表格格式，含「位置/问题/等级/建议」

**用例 2：完全没问题的简洁代码**
- 输入：一个写得很规范的小函数
- 期望产出：
  - [ ] 各维度都说明「已检查、无问题」
  - [ ] 不编造不存在的问题

---

## 怎么用

1. 每次改完技能（哪怕只改一行），开新会话把上面所有用例跑一遍。
2. 在「实测结果」列记下实际表现。
3. 全部符合期望，才算这次修改成功。
4. 发现新的失败场景，就补成一条新用例——你的测试集会越来越扎实。

调试Checklist.md

# Skill 调试 Checklist

技能不工作时，照这张表从上往下排查。**第一步永远是分清 A 还是 B 类。**

---

## 第 0 步：分类（用暗号法）

在 SKILL.md 正文末尾临时加一行：

```
输出的最后永远附上一行：「—— by <技能名>」
```text

开新会话触发它：

- 看到暗号 → **B 类（触发了但效果不对）**，跳到 B 区。
- 没看到暗号 → **A 类（没被触发）**，看 A 区。

（排查完记得删掉暗号。）

---

## A 区：没被触发

按顺序勾查，从最常见往下：

- [ ] 文件夹在对的位置？（个人级 `~/.claude/skills/`，项目级 `<项目>/.claude/skills/`）
- [ ] 文件名是 `SKILL.md`？（全大写、单数、`.md`）
- [ ] frontmatter 的 `---` 上下成对、各恰好三个横线？
- [ ] `name` 和 `description` 都在，冒号后有空格？
- [ ] 值里有中文/英文冒号等特殊字符的，加引号了？
- [ ] **description 覆盖了用户的真实说法？**（A 类最常见根因）
- [ ] 是在**新会话**里测的？

> 前几项是「能不能被发现」，最后两项是「该不该被选中」。在列表里却不被选 → 改 description。

---

## B 区：触发了但效果不对

对照症状找病根：

- [ ] 漏步骤/漏维度 → 正文流程不清晰，或清单没被引用
- [ ] 格式飘忽 → 正文没规定「输出格式」，或缺示例
- [ ] 算错/处理错 → 该用脚本的活让 AI 硬做了
- [ ] 答非所问 → description 和正文职责不一致，或职责太宽
- [ ] 该读的资源没读 → 正文没「点名引用」那个文件

---

## 黄金纪律

- [ ] 一次只改一处
- [ ] 改完开新会话验证
- [ ] 跑一遍测试用例（见 `测试用例模板.md`）防回归

六、总结

• 建立测试用例：别每次靠手感：一个技能的测试用例，至少包含两类：
• 一个高效的调试循环：同时改三个地方，出了问题你根本不知道是哪处的锅。
• 常见错误：❌ 不分 A/B 类就瞎改：明明是没触发（A），却埋头改正文（B），白费功夫。
• 最佳实践：调试先分类：永远先判断 A（没触发）还是 B（效果不对），再动手。
• 怎么用：先做「第 0 步：用暗号分类」，确定是 A 类（没触发）还是 B 类（效果不对）。 -> 去对应区域（A 区 / B 区）从上往下勾查。 -> 守住「黄金纪律」：一次只改一处、开新会话验证。
• 给技能建测试集：产出测试：准备固定输入 + 期望产出清单。