specops 0.2.2 → 0.2.4

package/.opencode/skills/writing-skills/SKILL.md

@@ -0,0 +1,654 @@
+---
+name: writing-skills
+description: 创建新 skill、编辑现有 skill 或在部署前验证 skill 是否有效时使用
+---
+
+# 编写 Skill
+
+## 概述
+
+**编写 skill 就是把测试驱动开发应用到流程文档上。**
+
+**个人 skill 放在 `.opencode/skills/<skill名>/SKILL.md`**
+
+你写测试用例（用子 agent 的压力场景），看它们失败（基线行为），写 skill（文档），看测试通过（agent 遵守），然后重构（堵住漏洞）。
+
+**核心原则：** 如果你没有看到 agent 在没有 skill 的情况下失败，你就不知道 skill 是否教了正确的东西。
+
+**必要背景：** 你必须理解 specops:test-driven-development 才能使用这个 skill。那个 skill 定义了基本的红-绿-重构循环。这个 skill 把 TDD 适配到文档上。
+
+**官方指南：** 关于 Anthropic 官方的 skill 编写最佳实践，参见 anthropic-best-practices.md。本文档提供了补充 TDD 方法的额外模式和指南。
+
+## 什么是 Skill？
+
+**skill** 是经过验证的技术、模式或工具的参考指南。Skill 帮助未来的 Claude 实例找到并应用有效的方法。
+
+**Skill 是：** 可复用的技术、模式、工具、参考指南
+
+**Skill 不是：** 关于你某次如何解决问题的叙事
+
+## TDD 映射到 Skill 创建
+
+| TDD 概念 | Skill 创建 |
+|-----------|-----------|
+| **测试用例** | 用子 agent 的压力场景 |
+| **生产代码** | Skill 文档（SKILL.md） |
+| **测试失败（红灯）** | Agent 在没有 skill 时违反规则（基线） |
+| **测试通过（绿灯）** | Agent 在有 skill 时遵守规则 |
+| **重构** | 堵住漏洞同时保持合规 |
+| **先写测试** | 在写 skill 之前运行基线场景 |
+| **看它失败** | 记录 agent 使用的确切合理化借口 |
+| **最少代码** | 写 skill 针对那些具体的违规 |
+| **看它通过** | 验证 agent 现在遵守了 |
+| **重构循环** | 发现新的合理化借口 → 堵住 → 重新验证 |
+
+整个 skill 创建过程遵循红-绿-重构。
+
+## 何时创建 Skill
+
+**创建条件：**
+- 技术对你来说不是直觉上显而易见的
+- 你会在不同项目中再次引用它
+- 模式广泛适用（不是项目特定的）
+- 其他人会受益
+
+**不要创建：**
+- 一次性解决方案
+- 其他地方有良好文档的标准实践
+- 项目特定的约定（放在 CLAUDE.md 中）
+- 机械约束（如果能用正则/验证自动化，就自动化，文档留给需要判断的事情）
+
+## Skill 类型
+
+### 技术
+有具体步骤的方法（condition-based-waiting、root-cause-tracing）
+
+### 模式
+思考问题的方式（flatten-with-flags、test-invariants）
+
+### 参考
+API 文档、语法指南、工具文档（office docs）
+
+## 目录结构
+
+```
+skills/
+  skill-name/
+    SKILL.md              # 主参考文档（必需）
+    supporting-file.*     # 仅在需要时
+```
+
+**扁平命名空间** - 所有 skill 在一个可搜索的命名空间中
+
+**单独文件用于：**
+1. **大量参考内容**（100+ 行）- API 文档、全面的语法
+2. **可复用工具** - 脚本、工具、模板
+
+**保持内联：**
+- 原则和概念
+- 代码模式（< 50 行）
+- 其他所有内容
+
+## SKILL.md 结构
+
+**Frontmatter（YAML）：**
+- 只支持两个字段：`name` 和 `description`
+- 总共最多 1024 个字符
+- `name`：只使用字母、数字和连字符（不要括号、特殊字符）
+- `description`：第三人称，只描述何时使用（不是它做什么）
+  - 以"...时使用"开头，聚焦触发条件
+  - 包含具体的症状、情况和上下文
+  - **绝不总结 skill 的流程或工作流**（见 CSO 部分了解原因）
+  - 尽量控制在 500 字符以内
+
+```markdown
+---
+name: Skill-Name-With-Hyphens
+description: [具体触发条件和症状]时使用
+---
+
+# Skill 名称
+
+## 概述
+这是什么？核心原则用 1-2 句话。
+
+## 何时使用
+[如果决策不明显，用小型内联流程图]
+
+症状和用例的要点列表
+何时不使用
+
+## 核心模式（用于技术/模式类）
+前后代码对比
+
+## 快速参考
+表格或要点，方便扫描常见操作
+
+## 实现
+简单模式内联代码
+大量参考或可复用工具链接到文件
+
+## 常见错误
+什么会出错 + 修复方法
+
+## 真实世界的影响（可选）
+具体结果
+```
+
+
+## Claude 搜索优化（CSO）
+
+**对发现至关重要：** 未来的 Claude 需要能找到你的 skill
+
+### 1. 丰富的 Description 字段
+
+**目的：** Claude 读取 description 来决定为给定任务加载哪些 skill。让它回答："我现在应该读这个 skill 吗？"
+
+**格式：** 以"...时使用"开头，聚焦触发条件
+
+**关键：Description = 何时使用，不是 Skill 做什么**
+
+Description 应该只描述触发条件。不要在 description 中总结 skill 的流程或工作流。
+
+**为什么这很重要：** 测试发现，当 description 总结了 skill 的工作流时，Claude 可能会按照 description 行事而不是阅读完整的 skill 内容。一个说"任务之间做代码审查"的 description 导致 Claude 只做了一次审查，尽管 skill 的流程图清楚地显示了两次审查（规格合规性检查，然后代码质量检查）。
+
+当 description 改为只说"在当前会话中执行有独立任务的实现计划时使用"（没有工作流总结）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。
+
+**陷阱：** 总结工作流的 description 创建了 Claude 会走的捷径。Skill 正文变成了 Claude 跳过的文档。
+
+```yaml
+# ❌ 坏：总结了工作流 - Claude 可能按这个行事而不是读 skill
+description: 执行计划时使用 - 每个任务分派子 agent 并在任务之间做代码审查
+
+# ❌ 坏：太多流程细节
+description: TDD 时使用 - 先写测试，看它失败，写最少代码，重构
+
+# ✅ 好：只有触发条件，没有工作流总结
+description: 在当前会话中执行有独立任务的实现计划时使用
+
+# ✅ 好：只有触发条件
+description: 实现任何功能或修复bug之前使用，在编写实现代码之前
+```
+
+**内容：**
+- 使用具体的触发器、症状和表明此 skill 适用的情况
+- 描述问题（竞态条件、不一致行为）而不是语言特定的症状（setTimeout、sleep）
+- 保持触发器技术无关，除非 skill 本身是技术特定的
+- 如果 skill 是技术特定的，在触发器中明确说明
+- 用第三人称写（注入到系统提示中）
+- **绝不总结 skill 的流程或工作流**
+
+```yaml
+# ❌ 坏：太抽象、模糊，没有包含何时使用
+description: 用于异步测试
+
+# ❌ 坏：第一人称
+description: 当异步测试不稳定时我可以帮你
+
+# ❌ 坏：提到了技术但 skill 不是特定于它的
+description: 当测试使用 setTimeout/sleep 且不稳定时使用
+
+# ✅ 好：以"...时使用"开头，描述问题，没有工作流
+description: 当测试有竞态条件、时序依赖或通过/失败不一致时使用
+
+# ✅ 好：技术特定的 skill 有明确的触发器
+description: 使用 React Router 处理认证重定向时使用
+```
+
+### 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 和频繁引用的 skill 加载到每个对话中。每个 token 都很重要。
+
+**目标字数：**
+- getting-started 工作流：每个 <150 词
+- 频繁加载的 skill：总共 <200 词
+- 其他 skill：<500 词（仍然要简洁）
+
+**技巧：**
+
+**把细节移到工具帮助中：**
+```bash
+# ❌ 坏：在 SKILL.md 中记录所有标志
+search-conversations 支持 --text, --both, --after DATE, --before DATE, --limit N
+
+# ✅ 好：引用 --help
+search-conversations 支持多种模式和过滤器。运行 --help 了解详情。
+```
+
+**使用交叉引用：**
+```markdown
+# ❌ 坏：重复工作流细节
+搜索时，用模板分派子 agent...
+[20 行重复的指令]
+
+# ✅ 好：引用其他 skill
+始终使用子 agent（节省 50-100 倍上下文）。必须：使用 [other-skill-name] 的工作流。
+```
+
+**压缩示例：**
+```markdown
+# ❌ 坏：冗长的示例（42 词）
+你的人类搭档："我们之前在 React Router 中怎么处理认证错误的？"
+你：我会搜索过去的对话，找 React Router 认证模式。
+[用搜索查询分派子 agent："React Router authentication error handling 401"]
+
+# ✅ 好：最小示例（20 词）
+搭档："我们之前怎么处理 React Router 的认证错误？"
+你：搜索中...
+[分派子 agent → 综合]
+```
+
+**消除冗余：**
+- 不要重复交叉引用的 skill 中已有的内容
+- 不要解释命令本身就能说明的东西
+- 不要包含同一模式的多个示例
+
+**验证：**
+```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`
+- 主动的，描述你正在做的动作
+
+### 4. 交叉引用其他 Skill
+
+**当编写引用其他 skill 的文档时：**
+
+只使用 skill 名称，带明确的要求标记：
+- ✅ 好：`**必需子 SKILL：** 使用 specops:test-driven-development`
+- ✅ 好：`**必要背景：** 你必须理解 specops: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` 将 skill 的流程图渲染为 SVG：
+```bash
+./render-graphs.js ../some-skill           # 每个图单独渲染
+./render-graphs.js ../some-skill --combine # 所有图合并到一个 SVG
+```
+
+## 代码示例
+
+**一个优秀的示例胜过许多平庸的**
+
+选择最相关的语言：
+- 测试技术 → TypeScript/JavaScript
+- 系统调试 → Shell/Python
+- 数据处理 → Python
+
+**好的示例：**
+- 完整且可运行
+- 注释良好，解释为什么
+- 来自真实场景
+- 清晰展示模式
+- 可以直接改编（不是通用模板）
+
+**不要：**
+- 用 5 种以上语言实现
+- 创建填空模板
+- 写人造的示例
+
+你擅长移植，一个好示例就够了。
+
+## 文件组织
+
+### 自包含 Skill
+```
+defense-in-depth/
+  SKILL.md    # 所有内容内联
+```
+适用场景：所有内容都能放下，不需要大量参考
+
+### 带可复用工具的 Skill
+```
+condition-based-waiting/
+  SKILL.md    # 概述 + 模式
+  example.ts  # 可改编的工作辅助函数
+```
+适用场景：工具是可复用代码，不只是叙述
+
+### 带大量参考的 Skill
+```
+pptx/
+  SKILL.md       # 概述 + 工作流
+  pptxgenjs.md   # 600 行 API 参考
+  ooxml.md       # 500 行 XML 结构
+  scripts/       # 可执行工具
+```
+适用场景：参考材料太大无法内联
+
+## 铁律（与 TDD 相同）
+
+```
+没有先写失败测试，就不能写 SKILL
+```
+
+这适用于新 skill 和对现有 skill 的编辑。
+
+先写了 skill 再测试？删掉。从头来过。
+编辑 skill 没有测试？同样违规。
+
+**没有例外：**
+- 不适用于"简单的添加"
+- 不适用于"只是加个章节"
+- 不适用于"文档更新"
+- 不要把未测试的变更留作"参考"
+- 不要在运行测试时"改编"
+- 删除就是删除
+
+**必要背景：** specops:test-driven-development skill 解释了为什么这很重要。同样的原则适用于文档。
+
+## 测试所有 Skill 类型
+
+不同的 skill 类型需要不同的测试方法：
+
+### 纪律执行类 Skill（规则/要求）
+
+**示例：** TDD、verification-before-completion、designing-before-coding
+
+**测试方法：**
+- 学术问题：他们理解规则吗？
+- 压力场景：他们在压力下遵守吗？
+- 多重压力组合：时间 + 沉没成本 + 疲劳
+- 识别合理化借口并添加明确的反驳
+
+**成功标准：** Agent 在最大压力下遵守规则
+
+### 技术类 Skill（操作指南）
+
+**示例：** condition-based-waiting、root-cause-tracing、defensive-programming
+
+**测试方法：**
+- 应用场景：他们能正确应用技术吗？
+- 变体场景：他们能处理边界情况吗？
+- 信息缺失测试：指令有没有空白？
+
+**成功标准：** Agent 成功将技术应用到新场景
+
+### 模式类 Skill（心智模型）
+
+**示例：** reducing-complexity、information-hiding concepts
+
+**测试方法：**
+- 识别场景：他们能识别模式何时适用吗？
+- 应用场景：他们能使用心智模型吗？
+- 反例：他们知道何时不应用吗？
+
+**成功标准：** Agent 正确识别何时/如何应用模式
+
+### 参考类 Skill（文档/API）
+
+**示例：** API 文档、命令参考、库指南
+
+**测试方法：**
+- 检索场景：他们能找到正确的信息吗？
+- 应用场景：他们能正确使用找到的信息吗？
+- 空白测试：常见用例是否被覆盖？
+
+**成功标准：** Agent 找到并正确应用参考信息
+
+## 跳过测试的常见合理化借口
+
+| 借口 | 现实 |
+|------|------|
+| "Skill 明显很清楚" | 对你清楚 ≠ 对其他 agent 清楚。测试它。 |
+| "只是个参考" | 参考可能有空白、不清楚的部分。测试检索。 |
+| "测试太过了" | 未测试的 skill 总有问题。15 分钟测试省几小时。 |
+| "出问题再测" | 出问题 = agent 用不了 skill。部署前测试。 |
+| "测试太烦了" | 测试比在生产中调试坏 skill 不那么烦。 |
+| "我有信心它没问题" | 过度自信保证出问题。还是测试。 |
+| "学术审查就够了" | 读 ≠ 用。测试应用场景。 |
+| "没时间测试" | 部署未测试的 skill 之后修复浪费更多时间。 |
+
+**以上所有都意味着：部署前测试。没有例外。**
+
+## 让 Skill 抵抗合理化
+
+执行纪律的 skill（比如 TDD）需要抵抗合理化。Agent 很聪明，在压力下会找到漏洞。
+
+**心理学注释：** 理解说服技术为什么有效有助于你系统地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025），关于权威、承诺、稀缺性、社会证明和统一性原则。
+
+### 明确堵住每个漏洞
+
+不要只陈述规则，禁止具体的变通方法：
+
+<Bad>
+```markdown
+先写了代码再写测试？删掉。
+```
+</Bad>
+
+<Good>
+```markdown
+先写了代码再写测试？删掉。从头来过。
+
+**没有例外：**
+- 不要把它留作"参考"
+- 不要在写测试时"改编"它
+- 不要看它
+- 删除就是删除
+```
+</Good>
+
+### 应对"精神 vs 字面"的论点
+
+在早期添加基础原则：
+
+```markdown
+**违反规则的字面意思就是违反规则的精神。**
+```
+
+这切断了整类"我在遵循精神"的合理化借口。
+
+### 构建合理化表格
+
+从基线测试中捕获合理化借口（见下面的测试部分）。Agent 提出的每个借口都放进表格：
+
+```markdown
+| 借口 | 现实 |
+|------|------|
+| "太简单不用测" | 简单代码也会出错。测试只要 30 秒。 |
+| "我之后再测" | 立刻通过的测试什么都证明不了。 |
+| "后写测试也能达到同样目的" | 后写测试 = "这做了什么？" 先写测试 = "这应该做什么？" |
+```
+
+### 创建危险信号列表
+
+让 agent 容易自查是否在合理化：
+
+```markdown
+## 危险信号 - 停下来，从头开始
+
+- 先写了代码再写测试
+- "我已经手动测过了"
+- "后写测试也能达到同样目的"
+- "重要的是精神不是仪式"
+- "这次情况不一样因为..."
+
+**以上所有都意味着：删掉代码。用 TDD 从头开始。**
+```
+
+### 更新 CSO 以包含违规症状
+
+在 description 中添加：你即将违反规则时的症状：
+
+```yaml
+description: 实现任何功能或修复bug之前使用，在编写实现代码之前
+```
+
+## Skill 的红-绿-重构
+
+遵循 TDD 循环：
+
+### 红灯：写失败测试（基线）
+
+在没有 skill 的情况下用子 agent 运行压力场景。记录确切行为：
+- 他们做了什么选择？
+- 他们使用了什么合理化借口（原文）？
+- 哪些压力触发了违规？
+
+这就是"看测试失败"，你必须在写 skill 之前看到 agent 自然会做什么。
+
+### 绿灯：写最少的 Skill
+
+写 skill 针对那些具体的合理化借口。不要为假设的情况添加额外内容。
+
+用 skill 运行同样的场景。Agent 现在应该遵守了。
+
+### 重构：堵住漏洞
+
+Agent 找到了新的合理化借口？添加明确的反驳。重新测试直到无懈可击。
+
+**测试方法：** 参见 @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
+**为什么不好：** 标签应该有语义含义
+
+## 停下来：在进入下一个 Skill 之前
+
+**写完任何 skill 后，你必须停下来完成部署流程。**
+
+**不要：**
+- 批量创建多个 skill 而不逐个测试
+- 在当前 skill 验证之前进入下一个
+- 因为"批量更高效"就跳过测试
+
+**下面的部署检查清单对每个 skill 都是必须的。**
+
+部署未测试的 skill = 部署未测试的代码。这违反了质量标准。
+
+## Skill 创建检查清单（TDD 适配版）
+
+**重要：使用 TodoWrite 为下面每个检查项创建 todo。**
+
+**红灯阶段 - 写失败测试：**
+- [ ] 创建压力场景（纪律类 skill 需要 3 个以上组合压力）
+- [ ] 在没有 skill 的情况下运行场景，逐字记录基线行为
+- [ ] 识别合理化借口/失败中的模式
+
+**绿灯阶段 - 写最少的 Skill：**
+- [ ] 名称只使用字母、数字、连字符（不要括号/特殊字符）
+- [ ] YAML frontmatter 只有 name 和 description（最多 1024 字符）
+- [ ] Description 以"...时使用"开头，包含具体的触发器/症状
+- [ ] Description 用第三人称写
+- [ ] 全文包含搜索关键词（错误、症状、工具）
+- [ ] 清晰的概述和核心原则
+- [ ] 针对红灯阶段识别的具体基线失败
+- [ ] 代码内联或链接到单独文件
+- [ ] 一个优秀的示例（不要多语言）
+- [ ] 用 skill 运行场景，验证 agent 现在遵守
+
+**重构阶段 - 堵住漏洞：**
+- [ ] 识别测试中的新合理化借口
+- [ ] 添加明确的反驳（如果是纪律类 skill）
+- [ ] 从所有测试迭代中构建合理化表格
+- [ ] 创建危险信号列表
+- [ ] 重新测试直到无懈可击
+
+**质量检查：**
+- [ ] 只在决策不明显时用小流程图
+- [ ] 快速参考表格
+- [ ] 常见错误章节
+- [ ] 没有叙事故事
+- [ ] 辅助文件只用于工具或大量参考
+
+**部署：**
+- [ ] 将 skill 提交到 git 并推送到你的 fork（如果已配置）
+- [ ] 考虑通过 PR 贡献回去（如果广泛有用）
+
+## 发现工作流
+
+未来的 Claude 如何找到你的 skill：
+
+1. **遇到问题**（"测试不稳定"）
+3. **找到 SKILL**（description 匹配）
+4. **扫描概述**（这相关吗？）
+5. **阅读模式**（快速参考表格）
+6. **加载示例**（只在实现时）
+
+**为这个流程优化** - 把可搜索的术语放在前面，经常出现。
+
+## 底线
+
+**创建 skill 就是流程文档的 TDD。**
+
+同样的铁律：没有先写失败测试就不能写 skill。
+同样的循环：红灯（基线）→ 绿灯（写 skill）→ 重构（堵住漏洞）。
+同样的好处：更高质量，更少意外，无懈可击的结果。
+
+如果你对代码遵循 TDD，对 skill 也要遵循。这是同样的纪律应用到文档上。