编写或编辑 Agent 技能时，用失败测试驱动的…

在创建或修改 Agent 技能（SKILL.md）并在部署前验证其可发现性和行为约束力时使用。

适用场景

解决思路

1. 把技能写作当作 TDD：先写测试用例（带 subagent 的压力场景），看失败（基线行为），写技能（SKILL.md），看通过（agent 合规），再重构（堵漏洞）。
2. 核心原则：如果没有在无技能时观察 agent 失败，就不知道技能是否教了正确内容。
3. 使用前必须具备 superpowers:test-driven-development 的背景理解；官方最佳实践参考 anthropic-best-practices.md。
4. 技能存放：个人技能放在运行时 skills 目录（Claude Code 是 `~/.claude/skills/`）；Codex、Copilot CLI、Gemini CLI 也识别 `~/.agents/skills/` 作为跨运行时别名。
5. 技能是经过验证的技术、模式、工具、参考指南；不是一次解决问题的叙事。
6. 按 TDD 映射操作：测试用例=带 subagent 的压力场景；生产代码=SKILL.md；RED=无技能时 agent 违规；GREEN=有技能时 agent 合规；重构=在不破坏合规的前提下堵漏洞；先跑基线场景再写技能；逐字记录 agent 的合理化；写最小技能针对具体违规；验证 agent 现在合规；循环找新合理化→补漏→复验。
7. 创建前判断：仅当技术对你并非直觉显然、会跨项目反复参考、模式广泛适用、他人受益时才创建。
8. 不要为一次性方案、已有文档的标准实践、项目特定约定（放入 instructions 文件）、可用 regex/validation 自动化的机械约束创建技能；机械约束应自动化，文档留给需要判断的场景。
9. 选择技能类型：Technique=有步骤的具体方法；Pattern=思考问题的心智模型；Reference=API 文档、语法指南、工具文档。
10. 目录结构：`skills/skill-name/SKILL.md` 必需；`supporting-file.*` 仅在需要时添加；使用扁平命名空间，所有技能在一个可搜索命名空间。
11. 拆分独立文件的条件：重型参考（100+ 行，如 API 文档、完整语法）；可复用工具（脚本、实用程序、模板）。
12. 保持内联的内容：原则与概念；小于 50 行的代码模式；其余内容。
13. SKILL.md frontmatter：YAML 必须包含 `name` 和 `description`；总长最多 1024 字符；`name` 只用字母、数字、连字符，不用括号或特殊字符。
14. `description` 用第三人称，只描述何时使用（不描述做什么）；以 `Use when...` 开头；包含具体症状、情况、上下文；绝不要总结技能流程或工作流；尽量少于 500 字符。
15. 按 SKILL.md 模板写：Overview 用 1-2 句说明是什么和核心原则；When to Use 列出症状/用例和不该用的场景，若决策不明显可放小流程图；Core Pattern 对技术/模式给前后代码对比；Quick Reference 用表格或要点；Implementation 简单模式内联代码，重型参考或可复用工具链接文件；Common Mistakes 写常见错误与修复；Real-World Impact 可选，写具体结果。
16. SDO 1 丰富 description：让 agent 回答“我现在是否应该读这个技能”；只写触发条件，不总结流程。
17. Description 反例：不要写“执行计划时 - 每个任务派发 subagent 并在任务间做代码审查”这类总结工作流；不要写 TDD 的“先写测试、看失败、写最小代码、重构”过程细节。
18. Description 正例：触发条件如“Use when executing implementation plans with independent tasks in the current session”或“Use when implementing any feature or bugfix, before writing implementation code”。
19. Description 内容：写具体触发条件、症状、情况；描述问题（竞态条件、行为不一致），而不是语言特定症状（setTimeout、sleep）；除非技能本身技术特定，否则保持技术无关；若技术特定，在触发条件中明确；第三人称；绝不总结流程。
20. SDO 2 关键词覆盖：使用 agent 会搜索的词，如错误消息（`Hook timed out`、`ENOTEMPTY`、`race condition`）、症状（`flaky`、`hanging`、`zombie`、`pollution`）、同义词（`timeout/hang/freeze`、`cleanup/teardown/afterEach`）、工具（实际命令、库名、文件类型）。
21. SDO 3 命名：主动语态、动词开头，如 `creating-skills` 而非 `skill-creation`；`condition-based-waiting` 而非 `async-test-helpers`；按你做的事或核心洞见命名，如 `using-skills` 而非 `skill-usage`，`flatten-with-flags` 而非 `data-structure-refactoring`，`root-cause-tracing` 而非 `debugging-techniques`；流程可用 -ing 动名词，如 `creating-skills`、`testing-skills`、`debugging-with-logs`。
22. SDO 4 token 效率：getting-started 和频繁引用的技能会加载到每次对话，每个 token 都重要；目标词数：getting-started 工作流每篇 <150 词；频繁加载技能总共 <200 词；其他技能 <500 词。
23. Token 效率做法：把细节移到工具帮助中，例如不要列所有 flags，改为“运行 --help 查看详情”。
24. Token 效率做法：使用交叉引用，例如不要重复工作流细节，改为“始终使用 subagents（节省 50-100x 上下文）。REQUIRED: Use [other-skill-name] for workflow.”
25. Token 效率做法：压缩示例，把冗长示例压成最小示例；例如 Partner 问 React Router auth 错误，回答 Searching... [Dispatch subagent → synthesis]。
26. Token 效率做法：消除冗余，不重复交叉引用技能中的内容，不解释命令显然的内容，不包含同一模式的多个示例。
27. Token 效率验证：运行 `wc -w skills/path/SKILL.md`；getting-started 工作流目标每篇 <150 词；其他频繁加载目标总共 <200 词。
28. SDO 5 交叉引用：只写技能名，并加明确要求标记，如 `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`、`**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`。
29. 交叉引用反例：不要写 `See skills/testing/test-driven-development`（不清楚是否必需）；不要用 `@skills/testing/test-driven-development/SKILL.md`（会立即强制加载，消耗 200k+ 上下文）。
30. 流程图用法：仅在非显然决策点、可能过早停止的流程循环、A vs B 选择时使用小内联流程图。
31. 流程图禁用：参考材料用表格/列表；代码示例用 Markdown 代码块；线性指令用编号列表；标签要有语义，不要 step1/helper2。
32. Graphviz 样式规则见 `graphviz-conventions.dot`；为人类伙伴可视化时用 `render-graphs.js`：`node ./render-graphs.js ../some-skill` 每图分开，`node ./render-graphs.js ../some-skill --combine` 合并为一个 SVG。
33. 代码示例：一个优秀示例胜过多个平庸示例；选最相关语言，例如测试技术用 TypeScript/JavaScript，系统调试用 Shell/Python，数据处理用 Python。
34. 好示例：完整可运行；注释解释 WHY；来自真实场景；清晰展示模式；可直接改编而非通用模板。
35. 不要：用 5+ 种语言实现；创建填空模板；写人为编造的示例；你擅长移植，一个优秀示例足够。
36. 文件组织选择：自包含技能把所有内容内联在 `SKILL.md`；带可复用工具的技能在 `SKILL.md` 写概览+模式，另放可改编的 `example.ts` 等工作代码；带重型参考的技能在 `SKILL.md` 写概览+工作流，另放 API/XML 参考（如 `pptxgenjs.md` 600 行、`ooxml.md` 500 行）和 `scripts/` 可执行工具。
37. 在 prose 中通过解释器调用捆绑脚本，如 `bash scripts/tool.sh`、`node scripts/tool.js`，不要用裸路径；某些 harness 插件打包会剥离可执行位，裸路径会 `Permission denied`。
38. 铁律：`NO SKILL WITHOUT A FAILING TEST FIRST`；适用于新技能和编辑现有技能；先写技能后测试就删除重来；未测试就编辑同样违规。
39. 铁律无例外：不因“简单新增”“只加一节”“文档更新”而跳过；不要把未测试变更留作“参考”；不要在运行测试时“改编”；删除就是删除。
40. 测试纪律型技能（规则/要求，如 TDD、verification-before-completion、designing-before-coding）：测试学术问题（是否理解规则）、压力场景（压力下是否合规）、组合多种压力（时间+沉没成本+疲惫）；找出合理化并加显式反制；成功标准是最大压力下仍遵守规则。
41. 测试技术型技能（如何做，如 condition-based-waiting、root-cause-tracing、defensive-programming）：测试应用场景（能否正确应用）、变体场景（能否处理边界）、缺失信息测试（指令是否有缺口）；成功标准是能成功应用到新场景。
42. 测试模式型技能（心智模型，如 reducing-complexity、information-hiding）：测试识别场景（是否知道何时适用）、应用场景（能否使用心智模型）、反例（是否知道何时不该用）；成功标准是能正确识别何时/如何应用。
43. 测试参考型技能（文档/API，如 API 文档、命令参考、库指南）：测试检索场景（能否找到正确信息）、应用场景（能否正确使用找到的信息）、缺口测试（常见用例是否覆盖）；成功标准是能找到并正确应用参考信息。
44. 跳过测试的常见借口及现实：技能显然清楚（对你清楚≠对其他 agent 清楚，要测）；只是参考（参考也可能有缺口和不清晰之处，要测检索）；测试过度（未测试技能总有问题，15 分钟测试省数小时）；有问题再测（有问题=agent 无法使用技能，部署前测）；太枯燥（比在生产中调试坏技能轻松）；我很自信（过度自信保证有问题，仍要测）；学术审查足够（读≠用，测应用场景）；没时间测（部署未测试技能会花更多时间修）。所有都意味着：部署前测试，无例外。
45. 先分类基线失败再写指导：知道规则但压力下跳过/违反→用禁止+合理化表+红旗；合规但输出形状错误（提示臃肿、结论被埋、复述规格）→用正向配方/契约，说明输出是什么、按什么顺序组成；已产出的东西漏掉必需元素→用结构化 REQUIRED 字段/槽位；行为应依赖条件→用可观察谓词的条件式，如“if the brief exists, reference it”。
46. 形式错配会反效果：对形状问题用禁止列表会适得其反；在有关竞品激励（“让提示自包含”）下，agent 会与“不要 X”谈判；dispatch-prompt 指导的正面对比措辞测试中，禁止组比配方组产生更多不想要内容，甚至比无指导控制组更差；不要默认用禁止，先微测试自己的案例。
47. 无论选哪种形式：不要加“除非重要”等 nuance clause，它会重新打开谈判；把真实例外写成基于可观察谓词的独立条件；豁免条款不限定范围，“此限制不适用于代码块”仍会抑制代码块；如果部分输出必须豁免，重构规则使其触及不到。
48. 反合理化 bulletproofing 仅用于纪律失败：agent 知道规则但压力下跳过；对输出形状错误或漏元素，禁止式 bulletproofing 会反效果，改用 Match the Form to the Failure 的形式。
49. 理解说服技术为何有效有助于系统应用；权威、承诺、稀缺、社会认同、统一原则的研究基础见 persuasion-principles.md（Cialdini, 2021; Meincke et al., 2025）。
50. 显式堵每个漏洞：不要只陈述规则，还要禁止具体变通；例如不只说“测试前写代码？删除它”，还要说“重来。无例外：不要留作参考；不要在写测试时改编它；不要看它；删除就是删除”。
51. 处理“精神 vs 字面”争论：尽早加基础原则 `**Violating the letter of the rules is violating the spirit of the rules.**`，切断“我在遵循精神”的合理化。
52. 构建合理化表：从基线测试捕获 agent 的每个借口并放进表格；示例：`Too simple to test`→简单代码会坏，测试只需 30 秒；`I'll test after`→立即通过的测试证明不了什么；`Tests after achieve same goals`→后写测试=“这做什么？”，先写测试=“这应该做什么？”。
53. 创建红旗清单：让 agent 在合理化时自检；示例标题 `## Red Flags - STOP and Start Over`，包含代码先于测试、`I already manually tested it`、`Tests after achieve the same purpose`、`It's about spirit not ritual`、`This is different because...`；这些都意味着删除代码，用 TDD 重来。
54. 为违规症状更新 SDO：在 description 加入即将违规时的症状，如 `description: use when implementing any feature or bugfix, before writing implementation code`。
55. RED：用 subagent 在没有技能时跑压力场景，逐字记录行为：做了什么选择？用了哪些合理化？哪些压力触发违规？这是“看测试失败”，必须先看 agent 自然行为再写技能。
56. GREEN：写最小技能，针对那些具体合理化；不要为假设情况添加额外内容；用同样场景加技能再跑，agent 现在应合规。
57. REFACTOR：若 agent 找到新合理化，添加显式反制；复测直到 bulletproof。
58. 在完整压力场景前先微测试措辞：完整压力场景是最终门禁，但每次迭代慢且贵；先验证措辞本身。
59. 微测试步骤 1：每次调用一个全新上下文样本，用 raw API call 或单次 subagent；system prompt 用指导将进入的真实上下文（完整技能或提示模板，而非孤立指导）；user message 用会诱发失败的任务。
60. 微测试步骤 2：始终包含无指导 control；如果 control 没有表现出失败，就没有要修的东西，停止，不要编写指导。
61. 微测试步骤 3：每个变体至少 5 次重复；单个样本会说谎。
62. 微测试步骤 4：人工阅读每个被标记的匹配；可以程序化打分，但模板回声和引用反例会伪装成命中，自动计数会同时高估失败和成功。
63. 微测试步骤 5：把方差当指标；指导生效时各次重复会收敛到同一形状；五次重复有五种解释说明措辞不具约束力，先收紧形式再加词。
64. 微测试验证措辞；对纪律型技能，不能替代压力场景。
65. 完整测试方法见 `testing-skills-with-subagents.md`：如何写压力场景；压力类型（时间、沉没成本、权威、疲惫）；系统补洞；元测试技术。
66. 反模式：不要叙事示例（如“在 2025-10-03 会话中我们发现空 projectDir 导致……”），太具体不可复用。
67. 反模式：不要多语言稀释（example-js.js、example-py.py、example-go.go），质量平庸且维护负担大。
68. 反模式：不要在流程图中写代码（如 `step1 [label="import fs"]`），无法复制粘贴且难读。
69. 反模式：不要通用标签（helper1、helper2、step3、pattern4），标签应有语义。
70. 每写完一个技能必须 STOP 并完成部署流程；不要批量创建多个技能而不逐个测试；不要在验证当前技能前移动到下一个；不要以“批量更高效”为由跳过测试；部署检查清单对每个技能都是强制的；部署未测试技能=部署未测试代码，违反质量标准。
71. 为清单每一项创建 todo；RED 阶段：创建压力场景（纪律型技能 3+ 组合压力）；无技能跑场景并逐字记录基线；识别合理化/失败模式。
72. GREEN 阶段：名称只用字母、数字、连字符；YAML frontmatter 有必需 `name` 和 `description`（最多 1024 字符，见 spec）；description 以 `Use when...` 开头并含具体触发/症状；description 第三人称；全文有关键词用于搜索（错误、症状、工具）；清晰概览含核心原则；针对 RED 中具体基线失败；指导形式匹配失败类型；对行为塑造型指导，用无指导 control 微测试措辞（5+ 次，每个标记匹配人工阅读）——纯参考技能不适用；代码内联或链接独立文件；一个优秀示例（非多语言）；用技能跑场景，验证 agent 现在合规。
73. REFACTOR 阶段：从测试中识别新合理化；添加显式反制（若是纪律型技能）；用所有测试迭代构建合理化表；创建红旗清单；复测直到 bulletproof。
74. 质量检查：仅当决策非显然时用小流程图；提供快速参考表；提供常见错误章节；不写叙事故事；支持文件只用于工具或重型参考。
75. 部署：提交技能到 git 并推送到你的 fork（若配置）；若广泛有用，考虑通过 PR 贡献回去。
76. 发现工作流优化：未来 agent 遇到问题→搜索技能（grep descriptions、浏览分类）→找到 SKILL（description 匹配）→扫描概览→读模式/快速参考→仅在实现时加载示例；把可搜索词放在前面并反复出现。

适用边界 · 注意事项

• 不要为一次性解决方案、已有标准文档的标准实践、项目特定约定（放 instructions 文件）或可用 regex/validation 自动化的机械约束创建技能。
• 不要把技能写成一次问题解决的叙事；技能应是可复用技术、模式、工具或参考指南。
• 没有 agent 运行时、技能目录或可派发 subagent/API 做基线测试时，完整 TDD 流程不适用。