Writing Skills 是一套面向 AI 智能体技能（Skill）文档的编写方法论，其核心主张是：写技能文档就是「把测试驱动开发（TDD）应用到流程文档上」。
用途与适用时机
当需要创建新的技能、编辑已有技能，或在部署前验证技能是否真正起作用时使用。文档建议在以下情况创建技能：该方法并非你一眼就能想到、你会跨项目反复引用、模式适用范围广（而非项目专属）、他人也能受益。不应为以下情况创建技能：一次性的解决方案、别处已有完善文档的标准做法、项目专属约定（应放进 CLAUDE.md）、以及可用正则或校验自动化的机械约束。
主要能力与方法
核心流程遵循 RED-GREEN-REFACTOR 循环：先写测试用例（带子智能体的压力场景），观察其失败（基线行为），再写技能文档，观察测试通过（智能体遵守），最后重构（封堵漏洞）。文档强调核心原则：如果你没有亲眼看到智能体在没有该技能时失败，就无法确定这个技能教的是对的东西。使用该技能前，必须先理解 superpowers:test-driven-development，因为它定义了基础的 RED-GREEN-REFACTOR 循环。
技能被定义为经过验证的技术、模式或工具的参考指南，是可复用的技术、模式、工具与参考手册，而不是「我某次如何解决问题」的叙述。技能分为三类：技术类（含步骤的具体方法）、模式类（思考问题的方式）、参考类（API 文档、语法指南、工具文档）。
使用方式与文件组织
目录采用扁平命名空间，每个技能一个目录，SKILL.md 为必需的主参考文件，仅在需要时拆出支撑文件：重参考（100 行以上）如 API 文档、可复用工具（脚本、工具、模板）单独成文件；原则与概念、50 行以内的代码模式保持内联。SKILL.md 的 frontmatter 使用 YAML，name 与 description 为必填字段，总计不超过 1024 字符；name 只能用字母、数字和连字符；description 用第三人称、以「Use when...」开头、只描述何时使用而不描述技能做什么，尽量控制在 500 字符以内。
文档特别强调描述字段不应概括技能的工作流程：测试发现，当描述总结了工作流，Claude 可能直接按描述执行而不去读完整技能内容。同时给出关键词覆盖（错误信息、症状、同义词、工具命令）、动词优先的命名（如 creating-skills 而非 skill-creation）、词数控制（入门工作流每个少于 150 词、频繁加载的技能总计少于 200 词、其他技能少于 500 词）以及跨技能引用方式（只用技能名并加显式要求标记，避免 @ 语法强制加载消耗上下文）等细则。
流程图仅用于非显而易见的决策点、可能过早停止的流程循环、以及「A 还是 B」的选择；参考材料、代码示例、线性指令不应使用流程图。代码示例主张一个优秀示例胜过多个平庸示例，选择最相关的语言，完整可运行、注释说明原因、来自真实场景。
测试与限制
文档提出「铁律」：没有失败的测试就不写技能，新建与编辑同样适用。测试方法按技能类型不同：纪律约束型技能用学术问题与多重压力场景测试；技术型技能用应用、变体与信息缺口场景测试；模式型技能用识别、应用与反例测试；参考型技能用检索、应用与缺口测试。文档还列举了跳过测试的常见借口及其反驳，并强调要显式封堵漏洞、回应「精神 vs 字面」的辩解。
需要说明的是：官方文档中关于 Anthropic 技能编写最佳实践、persuasion-principles.md 等引用资料，本资料未提供其具体内容；个人技能目录路径、render-graphs.js 等工具的具体信息也仅以原文形式给出，未提供更多说明。