这个 GitHub 爆火的 Skill 编写方法论到底能干嘛？实测来了
📌 本文介绍的 Skill 搬运自 GitHub 开源项目 obra/superpowers，该项目目前拥有 17.6 万+ Star，是 AI Agent 技能领域影响力最大的项目之一。
这个 Skill 是什么？
writing-skills 是来自顶级项目 obra/superpowers 的核心技能之一。它解决了一个非常实际的问题：如何编写高质量的 AI Agent 技能文档（SKILL.md）。
在 AI Agent 生态中，Skill 是一种让 Claude Code、Codex、Cursor 等 AI 编程助手掌握特定能力的机制。但写一个”能用的”Skill 很容易，写一个”好用的”Skill 很难——Agent 太聪明了，它会在压力下找到各种漏洞和自我辩解的方式来绕过你定的规则。
writing-skills 提出了一个非常新颖的思路：把 TDD（测试驱动开发）应用于流程文档编写。
核心思路：TDD × 文档
写过代码的同学都熟悉 TDD 的 RED-GREEN-REFACTOR 循环：先写失败的测试 → 写最少代码让测试通过 → 重构。writing-skills 把这个思想搬到了文档编写上：
| TDD 概念 | 技能编写对应 |
|---|---|
| 测试用例 | 用子 Agent 构造的压力场景 |
| 生产代码 | 技能文档 SKILL.md |
| 测试失败（RED） | 没有技能时 Agent 违反规则 |
| 测试通过（GREEN） | 有技能时 Agent 遵守规则 |
| 重构 | 堵上漏洞同时保持合规 |
核心原则只有一句话：如果你没有亲眼看到 Agent 在没有该技能时失败过，你就不知道这个技能教的东西对不对。
铁律
没有失败的测试，就没有技能。
这条铁律适用于新建技能和编辑现有技能。没有例外。
先写技能再测试？删掉，重来。编辑技能没有测试？同样违规。
实际工作流程
RED 阶段：观察失败
在没有技能的情况下，用子 Agent 运行压力场景（比如给它加时间压力、沉没成本压力、疲惫压力），然后逐字记录：
- Agent 做了什么选择？
- 它用了什么自我辩解（原话）？
- 哪些压力触发了违规？
GREEN 阶段：编写最小技能
针对 RED 阶段观察到的具体自我辩解，编写最精简的技能文档。不要为假设情况添加额外内容。然后验证：有技能时 Agent 是否遵守规则。
REFACTOR 阶段：堵上漏洞
Agent 找到了新的辩解方式？添加明确的反制。反复测试直到坚不可摧。
技能编写的完整检查清单
前置元数据规范
name：仅用字母、数字和连字符description：以 “Use when…” 开头，仅描述触发条件，绝不要概述工作流- 总计不超过 1024 字符
这里有个关键陷阱：如果 description 概述了技能的工作流程，Claude 可能会照着 description 做而不去读完整的技能正文。实测表明，把 description 从 “dispatches subagent per task with code review between tasks” 改为 “Use when executing implementation plans with independent tasks” 后，Agent 从只做一次审查变成了正确地遵循两阶段审查流程。
关键词覆盖
在技能中使用 Agent 会搜索的词：
- 错误消息：“Hook timed out”、“ENOTEMPTY”、“race condition”
- 症状：“flaky”、“hanging”、“zombie”、“pollution”
- 同义词：“timeout/hang/freeze”
- 工具：实际命令、库名、文件类型
命名原则
- 主动语态、动词优先：
creating-skills而非skill-creation - 动名词（-ing）适合过程类：
testing-skills、debugging-with-logs - 用你做的事或核心洞察来命名：
condition-based-waiting而非async-test-helpers
Token 效率
高频加载的技能会在每次对话中加载，每个 Token 都很宝贵：
- getting-started 工作流：< 150 词
- 高频技能：< 200 词
- 其他技能：< 500 词
技巧：把细节移到 --help、使用交叉引用、压缩示例、消除冗余。
让技能免疫自我辩解
Agent 很聪明，会在压力下找到各种漏洞。writing-skills 给出了几个关键策略：
1. 明确堵上每个漏洞
不要只说”先写测试再写代码”，要列出所有不能做的绕行方式：不要作为”参考”保留、不要在写测试时参考它、不要看它、删除就是删除。
2. 应对”精神 vs 文字”的争论
在文档早期加入：违反规则的字面含义就是违反规则的精神实质。
3. 建立自我辩解表
把 Agent 提出的每个借口都记录下来并逐一反驳，形成表格。
4. 创建红旗列表
让 Agent 在自我辩解时容易自检：先写代码、“我已经手动测试过了”、“这个情况不一样因为…”——看到这些就停下来重来。
四种技能类型的测试方法
| 技能类型 | 示例 | 测试方法 |
|---|---|---|
| 纪律执行类 | TDD、verification-before-completion | 学术问题 + 压力场景 + 多重压力组合 |
| 技术类 | condition-based-waiting | 应用场景 + 变体场景 + 信息缺失测试 |
| 模式类 | reducing-complexity | 识别场景 + 应用场景 + 反例 |
| 参考类 | API 文档 | 检索场景 + 应用场景 + 漏洞测试 |
常见反模式
- ❌ 叙事式示例：“在 2025-10-03 的会话中，我们发现……”——太具体，不可复用
- ❌ 多语言稀释：example-js.js、example-py.py、example-go.go——质量平庸、维护负担
- ❌ 流程图中的代码：不能复制粘贴，难以阅读
- ❌ 通用标签：helper1、helper2——标签应该有语义含义
适用场景
- ✅ 需要为 AI Agent 编写技能文档的任何开发者
- ✅ 想要提高 Agent 规则遵守率的团队
- ✅ 对 TDD 方法论感兴趣、想把它应用到文档工程的人
- ✅ 想要系统化测试和优化 Prompt/技能的质量追求者
不适用场景
- ❌ 一次性解决方案（不需要写成技能）
- ❌ 项目特定惯例（应该放到 CLAUDE.md）
- ❌ 可以用代码自动化的机械约束（不要浪费文档）
个人评价
推荐指数：⭐⭐⭐⭐⭐
writing-skills 是我见过的最有创意的技能编写方法论之一。它把软件工程中最成熟的实践——TDD——应用到了 AI Agent 的文档工程中，这个跨界组合产生了惊人的效果。
最打动我的是它的”铁律”哲学：没有测试的技能不应该存在。这不仅保证了技能质量，更重要的是建立了一种纪律文化。在 AI Agent 越来越强大的时代，这种纪律恰恰是我们最需要的。
原文档有 22,000+ 字符，包含大量实操细节、示例代码和完整的检查清单。强烈建议对 AI Agent 开发感兴趣的同学去 obra/superpowers 看原文。
本文介绍的 Skill 已搬运至中文版本，详见 awesome-ai-agent-skills-zh 仓库。
文章分享
如果这篇文章对你有帮助，欢迎分享给更多人！
音乐
暂未播放