概述
Writing Skills 本质上是把测试驱动开发（TDD）应用到流程文档的编写上。它的核心主张是：先写测试用例（用子智能体构造压力场景），看着它失败（基线行为），再写技能（文档），看着测试通过（智能体遵守规则），最后重构（堵住漏洞）。
核心原则：如果你没有亲眼看到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。
前置要求
文档明确要求：使用该技能前，你必须理解 superpowers:test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 循环，而本技能是把 TDD 适配到文档写作上。
关于 Anthropic 官方技能编写最佳实践，文档指向 anthropic-best-practices.md，作为对本技能 TDD 取向方法的补充。
什么是技能
技能是关于已验证的技术、模式或工具的参考指南，帮助未来的智能体找到并应用有效方法。
技能是：可复用的技术、模式、工具、参考指南。
技能不是：关于你某次如何解决问题的叙述。
技能的 TDD 映射
文档给出的对应关系如下：
- 测试用例 → 与子智能体进行的压力场景
- 生产代码 → 技能文档（SKILL.md）
- 测试失败（RED）→ 智能体在没有技能时违反规则（基线）
- 测试通过（GREEN）→ 智能体在技能存在时遵守规则
- 重构 → 在保持合规的前提下堵住漏洞
配套流程：先写测试（在写技能之前先运行基线场景）→ 看它失败（记录智能体使用的具体合理化说辞）→ 最小代码（写出针对这些具体违规的技能）→ 看它通过（验证智能体现在遵守）→ 重构循环（发现新的合理化说辞 → 堵住 → 重新验证）。整个技能创建过程都遵循 RED-GREEN-REFACTOR。
何时创建技能
应当创建：技术对你来说并非显而易见；你会跨项目反复引用它；模式适用面广（非项目专属）；其他人也会受益。
不应创建：一次性解决方案；已有充分文档的标准实践；项目专属约定（应写入你的 instructions 文件）；机械性约束（如果可以用正则或校验自动化，就自动化它——把文档留给需要判断力的地方）。
技能类型
- 技术（Technique）：有步骤可循的具体方法（如 condition-based-waiting、root-cause-tracing）。
- 模式（Pattern）：思考问题的方式（如 flatten-with-flags、test-invariants）。
- 参考（Reference）：API 文档、语法指南、工具文档（如 office docs）。
目录结构
skills/ skill-name/ SKILL.md # 主参考文件（必需） supporting-file.* # 仅在需要时提供
采用扁平命名空间——所有技能都在一个可搜索的命名空间中。需要拆分为独立文件的情况：重型参考（100 行以上）如 API 文档、完整语法；可复用工具如脚本、实用程序、模板。保留在内联的情况：原则与概念；代码模式（少于 50 行）；其余内容。
SKILL.md 结构
Frontmatter（YAML）：
- 两个必填字段：name 和 description（全部受支持字段见 agentskills.io/specification）。
- 总计最多 1024 字符。
- name：仅使用字母、数字和连字符（不得含括号、特殊字符）。
- description：第三人称，只描述“何时使用”（不描述“做什么”）。以“Use when...”开头，聚焦触发条件；包含具体症状、情境和上下文；绝不概括技能的过程或工作流；尽量控制在 500 字符以内。
示例：
name: Skill-Name-With-Hyphens description: Use when [specific triggering conditions and symptoms]
正文推荐分节：Overview（这是什么？用 1-2 句话说明核心原则）、When to Use（若决策不明显可放小型内联流程图；用项目符号列出症状和使用场景；以及何时不要使用）、Core Pattern（用于技术/模式，前后代码对比）、Quick Reference（用于快速浏览常见操作的表或项目符号）、Implementation（简单模式用内联代码；重型参考或可复用工具链接到文件）、Common Mistakes（出错点与修复方法）、Real-World Impact（可选，具体结果）。
技能发现优化（SDO）
对未来智能体能否发现你的技能至关重要。第 1 点是“丰富的 description 字段”：目的是让你的智能体读取 description。
运行环境与路径
个人技能位于你所用运行时的 skills 目录中（在 Claude Code 上是 ~/.claude/skills/）；其他运行时的路径可参见 codex-tools.md 或 gemini-tools.md。Codex、Copilot CLI 和 Gemini CLI 也都会把 ~/.agents/skills/ 识别为跨运行时的别名。
限制
关于该技能的收费、价格、平台支持范围、实际效果或使用步骤，资料中未提供更多信息。