本技能介绍如何创建、编辑和验证技能（skills）。其核心主张是：编写技能就是把测试驱动开发（TDD）应用到流程文档上。
一、用途与适用条件
技能是经过验证的技巧、模式或工具的参考指南，帮助未来的 Claude 实例找到并应用有效方法。技能是可复用的技巧、模式、工具、参考指南，而不是关于某次如何解决问题的叙事。
在以下情况创建技能：技巧对你来说不是直觉上显而易见的；你会跨多个项目再次引用它；模式适用范围广（不是项目特定）；其他人也会受益。
不要为以下内容创建技能：一次性解决方案；其他地方已有充分文档的标准实践；项目特定约定；机械性约束（如果可用 regex/validation 强制执行，就自动化；把文档留给需要判断的场景）。
技能类型包括：技巧（带有可执行步骤的具体方法）、模式（思考问题的方式）、参考（API 文档、语法指南、工具文档）。
二、核心方法与主要能力
技能的 TDD 映射：测试用例对应带子代理的压力场景；生产代码对应技能文档（SKILL.md）；测试失败（RED）对应没有技能时代理违反规则（基线）；测试通过（GREEN）对应存在技能时代理遵守规则；重构（REFACTOR）对应在保持遵守的同时堵住漏洞。
整个技能创建过程遵循 RED-GREEN-REFACTOR。核心原则是：如果你没有观察过代理在没有技能时失败，就不知道这个技能是否教对了东西。铁律为：没有先失败的测试，就没有技能。这同样适用于新技能和对现有技能的编辑。
前置背景要求：使用此技能前，必须理解 superpowers:test-driven-development，该技能定义了基础的 RED-GREEN-REFACTOR 循环。
RED 阶段：在没有技能的情况下，用子代理运行压力场景，逐字记录确切行为，包括它们做了哪些选择、使用了哪些合理化借口、哪些压力触发了违规。GREEN 阶段：编写处理这些具体合理化借口的最小技能，不添加假设性内容，然后运行相同场景验证代理现在会遵守。REFACTOR 阶段：识别新的合理化借口，添加明确反制，重新测试直到牢固。
三、使用方式与文档规范
个人技能位于特定代理的目录中（Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.agents/skills/）。
目录结构为扁平命名空间：skills/skill-name/SKILL.md（必需），supporting-file.*（仅在需要时）。大型参考资料（100+ 行，如 API 文档、完整语法）和可复用工具（脚本、实用程序、模板）单独成文件；原则和概念、代码模式（< 50 行）保留在正文中。
SKILL.md 结构：Frontmatter（YAML）要求两个必需字段 name 和 description，总计最多 1024 个字符；name 只使用字母、数字和连字符；description 使用第三人称，只描述何时使用，以 "Use when..." 开头，聚焦触发条件，包含具体症状、情境和上下文，绝不要概括技能的过程或工作流，如有可能保持在 500 字符以内。正文包含概述、何时使用、核心模式、快速参考、实现、常见错误、真实影响（可选）。
Claude 搜索优化（CSO）：description 字段的目的是让 Claude 决定为给定任务加载哪些技能，只描述触发条件。测试发现，当 description 概括技能工作流时，Claude 可能会遵循 description 而不是读取完整技能内容。关键词覆盖应包括错误消息、症状、同义词、工具、实际命令、库名、文件类型。命名使用主动语态、动词优先，如 creating-skills 而非 skill-creation。Token 效率方面，getting-started 工作流每个 <150 词，经常加载的技能总计 <200 词，其他技能 <500 词。详细细节可移到工具帮助中，通过交叉引用其他技能减少重复，可用 wc -w skills/path/SKILL.md 验证。
交叉引用其他技能时只使用技能名称并加上明确的要求标记（如 REQUIRED SUB-SKILL、REQUIRED BACKGROUND），不要使用 @ 链接，因为 @ 语法会立即强制加载文件，消耗 200k+ 上下文。
流程图只用于不明显的决策点、可能过早停止的流程循环、"何时使用 A vs B" 的决策；不要用于参考资料、代码示例、线性说明。可使用目录中的 render-graphs.js 将技能流程图渲染为 SVG：./render-graphs.js ../some-skill 或 ./render-graphs.js ../some-skill --combine。
代码示例应完整可运行、注释良好、来自真实场景、清楚展示模式、可直接改造；不要用 5+ 种语言实现、不要创建填空式模板、不要编写牵强示例。
四、测试与反制合理化借口
不同技能类型需要不同测试方法：强制纪律型技能（规则/要求）测试学术问题、压力场景、多重压力组合，识别合理化借口并添加明确反制，成功标准是代理在最大压力下遵循规则；技巧型技能（操作指南）测试应用场景、变化场景、缺失信息测试，成功标准是代理能把技巧成功应用到新场景；模式型技能（思维模型）测试识别场景、应用场景、反例，成功标准是代理能正确识别何时以及如何应用模式；参考型技能（文档/APIs）测试检索场景、应用场景、缺口测试，成功标准是代理能找到并正确应用参考信息。
常见跳过测试的合理化借口包括："技能显然很清楚"、"它只是参考资料"、"测试太过了"、"如果出现问题我再测试"、"测试太繁琐"、"我确信它很好"、"学术评审就够了"、"没时间测试"，文档中逐条给出了对应现实。
对于强制纪律型技能，应明确堵住每个漏洞，尽早加入基础原则（如：Violating the letter of the rules is violating the spirit of the rules），从基线测试中捕获合理化借口并建立表格，创建危险信号列表（Red Flags - STOP and Start Over），并针对违规症状更新 CSO。
五、反模式与部署流程
反模式包括：叙事示例（过于具体，无法复用）、多语言稀释（质量平庸，维护负担重）、流程图中的代码（无法复制粘贴）、泛泛标签（helper1、step2 等缺乏语义意义）。
STOP：写完任何技能后，必须停下并完成部署流程。不要不逐个测试就批量创建多个技能，不要在当前技能验证前就进入下一个技能，不要因为"批处理更高效"而跳过测试。
技能创建清单（TDD 改编版）包括 RED 阶段、GREEN 阶段、REFACTOR 阶段、质量检查、部署，共五个部分。质量检查要求：只有在决策不明显时才使用小流程图、快速参考表、常见错误小节、没有叙事故事、支持文件只用于工具或大型参考资料。部署要求：将技能提交到 git 并推送到你的 fork（如果已配置），考虑通过 PR 回馈（如果广泛有用）。
六、发现工作流与限制
未来的 Claude 找到技能的流程为：遇到问题 → 找到 SKILL（description 匹配）→ 扫描概述 → 读取模式（快速参考表）→ 加载示例（仅在实现时）。应尽早并经常放入可搜索术语。
限制与前置要求：使用本技能前必须理解 superpowers:test-driven-development；测试方法完整细节见 testing-skills-with-subagents.md；graphviz 样式规则见 graphviz-conventions.dot；Anthropic 官方技能编写最佳实践见 anthropic-best-practices.md。除资料中明确提到的内容外，其余具体操作细节暂未提供。