用途
writing-skills 是一项用于编写、编辑与验证 AI 智能体技能（Skill）的方法指南。它将测试驱动开发（TDD）应用于流程文档的写作：技能也是一种需要被测试的产出物。
核心原则：如果没有先观察智能体在没有该技能时如何失败，就无法判断这项技能是否教对了东西。
核心流程（RED-GREEN-REFACTOR 映射）
- 测试用例 = 用子智能体构造的压力场景
- 生产代码 = 技能文档（SKILL.md）
- 测试失败（RED）= 智能体在没有技能时违反规则（基线行为）
- 测试通过（GREEN）= 智能体在技能存在时遵守规则
- 重构 = 在维持遵守的前提下堵住漏洞
具体做法：先写测试、在写技能之前运行基线场景、记录智能体使用的确切借口、编写针对这些具体违规的技能、验证智能体是否遵守，然后循环发现新的借口、封堵、再验证。
前置要求：使用本技能之前，必须先理解 superpowers:test-driven-development 技能，它定义了 RED-GREEN-REFACTOR 循环的基础。
何时创建技能
应当创建：技术对你并非显而易见、你会跨项目反复参考、模式适用范围广（非项目专用）、他人也会受益。
不应创建：一次性解决方案、已有充分文档的标准实践、项目专用约定（应放入 CLAUDE.md）、机械性约束（若可用正则或校验自动化，就自动化，文档留给需要判断的场景）。
技能类型
- 技术（Technique）：有步骤可循的具体方法，如 condition-based-waiting、root-cause-tracing
- 模式（Pattern）：看待问题的方式，如 flatten-with-flags、test-invariants
- 参考（Reference）：API 文档、语法指南、工具文档
目录结构与文件组织
技能位于 skills/ 下的扁平命名空间，每个技能一个目录，SKILL.md 为主参考文件（必需）。重参考内容（100 行以上）、可复用工具应拆分为独立文件；原则、概念和 50 行以内的代码模式保持内联。
三种组织形态：自包含技能（全部内联）、含可复用工具的技能（如 example.ts）、含重型参考的技能（多个参考文件加 scripts/ 目录）。
SKILL.md 结构
YAML frontmatter 含两个必填字段 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 读取 description 来决定是否为某任务加载该技能。若描述中概述了工作流，Claude 可能直接照描述执行而不读技能正文。资料举例：描述写成“任务之间做代码审查”会导致 Claude 只做一次审查，而技能流程图实际要求两次（规格符合性审查、代码质量审查）；改成仅描述触发条件后，Claude 正确读取流程图并执行两阶段审查。
因此描述应使用具体触发词、症状与情境，描述问题（如竞态条件、行为不一致）而非语言特定症状；触发器保持技术无关，除非技能本身就是技术专用。关键字覆盖要包含错误信息、症状、同义词、实际命令与库名。命名为动词优先，如 creating-skills 而非 skill-creation。
词元效率
getting-started 与高频引用的技能会加载进每次对话，因此目标词数为：入门工作流每个低于 150 词，高频加载技能总计低于 200 词，其他技能低于 500 词。技巧包括把细节移入工具 --help、用交叉引用替代重复说明、压缩示例、消除冗余。可用 wc -w skills/path/SKILL.md 验证。
交叉引用
引用其他技能时只用技能名并加明确要求标记，例如 “REQUIRED SUB-SKILL: Use superpowers:test-driven-development”。不要使用 @ 链接，因为 @ 语法会立即强制加载文件，在你需要之前就消耗 200k+ 上下文。
流程图使用
仅在非显而易见的决策点、可能过早停止的流程循环、以及“A 与 B 何时使用”的决策中使用流程图。参考材料用表格或列表，代码示例用 Markdown 代码块，线性指令用有序列表，标签不得无语义含义（如 step1、helper2）。可用同目录下的 render-graphs.js 将技能流程图渲染为 SVG。
代码示例
一个优秀示例胜过多个平庸示例。按场景选最相关语言：测试技术用 TypeScript/JavaScript，系统调试用 Shell/Python，数据处理用 Python。好示例应完整可运行、注释说明原因、来自真实场景、清晰展示模式、可直接改造。不要用 5 种以上语言实现、不要做填空模板、不要写生造示例。
铁律
没有失败测试就不写技能。这同样适用于新技能和对已有技能的编辑。先写技能后测试？删除重来。未测试就编辑？同样违规。不留任何例外：不为“简单新增”、不为“只加一节”、不为“文档更新”破例；不要把未测试的改动留作“参考”；不要在跑测试时“顺手改造”；删除就是删除。
测试不同技能类型
- 纪律约束型（规则/要求，如 TDD）：用学术性提问、压力场景、多重压力叠加（时间+沉没成本+疲惫）测试，找出借口并加显式反制，成功标准是智能体在最大压力下仍遵守规则。
- 技术型（操作指南）：用应用场景、变体场景、缺失信息测试，成功标准是能应用于新场景。
- 模式型（心智模型）：用识别场景、应用场景、反例测试，成功标准是正确判断何时该用与不该用。
- 参考型（文档/API）：用检索场景、应用场景、缺口测试，成功标准是找到并正确应用信息。
常见借口与反驳
资料列出常见跳过测试的借口及其现实：技能“显而易见”只是对你清楚；只是参考也可能有缺口；测试是过度工程，但未测试技能必有隐患；“有问题再测”等于部署前不测；测试太琐碎，但比在生产中调试坏技能轻松；“我有信心”往往保证出问题；学术审阅不等于实际使用；没时间测试，但部署未测试技能后期修复更费时。
防借口化
对纪律约束型技能，要显式堵住每个漏洞：不要保留为“参考”、不要在写测试时“改造”、不要看它、删除就是删除。还应加入基础原则，如“违反规则的字面即违反规则的精神”，以切断“我是在遵循精神”这类辩解。资料还提到可参考 persuasion-principles.md 中关于权威、承诺、稀缺、社会认同与统一原则的研究基础。
适用场景
本技能适用于：为 Claude Code、Codex 等智能体创建新技能；编辑已有技能；在部署前验证技能是否有效。个人技能存放于智能体专用目录（Claude Code 为 ~/.claude/skills，Codex 为 ~/.agents/skills/）。
限制与未提供信息
资料未提供该技能的具体收费模式、价格、平台支持范围、性能或效果数据，这些内容暂未提供。官方最佳实践可参见资料中提到的 anthropic-best-practices.md，完整字段规范参见 agentskills.io/specification。