writing-skills Skill：让 Claude Agent 的技能文档真正可执行

Superpowers 是由 Jesse Vincent（@obra）和 Prime Radiant 团队维护的 Agent 开发方法论仓库，主仓库 star 数已超 266k，是目前最知名的 AI 编程 Agent 工具链之一。writing-skills 是该体系中的元技能（skill about skills），它将测试驱动开发（TDD）的核心思想移植到 Skill 文档编写领域——提出「先制造失败、再写出对策」的标准流程，让 Skill 真正可被 Agent 理解和执行，而不是沦为无人看的说明书。目前在 SkillHub.club 热门 Skill 排行榜位居第 4，热度分数 46.6，属于 superpowers 家族中曝光最稳定的技能之一。

功能与原则

writing-skills 的核心功能是提供一套系统化的 Skill 创作方法论，确保写出的 Skill 能被 Agent 真正执行而非仅被浏览。其设计原则有三条：

• TDD 映射：将软件开发中的 RED-GREEN-REFACTOR 循环完全映射到文档写作，Skill 即「生产代码」，压力测试场景即「测试用例」。
• 技能发现优化（SDO）：强调 description 字段必须只描述触发条件，而非总结工作流程，防止 Agent 跳过正文只读描述。
• 反理性化加固：针对 Agent 在压力下会找借口绕过规则这一特性，提供明确的禁止条款、合理化借口表格和红旗列表。

认可度

• GitHub Star：obra/superpowers 主仓库超 266k stars（截至 2026-08-04），23.8k forks，45 位贡献者
• SkillHub 排名：Hot Skills 第 4 位，热度分数 46.6
• Skill 类型分布：S/A/B/C 四档，writing-skills 属于 superpowers 体系的核心组件，superpowers 整体在 SkillHub 生态中拥有极高的引用率和二次开发率
• 社媒讨论：在 GitHub trending、Twitter/X AI 开发者社区、Reddit r/ClaudeAI 等多个渠道持续有讨论，Prime Radiant 团队保持高频更新（最新版本 v6.2.0，2026-07-24）

链接

GitHub（主仓库，含 writing-skills 源码）：https://github.com/obra/superpowers

writing-skills 直接路径：https://github.com/obra/superpowers/tree/main/skills/writing-skills

原作者

Jesse Vincent（@obra），GitHub: https://github.com/obra

Jesse Vincent 是 Prime Radiant 联合创始人，长期专注于开发者工具和编程环境研究。他主导开发的 superpowers 项目将二十年软件工程经验系统化，为 AI coding agent 提供了一套完整的开发方法论，在 GitHub 上拥有极高的社区认可度。

介绍

writing-skills 最初源于一个观察：大多数 Skill 文档写得像是「叙事性回忆录」——记录作者某次如何解决了一个问题，而不是提炼出可被 Agent 重复使用的可执行原则。结果是 Agent 读完后依然按照自己的直觉行事，Skill 形同虚设。

该 Skill 从 TDD 中汲取灵感，引入「先制造失败」的核心思想：创作者应先用子 Agent 模拟一个压力场景（不加载目标 Skill），记录 Agent 在没有指导时会怎么做、找什么借口；然后针对这些具体的失败模式编写 Skill 文档；最后重新运行测试，验证 Agent 现在是否遵守规则。这个循环持续迭代，直到 Skill 能够抵御所有已知和可预见的理性化绕过。

除了方法论，writing-skills 还提供大量实操规范：YAML frontmatter 的格式要求（name 只能用字母/数字/连字符，description 必须以「Use when…」开头且不超过 500 字符）、SDO 关键字布局策略、token 效率目标（getting-started 类 <150 词，其他常用类 <200 词）、以及如何用流程图和 Quick Reference Table 优化文档结构。

特点

• TDD for Documentation：将软件开发中最成功的质量保证机制移植到 Skill 创作，强制要求「无失败测试，不写 Skill」。
• SDO（Skill Discovery Optimization）：description 只写触发条件、不写工作流程，防止 Agent 把描述当捷径绕过正文——这是目前 Skill 编写中最容易被忽视也最致命的错误。
• 反理性化加固体系：提供借口表格、红旗列表、禁止条款模板，专门解决「Agent 知道规则但在压力下仍然绕过」这一高频失效模式。
• Token 效率规范：对不同类型 Skill 设置字数上限，防止 Skill 过长导致每次会话都加载卡顿。
• 跨 Agent 兼容：SkillHub 显示支持 Claude Code、Codex、Cursor、Kimi Code、OpenCode 等多平台，writing-skills 的方法论适用于所有遵循 Anthropic SKILL.md 规范的 Agent。

使用方法

安装：writing-skills 是 superpowers 体系的一部分，安装 superpowers 即包含该 Skill：

Claude Code：/plugin install superpowers@claude-plugins-official

Cursor：/add-plugin superpowers 或在插件市场搜索「superpowers」

其他 Agent 参考：https://github.com/obra/superpowers#installation

触发：当用户说「create a new skill」「write a skill for X」「edit this skill」或类似表达时，该 Skill 自动激活。

基础工作流：

1. RED 阶段：用子 Agent 跑一个压力场景（不加目标 Skill），记录 Agent 的具体失败行为和理性化借口。
2. GREEN 阶段：针对每个失败点编写 Skill 文档段落，重跑场景验证合规性。
3. REFACTOR 阶段：找到新借口/漏洞，添加显式反制条款，重复直到 Skill 无懈可击。

最小示例：假设要写一个 TDD skill，先问自己「Agent 在没有 TDD 要求时会怎么写代码？」，观察并记录其行为，然后写出禁止条款（写代码先于测试？删掉，重来）——这才是一个合格的 TDD Skill。

使用场景与人群

适用场景：为团队或开源社区编写可复用的 Agent Skill；修复已有但 Agent 不遵守的 Skill；构建内部最佳实践库。

目标用户：有 AI coding agent 使用经验、想把工作方法论系统化沉淀的开发者；为 Agent 编写 Skill 的 technical writer；希望建立内部 Skill 规范的企业团队。

不适合：只是想偶尔用 Agent 完成一次任务、不关心 Skill 复用性的普通用户。

输入与输出案例

案例 1：写一个 Code Review Skill

输入（用户）：「帮我写一个 code review skill，要求 agent 在提交前做检查。」

Agent 行为（RED 阶段，无 Skill）：Agent 直接进行一次 review，把所有问题列在一起，不区分优先级，不要求修改验证。

Skill 写入后的行为（GREEN 阶段）：Agent 严格做 spec 合规性检查 + 代码质量检查两次 review，要求每次发现必须验证修复。

案例 2：修复一个失效的 Skill

输入（用户）：「我们有个 TDD skill，但 agent 经常跳过测试直接写代码。」

Agent 行为（RED 阶段）：Agent 说「太简单了不需要测试」「我已经手动跑过了」「测试之后做也可以」。

Skill 写入后（GREEN 阶段）：Skill 明确「写代码先于测试 = 删掉重做」，附完整红旗列表和借口表格，Agent 在任何压力下都执行 RED-GREEN-REFACTOR 循环。

GitHub: https://github.com/obra/superpowers