用途
Writing Skills 用于在创建新技能、编辑已有技能，或在部署前验证技能是否有效时使用。它把测试驱动开发（TDD）的方法应用到流程文档上，帮助作者写出可被未来智能体正确发现和执行的技能。
核心原则
技能创建遵循 RED-GREEN-REFACTOR 循环：先写测试用例（用子智能体构造压力场景），观察失败（基线行为），再编写技能文档，观察测试通过（智能体遵守），最后重构（堵住漏洞）。核心原则是：如果没有亲眼看到智能体在没有该技能时失败，就不知道这个技能是否教对了东西。
使用该技能前，必须先理解 test-driven-development 技能，它定义了基本的 RED-GREEN-REFACTOR 循环。
什么是技能
技能是经过验证的技术、模式或工具的参考指南，帮助未来的智能体实例找到并应用有效方法。技能是可复用的技术、模式、工具和参考指南，而不是关于某次如何解决问题的叙述。
何时创建技能
适合创建：技术对你来说并非显而易见；你会跨项目反复参考；模式适用范围广（非项目专属）；其他人也会受益。
不适合创建：一次性解决方案；已有充分文档的标准实践；项目专属约定（应放入 CLAUDE.md）；机械性约束（若可用正则或校验自动化，就自动化，文档留给需要判断的场景）。
技能类型
- 技术（Technique）：有具体步骤的方法，如 condition-based-waiting、root-cause-tracing。
- 模式（Pattern）：思考问题的方式，如 flatten-with-flags、test-invariants。
- 参考（Reference）：API 文档、语法指南、工具文档。
目录结构
技能采用扁平命名空间，所有技能放在一个可搜索的命名空间中。每个技能目录包含必需的 SKILL.md，以及按需添加的支撑文件。重型参考（100 行以上）和可复用工具应拆分为独立文件；原则、概念和 50 行以内的代码模式保留在 SKILL.md 内联。
SKILL.md 结构
Frontmatter（YAML）仅支持 name 和 description 两个字段，总计不超过 1024 字符。name 只能使用字母、数字和连字符。description 用第三人称，只描述何时使用（不描述做什么），以“Use when...”开头，包含具体症状、情况和上下文，绝不总结技能流程或工作流，尽量控制在 500 字符以内。
正文建议包含：Overview（1-2 句核心原则）、When to Use（症状与用例列表、何时不用）、Core Pattern（前后对比）、Quick Reference（表格或要点）、Implementation（简单模式内联代码，重型参考链接到文件）、Common Mistakes（常见错误与修复）、Real-World Impact（可选，具体结果）。
Claude 搜索优化（CSO）
描述字段至关重要：智能体读取 description 来决定是否为当前任务加载该技能。描述应只写触发条件，不总结工作流。测试发现，若描述总结了工作流，智能体可能直接照描述执行而不读技能正文。例如描述写“任务间做代码审查”会导致只做一次审查，而技能流程图实际要求两次（规范符合性、代码质量）；改为只写触发条件后，智能体正确读取流程图并执行两阶段审查。
关键词覆盖应使用智能体会搜索的词：错误信息、症状、同义词、工具名和命令。命名使用主动语态、动词优先，如 creating-skills 而非 skill-creation。
Token 效率
入门工作流每个目标少于 150 词；频繁加载的技能总计少于 200 词；其他技能少于 500 词。技巧包括：把细节移到工具帮助（引用 --help）、使用交叉引用而非重复、压缩示例、消除冗余。可用 wc -w 验证字数。
交叉引用
引用其他技能时只写技能名并加明确要求标记，如“REQUIRED SUB-SKILL: Use test-driven-development”。不要使用 @ 链接，因为 @ 语法会立即强制加载文件，在你需要之前就消耗大量上下文。
流程图使用
流程图只用于：非显而易见的决策点、可能过早停止的流程循环、“何时用 A 还是 B”的决策。不要用于参考材料（用表格、列表）、代码示例（用 Markdown 代码块）、线性指令（用编号列表）。可用目录中的 render-graphs.js 将技能流程图渲染为 SVG。
代码示例
一个优秀示例胜过多个平庸示例。选择最相关的语言：测试技术用 TypeScript/JavaScript，系统调试用 Shell/Python，数据处理用 Python。好示例应完整可运行、注释解释原因、来自真实场景、清晰展示模式、可直接改编。不要用 5 种以上语言实现，不要做填空模板，不要写牵强示例。
铁律
没有失败的测试就不写技能。这适用于新技能和对已有技能的编辑。先写技能再测试？删除重来。未测试就编辑技能？同样违规。没有例外：不因“简单添加”、不因“只加一节”、不因“文档更新”而豁免。不要把未测试的改动留作“参考”，不要在运行测试时“改编”。删除就是删除。
测试各类技能
- 纪律约束型技能（规则/要求）：用学术问题测试是否理解规则，用压力场景测试是否遵守，组合多重压力（时间+沉没成本+疲惫），识别合理化说辞并加入明确反制。成功标准：智能体在最大压力下仍遵守规则。
- 技术型技能（操作指南）：用应用场景测试能否正确应用，用变体场景测试边界情况，用缺失信息测试指令是否有缺口。成功标准：智能体能在新场景成功应用技术。
- 模式型技能（心智模型）：用识别场景测试能否识别适用时机，用应用场景测试能否使用心智模型，用反例测试是否知道何时不该用。成功标准：智能体正确识别何时及如何应用模式。
- 参考型技能（文档/API）：用检索场景测试能否找到正确信息，用应用场景测试能否正确使用，用缺口测试检查常见用例是否覆盖。成功标准：智能体找到并正确应用参考信息。
常见跳过测试的合理化说辞
“技能显然很清楚”（对你清楚不等于对其他智能体清楚）、“只是参考而已”（参考也可能有缺口）、“测试是多余的”（未测试的技能总有问题）、“有问题再测”（问题就是智能体无法使用技能，应在部署前测试）、“测试太繁琐”（比在生产中调试坏技能轻松）、“我有信心”（过度自信必然出问题）、“学术审查就够了”（读不等于用）、“没时间测试”（部署未测试技能会浪费更多时间修复）。这些说辞都指向同一结论：部署前必须测试，没有例外。
防合理化
纪律约束型技能需要抵抗合理化。要明确堵住每个漏洞，不只陈述规则，还要禁止具体变通做法，例如：不要留作“参考”、不要在写测试时“改编”、不要看它、删除就是删除。应尽早加入基础原则：“违反规则的字面就是违反规则的精神”，以切断整类“我遵循的是精神”的合理化。可从基线测试中收集合理化说辞，建立合理化对照表。
限制
资料未提供该技能的具体收费、价格、平台支持范围或效果数据。使用前需先掌握 test-driven-development 技能。