用途
Writing Skills 用于在三个场景下使用：创建新技能、编辑已有技能、在部署前验证技能是否有效。它把测试驱动开发（TDD）的方法论应用到流程文档的编写中。
个人技能存放在运行时的技能目录中（Claude Code 上为 ~/.claude/skills/），Codex、Copilot CLI 和 Gemini CLI 也识别 ~/.agents/skills/ 作为跨运行时别名。具体路径可参考 codex-tools.md 或 gemini-tools.md。
核心流程
整个技能创建过程遵循 RED-GREEN-REFACTOR：
- 编写测试用例（使用子智能体的压力场景）
- 观察测试失败（基线行为）
- 编写技能（文档）
- 观察测试通过（智能体遵守）
- 重构（堵住漏洞）
核心原则是：如果没有观察过智能体在没有该技能时的失败，就无法知道技能是否教了正确的东西。
TDD 映射
| TDD 概念 | 技能创建 |
|---|---|
| 测试用例 | 使用子智能体的压力场景 |
| 生产代码 | 技能文档（SKILL.md） |
| 测试失败（RED） | 智能体在没有技能时违反规则（基线） |
| 测试通过（GREEN） | 智能体在技能存在时遵守 |
| 重构 | 在保持遵守的前提下堵住漏洞 |
何时创建技能
应当创建：技术对你来说并非直觉明显、你会跨项目反复参考、模式适用范围广（非项目专用）、他人也能受益。
不应创建：一次性解决方案、其他地方已有充分文档的标准实践、项目专用约定（放在说明文件中）、机械性约束（如果可用正则或校验强制执行，就自动化）。
技能类型
- 技术（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（1-2 句核心原则）、When to Use（症状与用例、何时不使用）、Core Pattern（前后代码对比）、Quick Reference（表格或要点）、Implementation（内联代码或链接文件）、Common Mistakes、Real-World Impact（可选）。
技能发现优化（SDO）
描述字段对技能被发现至关重要：智能体会读取 description 来决定是否加载某个技能。描述应只写触发条件，不要总结技能的工作流程。资料指出测试发现：当描述总结了工作流时，智能体可能直接按描述执行而不阅读完整技能内容，导致跳过技能正文中的步骤。
示例：
- ❌ 差：description: Use when executing plans - dispatches subagent per task with code review between tasks
- ✅ 好：description: Use when executing implementation plans with independent tasks in the current session
其它要点包括：关键词覆盖（错误信息、症状、同义词、工具名）、使用主动语态动词开头的命名（如 creating-skills 而非 skill-creation）、令牌效率（getting-started 工作流每个少于 150 词，频繁加载的技能总计少于 200 词，其它技能少于 500 词）。
交叉引用
引用其它技能时只用技能名并加上明确的需求标记，例如 REQUIRED SUB-SKILL: Use superpowers:test-driven-development。不要使用 @ 链接，因为 @ 语法会立即强制加载文件，消耗大量上下文。
流程图使用
流程图只用于：不明显的决策点、可能过早停止的流程循环、"何时用 A 还是 B" 的决策。不要用于参考材料、代码示例、线性说明。
可使用本目录下的 render-graphs.js 渲染技能流程图为 SVG：
node ./render-graphs.js ../some-skill # 每张图单独输出
node ./render-graphs.js ../some-skill --combine # 所有图合并为一个 SVG
代码示例
一个优秀的示例胜过许多平庸的示例。选择最相关的语言：测试技术用 TypeScript/JavaScript，系统调试用 Shell/Python，数据处理用 Python。示例应完整可运行、注释说明为什么、来自真实场景、清晰展示模式。不要用 5 种以上语言实现，不要做填空模板，不要编造示例。
文件组织
三种模式：自带内容的自包含技能（全部内联）；带可复用工具的技能（SKILL.md 加 example.ts 等可适配的工作代码）；带重型参考的技能（SKILL.md 加数百行 API 参考与 scripts/）。调用捆绑脚本时要通过解释器（bash scripts/tool.sh、node scripts/tool.js），不要用裸路径，因为某些插件打包器会剥离可执行位。
铁律
没有失败测试就不写技能。这条规则同时适用于新技能和对已有技能的编辑。先写技能再测试？删除重来。没有测试就编辑？同样违规。没有例外，包括"简单添加"、"只加一节"、"文档更新"。删除就是删除。
各类技能的测试方法
- 纪律强制型技能（规则/要求）：用学术问题、压力场景、多重压力组合测试；成功标准是智能体在最大压力下仍遵守规则。
- 技术型技能（操作指南）：用应用场景、变体场景、缺失信息测试；成功标准是能正确应用到新场景。
- 模式型技能（心智模型）：用识别场景、应用场景、反例测试；成功标准是能正确判断何时及如何应用。
- 参考型技能（文档/API）：用检索场景、应用场景、缺口测试；成功标准是能找到并正确应用信息。
常见跳过测试的借口
资料列出多种借口及其现实，例如"技能显然很清楚"（对你清楚不等于对其他智能体清楚）、"只是参考而已"（参考也可能有缺口）、"测试是杀鸡用牛刀"、"出问题再测"、"太繁琐"、"我有信心"、"学术评审就够了"、"没时间测"。结论一致：部署前必须测试，没有例外。
让形式匹配失败
在编写指导前先对基线失败分类。能防住一种失败类型的形式，可能在另一种失败类型上适得其反。例如：压力下跳过或违反规则（明知故犯）应使用禁止 + 合理化表格 + 红旗标记，而不是软性指导（"prefer..."、"consider..."）；如果只是输出形状不对（提示臃肿、内容埋没），则该使用另一种形式（原文此处被截断）。
限制与未提供内容
资料未提供该技能的价格、安装命令、支持平台清单、收费模式以及可量化的使用效果数据，这些内容暂未提供。