用途
writing-skills 是一个用于创建、编辑和部署前验证 AI 智能体技能（Skill）的指导文档，来源于 davila7/claude-code-templates，地址为 https://www.skills.sh/davila7/claude-code-templates/writing-skills。
它把测试驱动开发（TDD）的方法应用到流程文档编写上。个人技能存放在各智能体专属目录中，例如 Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.codex/skills。
主要能力
TDD 映射
技能创建过程整体遵循 RED-GREEN-REFACTOR：
- 测试用例：带子智能体的压力场景
- 生产代码：技能文档（SKILL.md）
- 测试失败（RED）：智能体在没有技能时违反规则（基线）
- 测试通过（GREEN）：技能存在时智能体遵守规则
- 重构：在保持合规的前提下封闭漏洞
核心原则：如果你没有亲眼看着智能体在没有技能时失败，你就不知道这个技能教的是不是对的东西。要求先跑基线场景、记录智能体的确切合理化借口，再写技能针对这些具体违规行为，最后验证智能体是否合规。
前置背景要求：使用前必须理解 superpowers:test-driven-development，该技能定义了基本的 RED-GREEN-REFACTOR 循环。
何时创建技能
创建：技术对你并非显而易见；你会跨项目再次参考；模式适用面广（非项目专属）；他人也能受益。
不创建：一次性方案；其他地方已有充分文档的标准做法；项目专属约定（应放入 CLAUDE.md）。
技能类型
- 技术（Technique）：有步骤可循的具体方法
- 模式（Pattern）：思考问题的方式
- 参考（Reference）：API 文档、语法指南、工具文档
目录结构
skills/
skill-name/
SKILL.md # 主参考（必需）
supporting-file.* # 仅在需要时
扁平命名空间，所有技能在一个可搜索命名空间中。重参考内容（100 行以上）和可复用工具应拆分为独立文件；原则、概念和代码模式（少于 50 行）保持内联。
SKILL.md 结构
Frontmatter（YAML）只支持两个字段：name 和 description，总计最多 1024 个字符。name 只用字母、数字和连字符。description 用第三人称，只描述何时使用（不是做什么），以 "Use when..." 开头，包含具体症状、情境和上下文，可能的话保持在 500 字符以下。正文包含 Overview、When to Use、Core Pattern、Quick Reference、Implementation、Common Mistakes、Real-World Impact（可选）等段落。
Claude 搜索优化（CSO）
描述字段只描述触发条件，不要总结技能流程或工作流。测试发现，当描述总结了工作流时，Claude 可能直接按描述执行而不读完整技能内容。例如描述写 "任务间代码审查" 会导致 Claude 只做一次审查，而技能流程图明确要求两次（规格合规性然后代码质量）。
关键词覆盖：使用 Claude 会搜索的词，包括错误信息、症状、同义词、工具的实际命令与库名。
描述性命名：主动语态、动词优先，例如 creating-skills 而非 skill-creation，condition-based-waiting 而非 async-test-helpers。
Token 效率：getting-started 工作流每个少于 150 词，频繁加载的技能总计少于 200 词，其他技能少于 500 词。技巧包括把细节移到工具帮助、使用交叉引用、压缩示例、消除冗余。可用 wc -w skills/path/SKILL.md 验证。
交叉引用
引用其他技能时只用技能名并加明确要求标记，例如 **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development。不使用 @ 链接，因为 @ 语法会强制立即加载文件，在需要前就消耗 200k+ 上下文。
流程图使用
仅用于非显而易见的决策点、可能过早停止的流程循环、"何时用 A 而非 B" 的判断。不用于参考材料、代码示例、线性指令。可用目录中的 render-graphs.js 渲染为 SVG。
代码示例
一个好例子胜过多个平庸例子。选择最相关的语言：测试技术用 TypeScript/JavaScript，系统调试用 Shell/Python，数据处理用 Python。好例子应完整可运行、注释说明为什么、来自真实场景、清晰展示模式、可直接改写。不要用多种语言实现、不要填空模板、不要刻意编造的示例。
使用方式
铁律
NO SKILL WITHOUT A FAILING TEST FIRST。适用于新技能和对现有技能的编辑。先写技能再测试就删除重来；没测试就编辑同样违规。没有例外：不因"简单添加"、"只加一节"、"文档更新"而豁免，不把未测试的改动留作"参考"，不在运行测试时"适配"。删除就是删除。
测试各类技能
- 纪律类技能（规则/要求）：用学术问题、压力场景、多重压力组合测试，找出合理化借口并加显式反驳。成功标准是智能体在最大压力下仍遵守规则。
- 技术类技能：用应用场景、变化场景、缺失信息测试。成功标准是智能体能把技术应用到新场景。
- 模式类技能：用识别场景、应用场景、反例测试。成功标准是正确判断何时如何应用。
- 参考类技能：用检索场景、应用场景、缺口测试。成功标准是找到并正确应用参考信息。
常见跳过测试的借口
文档列出了多种借口及其现实反驳，例如"技能显然很清楚"（对你清楚不等于对其他智能体清楚）、"只是参考"（参考也可能有缺口）、"测试是过度"（未测试技能总有问题）、"出问题再测"（问题就是智能体用不了技能，部署前测）、"我很有信心"（过度自信保证会出问题），结论都是部署前必须测试，没有例外。
防理性化
执行纪律的技能需要抵抗合理化。要显式封闭每个漏洞，不只是陈述规则，还要禁止具体变通做法（不留作"参考"、不在写测试时"适配"、不去看它、删除就是删除）。应尽早加入基础原则：违反规则的文字就是违反规则的精神。并建立合理化借口表，把基线测试中智能体的每个借口都列入。
文档还提到，理解说服技巧为何有效有助于系统应用，参见 persuasion-principles.md（Cialdini, 2021; Meincke et al., 2025）关于权威、承诺、稀缺、社会认同和统一原则的研究基础。
适用场景
适用于创建新的智能体技能、编辑现有技能，或在部署前验证技能是否有效。适合编写 Claude Code、Codex 等 AI 智能体技能文档的人员，尤其是需要让技能在压力下仍被遵守的场景。
限制
使用前必须具备 superpowers:test-driven-development 的背景知识。资料中未提供关于收费、价格、平台支持范围、具体效果数据或其他环境要求的更多信息。