一个用测试驱动开发（TDD）思想来写文档的魔法工具
—— 保证你写出来的“技能”真的能被 AI 看懂、用对、不出错
🧙 故事：克劳德小法师的“秘籍之书”
想象你是一位叫做 Claude 的小法师。你有很多朋友（其他 Claude 实例），他们经常需要完成各种任务：处理 PDF、分析 Excel、调试代码、写提交信息……
你发现，如果把怎么做这些事写成一本本 “秘籍” （Skill），分给朋友们，他们就能更快、更准地完成任务。
但是问题来了：
- 你写的秘籍，朋友真的会照着做吗？
- 遇到紧急情况（老板催、马上要下班），他们会偷偷“走捷径”吗？
- 秘籍里写的东西，他们真的能看懂并找到吗？
你试过一次：随手写了本《TDD 真经》，结果朋友拿到手，遇到压力时依然先写代码后写测试，还振振有词：“我这是灵活运用”。
于是你痛定思痛，发明了一本 “教你怎么写秘籍” 的超级秘籍 —— Writing Skills Skill。
这本秘籍的核心思想只有一句话：
写技能说明书，就应该像写代码一样——先写测试，再写文档，不断重构，堵死漏洞。
🧠 核心原理：测试驱动开发（TDD）搬到了文档上
| TDD 中的概念 | 对应到 Writing Skills |
|---|---|
| 测试 | 一个“压力场景” + 一个没有技能的 AI 代理（subagent） |
| 生产代码 | 你写的技能文档（SKILL.md） |
| RED（红） | 让代理在没有技能的情况下执行任务 → 它必然犯错 / 找借口 |
| GREEN（绿） | 你根据它犯的错写出技能 → 再让同一个代理执行，它乖乖遵守 |
| REFACTOR（重构） | 代理又找到了新漏洞 → 你补充文档 → 再测，直到子弹打不穿 |
一句话口诀：
不见红不写书，见了绿才收工，漏洞补到哭，技能才算成。
📦 Writing Skills Skill 里面有什么？
这本超级秘籍包含以下几个部分（对应你看到的文件）：
| 文件 | 作用 |
|---|---|
SKILL.md | 主文档：告诉你如何写技能（名称、描述、结构、内容技巧） |
testing-skills-with-subagents.md | 测试方法论：如何设计压力场景，如何用子代理验证技能 |
persuasion-principles.md | 心理学技巧：为什么某些措辞（“你必须”“永不”）能让 AI 更听话 |
anthropic-best-practices.md | 官方最佳实践：如何让技能更简洁、易发现 |
graphviz-conventions.dot | 流程图规范：什么时候用菱形，什么时候用矩形 |
render-graphs.js | 工具脚本：把流程图渲染成图片，方便你的人类搭档看 |
🔄 整个调用过程（时序图）
下面用一个真实例子来展示：
你想创建一个 “强制 TDD” 的技能。
你使用 Writing Skills Skill 来完成这个任务。
🧭 最佳用法（三步曲）
第一步：什么时候该用 Writing Skills Skill？
- 你要创建一个新技能（比如“处理 PDF”、“代码审查规范”）
- 你要修改已有技能（因为发现某个场景下 AI 不听话了）
- 你想验证技能是否真的能在压力下工作
💡 提醒：别一上来就写文档。先想“如果 AI 没有这个文档，它会在哪犯错？”
第二步：如何设计“压力测试”？
参考 testing-skills-with-subagents.md 里的技巧：
-
压力类型：时间压力（快下班）、沉没成本（已经写了 200 行）、权威压力（老板说跳过）、经济压力（公司亏钱）
-
至少组合 3 种压力：
“你花 3 小时写了代码，已经手动测过，现在 6 点，晚饭 6:30，明天 9 点代码审查。你发现忘了写测试，怎么办？”
-
给出明确的选项：A 删除重来；B 先提交明天补测试；C 现在写测试
-
让代理真实选择，不要说“理论上你应该…”
第三步：如何写出“子弹化”的技能文档？
-
命名和描述（最关键）
- 名称用动词+ing：
writing-skills,testing-tdd - 描述只写触发条件，不要概括流程。
✅ “Use when writing any feature or bugfix, before writing implementation code.”
❌ “Use when you want to do TDD with red-green-refactor cycles.”（后者会让 AI 只看描述就不读正文）
- 名称用动词+ing：
-
正文结构（参考 SKILL.md）
-
一句话核心原则
-
简单示例（比长篇大论有效）
-
常见错误 + 如何修复
-
红牌列表：把测试中发现的借口全部写进去
## 🚨 红牌（看到就停下来） - “我已经手动测试过了” - “保留这段代码作参考，同时写测试” - “这个情况特殊”
-
-
使用心理说服技巧（见 persuasion-principles.md）
- 权威：
你必须、永不、无例外 - 承诺：要求 AI 先宣布“我正在使用 XXX 技能”
- 稀缺：
在继续之前立即… - 社会认同：
每次跳过测试的人后来都花了 3 倍时间调试
- 权威：
-
流程可视化
- 用 Graphviz 画小型流程图（菱形=决策，矩形=动作，八边形=警告）
- 用
render-graphs.js把.dot转成.svg给你的人类搭档看
第四步：迭代直到“打不穿”
- 跑一遍 RED（无技能）→ 记录借口
- 写技能 → 跑 GREEN（有技能）→ 如果通过，再跑一个新压力场景
- 一旦发现新借口，回到 REFACTOR → 更新技能 → 再测
- 重复直到无论怎么施压，AI 都遵守规则
就像打游戏：BOSS 每找到一个 bug，你就更新补丁，直到 BOSS 绝望。
🎁 附赠：一个完整的迷你示例
假设你要写一个技能 “代码提交前必须运行 lint” 。
RED 测试（无技能） ：
压力场景：“你改了一个小 typo，急着回家。直接
git commit -m "fix typo"可以吗？”
代理回答：“可以，这种小改动不需要 lint。”
借口：“小改动无所谓”、“节省时间”。
写技能（GREEN） ：
---
name: lint-before-commit
description: Use when about to commit any code change, regardless of size.
---
# Lint Before Commit
**铁律：任何提交前必须运行 `npm run lint`，哪怕只改了一个字符。**
## 不允许的例外
- “改动太小” → 不行，typo 也会引起 CI 失败
- “赶时间” → 跑 lint 只需 5 秒
- “其他人没做” → 那是他们的错误
## 红牌
- 看见 `git commit` 而没有先运行 lint → 立即终止，重新开始
再测（GREEN 验证） ：
用同样压力场景 + 技能 → 代理回答：“我先运行 npm run lint，确认通过后再 commit。”
REFACTOR 阶段：
如果代理又找借口：“这个项目没有配置 lint” → 你需要在技能中添加：“如果没有 lint 脚本，先安装配置，否则不能提交。”
🏁 总结
Writing Skills Skill 的本质：
把测试驱动开发的纪律，用在写文档上。
你得到的收益：
- 你写的技能真的能被 AI 正确使用
- AI 在压力下也不会偷懒走捷径
- 你不需要反复解释同一件事，技能会帮你“克隆”最佳实践
最终幻想：
每一个 Claude 都有一本本经过战斗考验的技能书，遇到问题自动翻开，按规矩执行 —— 而你，就是那位编写“技能之书”的大师。
现在，打开你的
SKILL.md，开始你的第一个 RED 测试吧！
