安装方式
手动下载安装
下载 ZIP 后解压到技能目录即可安装。若在桌面客户端 WebView中直接下载出现异常，本站会改为提示页 + 原始链接，请按页内说明操作。
下载 ZIP (oss-superpowers-writing-skills-v1.0.0.zip)触发指令
/writing-skills
跨平台安装指引
该技能声明兼容以下 1 个平台，将 ZIP 解压到对应目录即可被识别。
unzip oss-superpowers-writing-skills-v1.0.0.zip -d ~/.claude/skills/
mkdir -p 创建；启用 Skill 后请重启对应 Agent 让配置生效。
使用指南
撰写技能（Skills）
写技能 = 把 TDD 用在流程文档上。
个人技能目录示例：Claude Code 用 ~/.claude/skills，Codex 用 ~/.agents/skills/。
你写 压力场景（带子代理的测试），看 无技能时的失败基线，再写 技能文档，再看 有技能时是否遵守，最后 收紧漏洞（重构）。
核心： 若没见过 无技能时代理如何失败，就不知道技能是否教对了。
前置： 必须先理解 test-driven-development；本技能把红—绿—重构映射到文档。
官方补充： Anthropic 技能撰写最佳实践见 anthropic-best-practices.md，与本文 TDD 取向互补。
技能是什么
技能是 可复用的方法、模式、工具、参考手册。
不是「我某次怎么解决的故事」。
与 TDD 的对应
| TDD | 技能 | |-----|------| | 测试用例 | 带子代理的压力场景 | | 生产代码 | SKILL.md | | 红 | 无技能时违规（基线） | | 绿 | 有技能时遵守 | | 重构 | 堵漏洞同时保持遵守 | | 先写测试 | 写技能 前 先跑基线 | | 看它失败 | 记录代理的借口原文 | | 最简实现 | 只针对这些违规写技能 | | 看它通过 | 再跑场景确认 | | 重构循环 | 新借口 → 补规则 → 再验 |
何时新建技能
适合： 技巧不直观、会跨项目复用、模式够通用、他人也用得上。
不适合： 一次性解法、别处已有标准文档、仅项目约定（放 CLAUDE.md）、可用正则/校验机戒 enforce 的（优先自动化）。
技能类型
- 技法：有步骤可循（如条件等待、根因追踪）
- 模式：思维方式（如用不变量测）
- 参考：API、语法、工具文档（如 Office）
目录结构
skills/
skill-name/
SKILL.md # 必填主文档
其他文件 # 仅当必要（大参考、脚本）
扁平命名空间；大参考（100+ 行）或 可复用脚本 才拆文件；原则与短代码模式可内联。
SKILL.md 结构建议
YAML 头： name、description 必填（见 agentskills.io/specification）；总长 ≤1024 字符。name 仅字母数字连字符。description 用 第三人称，只写 何时用（触发条件、症状），不要 概括流程（见下 CSO）。
正文建议块：概述、何时用（可含小流程图）、核心模式、速查表、实现要点、常见错误、可选「真实收益」。
Claude 检索优化（CSO）
描述字段只写「何时用」，不写「做什么」： 若描述里总结工作流，模型可能 只读描述不读正文，导致少做步骤（实测：写「任务间 code review」会只做一次评审，改描述为纯触发条件后才会读流程图做两阶段评审）。
好描述： 以「在……情况下使用」开头，写 具体问题/症状（竞态、不稳定），少写技术细节除非技能本身绑技术栈。
关键词： 错误文案、症状词、同义词、真实命令与库名。
命名： 动词开头、-ing 进程名往往好用（creating-skills）。
Token： 入门/高频加载技能要短（如每工作流 <150 词，整技能 <200–500 词）；细节移到 --help 或其它技能交叉引用，不要重复贴长流程。
交叉引用其它技能
用 **必须子技能：** Use superpowers:xxx 或 **必须先掌握：**，不要用 @path 强制预加载（烧上下文）。
流程图
仅当 决策不显然、易早停、或 A/B 选择时用 Graphviz；参考材料用表；线性步骤用编号列表。风格见 @graphviz-conventions.dot；可用目录内 render-graphs.js 渲染 SVG。
代码示例
一个精品胜过多个平庸；选最相关语言；完整可运行、注释讲 为什么；不要五种语言各一份填空模板。
文件组织形态
- 全内联：单 SKILL.md
- 带可复用工具：SKILL.md + 示例代码
- 重参考：SKILL.md + 大参考 md + scripts/
铁律（与 TDD 相同）
没有先失败的测试（基线场景），就不写技能。
没有先测的编辑，就不算完成修改。
先写技能再测、或「小改不用测」→ 删改重来。无例外。
各类技能的测法简述： 纪律类 → 学术问答 + 高压组合（时间/沉没成本/疲惫）+ 收集借口进表；技法类 → 应用场景与变体；模式类 → 识别何时用/不用；参考类 → 检索与应用、覆盖缺口测试。
跳过测试的借口
「显然清楚」「只是参考」「测试小题大做」「上线再测」「太烦」「我很有把握」「通读就够了」「没时间」—— 全部驳回：发布前必须测。
防「合理化」写作技巧
规则要 显式封死漏洞（列清「不要保留作参考、不要边测边改编」等）；文首可加 违反字面即违反精神；把基线里出现的借口收进 借口—现实 表；列 红旗—停 清单；描述里可写 即将违反时的症状。
技能的红—绿—重构
- 红： 无技能跑压力场景，记录行为与 原文借口。
- 绿： 写 最小 技能只堵已见问题；再跑应遵守。
- 重构： 新借口 → 补条文 → 再测至够硬。
完整方法论见 @testing-skills-with-subagents.md（压力类型、堵洞顺序、元测试）。
反模式
叙事型「某年某月我们发现…」；多语言稀释；流程图里塞代码；无意义节点名 helper1/step3。
部署纪律
每写一个技能必须走完部署清单；不要批量写一堆却都不测。未测技能 = 未测代码。
清单摘要（须 TodoWrite 逐项）
红： 3+ 组合压力场景（纪律类）、无技能跑基线、记录失败模式。
绿： name/description 合规、概述、针对基线、代码或链接、一个好例子、有技能再跑通过。
重构： 新借口、理性化表、红旗列表、复测。
质量： 非显然才用流程图、速查表、常见错误、无小说叙事、附属文件仅当必要。
发布： 提交 git，有用可提 PR。
发现路径
用户遇问题 → description 命中 → 扫概述 → 看速查 → 需要时再加载示例。把可搜词放前、放密。
结语
写技能与写生产代码 同一纪律：先失败测试、红绿重构、证据先于断言。你会 TDD 写代码，就该 TDD 写技能。
<!-- zh-only -->
# 撰写技能（Skills）
**写技能 = 把 TDD 用在流程文档上。**
个人技能目录示例：Claude Code 用 `~/.claude/skills`，Codex 用 `~/.agents/skills/`。
你写 **压力场景（带子代理的测试）**，看 **无技能时的失败基线**，再写 **技能文档**，再看 **有技能时是否遵守**，最后 **收紧漏洞**（重构）。
**核心：** 若没见过 **无技能时代理如何失败**，就不知道技能是否教对了。
**前置：** 必须先理解 **test-driven-development**；本技能把红—绿—重构映射到文档。
**官方补充：** Anthropic 技能撰写最佳实践见 `anthropic-best-practices.md`，与本文 TDD 取向互补。
## 技能是什么
技能是 **可复用的方法、模式、工具、参考手册**。
**不是**「我某次怎么解决的故事」。
## 与 TDD 的对应
| TDD | 技能 |
|-----|------|
| 测试用例 | 带子代理的压力场景 |
| 生产代码 | SKILL.md |
| 红 | 无技能时违规（基线） |
| 绿 | 有技能时遵守 |
| 重构 | 堵漏洞同时保持遵守 |
| 先写测试 | 写技能 **前** 先跑基线 |
| 看它失败 | 记录代理的借口原文 |
| 最简实现 | 只针对这些违规写技能 |
| 看它通过 | 再跑场景确认 |
| 重构循环 | 新借口 → 补规则 → 再验 |
## 何时新建技能
**适合：** 技巧不直观、会跨项目复用、模式够通用、他人也用得上。
**不适合：** 一次性解法、别处已有标准文档、仅项目约定（放 CLAUDE.md）、可用正则/校验机戒 enforce 的（优先自动化）。
## 技能类型
- **技法**：有步骤可循（如条件等待、根因追踪）
- **模式**：思维方式（如用不变量测）
- **参考**：API、语法、工具文档（如 Office）
## 目录结构
```
skills/
skill-name/
SKILL.md # 必填主文档
其他文件 # 仅当必要（大参考、脚本）
```
扁平命名空间；**大参考**（100+ 行）或 **可复用脚本** 才拆文件；原则与短代码模式可内联。
## SKILL.md 结构建议
**YAML 头：** `name`、`description` 必填（见 [agentskills.io/specification](https://agentskills.io/specification)）；总长 ≤1024 字符。`name` 仅字母数字连字符。`description` 用 **第三人称**，只写 **何时用**（触发条件、症状），**不要** 概括流程（见下 CSO）。
正文建议块：概述、何时用（可含小流程图）、核心模式、速查表、实现要点、常见错误、可选「真实收益」。
## Claude 检索优化（CSO）
**描述字段只写「何时用」，不写「做什么」：** 若描述里总结工作流，模型可能 **只读描述不读正文**，导致少做步骤（实测：写「任务间 code review」会只做一次评审，改描述为纯触发条件后才会读流程图做两阶段评审）。
**好描述：** 以「在……情况下使用」开头，写 **具体问题/症状**（竞态、不稳定），少写技术细节除非技能本身绑技术栈。
**关键词：** 错误文案、症状词、同义词、真实命令与库名。
**命名：** 动词开头、-ing 进程名往往好用（`creating-skills`）。
**Token：** 入门/高频加载技能要短（如每工作流 <150 词，整技能 <200–500 词）；细节移到 `--help` 或其它技能交叉引用，不要重复贴长流程。
## 交叉引用其它技能
用 **`**必须子技能：** Use superpowers:xxx`** 或 **`**必须先掌握：**`**，不要用 `@path` 强制预加载（烧上下文）。
## 流程图
仅当 **决策不显然**、易早停、或 A/B 选择时用 Graphviz；参考材料用表；线性步骤用编号列表。风格见 `@graphviz-conventions.dot`；可用目录内 `render-graphs.js` 渲染 SVG。
## 代码示例
**一个精品胜过多个平庸**；选最相关语言；完整可运行、注释讲 **为什么**；不要五种语言各一份填空模板。
## 文件组织形态
- 全内联：单 SKILL.md
- 带可复用工具：SKILL.md + 示例代码
- 重参考：SKILL.md + 大参考 md + scripts/
## 铁律（与 TDD 相同）
```
没有先失败的测试（基线场景），就不写技能。
没有先测的编辑，就不算完成修改。
```
先写技能再测、或「小改不用测」→ **删改重来**。无例外。
**各类技能的测法简述：** 纪律类 → 学术问答 + 高压组合（时间/沉没成本/疲惫）+ 收集借口进表；技法类 → 应用场景与变体；模式类 → 识别何时用/不用；参考类 → 检索与应用、覆盖缺口测试。
## 跳过测试的借口
「显然清楚」「只是参考」「测试小题大做」「上线再测」「太烦」「我很有把握」「通读就够了」「没时间」—— **全部驳回：发布前必须测。**
## 防「合理化」写作技巧
规则要 **显式封死漏洞**（列清「不要保留作参考、不要边测边改编」等）；文首可加 **违反字面即违反精神**；把基线里出现的借口收进 **借口—现实** 表；列 **红旗—停** 清单；描述里可写 **即将违反时的症状**。
## 技能的红—绿—重构
- **红：** 无技能跑压力场景，记录行为与 **原文借口**。
- **绿：** 写 **最小** 技能只堵已见问题；再跑应遵守。
- **重构：** 新借口 → 补条文 → 再测至够硬。
完整方法论见 `@testing-skills-with-subagents.md`（压力类型、堵洞顺序、元测试）。
## 反模式
叙事型「某年某月我们发现…」；多语言稀释；流程图里塞代码；无意义节点名 helper1/step3。
## 部署纪律
**每写一个技能必须走完部署清单**；不要批量写一堆却都不测。未测技能 = 未测代码。
## 清单摘要（须 TodoWrite 逐项）
**红：** 3+ 组合压力场景（纪律类）、无技能跑基线、记录失败模式。
**绿：** name/description 合规、概述、针对基线、代码或链接、一个好例子、有技能再跑通过。
**重构：** 新借口、理性化表、红旗列表、复测。
**质量：** 非显然才用流程图、速查表、常见错误、无小说叙事、附属文件仅当必要。
**发布：** 提交 git，有用可提 PR。
## 发现路径
用户遇问题 → description 命中 → 扫概述 → 看速查 → 需要时再加载示例。**把可搜词放前、放密。**
## 结语
写技能与写生产代码 **同一纪律**：先失败测试、红绿重构、证据先于断言。你会 TDD 写代码，就该 TDD 写技能。