用途
本技能用于指导如何创建新技能、编辑现有技能，以及在部署前验证技能是否有效。它的核心主张是：编写技能就是将测试驱动开发（TDD）应用于流程文档。
技能被定义为经过验证的技术、模式或工具的参考指南，帮助未来的智能体实例找到并应用有效方法。技能是可复用的技术、模式、工具或参考指南，而不是关于某次如何解决问题的叙事。
核心原则
如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。
使用本技能前，必须先理解 superpowers:test-driven-development，该技能定义了基本的红-绿-重构循环，本技能将 TDD 适配到文档编写中。Anthropic 官方的技能编写最佳实践参见 anthropic-best-practices.md。
TDD 映射
- 测试用例 → 带子智能体的压力场景
- 生产代码 → 技能文档（SKILL.md）
- 测试失败（红）→ 智能体在没有技能时违反规则（基线）
- 测试通过（绿）→ 智能体在有技能时遵守规则
- 重构 → 在保持合规的同时堵住漏洞
整个技能创建过程遵循红-绿-重构：先写测试（编写技能前先运行基线场景），观察失败（记录智能体使用的确切合理化借口），最小代码（编写针对那些具体违规行为的技能），观察通过（验证智能体现在遵守规则），重构循环（发现新的合理化借口 → 堵住 → 重新验证）。
何时创建技能
创建条件：技术对你来说不是直觉上显而易见的；你会在不同项目中反复引用；模式具有广泛适用性（非项目特定）；其他人也会受益。
不要创建：一次性解决方案；其他地方有充分文档的标准实践；项目特定的约定（放在 CLAUDE.md 中）；机械性约束（如果可以用正则/验证强制执行，就自动化，文档留给需要判断的场景）。
技能类型
- 技术类：有具体步骤的方法（condition-based-waiting、root-cause-tracing）
- 模式类：思考问题的方式（flatten-with-flags、test-invariants）
- 参考类：API 文档、语法指南、工具文档（office docs）
目录结构与 SKILL.md 结构
目录结构为 skills/skill-name/SKILL.md，支持文件仅在需要时添加，采用扁平命名空间。大量参考内容（100+ 行）或可复用工具应分离为独立文件；原则、概念和小于 50 行的代码模式保持内联。
SKILL.md 的 Frontmatter（YAML）包含两个必需字段 name 和 description，总计最多 1024 字符。name 只使用字母、数字和连字符；description 用第三人称，仅描述何时使用，以“Use when...”开头，聚焦触发条件，包含具体症状、场景和上下文，绝不总结技能的流程或工作流，尽量控制在 500 字符以内。
正文结构包括：概述、何时使用、核心模式、快速参考、实现、常见错误、实际效果（可选）。
Claude 搜索优化（CSO）
发现至关重要，未来的智能体需要找到你的技能。要点包括：
- 丰富的描述字段：描述 = 何时使用，不是技能做什么。测试表明，当描述总结了技能的工作流时，智能体可能会跟随描述而非阅读完整技能内容。
- 关键词覆盖：使用错误信息、症状、同义词、工具名称等会被搜索的词语。
- 描述性命名：使用主动语态、动词优先，如 creating-skills 而非 skill-creation。
- Token 效率：getting-started 工作流每个小于 150 词，频繁加载的技能总计小于 200 词，其他技能小于 500 词。技巧包括将细节移到工具帮助中、使用交叉引用、压缩示例、消除冗余。
- 交叉引用其他技能：仅使用技能名称并带明确必需标记，避免使用 @ 链接（会立即强制加载文件，消耗大量上下文）。
流程图使用
仅在非显而易见的决策点、可能过早停止的流程循环、“何时使用 A vs B”的决策时使用流程图。绝不用于参考资料、代码示例或线性指令。可使用 render-graphs.js 将流程图渲染为 SVG。
代码示例
一个优秀的示例胜过多个平庸的。选择最相关的语言，示例应完整可运行、注释良好、来自真实场景、清晰展示模式、可直接适配。不要用 5 种以上语言实现，不要创建填空模板，不要写人为构造的示例。
铁律
没有失败的测试就不写技能。这适用于新技能和对现有技能的编辑。先写技能再测试？删掉它，重新开始。编辑技能不测试？同样违规。无例外：不适用于“简单的添加”、“只是加一个章节”、“文档更新”。不要保留未测试的更改作为“参考”，不要在运行测试时“调整”。删除就是删除。
测试所有技能类型
- 纪律执行类技能（规则/要求）：测试学术性问题、压力场景、多重压力组合，识别合理化借口并添加明确反驳。成功标准是智能体在最大压力下遵循规则。
- 技术类技能（操作指南）：测试应用场景、变体场景、缺失信息测试。成功标准是智能体成功将技术应用于新场景。
- 模式类技能（心智模型）：测试识别场景、应用场景、反例。成功标准是智能体正确识别何时/如何应用模式。
- 参考类技能（文档/API）：测试检索场景、应用场景、覆盖测试。成功标准是智能体找到并正确应用参考信息。
让技能经受住合理化的考验
执行纪律的技能需要抵抗合理化。应明确堵住每个漏洞，禁止具体的变通方法；应对“精神 vs 字面”的辩论，在前面加入基础原则（违反规则的字面意思就是违反规则的精神）；构建合理化借口表，从基线测试中捕获借口；创建红线列表，让智能体容易自查是否在合理化。
技能的红-绿-重构
- 红：编写失败的测试（基线）。在没有技能的情况下运行压力场景，逐字记录行为、合理化借口和触发违规的压力。
- 绿：编写最小技能。编写针对那些具体合理化借口的技能，不要为假设情况添加额外内容。用技能运行相同场景，智能体应遵守。
- 重构：堵住漏洞。智能体找到新的合理化借口时，添加明确的反驳，重新测试直到无懈可击。
测试方法论参见 testing-skills-with-subagents.md，涵盖如何编写压力场景、压力类型（时间、沉没成本、权威、疲惫）、系统地堵住漏洞、元测试技巧。
反模式
- 叙事式示例：太具体，不可复用
- 多语言稀释：质量平庸，维护负担重
- 流程图中的代码：无法复制粘贴，难以阅读
- 通用标签：标签应有语义意义
技能创建清单（TDD 适配版）
红色阶段：创建压力场景（纪律类技能需 3 个以上组合压力）；在没有技能的情况下运行场景并逐字记录基线行为；识别合理化借口中的模式。
绿色阶段：名称只使用字母、数字、连字符；YAML frontmatter 包含必需的 name 和 description 字段；描述以“Use when...”开头并包含具体触发条件/症状；描述用第三人称；全文包含搜索关键词；带有核心原则的清晰概述；解决红色阶段识别出的具体基线失败；代码内联或链接到独立文件；一个优秀的示例；用技能运行场景验证智能体遵守。
重构阶段：从测试中识别新的合理化借口；添加明确的反驳；从所有测试迭代中构建合理化借口表；创建红线列表；重新测试直到无懈可击。
质量检查：仅在决策不明显时使用小流程图；快速参考表；常见错误章节；无叙事性故事；支持文件仅用于工具或大量参考。
部署：将技能提交到 git 并推送到你的 fork（如果已配置）；考虑通过 PR 贡献回去（如果具有广泛用途）。
发现工作流
未来的智能体如何找到你的技能：遇到问题 → 找到技能（描述匹配）→ 浏览概述 → 阅读模式（快速参考表）→ 加载示例（仅在实现时）。为此流程优化，把可搜索的术语放在前面和各处。
总结
创建技能就是流程文档的 TDD。同样的铁律：没有失败的测试就不写技能。同样的循环：红（基线）→ 绿（写技能）→ 重构（堵漏洞）。同样的好处：更高的质量、更少的意外、无懈可击的结果。