Appearance
Superpowers 的 writing-skills 有一个反直觉的核心：写 skill 不是先写文档再测试，而是先跑"失败场景"确认 agent 会在哪里出错，再针对性地写文档堵住那些漏洞。这套方法本质上是把软件工程的 TDD（测试驱动开发）搬到了流程文档的写作上。理解这一点，比看懂任何一条具体规则都更重要。
writing-skills：Superpowers 是怎么设计 skill 文档的
Skill 写作的本质是 TDD
大多数人写文档的直觉是：先把知识整理出来，写成文字，然后验证它能不能被理解。Superpowers 反转了这个顺序。
它的铁律是：没有先跑过失败场景，就没有资格写 skill。
这和 TDD 的"先写红灯测试，再写代码让测试变绿"完全一致，只是把"测试"换成了"让 agent 在没有 skill 的情况下执行任务"，把"代码"换成了"文档"。
| TDD 概念 | Skill 写作对应 |
|---|---|
| 测试用例（Test case） | 给 subagent 的压力场景 |
| 生产代码（Production code） | SKILL.md 文档 |
| 红灯（RED） | Agent 违反规则或用错方法 |
| 绿灯（GREEN） | Agent 读取 skill 后正确行为 |
| 重构（REFACTOR） | 堵住新发现的借口/漏洞 |
为什么这个顺序如此重要？因为"清楚"是相对的。对你清楚的东西，对另一个 agent 未必清楚。不跑基线场景，你根本不知道哪些地方会出问题。先写文档再测试，就像先写代码再想测什么——你会无意识地让测试通过已知的代码路径，而不是真正发现问题。
Description 字段：只写触发条件，不写工作流
Superpowers 在 CSO（Claude Search Optimization）部分有一个具体教训，值得单独拿出来说。
Description 字段决定了 Claude 在遇到任务时是否加载这个 skill。直觉上，你可能想把 skill 的工作流摘要写进去，这样 Claude 一眼就知道这个 skill 做什么。这是个陷阱。
实测结果：一个 description 写了"two-stage code review"流程的 skill，Claude 只做了一次 review 就结束了——因为它读了 description 之后认为自己已经理解了工作流，没有继续读 SKILL.md 的正文。改成只写触发条件后，Claude 才完整执行了两阶段流程。
这揭示了一个反直觉的设计原则：description 是给 Claude 看的广告，不是操作手册。广告的作用是触发"我需要读这个 skill"的判断，操作细节放在正文里。
yaml
# 错误：摘要了工作流
description: Use when executing plans - dispatches subagent per task with code review between tasks
# 正确：只写触发条件
description: Use when executing implementation plans with independent tasks in the current session说服心理学：让规则在压力下依然有效
Skill 文档不只是信息载体，它还需要在 agent"有理由"跳过规则时依然有约束力。Superpowers 借鉴了 Cialdini 的说服原则，把它们显式地用在了 skill 设计上。
研究数据（Meincke et al., 2025，N=28,000 次 LLM 对话）表明：使用说服技巧后合规率从 33% 提升到了 72%。
三个最有效的原则：
权威（Authority）：用命令式语言消除决策空间。"YOU MUST"、"Never"、"No exceptions"比"建议"或"通常"有效得多。规则的价值在于它是规则，不是建议。
承诺（Commitment）：要求 agent 在执行前先公开声明。"Announce skill usage"这类要求制造了承诺感——公开说出来之后，中途放弃的心理成本更高。
社会证明（Social Proof）：用"每次都这样"、"X without Y = 失败"的句式，把规则变成常识而非个人偏好。
对于纪律性 skill（如 TDD、代码审查），组合使用权威 + 承诺 + 社会证明效果最好。参考性 skill（API 文档、工具使用）则不需要这些——保持清晰即可。
堵漏洞：从借口表建反案例
Skill 文档中最有价值、也最常被忽略的部分，是"借口表"（Rationalization Table）。
这张表的内容来自基线测试阶段——你让 agent 在没有 skill 的情况下执行任务，逐字记录它给出的每一个不遵守规则的理由，然后把这些理由和对应的反驳写进 skill 正文。
markdown
| 借口 | 实际情况 |
|------|---------|
| "这段代码太简单了，不需要测试" | 简单的代码也会出错，写测试只需要 30 秒 |
| "我已经手动测了" | 手动测试不能替代自动化测试 |
| "先写代码再补测试，目的是一样的" | 先写代码的测试是"这代码做了什么"，先写测试是"这代码该做什么"——完全不同 |这套做法不是在"骗"agent，而是用规则文档做到了人类团队靠文化和流程才能做到的事：把常见的偷懒理由预先堵死。
文件结构与 Token 效率
Superpowers 对 skill 文件结构有明确的 Token 效率要求。
启动时只有 name 和 description 两个字段加载到系统提示里。SKILL.md 正文只有在 skill 被激活时才读入。其他支撑文件只有在被 SKILL.md 明确引用时才按需加载。
这意味着：
- 高频加载的 skill（getting-started 类型）正文目标 150 词以内
- 普通 skill 500 行以内
- 超过 100 行的参考资料提取到独立文件，在 SKILL.md 中用链接引用
文件组织原则：单个 SKILL.md 能放下的放进去；需要大段 API 文档的建子目录；可复用的工具脚本单独放文件。深度超过一级的嵌套引用要避免——Claude 在读二级引用时可能只读 head -100，导致信息不完整。
何时创建 Skill，何时不必
Superpowers 给出了清晰的判断标准。
应该创建 skill 的情况：这个方法对你来说不是直觉显然的；你会在多个项目里反复用到它；它有足够的通用性（不是项目特定的配置）。
不应该创建 skill 的情况：一次性的解决方案；标准实践（别人的文档里已经写清楚了）；项目特定的约定（放进 CLAUDE.md）；可以用 linting 或自动化强制的事情（能自动化的不要靠文档）。
最后一条值得注意：能用 regex 验证或 CI 检查的约束，不应该浪费在文档上。文档用来处理需要判断的情况，自动化用来处理机械性的检查。
FAQ
Q: 如果 skill 很简单，真的需要先跑失败场景吗？ A: Superpowers 的立场是"简单"是你的主观判断，不是 agent 的感受。文档中的借口表里第一条就是"这个 skill 显然清楚"——这句话在测试结果面前往往站不住脚。15 分钟的测试能省掉之后几小时的调试。
Q: Description 字段到底该写多少字？ A: 原则上越短越好，但要包含让 Claude 判断"这个 skill 和当前任务相关"所需的关键词。推荐 500 字符以内。关键是：只写触发条件，不写工作流摘要。
Q: 借口表有多重要，能不写吗？ A: 对于纪律性 skill（强制要求某种流程的），借口表是核心。对于技术性 skill（教具体操作方法的），可以省略，换成"常见错误"章节即可。
Q: 多语言代码示例有必要写吗？ A: 明确不建议。一个优质的例子胜过五种语言的平庸例子。选最能说明问题的语言写一个完整可运行的示例，其他语言留给 Claude 自己迁移。