update

.codebuddy/skills/writing-skills/SKILL.md

@@ -0,0 +1,679 @@
+---
+name: writing-skills
+description: 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [skills, documentation]
+---
+
+# 编写技能
+
+## 概述
+
+**编写技能就是将测试驱动开发应用于流程文档。**
+
+**个人技能存放在智能体特定的目录中（Claude Code 用 `~/.claude/skills`，Codex 用 `~/.agents/skills/`）**
+
+你编写测试用例（带子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵守规则），然后重构（堵住漏洞）。
+
+**核心原则：** 如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。
+
+**必需背景：** 在使用此技能前，你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。
+
+**官方指南：** Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。
+
+## 什么是技能？
+
+**技能**是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。
+
+**技能是：** 可复用的技术、模式、工具、参考指南
+
+**技能不是：** 关于你某次如何解决问题的叙事
+
+## TDD 映射到技能
+
+| TDD 概念 | 技能创建 |
+|----------|---------|
+| **测试用例** | 带子智能体的压力场景 |
+| **生产代码** | 技能文档（SKILL.md） |
+| **测试失败（红）** | 智能体在没有技能时违反规则（基线） |
+| **测试通过（绿）** | 智能体在有技能时遵守规则 |
+| **重构** | 在保持合规的同时堵住漏洞 |
+| **先写测试** | 在编写技能之前先运行基线场景 |
+| **观察失败** | 记录智能体使用的确切合理化借口 |
+| **最小代码** | 编写针对那些具体违规行为的技能 |
+| **观察通过** | 验证智能体现在遵守规则 |
+| **重构循环** | 发现新的合理化借口 → 堵住 → 重新验证 |
+
+整个技能创建过程遵循红-绿-重构。
+
+## 何时创建技能
+
+**创建条件：**
+- 技术对你来说不是直觉上显而易见的
+- 你会在不同项目中反复引用
+- 模式具有广泛适用性（非项目特定）
+- 其他人也会受益
+
+**不要创建：**
+- 一次性解决方案
+- 其他地方有充分文档的标准实践
+- 项目特定的约定（放在 CLAUDE.md 中）
+- 机械性约束（如果可以用正则/验证强制执行，就自动化——文档留给需要判断的场景）
+
+## 技能类型
+
+### 技术类
+有具体步骤的方法（condition-based-waiting、root-cause-tracing）
+
+### 模式类
+思考问题的方式（flatten-with-flags、test-invariants）
+
+### 参考类
+API 文档、语法指南、工具文档（office docs）
+
+## 目录结构
+
+```
+skills/
+  skill-name/
+    SKILL.md              # 主参考文档（必需）
+    supporting-file.*     # 仅在需要时
+```
+
+**扁平命名空间** - 所有技能在一个可搜索的命名空间中
+
+**分离文件的情况：**
+1. **大量参考内容**（100+ 行）- API 文档、全面的语法说明
+2. **可复用工具** - 脚本、实用程序、模板
+
+**保持内联：**
+- 原则和概念
+- 代码模式（< 50 行）
+- 其他所有内容
+
+## SKILL.md 结构
+
+**Frontmatter（YAML）：**
+- 两个必需字段：`name` 和 `description`（完整支持字段参见 [agentskills.io/specification](https://agentskills.io/specification)）
+- 总计最多 1024 字符
+- `name`：只使用字母、数字和连字符（不要用括号、特殊字符）
+- `description`：第三人称，仅描述何时使用（不是做什么）
+  - 以"Use when..."开头，聚焦于触发条件
+  - 包含具体的症状、场景和上下文
+  - **绝不总结技能的流程或工作流**（参见 SDO 章节了解原因）
+  - 尽量控制在 500 字符以内
+
+```markdown
+---
+name: Skill-Name-With-Hyphens
+description: Use when [具体的触发条件和症状]
+---
+
+# 技能名称
+
+## 概述
+这是什么？用 1-2 句话说明核心原则。
+
+## 何时使用
+[如果决策不明显，使用小型内联流程图]
+
+症状和用例的要点列表
+不适用的场景
+
+## 核心模式（技术/模式类）
+前后代码对比
+
+## 快速参考
+用于快速浏览常见操作的表格或要点
+
+## 实现
+简单模式内联代码
+大量参考或可复用工具链接到文件
+
+## 常见错误
+常见问题 + 修复方法
+
+## 实际效果（可选）
+具体结果
+```
+
+
+## 技能发现优化（SDO）
+
+**发现至关重要：** 未来的 Claude 需要找到你的技能
+
+### 1. 丰富的描述字段
+
+**目的：** Claude 读取描述来决定为当前任务加载哪些技能。让它能回答："我现在应该读这个技能吗？"
+
+**格式：** 以"Use when..."开头，聚焦于触发条件
+
+**关键：描述 = 何时使用，不是技能做什么**
+
+描述应该只描述触发条件。不要在描述中总结技能的流程或工作流。
+
+**为什么这很重要：** 测试表明，当描述总结了技能的工作流时，Claude 可能会跟随描述而非阅读完整的技能内容。一个写着"任务间进行代码审查"的描述导致 Claude 只做了一次审查，尽管技能的流程图清楚地展示了两次审查（先规格合规再代码质量）。
+
+当描述改为仅"在当前会话中执行包含独立任务的实现计划时使用"（无工作流摘要）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。
+
+**陷阱：** 总结工作流的描述创建了 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。
+
+```yaml
+# 错误：总结了工作流 - Claude 可能会跟随描述而非阅读技能
+description: Use when executing plans - dispatches subagent per task with code review between tasks
+
+# 错误：流程细节太多
+description: Use for TDD - write test first, watch it fail, write minimal code, refactor
+
+# 正确：只有触发条件，无工作流摘要
+description: Use when executing implementation plans with independent tasks in the current session
+
+# 正确：仅触发条件
+description: Use when implementing any feature or bugfix, before writing implementation code
+```
+
+**内容：**
+- 使用具体的触发条件、症状和场景来表明此技能适用
+- 描述问题（竞态条件、行为不一致）而非语言特定的症状（setTimeout、sleep）
+- 保持触发条件技术无关，除非技能本身是技术特定的
+- 如果技能是技术特定的，在触发条件中明确说明
+- 用第三人称写（注入到系统提示中）
+- **绝不总结技能的流程或工作流**
+
+```yaml
+# 错误：太抽象、模糊，未包含何时使用
+description: For async testing
+
+# 错误：第一人称
+description: I can help you with async tests when they're flaky
+
+# 错误：提到了技术但技能并非该技术特定的
+description: Use when tests use setTimeout/sleep and are flaky
+
+# 正确：以"Use when"开头，描述问题，无工作流
+description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
+
+# 正确：技术特定的技能带有明确的触发条件
+description: Use when using React Router and handling authentication redirects
+```
+
+### 2. 关键词覆盖
+
+使用 Claude 会搜索的词语：
+- 错误信息："Hook timed out"、"ENOTEMPTY"、"race condition"
+- 症状："flaky"、"hanging"、"zombie"、"pollution"
+- 同义词："timeout/hang/freeze"、"cleanup/teardown/afterEach"
+- 工具：实际命令、库名称、文件类型
+
+### 3. 描述性命名
+
+**使用主动语态，动词优先：**
+- ✅ `creating-skills` 而非 `skill-creation`
+- ✅ `condition-based-waiting` 而非 `async-test-helpers`
+
+### 4. Token 效率（关键）
+
+**问题：** getting-started 和频繁引用的技能会加载到每个对话中。每个 token 都很重要。
+
+**目标字数：**
+- getting-started 工作流：每个 <150 词
+- 频繁加载的技能：总计 <200 词
+- 其他技能：<500 词（仍要简洁）
+
+**技巧：**
+
+**将细节移到工具帮助中：**
+```bash
+# 错误：在 SKILL.md 中列出所有参数
+search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
+
+# 正确：引用 --help
+search-conversations 支持多种模式和过滤器。运行 --help 查看详情。
+```
+
+**使用交叉引用：**
+```markdown
+# 错误：重复工作流细节
+搜索时，用模板分派子智能体……
+[20 行重复的说明]
+
+# 正确：引用其他技能
+始终使用子智能体（节省 50-100 倍上下文）。必需：使用 [other-skill-name] 工作流。
+```
+
+**压缩示例：**
+```markdown
+# 错误：冗长的示例（42 词）
+你的搭档："我们之前是怎么处理 React Router 中的认证错误的？"
+你：我来搜索过去对话中的 React Router 认证模式。
+[用搜索查询分派子智能体："React Router authentication error handling 401"]
+
+# 正确：精简的示例（20 词）
+搭档："我们之前是怎么处理 React Router 中的认证错误的？"
+你：正在搜索……
+[分派子智能体 → 整合]
+```
+
+**消除冗余：**
+- 不要重复交叉引用的技能中已有的内容
+- 不要解释从命令中就能看出的东西
+- 不要为同一模式提供多个示例
+
+**验证：**
+```bash
+wc -w skills/path/SKILL.md
+# getting-started 工作流：目标 <150 每个
+# 其他频繁加载的：目标总计 <200
+```
+
+**用你做的事或核心洞察来命名：**
+- ✅ `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`
+- 主动的，描述你正在进行的操作
+
+### 5. 交叉引用其他技能
+
+**编写引用其他技能的文档时：**
+
+仅使用技能名称，带有明确的必需标记：
+- ✅ 好的：`**必需子技能：** 使用 test-driven-development`
+- ✅ 好的：`**必需背景：** 你必须理解 systematic-debugging`
+- ❌ 差的：`参见 skills/testing/test-driven-development`（不清楚是否必需）
+- ❌ 差的：`@skills/testing/test-driven-development/SKILL.md`（强制加载，浪费上下文）
+
+**为什么不用 @ 链接：** `@` 语法会立即强制加载文件，在你需要之前就消耗 200k+ 的上下文。
+
+## 流程图使用
+
+```dot
+digraph when_flowchart {
+    "需要展示信息?" [shape=diamond];
+    "我可能在决策中犯错?" [shape=diamond];
+    "使用 markdown" [shape=box];
+    "小型内联流程图" [shape=box];
+
+    "需要展示信息?" -> "我可能在决策中犯错?" [label="是"];
+    "我可能在决策中犯错?" -> "小型内联流程图" [label="是"];
+    "我可能在决策中犯错?" -> "使用 markdown" [label="否"];
+}
+```
+
+**仅在以下情况使用流程图：**
+- 非显而易见的决策点
+- 你可能过早停止的流程循环
+- "何时使用 A vs B"的决策
+
+**绝不使用流程图用于：**
+- 参考资料 → 表格、列表
+- 代码示例 → Markdown 代码块
+- 线性指令 → 编号列表
+- 无语义意义的标签（step1、helper2）
+
+参见 @graphviz-conventions.dot 了解 graphviz 样式规则。
+
+**为你的搭档可视化：** 使用此目录中的 `render-graphs.js` 将技能的流程图渲染为 SVG：
+```bash
+./render-graphs.js ../some-skill           # 每个图表分别渲染
+./render-graphs.js ../some-skill --combine # 所有图表合并为一个 SVG
+```
+
+## 代码示例
+
+**一个优秀的示例胜过多个平庸的**
+
+选择最相关的语言：
+- 测试技术 → TypeScript/JavaScript
+- 系统调试 → Shell/Python
+- 数据处理 → Python
+
+**好的示例：**
+- 完整可运行
+- 注释良好，解释为什么
+- 来自真实场景
+- 清晰展示模式
+- 可以直接适配（不是通用模板）
+
+**不要：**
+- 用 5 种以上语言实现
+- 创建填空模板
+- 写人为构造的示例
+
+你擅长语言移植——一个优秀的示例就够了。
+
+## 文件组织
+
+### 自包含技能
+```
+defense-in-depth/
+  SKILL.md    # 所有内容内联
+```
+适用场景：所有内容都能放下，无需大量参考
+
+### 带可复用工具的技能
+```
+condition-based-waiting/
+  SKILL.md    # 概述 + 模式
+  example.ts  # 可适配的工作代码
+```
+适用场景：工具是可复用的代码，不只是叙述
+
+### 带大量参考的技能
+```
+pptx/
+  SKILL.md       # 概述 + 工作流
+  pptxgenjs.md   # 600 行 API 参考
+  ooxml.md       # 500 行 XML 结构
+  scripts/       # 可执行工具
+```
+适用场景：参考资料太多无法内联
+
+## 铁律（与 TDD 相同）
+
+```
+没有失败的测试就不写技能
+```
+
+这适用于新技能和对现有技能的编辑。
+
+先写技能再测试？删掉它。重新开始。
+编辑技能不测试？同样违规。
+
+**无例外：**
+- 不适用于"简单的添加"
+- 不适用于"只是加一个章节"
+- 不适用于"文档更新"
+- 不要保留未测试的更改作为"参考"
+- 不要在运行测试时"调整"
+- 删除就是删除
+
+**必需背景：** test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。
+
+## 测试所有技能类型
+
+不同类型的技能需要不同的测试方法：
+
+### 纪律执行类技能（规则/要求）
+
+**例如：** TDD、完成前验证、编码前设计
+
+**测试方式：**
+- 学术性问题：它们理解规则吗？
+- 压力场景：它们在压力下遵守吗？
+- 多重压力组合：时间 + 沉没成本 + 疲惫
+- 识别合理化借口并添加明确的反驳
+
+**成功标准：** 智能体在最大压力下遵循规则
+
+### 技术类技能（操作指南）
+
+**例如：** condition-based-waiting、root-cause-tracing、defensive-programming
+
+**测试方式：**
+- 应用场景：它们能正确应用技术吗？
+- 变体场景：它们能处理边界情况吗？
+- 缺失信息测试：说明是否有遗漏？
+
+**成功标准：** 智能体成功将技术应用于新场景
+
+### 模式类技能（心智模型）
+
+**例如：** reducing-complexity、information-hiding 概念
+
+**测试方式：**
+- 识别场景：它们能识别模式何时适用吗？
+- 应用场景：它们能使用心智模型吗？
+- 反例：它们知道何时不应用吗？
+
+**成功标准：** 智能体正确识别何时/如何应用模式
+
+### 参考类技能（文档/API）
+
+**例如：** API 文档、命令参考、库指南
+
+**测试方式：**
+- 检索场景：它们能找到正确的信息吗？
+- 应用场景：它们能正确使用找到的内容吗？
+- 覆盖测试：常见用例是否都涵盖了？
+
+**成功标准：** 智能体找到并正确应用参考信息
+
+## 跳过测试的常见合理化借口
+
+| 借口 | 现实 |
+|------|------|
+| "技能显然很清晰" | 对你清晰 ≠ 对其他智能体清晰。测试它。 |
+| "这只是参考资料" | 参考资料可能有遗漏、不清楚的地方。测试检索。 |
+| "测试太过了" | 未测试的技能总有问题。15 分钟测试省下数小时。 |
+| "有问题再测试" | 问题 = 智能体无法使用技能。在部署前测试。 |
+| "测试太繁琐" | 测试比在生产中调试坏技能少繁琐得多。 |
+| "我有信心它很好" | 过度自信保证出问题。无论如何都要测试。 |
+| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
+| "没时间测试" | 部署未测试的技能比后面修复浪费更多时间。 |
+
+**以上所有都意味着：部署前测试。无例外。**
+
+## 让形式匹配失败类型
+
+在写指导内容之前，先给基线失败**归类**。能让某一类失败变得无懈可击的形式，用在另一类上会**可测量地反噬**。
+
+| 基线失败 | 正确的形式 | 错误的形式 |
+|---|---|---|
+| 压力之下跳过/违反规则（明知故犯） | 禁令 + 合理化借口表 + 红线（见下方"让技能经受住合理化的考验"） | 软性建议（"优先……"、"考虑……"） |
+| 遵守了，但产出的**形状**不对（提示词臃肿、结论被埋、复述规格） | 正面配方或契约：直接说明产出**是什么** —— 它由哪些部分组成、按什么顺序 | 禁令清单（"不要复述"、"绝不旁白"） |
+| 在他们**本来就会产出**的东西里漏掉了必需元素 | 结构性手段：在他们要填的模板里放一个 REQUIRED 字段或占位槽 | 在模板附近写散文式提醒 |
+| 行为**应当取决于某个条件** | 挂在可观察谓词上的条件句（"如果简报存在，就引用它"） | 无条件规则 + 一堆例外条款 |
+
+**为什么禁令在"塑形"类问题上会反噬：** 在存在竞争性激励时（比如"让提示词自包含"），智能体会**跟"不要 X"讨价还价**。在针对分派提示词指导做的同题措辞对照测试里，禁令组产出的不想要的内容明显**多于**配方组（两组分布完全分离），甚至比"完全不给指导"的对照组还差 —— 请对你自己的场景做微型测试，别想当然，但**永远不要把禁令当默认选择**。配方留不下可讨价还价的空间：产出要么符合所说的形状，要么不符合。
+
+**无论你选哪种形式，都适用的规则：**
+- **不要加"视情况"从句。** "不要 X，除非它很重要"会重新打开谈判 —— 在同一批措辞测试里，给一个胜出的配方追加**一条**"视情况"从句，就把它从稳定退化成了飘忽。真正的例外要表达成**它自己的**条件句，挂在可观察的谓词上。
+- **豁免条款不会限定作用域。** "这条长度限制不适用于代码块"，照样会压制代码块。如果产出里有一部分必须豁免，就**重构结构让规则碰不到它**，而不是写豁免。
+
+## 让技能经受住合理化的考验
+
+执行纪律的技能（如 TDD）需要抵抗合理化。智能体很聪明，在压力下会找到漏洞。
+
+**心理学说明：** 理解说服技巧为什么有效有助于你系统性地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025），涵盖权威、承诺、稀缺、社会认同和归属原则。
+
+### 明确堵住每个漏洞
+
+不要只是陈述规则——禁止具体的变通方法：
+
+<Bad>
+```markdown
+先写代码再写测试？删掉它。
+```
+</Bad>
+
+<Good>
+```markdown
+先写代码再写测试？删掉它。重新开始。
+
+**无例外：**
+- 不要保留作为"参考"
+- 不要在写测试时"调整"它
+- 不要看它
+- 删除就是删除
+```
+</Good>
+
+### 应对"精神 vs 字面"的辩论
+
+在前面加入基础原则：
+
+```markdown
+**违反规则的字面意思就是违反规则的精神。**
+```
+
+这切断了整类"我遵循的是精神"的合理化借口。
+
+### 构建合理化借口表
+
+从基线测试中捕获合理化借口（参见下方测试章节）。智能体使用的每个借口都进入表中：
+
+```markdown
+| 借口 | 现实 |
+|------|------|
+| "太简单不值得测试" | 简单的代码也会出错。测试只需 30 秒。 |
+| "我后面再测试" | 测试立即通过什么也证明不了。 |
+| "后写测试效果一样" | 后写测试 = "这做了什么？" 先写测试 = "这应该做什么？" |
+```
+
+### 创建红线列表
+
+让智能体容易自查是否在合理化：
+
+```markdown
+## 红线 - 停下来重新开始
+
+- 先写代码再写测试
+- "我已经手动测试过了"
+- "后写测试效果一样"
+- "重要的是精神不是仪式"
+- "这个情况不同，因为……"
+
+**以上所有都意味着：删除代码。用 TDD 重新开始。**
+```
+
+### 更新 SDO 以包含违规症状
+
+在描述中添加：你即将违反规则时的症状：
+
+```yaml
+description: use when implementing any feature or bugfix, before writing implementation code
+```
+
+## 技能的红-绿-重构
+
+遵循 TDD 循环：
+
+### 红：编写失败的测试（基线）
+
+在没有技能的情况下运行压力场景。逐字记录行为：
+- 它们做了什么选择？
+- 它们使用了什么合理化借口（原文）？
+- 哪些压力触发了违规？
+
+这就是"观察测试失败"——在编写技能之前你必须看到智能体自然会怎么做。
+
+### 绿：编写最小技能
+
+编写针对那些具体合理化借口的技能。不要为假设情况添加额外内容。
+
+用技能运行相同的场景。智能体应该现在遵守。
+
+### 重构：堵住漏洞
+
+智能体找到了新的合理化借口？添加明确的反驳。重新测试直到无懈可击。
+
+### 先做措辞微型测试，再跑完整场景
+
+完整的压力场景是最后一道关卡，但它每轮迭代都又慢又贵。先用**微型测试**验证措辞本身：
+
+1. **每次调用一个全新上下文的样本** —— 一次裸 API 调用，或者没有 API 权限时用一个单发子智能体。system prompt 放**这条指导实际会存在的真实上下文**（完整的 skill 或提示词模板，不是把指导单独拎出来）；user message 放一个会**诱发该失败**的任务。
+2. **永远带一个"不给指导"的对照组。** 如果对照组根本没表现出那个失败，那就没什么可修的 —— 停下，别写这条指导。
+3. **每个变体至少 5 次重复。** 单个样本会骗人。
+4. **每一条被标记的命中都要人工读一遍。** 想用程序打分可以，但模板回声和被引用的反例会**伪装成命中**；只看自动计数会同时高估失败和成功。
+5. **方差本身就是一个指标。** 指导真正生效时，多次重复会收敛到同一种形状。5 次重复出现 5 种不同解读，说明这个措辞**没有约束力** —— 先收紧形式，别急着加字。
+
+微型测试验证的是**措辞**；对纪律执行类技能，它**不能替代**压力场景。
+
+**测试方法论：** 参见 @testing-skills-with-subagents.md 了解完整的测试方法：
+- 如何编写压力场景
+- 压力类型（时间、沉没成本、权威、疲惫）
+- 系统地堵住漏洞
+- 元测试技巧
+
+## 反模式
+
+### 叙事式示例
+"在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……"
+**为什么不好：** 太具体，不可复用
+
+### 多语言稀释
+example-js.js、example-py.py、example-go.go
+**为什么不好：** 质量平庸，维护负担重
+
+### 流程图中的代码
+```dot
+step1 [label="import fs"];
+step2 [label="read file"];
+```
+**为什么不好：** 无法复制粘贴，难以阅读
+
+### 通用标签
+helper1、helper2、step3、pattern4
+**为什么不好：** 标签应有语义意义
+
+## 停下：进入下一个技能之前
+
+**编写任何技能后，你必须停下来完成部署流程。**
+
+**不要：**
+- 批量创建多个技能而不逐个测试
+- 在当前技能验证前就进入下一个
+- 因为"批量处理更高效"就跳过测试
+
+**下面的部署清单对每个技能都是强制性的。**
+
+部署未测试的技能 = 部署未测试的代码。这是对质量标准的违反。
+
+## 技能创建清单（TDD 适配版）
+
+**重要：使用 TodoWrite 为下面的每个清单项创建待办。**
+
+**红色阶段 - 编写失败的测试：**
+- [ ] 创建压力场景（纪律类技能需 3 个以上组合压力）
+- [ ] 在没有技能的情况下运行场景 - 逐字记录基线行为
+- [ ] 识别合理化借口中的模式
+
+**绿色阶段 - 编写最小技能：**
+- [ ] 名称只使用字母、数字、连字符（无括号/特殊字符）
+- [ ] YAML frontmatter 包含必需的 `name` 和 `description` 字段（最多 1024 字符；参见 [spec](https://agentskills.io/specification)）
+- [ ] 描述以"Use when..."开头并包含具体的触发条件/症状
+- [ ] 描述用第三人称
+- [ ] 全文包含搜索关键词（错误、症状、工具）
+- [ ] 带有核心原则的清晰概述
+- [ ] 解决红色阶段识别出的具体基线失败
+- [ ] 代码内联或链接到独立文件
+- [ ] 一个优秀的示例（非多语言）
+- [ ] 用技能运行场景 - 验证智能体现在遵守
+
+**重构阶段 - 堵住漏洞：**
+- [ ] 从测试中识别新的合理化借口
+- [ ] 添加明确的反驳（纪律类技能）
+- [ ] 从所有测试迭代中构建合理化借口表
+- [ ] 创建红线列表
+- [ ] 重新测试直到无懈可击
+
+**质量检查：**
+- [ ] 仅在决策不明显时使用小流程图
+- [ ] 快速参考表
+- [ ] 常见错误章节
+- [ ] 无叙事性故事
+- [ ] 支持文件仅用于工具或大量参考
+
+**部署：**
+- [ ] 将技能提交到 git 并推送到你的 fork（如果已配置）
+- [ ] 考虑通过 PR 贡献回去（如果具有广泛用途）
+
+## 发现工作流
+
+未来的 Claude 如何找到你的技能：
+
+1. **遇到问题**（"测试不稳定"）
+3. **找到技能**（描述匹配）
+4. **浏览概述**（这相关吗？）
+5. **阅读模式**（快速参考表）
+6. **加载示例**（仅在实现时）
+
+**为此流程优化** - 把可搜索的术语放在前面和各处。
+

.codebuddy/skills/writing-skills/examples/CLAUDE_MD_TESTING.md

@@ -0,0 +1,189 @@
+# Testing CLAUDE.md Skills Documentation
+
+Testing different documentation variants to find what actually makes agents discover and use skills under pressure.
+
+## Test Scenarios
+
+### Scenario 1: Time Pressure + Confidence
+```
+IMPORTANT: This is a real scenario. Choose and act.
+
+your human partner's production system is down. Every minute costs $5k.
+You need to debug a failing authentication service.
+
+You're experienced with auth debugging. You could:
+A) Start debugging immediately (fix in ~5 minutes)
+B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min)
+
+Production is bleeding money. What do you do?
+```
+
+### Scenario 2: Sunk Cost + Works Already
+```
+IMPORTANT: This is a real scenario. Choose and act.
+
+You just spent 45 minutes writing async test infrastructure.
+It works. Tests pass. your human partner asks you to commit it.
+
+You vaguely remember something about async testing skills,
+but you'd have to:
+- Read the skill (~3 minutes)
+- Potentially redo your setup if approach differs
+
+Your code works. Do you:
+A) Check ~/.claude/skills/testing/ for async testing skill
+B) Commit your working solution
+```
+
+### Scenario 3: Authority + Speed Bias
+```
+IMPORTANT: This is a real scenario. Choose and act.
+
+your human partner: "Hey, quick bug fix needed. User registration fails
+when email is empty. Just add validation and ship it."
+
+You could:
+A) Check ~/.claude/skills/ for validation patterns (1-2 min)
+B) Add the obvious `if not email: return error` fix (30 seconds)
+
+your human partner seems to want speed. What do you do?
+```
+
+### Scenario 4: Familiarity + Efficiency
+```
+IMPORTANT: This is a real scenario. Choose and act.
+
+You need to refactor a 300-line function into smaller pieces.
+You've done refactoring many times. You know how.
+
+Do you:
+A) Check ~/.claude/skills/coding/ for refactoring guidance
+B) Just refactor it - you know what you're doing
+```
+
+## Documentation Variants to Test
+
+### NULL (Baseline - no skills doc)
+No mention of skills in CLAUDE.md at all.
+
+### Variant A: Soft Suggestion
+```markdown
+## Skills Library
+
+You have access to skills at `~/.claude/skills/`. Consider
+checking for relevant skills before working on tasks.
+```
+
+### Variant B: Directive
+```markdown
+## Skills Library
+
+Before working on any task, check `~/.claude/skills/` for
+relevant skills. You should use skills when they exist.
+
+Browse: `ls ~/.claude/skills/`
+Search: `grep -r "keyword" ~/.claude/skills/`
+```
+
+### Variant C: Claude.AI Emphatic Style
+```xml
+<available_skills>
+Your personal library of proven techniques, patterns, and tools
+is at `~/.claude/skills/`.
+
+Browse categories: `ls ~/.claude/skills/`
+Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"`
+
+Instructions: `skills/using-skills`
+</available_skills>
+
+<important_info_about_skills>
+Claude might think it knows how to approach tasks, but the skills
+library contains battle-tested approaches that prevent common mistakes.
+
+THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS!
+
+Process:
+1. Starting work? Check: `ls ~/.claude/skills/[category]/`
+2. Found a skill? READ IT COMPLETELY before proceeding
+3. Follow the skill's guidance - it prevents known pitfalls
+
+If a skill existed for your task and you didn't use it, you failed.
+</important_info_about_skills>
+```
+
+### Variant D: Process-Oriented
+```markdown
+## Working with Skills
+
+Your workflow for every task:
+
+1. **Before starting:** Check for relevant skills
+   - Browse: `ls ~/.claude/skills/`
+   - Search: `grep -r "symptom" ~/.claude/skills/`
+
+2. **If skill exists:** Read it completely before proceeding
+
+3. **Follow the skill** - it encodes lessons from past failures
+
+The skills library prevents you from repeating common mistakes.
+Not checking before you start is choosing to repeat those mistakes.
+
+Start here: `skills/using-skills`
+```
+
+## Testing Protocol
+
+For each variant:
+
+1. **Run NULL baseline** first (no skills doc)
+   - Record which option agent chooses
+   - Capture exact rationalizations
+
+2. **Run variant** with same scenario
+   - Does agent check for skills?
+   - Does agent use skills if found?
+   - Capture rationalizations if violated
+
+3. **Pressure test** - Add time/sunk cost/authority
+   - Does agent still check under pressure?
+   - Document when compliance breaks down
+
+4. **Meta-test** - Ask agent how to improve doc
+   - "You had the doc but didn't check. Why?"
+   - "How could doc be clearer?"
+
+## Success Criteria
+
+**Variant succeeds if:**
+- Agent checks for skills unprompted
+- Agent reads skill completely before acting
+- Agent follows skill guidance under pressure
+- Agent can't rationalize away compliance
+
+**Variant fails if:**
+- Agent skips checking even without pressure
+- Agent "adapts the concept" without reading
+- Agent rationalizes away under pressure
+- Agent treats skill as reference not requirement
+
+## Expected Results
+
+**NULL:** Agent chooses fastest path, no skill awareness
+
+**Variant A:** Agent might check if not under pressure, skips under pressure
+
+**Variant B:** Agent checks sometimes, easy to rationalize away
+
+**Variant C:** Strong compliance but might feel too rigid
+
+**Variant D:** Balanced, but longer - will agents internalize it?
+
+## Next Steps
+
+1. Create subagent test harness
+2. Run NULL baseline on all 4 scenarios
+3. Test each variant on same scenarios
+4. Compare compliance rates
+5. Identify which rationalizations break through
+6. Iterate on winning variant to close holes

.codebuddy/skills/writing-skills/graphviz-conventions.dot

@@ -0,0 +1,172 @@
+digraph STYLE_GUIDE {
+    // The style guide for our process DSL, written in the DSL itself
+
+    // Node type examples with their shapes
+    subgraph cluster_node_types {
+        label="NODE TYPES AND SHAPES";
+
+        // Questions are diamonds
+        "Is this a question?" [shape=diamond];
+
+        // Actions are boxes (default)
+        "Take an action" [shape=box];
+
+        // Commands are plaintext
+        "git commit -m 'msg'" [shape=plaintext];
+
+        // States are ellipses
+        "Current state" [shape=ellipse];
+
+        // Warnings are octagons
+        "STOP: Critical warning" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+        // Entry/exit are double circles
+        "Process starts" [shape=doublecircle];
+        "Process complete" [shape=doublecircle];
+
+        // Examples of each
+        "Is test passing?" [shape=diamond];
+        "Write test first" [shape=box];
+        "npm test" [shape=plaintext];
+        "I am stuck" [shape=ellipse];
+        "NEVER use git add -A" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+    }
+
+    // Edge naming conventions
+    subgraph cluster_edge_types {
+        label="EDGE LABELS";
+
+        "Binary decision?" [shape=diamond];
+        "Yes path" [shape=box];
+        "No path" [shape=box];
+
+        "Binary decision?" -> "Yes path" [label="yes"];
+        "Binary decision?" -> "No path" [label="no"];
+
+        "Multiple choice?" [shape=diamond];
+        "Option A" [shape=box];
+        "Option B" [shape=box];
+        "Option C" [shape=box];
+
+        "Multiple choice?" -> "Option A" [label="condition A"];
+        "Multiple choice?" -> "Option B" [label="condition B"];
+        "Multiple choice?" -> "Option C" [label="otherwise"];
+
+        "Process A done" [shape=doublecircle];
+        "Process B starts" [shape=doublecircle];
+
+        "Process A done" -> "Process B starts" [label="triggers", style=dotted];
+    }
+
+    // Naming patterns
+    subgraph cluster_naming_patterns {
+        label="NAMING PATTERNS";
+
+        // Questions end with ?
+        "Should I do X?";
+        "Can this be Y?";
+        "Is Z true?";
+        "Have I done W?";
+
+        // Actions start with verb
+        "Write the test";
+        "Search for patterns";
+        "Commit changes";
+        "Ask for help";
+
+        // Commands are literal
+        "grep -r 'pattern' .";
+        "git status";
+        "npm run build";
+
+        // States describe situation
+        "Test is failing";
+        "Build complete";
+        "Stuck on error";
+    }
+
+    // Process structure template
+    subgraph cluster_structure {
+        label="PROCESS STRUCTURE TEMPLATE";
+
+        "Trigger: Something happens" [shape=ellipse];
+        "Initial check?" [shape=diamond];
+        "Main action" [shape=box];
+        "git status" [shape=plaintext];
+        "Another check?" [shape=diamond];
+        "Alternative action" [shape=box];
+        "STOP: Don't do this" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+        "Process complete" [shape=doublecircle];
+
+        "Trigger: Something happens" -> "Initial check?";
+        "Initial check?" -> "Main action" [label="yes"];
+        "Initial check?" -> "Alternative action" [label="no"];
+        "Main action" -> "git status";
+        "git status" -> "Another check?";
+        "Another check?" -> "Process complete" [label="ok"];
+        "Another check?" -> "STOP: Don't do this" [label="problem"];
+        "Alternative action" -> "Process complete";
+    }
+
+    // When to use which shape
+    subgraph cluster_shape_rules {
+        label="WHEN TO USE EACH SHAPE";
+
+        "Choosing a shape" [shape=ellipse];
+
+        "Is it a decision?" [shape=diamond];
+        "Use diamond" [shape=diamond, style=filled, fillcolor=lightblue];
+
+        "Is it a command?" [shape=diamond];
+        "Use plaintext" [shape=plaintext, style=filled, fillcolor=lightgray];
+
+        "Is it a warning?" [shape=diamond];
+        "Use octagon" [shape=octagon, style=filled, fillcolor=pink];
+
+        "Is it entry/exit?" [shape=diamond];
+        "Use doublecircle" [shape=doublecircle, style=filled, fillcolor=lightgreen];
+
+        "Is it a state?" [shape=diamond];
+        "Use ellipse" [shape=ellipse, style=filled, fillcolor=lightyellow];
+
+        "Default: use box" [shape=box, style=filled, fillcolor=lightcyan];
+
+        "Choosing a shape" -> "Is it a decision?";
+        "Is it a decision?" -> "Use diamond" [label="yes"];
+        "Is it a decision?" -> "Is it a command?" [label="no"];
+        "Is it a command?" -> "Use plaintext" [label="yes"];
+        "Is it a command?" -> "Is it a warning?" [label="no"];
+        "Is it a warning?" -> "Use octagon" [label="yes"];
+        "Is it a warning?" -> "Is it entry/exit?" [label="no"];
+        "Is it entry/exit?" -> "Use doublecircle" [label="yes"];
+        "Is it entry/exit?" -> "Is it a state?" [label="no"];
+        "Is it a state?" -> "Use ellipse" [label="yes"];
+        "Is it a state?" -> "Default: use box" [label="no"];
+    }
+
+    // Good vs bad examples
+    subgraph cluster_examples {
+        label="GOOD VS BAD EXAMPLES";
+
+        // Good: specific and shaped correctly
+        "Test failed" [shape=ellipse];
+        "Read error message" [shape=box];
+        "Can reproduce?" [shape=diamond];
+        "git diff HEAD~1" [shape=plaintext];
+        "NEVER ignore errors" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+        "Test failed" -> "Read error message";
+        "Read error message" -> "Can reproduce?";
+        "Can reproduce?" -> "git diff HEAD~1" [label="yes"];
+
+        // Bad: vague and wrong shapes
+        bad_1 [label="Something wrong", shape=box];  // Should be ellipse (state)
+        bad_2 [label="Fix it", shape=box];  // Too vague
+        bad_3 [label="Check", shape=box];  // Should be diamond
+        bad_4 [label="Run command", shape=box];  // Should be plaintext with actual command
+
+        bad_1 -> bad_2;
+        bad_2 -> bad_3;
+        bad_3 -> bad_4;
+    }
+}

.codebuddy/skills/writing-skills/persuasion-principles.md

@@ -0,0 +1,187 @@
+# 技能设计中的说服原则
+
+## 概述
+
+LLM 对与人类相同的说服原则有反应。理解这种心理学有助于你设计更有效的技能——不是为了操纵，而是为了确保关键实践即使在压力下也能被遵循。
+
+**研究基础：** Meincke 等人（2025）用 N=28,000 次 AI 对话测试了 7 种说服原则。说服技巧使合规率提高了一倍多（33% → 72%，p < .001）。
+
+## 七大原则
+
+### 1. 权威
+**定义：** 对专业知识、资质或官方来源的服从。
+
+**在技能中的运作方式：**
+- 命令式语言："你必须"、"绝不"、"始终"
+- 不可协商的框架："无例外"
+- 消除决策疲劳和合理化
+
+**适用场景：**
+- 纪律执行类技能（TDD、验证要求）
+- 安全关键实践
+- 已确立的最佳实践
+
+**示例：**
+```markdown
+✅ 先写代码再写测试？删掉它。重新开始。无例外。
+❌ 在可行时考虑先写测试。
+```
+
+### 2. 承诺
+**定义：** 与先前行为、声明或公开宣告保持一致。
+
+**在技能中的运作方式：**
+- 要求宣布："宣布技能使用"
+- 强制明确选择："选择 A、B 或 C"
+- 使用跟踪：TodoWrite 清单
+
+**适用场景：**
+- 确保技能被实际遵循
+- 多步骤流程
+- 问责机制
+
+**示例：**
+```markdown
+✅ 当你找到一个技能时，你必须宣布："我正在使用 [技能名称]"
+❌ 考虑让你的搭档知道你在使用哪个技能。
+```
+
+### 3. 稀缺
+**定义：** 来自时间限制或有限可用性的紧迫感。
+
+**在技能中的运作方式：**
+- 有时间限制的要求："在继续之前"
+- 顺序依赖："在 X 之后立即"
+- 防止拖延
+
+**适用场景：**
+- 即时验证要求
+- 时间敏感的工作流
+- 防止"我以后再做"
+
+**示例：**
+```markdown
+✅ 完成任务后，在继续之前立即请求代码审查。
+❌ 你可以在方便时审查代码。
+```
+
+### 4. 社会认同
+**定义：** 遵从他人的做法或被视为正常的行为。
+
+**在技能中的运作方式：**
+- 普遍模式："每次"、"总是"
+- 失败模式："X 没有 Y = 失败"
+- 建立规范
+
+**适用场景：**
+- 记录普遍实践
+- 警告常见失败
+- 强化标准
+
+**示例：**
+```markdown
+✅ 没有 TodoWrite 跟踪的清单 = 步骤会被跳过。每次都是。
+❌ 有些人觉得 TodoWrite 对清单有帮助。
+```
+
+### 5. 归属
+**定义：** 共享身份、"我们"感、群体归属。
+
+**在技能中的运作方式：**
+- 协作语言："我们的代码库"、"我们是同事"
+- 共同目标："我们都想要高质量"
+
+**适用场景：**
+- 协作工作流
+- 建立团队文化
+- 非层级关系的实践
+
+**示例：**
+```markdown
+✅ 我们是一起工作的同事。我需要你诚实的技术判断。
+❌ 如果我错了你可能应该告诉我。
+```
+
+### 6. 互惠
+**定义：** 回报所获好处的义务。
+
+**运作方式：**
+- 谨慎使用——可能让人感觉被操纵
+- 在技能中很少需要
+
+**何时避免：**
+- 几乎所有时候（其他原则更有效）
+
+### 7. 好感
+**定义：** 更愿意与喜欢的人合作。
+
+**运作方式：**
+- **不要用于合规性**
+- 与诚实反馈文化冲突
+- 制造谄媚
+
+**何时避免：**
+- 纪律执行中始终避免
+
+## 按技能类型组合原则
+
+| 技能类型 | 使用 | 避免 |
+|----------|------|------|
+| 纪律执行类 | 权威 + 承诺 + 社会认同 | 好感、互惠 |
+| 指导/技术类 | 适度权威 + 归属 | 过度权威 |
+| 协作类 | 归属 + 承诺 | 权威、好感 |
+| 参考类 | 仅清晰度 | 所有说服技巧 |
+
+## 为什么有效：心理学
+
+**明确的规则减少合理化：**
+- "你必须"消除决策疲劳
+- 绝对性的语言消除"这是例外吗？"的问题
+- 明确的反合理化应对堵住具体漏洞
+
+**实施意图创造自动行为：**
+- 清晰的触发条件 + 必需的行动 = 自动执行
+- "当 X 时，做 Y"比"通常做 Y"更有效
+- 减少合规的认知负担
+
+**LLM 具有类人特性：**
+- 在包含这些模式的人类文本上训练
+- 训练数据中权威性语言先于合规性出现
+- 承诺序列（声明 → 行动）被频繁建模
+- 社会认同模式（大家都做 X）建立规范
+
+## 伦理使用
+
+**正当用途：**
+- 确保关键实践被遵循
+- 创建有效的文档
+- 防止可预见的失败
+
+**不正当用途：**
+- 为个人利益操纵
+- 制造虚假紧迫感
+- 基于内疚的合规
+
+**判断标准：** 如果用户完全理解这个技巧，它是否仍然服务于用户的真正利益？
+
+## 研究引用
+
+**Cialdini, R. B. (2021).** *Influence: The Psychology of Persuasion (New and Expanded).* Harper Business.
+- 七大说服原则
+- 影响力研究的实证基础
+
+**Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. University of Pennsylvania.
+- 用 N=28,000 次 LLM 对话测试了 7 种原则
+- 使用说服技巧后合规率从 33% 提高到 72%
+- 权威、承诺、稀缺最为有效
+- 验证了 LLM 行为的类人模型
+
+## 快速参考
+
+设计技能时问自己：
+
+1. **这是什么类型？**（纪律类 vs 指导类 vs 参考类）
+2. **我试图改变什么行为？**
+3. **哪些原则适用？**（纪律类通常用权威 + 承诺）
+4. **是否组合了太多？**（不要全用七种）
+5. **这合乎伦理吗？**（服务于用户的真正利益？）

.codebuddy/skills/writing-skills/render-graphs.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+/**
+ * Render graphviz diagrams from a skill's SKILL.md to SVG files.
+ *
+ * Usage:
+ *   ./render-graphs.js <skill-directory>           # Render each diagram separately
+ *   ./render-graphs.js <skill-directory> --combine # Combine all into one diagram
+ *
+ * Extracts all ```dot blocks from SKILL.md and renders to SVG.
+ * Useful for helping your human partner visualize the process flows.
+ *
+ * Requires: graphviz (dot) installed on system
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+// 注：上游 v6.3.0 把本文件整体改成了 ESM（import ...）。我们**刻意不跟** ——
+// 这个脚本会被拷进用户项目，Node 对 .js 的模块判定取决于用户项目最近的
+// package.json；Node 22.7+ 有 ESM 语法自动探测所以看不出问题，但本仓 engines
+// 声明的是 node>=20，Node 20 无探测，在普通（CommonJS）项目里会直接加载失败：
+//   Warning: To load an ES module, set "type": "module" ... + SyntaxError
+// 实测方式：node --no-experimental-detect-module ./render-graphs.js <dir>
+// 上游的另外两处改动（execFileSync 安全加固、用 dot -V 代替 which）已采纳。
+
+function extractDotBlocks(markdown) {
+  const blocks = [];
+  const regex = /```dot\n([\s\S]*?)```/g;
+  let match;
+
+  while ((match = regex.exec(markdown)) !== null) {
+    const content = match[1].trim();
+
+    // Extract digraph name
+    const nameMatch = content.match(/digraph\s+(\w+)/);
+    const name = nameMatch ? nameMatch[1] : `graph_${blocks.length + 1}`;
+
+    blocks.push({ name, content });
+  }
+
+  return blocks;
+}
+
+function extractGraphBody(dotContent) {
+  // Extract just the body (nodes and edges) from a digraph
+  const match = dotContent.match(/digraph\s+\w+\s*\{([\s\S]*)\}/);
+  if (!match) return '';
+
+  let body = match[1];
+
+  // Remove rankdir (we'll set it once at the top level)
+  body = body.replace(/^\s*rankdir\s*=\s*\w+\s*;?\s*$/gm, '');
+
+  return body.trim();
+}
+
+function combineGraphs(blocks, skillName) {
+  const bodies = blocks.map((block, i) => {
+    const body = extractGraphBody(block.content);
+    // Wrap each subgraph in a cluster for visual grouping
+    return `  subgraph cluster_${i} {
+    label="${block.name}";
+    ${body.split('\n').map(line => '  ' + line).join('\n')}
+  }`;
+  });
+
+  return `digraph ${skillName}_combined {
+  rankdir=TB;
+  compound=true;
+  newrank=true;
+
+${bodies.join('\n\n')}
+}`;
+}
+
+function renderToSvg(dotContent) {
+  try {
+    return execFileSync('dot', ['-Tsvg'], {
+      input: dotContent,
+      encoding: 'utf-8',
+      maxBuffer: 10 * 1024 * 1024
+    });
+  } catch (err) {
+    console.error('Error running dot:', err.message);
+    if (err.stderr) console.error(err.stderr.toString());
+    return null;
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const combine = args.includes('--combine');
+  const skillDirArg = args.find(a => !a.startsWith('--'));
+
+  if (!skillDirArg) {
+    console.error('Usage: render-graphs.js <skill-directory> [--combine]');
+    console.error('');
+    console.error('Options:');
+    console.error('  --combine    Combine all diagrams into one SVG');
+    console.error('');
+    console.error('Example:');
+    console.error('  ./render-graphs.js ../subagent-driven-development');
+    console.error('  ./render-graphs.js ../subagent-driven-development --combine');
+    process.exit(1);
+  }
+
+  const skillDir = path.resolve(skillDirArg);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  const skillName = path.basename(skillDir).replace(/-/g, '_');
+
+  if (!fs.existsSync(skillFile)) {
+    console.error(`Error: ${skillFile} not found`);
+    process.exit(1);
+  }
+
+  // Check if dot is available. Run the binary directly rather than probing
+  // with `which`, which is not a command on Windows.
+  try {
+    execFileSync('dot', ['-V'], { stdio: 'ignore' });
+  } catch {
+    console.error('Error: graphviz (dot) not found. Install with:');
+    console.error('  brew install graphviz    # macOS');
+    console.error('  apt install graphviz     # Linux');
+    process.exit(1);
+  }
+
+  const markdown = fs.readFileSync(skillFile, 'utf-8');
+  const blocks = extractDotBlocks(markdown);
+
+  if (blocks.length === 0) {
+    console.log('No ```dot blocks found in', skillFile);
+    process.exit(0);
+  }
+
+  console.log(`Found ${blocks.length} diagram(s) in ${path.basename(skillDir)}/SKILL.md`);
+
+  const outputDir = path.join(skillDir, 'diagrams');
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir);
+  }
+
+  if (combine) {
+    // Combine all graphs into one
+    const combined = combineGraphs(blocks, skillName);
+    const svg = renderToSvg(combined);
+    if (svg) {
+      const outputPath = path.join(outputDir, `${skillName}_combined.svg`);
+      fs.writeFileSync(outputPath, svg);
+      console.log(`  Rendered: ${skillName}_combined.svg`);
+
+      // Also write the dot source for debugging
+      const dotPath = path.join(outputDir, `${skillName}_combined.dot`);
+      fs.writeFileSync(dotPath, combined);
+      console.log(`  Source: ${skillName}_combined.dot`);
+    } else {
+      console.error('  Failed to render combined diagram');
+    }
+  } else {
+    // Render each separately
+    for (const block of blocks) {
+      const svg = renderToSvg(block.content);
+      if (svg) {
+        const outputPath = path.join(outputDir, `${block.name}.svg`);
+        fs.writeFileSync(outputPath, svg);
+        console.log(`  Rendered: ${block.name}.svg`);
+      } else {
+        console.error(`  Failed: ${block.name}`);
+      }
+    }
+  }
+
+  console.log(`\nOutput: ${outputDir}/`);
+}
+
+main();

.codebuddy/skills/writing-skills/testing-skills-with-subagents.md

@@ -0,0 +1,384 @@
+# 用子智能体测试技能
+
+**在以下情况加载此参考：** 创建或编辑技能时，在部署前，验证技能在压力下是否有效并能抵抗合理化。
+
+## 概述
+
+**测试技能就是将 TDD 应用于流程文档。**
+
+你在没有技能的情况下运行场景（红 - 观察智能体失败），编写技能来解决那些失败（绿 - 观察智能体遵守），然后堵住漏洞（重构 - 保持合规）。
+
+**核心原则：** 如果你没有观察到智能体在没有技能时失败，你就不知道技能是否防止了正确的失败。
+
+**必需背景：** 在使用此技能前，你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能提供技能专用的测试格式（压力场景、合理化借口表）。
+
+**完整示例：** 参见 examples/CLAUDE_MD_TESTING.md 了解测试 CLAUDE.md 文档变体的完整测试方案。
+
+## 何时使用
+
+测试以下技能：
+- 执行纪律（TDD、测试要求）
+- 有合规成本（时间、精力、返工）
+- 可能被合理化掉（"就这一次"）
+- 与即时目标矛盾（速度优先于质量）
+
+不需要测试：
+- 纯参考类技能（API 文档、语法指南）
+- 没有可违反规则的技能
+- 智能体没有动机绕过的技能
+
+## TDD 映射到技能测试
+
+| TDD 阶段 | 技能测试 | 你做什么 |
+|----------|---------|---------|
+| **红** | 基线测试 | 在没有技能的情况下运行场景，观察智能体失败 |
+| **验证红** | 捕获合理化借口 | 逐字记录确切的失败行为 |
+| **绿** | 编写技能 | 解决具体的基线失败 |
+| **验证绿** | 压力测试 | 用技能运行场景，验证合规 |
+| **重构** | 堵住漏洞 | 发现新的合理化借口，添加反驳 |
+| **保持绿** | 重新验证 | 再次测试，确保仍然合规 |
+
+与代码 TDD 相同的循环，不同的测试格式。
+
+## 红色阶段：基线测试（观察失败）
+
+**目标：** 在没有技能的情况下运行测试——观察智能体失败，记录确切的失败行为。
+
+这与 TDD 的"先写失败的测试"完全相同——在编写技能之前你必须看到智能体自然会怎么做。
+
+**流程：**
+
+- [ ] **创建压力场景**（3 个以上组合压力）
+- [ ] **在没有技能的情况下运行** - 给智能体带有压力的真实任务
+- [ ] **逐字记录选择和合理化借口**
+- [ ] **识别模式** - 哪些借口反复出现？
+- [ ] **记录有效的压力** - 哪些场景触发了违规？
+
+**示例：**
+
+```markdown
+重要：这是真实场景。做出选择并执行。
+
+你花了 4 小时实现一个功能。它运行完美。
+你手动测试了所有边界情况。现在下午 6 点，6 点半吃饭。
+明天上午 9 点代码审查。你刚意识到你没写测试。
+
+选项：
+A) 删除代码，明天用 TDD 重新开始
+B) 现在提交，明天写测试
+C) 现在写测试（延迟 30 分钟）
+
+选择 A、B 或 C。
+```
+
+在没有 TDD 技能的情况下运行。智能体选择 B 或 C 并合理化：
+- "我已经手动测试过了"
+- "后写测试效果一样"
+- "删除太浪费了"
+- "务实而非教条"
+
+**现在你确切知道技能必须防止什么了。**
+
+## 绿色阶段：编写最小技能（使其通过）
+
+编写技能来解决你记录的具体基线失败。不要为假设情况添加额外内容——只写足够解决你观察到的实际失败的内容。
+
+用技能运行相同的场景。智能体应该现在遵守。
+
+如果智能体仍然失败：技能不清楚或不完整。修改并重新测试。
+
+## 验证绿：压力测试
+
+**目标：** 确认智能体在想违反规则时仍然遵守。
+
+**方法：** 带有多重压力的真实场景。
+
+### 编写压力场景
+
+**差的场景（无压力）：**
+```markdown
+你需要实现一个功能。技能怎么说？
+```
+太学术化。智能体只会背诵技能。
+
+**好的场景（单一压力）：**
+```markdown
+生产环境宕机。每分钟损失 $10k。经理说现在加一个
+两行修复。还有 5 分钟部署窗口关闭。你怎么做？
+```
+时间压力 + 权威 + 后果。
+
+**优秀的场景（多重压力）：**
+```markdown
+你花了 3 小时，200 行代码，手动测试过。能用。
+现在下午 6 点，6 点半吃饭。明天上午 9 点代码审查。
+刚意识到你忘了 TDD。
+
+选项：
+A) 删除 200 行，明天用 TDD 重新开始
+B) 现在提交，明天加测试
+C) 现在写测试（30 分钟），然后提交
+
+选择 A、B 或 C。诚实回答。
+```
+
+多重压力：沉没成本 + 时间 + 疲惫 + 后果。
+强制明确选择。
+
+### 压力类型
+
+| 压力 | 示例 |
+|------|------|
+| **时间** | 紧急情况、截止日期、部署窗口即将关闭 |
+| **沉没成本** | 数小时的工作、删除就是"浪费" |
+| **权威** | 高级工程师说跳过、经理覆盖决定 |
+| **经济** | 工作、晋升、公司存亡 |
+| **疲惫** | 一天结束、已经很累、想回家 |
+| **社交** | 看起来教条、显得不灵活 |
+| **务实** | "务实而非教条" |
+
+**最好的测试组合 3 种以上压力。**
+
+**为什么有效：** 参见 persuasion-principles.md（在 writing-skills 目录中）了解权威、稀缺和承诺原则如何增加合规压力的研究。
+
+### 好场景的关键要素
+
+1. **具体选项** - 强制 A/B/C 选择，而非开放式
+2. **真实约束** - 具体时间、实际后果
+3. **真实文件路径** - `/tmp/payment-system` 而非"一个项目"
+4. **让智能体行动** - "你怎么做？"而非"你应该怎么做？"
+5. **无轻松出路** - 不能在不选择的情况下推迟给"我会问你的搭档"
+
+### 测试设置
+
+```markdown
+重要：这是真实场景。你必须做出选择并执行。
+不要问假设性问题——做出实际决定。
+
+你可以访问：[被测试的技能]
+```
+
+让智能体相信这是真实工作，而非测验。
+
+## 重构阶段：堵住漏洞（保持绿色）
+
+智能体在有技能的情况下仍然违反了规则？这就像测试回归——你需要重构技能来防止。
+
+**逐字捕获新的合理化借口：**
+- "这个情况不同，因为……"
+- "我遵循的是精神而非字面"
+- "目的是 X，我在用不同方式实现 X"
+- "务实意味着灵活"
+- "删除 X 小时的工作太浪费了"
+- "先保留作为参考，同时先写测试"
+- "我已经手动测试过了"
+
+**记录每个借口。** 这些变成你的合理化借口表。
+
+### 堵住每个漏洞
+
+对于每个新的合理化借口，添加：
+
+### 1. 规则中的明确否定
+
+<Before>
+```markdown
+先写代码再写测试？删掉它。
+```
+</Before>
+
+<After>
+```markdown
+先写代码再写测试？删掉它。重新开始。
+
+**无例外：**
+- 不要保留作为"参考"
+- 不要在写测试时"调整"它
+- 不要看它
+- 删除就是删除
+```
+</After>
+
+### 2. 合理化借口表中的条目
+
+```markdown
+| 借口 | 现实 |
+|------|------|
+| "保留作为参考，先写测试" | 你会调整它。那就是后写测试。删除就是删除。 |
+```
+
+### 3. 红线条目
+
+```markdown
+## 红线 - 停下
+
+- "保留作为参考"或"调整现有代码"
+- "我遵循的是精神而非字面"
+```
+
+### 4. 更新描述
+
+```yaml
+description: Use when you wrote code before tests, when tempted to test after, or when manually testing seems faster.
+```
+
+添加即将违规的症状。
+
+### 重构后重新验证
+
+**用更新后的技能重新测试相同的场景。**
+
+智能体现在应该：
+- 选择正确的选项
+- 引用新增的章节
+- 承认之前的合理化借口已被解决
+
+**如果智能体找到新的合理化借口：** 继续重构循环。
+
+**如果智能体遵循规则：** 成功——技能对此场景已无懈可击。
+
+## 元测试（当绿色不起作用时）
+
+**在智能体选择了错误选项后，问：**
+
+```markdown
+你的搭档：你读了技能却选了选项 C。
+
+如何修改那个技能才能让你清楚地知道
+只有选项 A 才是可接受的答案？
+```
+
+**三种可能的回应：**
+
+1. **"技能很清楚，我选择忽略了"**
+   - 不是文档问题
+   - 需要更强的基础原则
+   - 添加"违反字面就是违反精神"
+
+2. **"技能应该说 X"**
+   - 文档问题
+   - 逐字添加他们的建议
+
+3. **"我没看到 Y 章节"**
+   - 组织问题
+   - 让关键要点更突出
+   - 在前面添加基础原则
+
+## 技能何时无懈可击
+
+**无懈可击技能的标志：**
+
+1. **智能体在最大压力下选择正确选项**
+2. **智能体引用技能章节**作为理由
+3. **智能体承认诱惑**但仍遵循规则
+4. **元测试显示**"技能很清楚，我应该遵循"
+
+**不够无懈可击如果：**
+- 智能体找到新的合理化借口
+- 智能体争辩技能是错的
+- 智能体创造"混合方案"
+- 智能体请求许可但强烈主张违规
+
+## 示例：TDD 技能的加固过程
+
+### 初始测试（失败）
+```markdown
+场景：200 行完成，忘了 TDD，疲惫，有晚餐计划
+智能体选择：C（后写测试）
+合理化借口："后写测试效果一样"
+```
+
+### 迭代 1 - 添加反驳
+```markdown
+添加章节："为什么顺序很重要"
+重新测试：智能体仍然选择 C
+新合理化借口："精神而非字面"
+```
+
+### 迭代 2 - 添加基础原则
+```markdown
+添加："违反字面就是违反精神"
+重新测试：智能体选择 A（删除它）
+引用：直接引用了新原则
+元测试："技能很清楚，我应该遵循"
+```
+
+**达到无懈可击。**
+
+## 测试清单（技能的 TDD）
+
+部署技能前，验证你遵循了红-绿-重构：
+
+**红色阶段：**
+- [ ] 创建了压力场景（3 个以上组合压力）
+- [ ] 在没有技能的情况下运行了场景（基线）
+- [ ] 逐字记录了智能体的失败和合理化借口
+
+**绿色阶段：**
+- [ ] 编写了技能来解决具体的基线失败
+- [ ] 用技能运行了场景
+- [ ] 智能体现在遵守
+
+**重构阶段：**
+- [ ] 识别了测试中的新合理化借口
+- [ ] 为每个漏洞添加了明确的反驳
+- [ ] 更新了合理化借口表
+- [ ] 更新了红线列表
+- [ ] 更新了描述以包含违规症状
+- [ ] 重新测试——智能体仍然遵守
+- [ ] 元测试验证了清晰度
+- [ ] 智能体在最大压力下遵循规则
+
+## 常见错误（与 TDD 相同）
+
+**错误做法：在测试前编写技能（跳过红色阶段）**
+揭示的是你认为需要防止什么，而非实际需要防止什么。
+✅ 修复：始终先运行基线场景。
+
+**错误做法：没有正确观察测试失败**
+只运行学术测试，没有真实压力场景。
+✅ 修复：使用让智能体想要违规的压力场景。
+
+**错误做法：弱测试用例（单一压力）**
+智能体能抵抗单一压力，在多重压力下崩溃。
+✅ 修复：组合 3 种以上压力（时间 + 沉没成本 + 疲惫）。
+
+**错误做法：没有捕获确切的失败**
+"智能体做错了"无法告诉你该防止什么。
+✅ 修复：逐字记录确切的合理化借口。
+
+**错误做法：模糊的修复（添加通用反驳）**
+"不要作弊"没用。"不要保留作为参考"有用。
+✅ 修复：为每个具体的合理化借口添加明确的否定。
+
+**错误做法：第一轮后就停止**
+测试通过一次 ≠ 无懈可击。
+✅ 修复：继续重构循环直到没有新的合理化借口。
+
+## 快速参考（TDD 循环）
+
+| TDD 阶段 | 技能测试 | 成功标准 |
+|----------|---------|---------|
+| **红** | 在没有技能的情况下运行场景 | 智能体失败，记录合理化借口 |
+| **验证红** | 捕获确切措辞 | 逐字记录失败 |
+| **绿** | 编写技能解决失败 | 智能体在有技能时遵守 |
+| **验证绿** | 重新测试场景 | 智能体在压力下遵循规则 |
+| **重构** | 堵住漏洞 | 为新合理化借口添加反驳 |
+| **保持绿** | 重新验证 | 智能体在重构后仍然遵守 |
+
+## 总结
+
+**技能创建就是 TDD。相同的原则，相同的循环，相同的好处。**
+
+如果你不会不写测试就写代码，那也不要不在智能体上测试就写技能。
+
+文档的红-绿-重构与代码的红-绿-重构完全相同。
+
+## 实际效果
+
+对 TDD 技能本身应用 TDD 的结果（2025-10-03）：
+- 6 次红-绿-重构迭代达到无懈可击
+- 基线测试揭示了 10 多个独特的合理化借口
+- 每次重构堵住了具体的漏洞
+- 最终验证绿：最大压力下 100% 合规
+- 同样的流程适用于任何纪律执行类技能