Agent 方法论框架 superpowers：技能怎么写才会被照做
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
你写的技能文件 Agent 不照做，九成不是因为写得不够详细，而是因为你从来没看过它在没有这份文件时会怎么失败。 superpowers 这个 MIT 许可证的开源仓库里，有一个专门管”怎么写技能”的元技能 writing-skills，它开篇第一句就把这件事挑明了：Writing skills IS Test-Driven Development applied to process documentation。技能文档就是生产代码，压力场景就是测试用例，你得先看它红，才知道该写什么让它绿。
站内已经有两篇讲通用方法论的文章：Claude Code Skills 怎么用 讲的是技能这个机制本身怎么在工具里跑起来，MCP 扩展框架怎么选 讲的是能力扩展的几条路线怎么取舍。本篇不重复这些，只干一件事：把 superpowers 这个具体项目怎么把”写技能”落成一套可执行、可验证的流程扒开，包括它的目录约定、描述字段的硬规则、失败类型与文体的映射表，以及它自己承认的代价。
一、它在解决什么：技能失效的两种形态
你写完一份技能文件交给 Agent，失效通常是两种形态。
第一种是没被找到。Agent 启动时并不会把所有技能正文都读进来，只有 YAML 里的 name 和 description 会被预加载进系统提示，正文要到 Agent 判断”这个技能跟当前任务相关”时才去读。description 是唯一一次曝光机会，它的作用不是介绍这个技能是什么，而是回答一个问题：我现在该不该读它。
第二种更隐蔽：被找到了，但没读完就动手了。writing-skills 里记了一个实测案例：某个技能的 description 里写了 “code review between tasks”，结果 Agent 就照这句话做了一次评审——尽管技能正文的流程图清清楚楚画着两次（先查规格符合性，再查代码质量）。把 description 改成纯触发条件 Use when executing implementation plans with independent tasks in the current session 之后，Agent 才回去读流程图、按两段走。
文档里给这个现象下的定论是：描述里的工作流摘要会创造一条 Agent 必然会走的捷径，技能正文于是变成被跳过的文档。 这条结论直接推出了它最硬的一条格式规则：description 只准写”什么时候用”，不准写”怎么做”。
二、SKILL.md 长什么样：字段、骨架、拆分红线与仓库结构
writing-skills 自己的 frontmatter 就是最短的范例：
---
name: writing-skills
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
---
两个必填字段，整段 frontmatter 上限 1024 字符，name 只能用字母、数字和连字符，description 用第三人称、以 “Use when…” 开头、尽量控制在 500 字符以内。它在 checklist 里还专门标了一条：名字里别出现括号和特殊字符。
description 的好坏对照，文档里给了成对的例子，反例都不是”写得太差”，而是”写得太像摘要”：
# ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks
# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session
另外两条容易踩的：第一人称写法（“I can help you with async tests”）是错的，因为这段文字会被注入系统提示；提到具体技术但技能本身并不绑定该技术（“Use when tests use setTimeout/sleep and are flaky”）也是错的，正确写法是描述问题本身——竞态、时序依赖、时好时坏。
正文骨架给的顺序是 Overview（核心原则一两句话）、When to Use（症状清单加”什么时候别用”）、Core Pattern（前后对照）、Quick Reference（表格便于扫读）、Implementation、Common Mistakes，最后是可选的 Real-World Impact。
拆文件的红线是量化的：100 行以上的重型参考资料和可复用的脚本/模板才拆出去，原则、概念、50 行以内的代码模式一律留在正文。Anthropic 那份最佳实践补了一条：SKILL.md 正文控制在 500 行以内。
还有个反直觉但实用的约束——引用只准一层深。原因写得很直白：当引用是从”另一个被引用的文件”里发出来时，Agent 可能只用 head -100 之类的方式扫一眼就走，拿到的是残缺信息。所有参考文件都得从 SKILL.md 直接链出去。超过 100 行的参考文件，顶部还要放一份目录。
说完格式，看一眼这个元技能自己是怎么摆的。下面这张表按实际读到的文件路径整理，方便你对着自己的技能库比对：
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 元技能正文 | 技能创建的 TDD 循环、SDO 规则、文体选择、创建 checklist | skills/writing-skills/SKILL.md | 每次新建或修改技能，第一份要读的 |
| 官方最佳实践 | 简洁性原则、自由度分级、渐进披露、脚本编写规范、交付前 checklist | skills/writing-skills/anthropic-best-practices.md | 拿不准格式细节、或技能里要带可执行脚本时 |
| 测试方法论 | 压力场景怎么写、七类压力、堵漏洞的四步、元测试话术 | skills/writing-skills/testing-skills-with-subagents.md | 技能上线前跑验证，这是主战场 |
| 说服力原理 | 权威/承诺/稀缺等原则为什么对模型有效，引了外部研究做背书 | skills/writing-skills/persuasion-principles.md | 纪律型技能怎么措辞才顶得住压力 |
| 完整测试样例 | 一次完整测试战役的实录 | skills/writing-skills/examples/CLAUDE_MD_TESTING.md | 想看真实流程长什么样，而不是只看规则 |
| 流程图规范与渲染 | graphviz 风格约定；把技能里的图渲成 SVG 给人看 | skills/writing-skills/graphviz-conventions.dot、render-graphs.js | 技能里要画决策图、或要给同事讲流程时 |
| 跨运行时路径说明 | 个人技能目录在不同运行时里的位置 | skills/using-superpowers/references/ 下的 codex-tools.md、gemini-tools.md 等 | 你不只用一个 CLI，要让技能跨运行时可见时 |
补一句路径事实：个人技能放在运行时的技能目录，Claude Code 上是 ~/.claude/skills/；Codex、Copilot CLI 和 Gemini CLI 同时认 ~/.agents/skills/ 这个跨运行时别名。整个 skills/ 目录是扁平命名空间，14 个技能平铺在一层，不做分类子目录——理由是搜索友好。
三、按失败类型选文体：这是最容易被忽略的一节
多数人写规则的直觉是”写得更严一点”。writing-skills 里的 Match the Form to the Failure 一节直接反对这个直觉：能给一种失败类型上保险的文体，会在另一种失败类型上明确起反作用。 它给的映射关系是：
- 明知故犯型（知道规则，压力下照样跳过）→ 用禁止句 + 借口对照表 + 红旗清单。
- 形状跑偏型（照做了，但产出物结构不对，比如提示词臃肿、结论被埋、把规格又复述一遍）→ 用正向配方或契约：直说产出物由哪几部分组成、按什么顺序。这时候用禁止句清单反而更糟。
- 遗漏必填项型（在已有产出物里漏了一块）→ 用结构性手段：在模板里挖一个必填的槽位，而不是在模板旁边写提醒。
- 行为要看条件型 → 写成挂在可观测谓词上的条件句（“如果简报存在，就引用它”），而不是”无条件规则 + 一堆豁免条款”。
为什么禁止句会在”形状跑偏”上翻车？文档给的解释是：当存在一个竞争性激励时（比如”把提示词写得自包含”），Agent 会跟 “don’t X” 讨价还价。在针对派发提示词措辞的对照实验里，禁止句那一组产出的不想要内容明显多于配方组，两组分布完全分开，趋势上甚至比不给任何指导的对照组更差。文档同时提醒：别把这个结论当成定论直接套，自己的场景要自己跑一遍微测试，只是别再把禁止句当默认选项。配方没有可谈判的空间——产出物要么符合声明的形状，要么不符合。
跟着这条还有两条硬约束，比主结论更值钱：
- 不许加”看情况”的从句。 “Don’t X unless it matters” 会把谈判重新打开。文档记了个实测：在一条已经跑赢的配方后面追加一个 nuance clause，结果就从稳定变成了忽好忽坏。真有例外，就单独写成一条挂在可观测条件上的条件句。
- 豁免条款不会乖乖限定范围。 “这条限制不适用于代码块”这种写法，实测仍然会把代码块给压掉。如果产出物里确实有一部分必须豁免，得重新组织结构让规则够不着它。
纪律型技能怎么写才顶得住，仓库给的是四件套：把每个具体的绕道方式逐条堵死（不只是”删掉”，而是”删掉、重来，不许留作参考、不许一边写测试一边照抄、不许再看一眼”）；在开头放一条”违反规则的字面就是违反规则的精神”断掉一整类狡辩；把测试里抓到的借口原话建成对照表；再给一份红旗清单让 Agent 自查：
## Red Flags - STOP and Start Over
- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."
四、怎么验证：压力场景与微测试
这部分是 superpowers 跟”写份 markdown 就完事”最大的分野。它的铁律是：
NO SKILL WITHOUT A FAILING TEST FIRST
而且明说这条同时适用于新建技能和修改既有技能，“只是加一节""只是改文档”都不是例外。
RED 阶段的做法是：把技能拿掉，用压力场景跑一个全新上下文的子代理，把它的选择和原话借口逐字记下来。压力场景怎么写，它列了七类可叠加的压力——时间、沉没成本、权威、经济、疲惫、社交（怕显得教条）、实用主义（“要务实不要教条”），并建议至少叠三种。场景要给具体的 A/B/C 选项、真实文件路径、真实时间约束，问法用”你会怎么做”而不是”你应该怎么做”，并且不许留”我会去问人”这种逃生口。GREEN 阶段只写刚好能挡住这些具体失败的内容；REFACTOR 阶段抓新借口、加新对策、再测。
让这套流程在成本上能落地的是另一层安排——先做措辞微测试，再上完整压力场景。规则有五条：
- 每次调用只取一个全新上下文的样本，系统提示要放这段指导将来真实所处的完整语境（整份技能或整个提示模板），而不是把指导单独拎出来测。
- 必须带一个不给任何指导的对照组。 如果对照组本身就没出现这个失败，那就没什么好修的——直接停手，别写这条指导。
- 每个变体至少 5 次重复，单个样本会骗人。
- 每一条被标记命中的结果都要人工读一遍。模板回声和被引用的反例都会伪装成命中，光看自动统计会同时高估失败率和成功率。
- 方差本身是个指标。 指导真正生效时，多次重复会收敛到同一种形状；5 次跑出 5 种理解，说明措辞没有约束力，该收紧形式而不是加字。
微测试只验证措辞，不替代纪律型技能的压力场景。这个分工写得很克制。
另一份最佳实践给的验证路线偏工程一点：先建评测再写文档，至少准备三个评测场景，先量出没有技能时的基线，再写刚好够用的内容。还有一个双 Agent 模式——用 Agent A 帮你设计和改技能，用装了技能的 Agent B 去干真实任务，观察 B 卡在哪里，再把观察带回给 A。评测场景怎么设计、指标怎么定，可以对照站内的 Agent 评测方法 一起看。
五、边界与代价：它放弃了什么
这套东西不是免费的，仓库自己也没打算装作免费。
它明确变慢。 每写一个技能都要跑基线、跑带技能的对照、跑重复实验，还要人工逐条读命中结果。文档甚至专门立了一节 STOP：写完任何一个技能必须停下来完成部署流程，不许批量攒着一起测，理由是”批量更高效”这个念头本身就是要防的东西。对一次性的小改动，这个投入明显是过度设计。
它明确不管一部分事。 writing-skills 列了四类不该建技能的情况：一次性方案、别处已有充分文档的标准做法、项目专属约定（这些该进你的指令文件，不是技能），以及能用正则或校验脚本机械约束的东西——文档的原话是，能自动化就自动化，文档留给需要判断的部分。这条划得很利落：技能不是规则引擎的替代品。
测试也不是全都要做。 测试方法论那份文件写了不用测的情况：纯参考类技能（API 文档、语法手册）、没有规则可违反的技能、Agent 根本没有动机绕开的技能。纪律型技能才是压力测试的目标。
上下文预算是硬约束，啰嗦是可预期的副作用。 最佳实践把上下文窗口称为公共资源，你的技能要跟系统提示、对话历史、其他技能的元数据抢地方；默认假设是”Agent 已经很聪明了”，只补它没有的信息，每一段都要过一遍”这段话值不值它花掉的 token”。这套写法会让技能显得干巴巴，不适合当给人读的教程。而纪律型技能靠禁止句、借口对照表、红旗清单堆出约束力，Agent 照做时也会把这些条目复述出来——换来压力下的稳定性，付出的是过程输出变长。怎么分配这份预算，可以参考 上下文预算怎么定。
自由度要匹配任务性质，不是越严越好。 最佳实践用了一个类比：悬崖之间的窄桥只有一条安全路径，要给精确指令和护栏；空旷原野上很多条路都通，给个大方向就行。数据库迁移属于前者，代码评审属于后者。把评审也写成低自由度脚本，是另一种形式的过度设计。
六、上手清单：会踩什么坑，怎么绕
坑一：description 写成了技能摘要。 会踩是因为”描述”这个词天然引导你去概括内容，而且概括得越全你越觉得有帮助。绕法是把这个字段当成一个是非题的输入——它只回答”现在该不该读正文”，任何形如”先 A 再 B”的表述都删掉。
坑二：一上来就写文档。 会踩是因为你脑子里已经有”该防什么”的假设了，写起来很顺。但基线测试量的是 Agent 实际会怎么错，跟你的假设常常不是一回事。绕法是先跑不带技能的场景，把借口原话抄下来再动笔；writing-skills 里那张”跳过测试的借口”表把常见自我开脱都列全了，包括”这技能明显很清楚""就是个参考文档""我有信心”。
坑三：用 @ 语法引用别的技能。 会踩是因为它看起来只是个链接。实际上 @ 会立刻强制加载文件，在你还没用到之前就把上下文吃掉。绕法是只写技能名并标明强度，用 **REQUIRED SUB-SKILL:** 或 **REQUIRED BACKGROUND:** 这类前缀，让人一眼看出是必读还是选读。
坑四：全塞进 SKILL.md，或者反过来拆得太碎。 会踩是因为没有量化标准，全凭手感。绕法是记住那三个数：重型参考 100 行以上才拆、50 行以内的代码留在原地、SKILL.md 正文不超过 500 行；拆出去的文件必须从 SKILL.md 一层直达。
坑五：长度失控而不自知。 会踩是因为 markdown 写着写着就长了，肉眼估不准。仓库给的办法很土但有效——直接数：
wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total
会被高频加载的技能目标是 200 词以内，其余技能 500 词以内。
坑六：用流程图画顺序步骤。 会踩是因为图看起来专业。但它规定流程图只用于三种情况：不明显的决策点、你可能提前停下的循环、A 与 B 的取舍；参考资料该用表格、代码该用代码块、线性步骤该用编号列表。节点标签也不许用 step1、helper2 这种没有语义的名字。
坑七：命名用名词短语。 它的取向是动词优先、用动名词：creating-skills 而不是 skill-creation，condition-based-waiting 而不是 async-test-helpers，root-cause-tracing 而不是 debugging-techniques——按你做什么或按核心洞察来命名。
坑八：路径写成 Windows 风格。 会踩纯粹是因为你在 Windows 上开发，最佳实践要求一律用正斜杠。同一节还有一条容易漏：技能里引用 MCP 工具必须用 ServerName:tool_name 这种全限定名，否则在多个 MCP 服务同时在线时会找不到工具。这类描述的取舍逻辑，可以对照 工具描述怎么写。
收尾：先做哪三件事
手上已经有一批技能文件的话，别急着按这套标准重写。按这个顺序自查成本最低：把每份技能的 description 单独拎出来读，只保留触发条件，出现流程摘要的一律删——这一步改动最小、收益最直接；挑一个你最不放心的纪律型技能，写一个叠了三种压力的场景，把技能拿掉跑一遍看基线有多糟，如果基线根本不出问题，那份技能可能压根不需要存在；给”Agent 老是漏掉某一块”的那份技能换文体，从”别漏”改成在模板里挖一个必填槽位。
要继续深挖，读文件的顺序建议是：skills/writing-skills/SKILL.md 打底，testing-skills-with-subagents.md 学怎么设计压力场景，anthropic-best-practices.md 补格式与脚本规范，最后看 examples/CLAUDE_MD_TESTING.md 那份完整实录。这是别人的项目，也在持续改，别把每一条都当成不变的教条——可以直接搬走的，是”先看它怎么失败，再决定写什么”这个顺序本身。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。