★ FEATURED ARTICLE 开头就直接聊。你可能在 GitHub 或技术论坛上刷到过 “superpowers” 这个词第一反应多半是这又是什么中二命名但如果你正在用 Codex CLI、Claude Code 这类终端里的 AI 编程助手并且被“每次都要重新教它做事”折磨过那 superpowers 这套东西确实值得花一个下午研究清楚。简单说superpowers 是一套给 AI 编码助手挂载“技能包”的方案。它的核心不是帮你写某一行代码而是把“遇到什么任务就走什么流程”这件事固化下来让 AI 不再是每次对话都失忆的临时工而是一个带着工作手册上岗的正式员工。这篇文章适合已经被 AI 编程助手吊打过、想让 AI 输出更稳定的人也适合团队里想沉淀统一开发规范的人。我会从原理讲到安装再给出 Java 场景的完整示例和排坑记录。1. 先搞清楚 superpowers 到底是什么我一开始也以为 superpowers 是个独立的 IDE 或者编译器结果装上之后发现完全不是一回事。它更像一个“技能加载框架”挂在 Codex CLI、Claude Code 这类 agent 工具上作用是让 AI 在执行任务时能主动读取一套预先写好的方法论文件。1.1 名字很中二但本质是“技能包”所谓的技能包其实就是一批 Markdown 文件里面用固定格式描述了某个任务的完整做法。拿生活里的例子类比你招了一个能力很强但完全没经验的新人与其每天反复口头交代“开会要提前十分钟、周报要按模板写”不如直接丢给他一本《新人手册》。他看到什么场景就翻对应的页照着做。superpowers 干的活就是把这种手册塞给 AI 编程助手。每个技能文件通常长这样--- name: java-unit-test description: 当用户要求编写或修复 Java 单元测试时使用 --- # Java 单元测试技能 ## 目标 编写符合团队规范的 JUnit 5 单元测试。 ## 步骤 1. 先检查被测类的依赖注入方式 2. 优先使用 Mockito 模拟外部依赖 3. 测试方法命名遵循 method_should_xxx 规范 ...模型在收到用户请求时会先扫一眼技能目录里的 description 字段如果发现当前任务和某个技能描述匹配就把这个技能的正文加载到上下文里然后按照里面的步骤执行。这就是“触发”的整个过程。1.2 它解决了 AI 编程的哪个痛点用过 Codex CLI 的人应该都有一个体会前几个问题回答得像大神越到后面越像失忆患者。原因很现实——每一次会话都是全新的上下文模型根本不记得你十分钟前教过它“这个项目不要用 Lombok”。你不得不把同样的约束、规范、偏好反复粘贴烦不烦superpowers 的思路是既然模型记不住那就把该记住的东西写进文件里在需要的时候主动加载。这解决了几个很实际的问题上下文断裂技能文件替代口头交代每次会话都能重新加载。重复劳动不用再复制粘贴几十行的“开发规范”到对话框里。团队不一致不同成员用同一个技能目录产出的代码风格统一。方法论沉淀踩过的坑、总结的经验都能写成技能变成可复用的资产。说白了它把 prompt engineering 从“聊天记录”升级成了“结构化知识库”。这比在 system prompt 里塞一大堆规则要灵活得多——system prompt 是无脑全量注入技能是按需加载省上下文又精准。1.3 和 Codex CLI / Claude Code 的关系Codex CLI 是 OpenAI 推出的开源终端编程助手Claude Code 是 Anthropic 的类似产品。它们本身已经很能打能读文件、跑测试、改代码但问题是它们的行为完全靠用户现场指挥。superpowers 的作用是给这些 agent 戴上“手套”。它不是一个独立的模型也不是一个新的 IDE只是一套目录结构和加载规则。你把它初始化到合适的位置再在 agent 的配置里告诉它“技能目录在哪”剩下的就交给 agent 自己去读。这种设计的好处是不绑定具体厂商——Codex 能用Claude Code 能用以后换别的编辑器类 agent 大概率也能用只要它支持读取本地 Markdown 文件作为上下文。提示我第一次安装时最大的误区是以为 superpowers 会自动改动 Codex 的行为。实际上它更像一本放在桌上的手册agent 愿不愿意翻、什么时候翻取决于你的配置和技能描述写得好不好。这一点后面细说。2. 安装与初始化从零把 superpowers 跑起来安装过程本身不复杂但有几个细节容易踩坑。我以 Codex CLI 为例。2.1 前置条件Node.js 版本建议 18 以上npm 可用。已经装好并登录了 Codex CLI能用自然语言对话跑通基本流程。网络正常能访问 npm registry 和 OpenAI API。为什么要 Node.js因为 superpowers 的加载器本身是个命令行工具通过 npm 分发和 Codex CLI 的生态保持一致。如果你之前装过其他 agent 工具大概率环境里已经有 Node 了。2.2 安装步骤打开终端执行npm install -g superpowers看到一堆安装日志滚动后验证一下superpowers --version能输出版本号就说明装好了。然后初始化技能目录superpowers init这个命令会在你的用户目录下创建默认的技能文件夹并生成一个示例技能文件。不同版本生成的路径可能略有差异常见的是~/.codex/skills或者是项目级目录.superpowers/skills我个人建议优先用项目级目录这样技能可以跟着仓库走团队成员 clone 下来天然共享同一套规范。如果你的 superpowers 版本默认生成的是用户级目录也没关系手动在项目根目录创建.superpowers/skills一样能生效。2.3 目录结构说明初始化完成后你会看到类似这样的结构.superpowers/ └── skills/ ├── java-unit-test/ │ └── SKILL.md ├── commit-message/ │ └── SKILL.md └── code-review/ └── SKILL.md每个技能一个文件夹文件夹里至少有一个SKILL.md文件。这个文件就是技能的全部内容里面包含 frontmatter 和正文。也有实现支持在同一个文件夹里放多个辅助文件比如模板、示例代码但最小可用单元就是一个 SKILL.md。这里有个容易混淆的点有的教程把技能目录直接放在用户主目录下有的放在~/.codex/下还有的放在项目下。其实原理都一样——agent 启动时根据配置扫描这些目录加载里面的技能清单。你可以在不同的层级都放技能但要搞清楚哪些是全局通用的、哪些是项目专用的别混在一起。2.4 让 Codex 认到技能并验证加载光有目录还不够Codex CLI 得知道去这里找。通常有两种方式一种是在项目的AGENTS.md或codex.md看你的 Codex CLI 版本支持哪种里写明## 技能 当需要执行特定任务时先查看 .superpowers/skills 目录下的技能文件。另一种是直接在对话里告诉它“先读取 .superpowers/skills 目录看看有没有合适的技能有就按技能执行。”第一次跑通后后续会话它会自己记得如果配置引导得好。验证是否生效的方法很简单让 Codex 执行一个和示例技能相关的任务比如“写一条 git 提交信息”然后观察它的输出里是否出现了技能文件里的措辞、步骤或标题。如果它完全没反应大概率是技能目录没被扫描到或者 description 里的触发条件和你的表达不匹配。注意不同版本的 Codex CLI 对 AGENTS.md 的支持程度不一样。老版本可能根本不读这个文件新版本又可能优先读它。最稳妥的办法是先手动指一次路径跑通后再固化到配置里。3. 核心机制技能文件到底怎么工作这一节是重点。很多人装上 superpowers 之后发现“没什么用”十有八九是没搞懂技能文件的设计逻辑。它不是随便写一段 Markdown 就能生效的触发条件和内容组织是关键。3.1 SKILL.md 的元信息和命名规范SKILL.md 的 frontmatter 里最重要的字段是 name 和 descriptionname技能的唯一标识建议用短横线连接的小写英文比如java-unit-test。description给模型看的“触发条件说明”。这里不是让你写“这是一个关于 Java 单测的技能”而是写清楚“当用户提到 X、Y、Z 场景时使用”。为什么 description 这么重要因为 agent 的上下文窗口有限它不可能把每个技能都读一遍。它通常是先扫各技能的 description做一次快速匹配命中才加载正文。所以 description 写得好不好直接决定技能能不能被触发。举个例子下面是无效写法description: Java 单元测试技能包含 JUnit5 和 Mockito 的使用方法。模型看到这个描述能知道这是个 Java 单测技能但不知道什么情况下该调它。改成这样效果就好很多description: 当用户要求编写、修复或重构 Java 单元测试或提到 JUnit、Mockito、测试覆盖率的场景时使用。把“用户会怎么说”和“你会做什么”都塞进描述里命中率会明显提升。3.2 模型如何触发技能描述匹配与控制手段触发机制说白了就是检索 加载。在实际使用中我总结出三条经验第一描述语言要贴近真实用户表达。比如用户习惯说“帮我补个测试”你的描述里就别只写“当需要编写单元测试时使用”而是写上“当用户说补测试、写测试、测覆盖率、修挂掉的测试时使用”。宁可多写几个常见说法也别怕啰嗦。第二支持显式引用时优先用显式引用。不少超能力的加载器支持类似/use skill_name或者“按 XX 技能执行”的指令。这种强制引用不依赖语义匹配确定性最高。我建议把这一步写进 AGENTS.md告诉 agent“当用户明确提到技能名时无条件加载对应技能。”第三技能正文要按步骤拆解。模型对“动词开头的短步骤”执行得最稳。别写一大段散文改成有序列表## 步骤 1. 运行 mvn test 查看当前失败情况 2. 定位被测类对应的测试文件 3. 为每个公共方法补充至少一个正常路径用例和异常路径用例 4. 断言时优先使用 AssertJ不使用 JUnit 自带的 assertEquals每条指令都是可验证的执行动作模型就不容易自创流程。3.3 技能文件里应该写什么技能正文没有严格的格式要求但基于我自己的经验下面这几个板块值得保留目标用两三句话说清楚这个技能要达成什么结果。模型在执行中迷失方向时会回头重新读这段。步骤按顺序排列的操作清单每一条都是一次行动。检查表完成后逐项勾选防止遗漏。比如“所有测试是否可重复执行”“是否清理了无用的 import”。禁止事项明确什么不能做。这是最容易被人忽略、也最有效的内容。比如“禁止生成只测私有方法的测试”“禁止为了通过测试而修改生产代码”。模板/示例如果有固定的输出格式给一段示例比描述十句都管用。还有一个实用技巧把“这个技能不适用什么”也写进去。如果用户要做的是代码重构而不是写测试你的 java-unit-test 技能应该主动说明自己不适用避免模型硬套。3.4 多个技能的优先级与冲突处理技能多了之后一定会遇到“一个请求同时命中好几个技能”的尴尬。比如用户说“帮我给登录模块补个测试”这时 java-unit-test 和 code-review 都可能跳出来。怎么办我的建议是控制 description 的重叠范围并在技能里加一个适用性判断。比如在 java-unit-test 的步骤第一步写“先确认这是一个测试需求如果是其他任务请忽略本技能”。这相当于给模型一个“拒绝调用”的出口避免多个技能争抢。另外命名规范也能减少冲突。技能名称尽量带上领域标签比如java-unit-test、python-lint-fix、commit-message-convention一眼就能看出边界。如果你用某个平台的 marketplace 扩展还要注意内置技能和自定义技能的命名冲突覆盖时通常报错或者静默替换这点我会在第 5 节详细说。4. 实操用 superpowers 完成一个 Java 小需求搜索词里的 “superpowers java” 热度不低说明好多人是冲着 Java 开发场景去的。确实Java 项目里条条框框特别多依赖管理、测试框架、代码风格、提交信息随便哪一项都能让 AI 自由发挥出一堆风格迥异的代码。我用一个写单元测试的案例完整走一遍从技能编写到触发的流程。4.1 准备一个“Java 开发规范”技能假设你的团队要求使用 JUnit 5Mockito 做依赖 mock断言用 AssertJ测试类命名以Test结尾测试方法命名遵循method_should_xxx。那就先写一个技能文件--- name: java-unit-test description: 当用户要求编写、修复或重构 Java 单元测试或提到 JUnit、Mockito、测试覆盖率的场景时使用。当用户说“补测试”“写单测”“修挂掉的测试”时也使用。 --- # Java 单元测试技能 ## 目标 产出一份符合团队规范的 JUnit 5 单元测试代码。 ## 步骤 1. 检查被测类列出公共方法清单。 2. 找到对应的 src/test/java 目录确认测试文件是否存在。 3. 若测试文件不存在创建 ClassNameTest.java类名以 Test 结尾。 4. 为每个公共方法编写至少一个正常路径用例和一个边界/异常路径用例。 5. 使用 Mock 创建依赖使用 InjectMocks 注入被测试类。 6. 断言统一使用 AssertJassertThat(...)。 7. 运行 mvn test只保留全部通过的用例。 ## 检查表 - 测试能否无网络环境运行 - 是否没有修改生产代码 - 是否有 System.out.println 残留 ## 禁止事项 - 禁止测试私有方法 - 禁止为了通过测试而改动被测类的业务逻辑 - 禁止生成随机值断言比如 assertThat(result).isTrue() - 如果用户请求与测试无关忽略本技能这里每一条规矩都针对真实世界里 AI 编程常犯的错误——AI 特别喜欢把方法改成 public 或者删除 private 修饰符来“方便测试”也特别喜欢生成毫无意义的真值断言。4.2 在 Codex CLI 里呼叫技能技能文件放好之后在项目目录里启动 Codex CLI输入登录模块那边登录成功后返回的 token 字段总是为 null帮我按团队规范补一下单元测试。注意我的表达里特意没有提“superpowers”三个字。正常来说模型看到“补单元测试”“团队规范”这些词就应该主动去扫描技能目录命中 java-unit-test 并加载正文。如果一切顺利它输出的测试代码会严格遵循技能里的 AssertJ 断言、Mockito 注入和命名规范。4.3 技能没有触发时的排查链路如果模型完全没反应别慌按顺序查这几项第一看技能文件路径是否在扫描范围内。用命令行确认你的 superpowers 初始化到了哪个目录和 AGENTS.md 里写的是否一致。路径写歪是最常见的原因。第二看 description 是否和用户表达偏离太远。可以人为贴近用户的话术“帮我补测试”“写好一点”“按规范来”把这些口语都塞进 description。第三尝试显式触发。直接在 Codex CLI 里输入“使用 java-unit-test 技能帮我写测试”。如果这样都不生效那基本可以断定是技能根本没被扫描到而不是触发逻辑的问题。第四检查 Codex 的上下文是否被截断。有些任务模型只读取了一部分上下文就动手了你可以让它“先总结你当前加载了哪些技能”确认它有没有真的读到文件。4.4 和 WordBuddy 这类文档工具配合最后回应一下“worbuddy 怎么用 superpowers”。如果你手里的 WordBuddy 是文档生成/AI 写作类工具思路是两段式流水线让 Codex 借助 superpowers 技能完成技术内容的生成和校验输出结构化的 Markdown 材料再把材料交给 WordBuddy 做排版、润色、转文档格式。举个例子我在写技术方案时就写过一个tech-design-doc技能里面规定了方案文档必须包含背景、目标、技术选型对比、影响范围、回滚方案。Codex 按技能生成原始文档后我会把内容丢给 WordBuddy 做最终的美化排版。这样分工的好处是AI 写代码和写文档的语境完全分开不会互相污染每种工具只做自己最擅长的事。如果你的团队有类似的文档工具完全可以复制这种配合模式核心就是superpowers 管内容质量WordBuddy 管排版呈现。5. 常见问题与排查技巧实录技能系统用起来不难但踩过的坑一个接一个。我把自己遇到的典型问题整理成表省得你重新走一遍弯路。问题现象可能原因排查命令/操作解决方案技能完全没有触发技能目录路径没被扫描superpowers list查看已加载技能检查 AGENTS.md 中配置的路径手动指定目录模型读到了但不按技能执行技能正文太长模型只看前面几步观察模型输出是否引用了技能步骤精简正文把强约束提到最前面多个技能同时命中description 重叠查看各技能描述是否有共同关键词缩窄描述范围加“不适用场景”说明技能在项目 A 生效项目 B 不生效技能放在用户级目录而项目级没配置比较不同项目的配置差异统一把技能放在项目 .superpowers/skills更新技能文件后行为没变agent 缓存了旧结果重启 Codex CLI清除会话缓存重新加载上下文被技能文档挤爆技能文件写得过长像百科全书统计技能文件行数只写方法论和检查表百科内容不放入技能除了这个表还有两个实操心得值得单独说说。第一个是“技能里要多写禁止事项少写鼓励事项”。模型对“不要做什么”的执行力远高于“尽量做什么”。比如你写“尽量使用 AssertJ”模型可能还是用原生 assertEquals但你写“禁止使用 assertEquals统一使用 AssertJ”它就会老实很多。我后来把技能里的所有正面描述都改成了“禁止/必须/唯一允许”这类强约束句式效果立竿见影。第二个是“技能也要做版本管理”。当你把技能文件放进 Git 仓库后它会随代码变更一起演进。我建议把技能文件当成一等公民对待每次修改都要提交 PR、写变更说明。否则三个月后你会发现自己早已不记得某个技能为什么要这样写而 AI 还在按一条过时的规定产出代码。6. 把 superpowers 用出真正“超能力”的经验到这一步你已经不是那个只会给 AI 下碎片化指令的新手了。你在建立一个模型可以反复读取、团队可以共同维护的方法论库。我个人的体会是别贪多。刚开始不要一次性写五十个技能那只会让模型在匹配时晕头转向。从三个场景切入就够了最频繁的、最容出错、最需要对齐规范的。我用 superpowers 的第一周只写了三个技能一个是提交信息规范一个是单元测试规范一个是代码审查清单。一周之后AI 产出的 commit message 再也没有出现过乱写的英文新写的测试也几乎不需要我再改风格。还有一个小技巧在技能文件里给 AI 留一个“投诉通道”。比如在 java-unit-test 技能的末尾写上“如果你觉得本技能不适合当前需求请直接说明并忽略它”。这个句子能防止模型在技能和现实冲突时强行套模板。本质上是承认技能不是万能的反而能让模型更愿意参考它。至于“superpowers 还能干什么”我倒觉得不用急着扩展。先把手头这几个技能打磨到“每次调用都能稳定产出想要结果”的程度再去覆盖新场景。做得好的技能哪怕只有五个也比五十个吃灰的技能强得多。工具只是容器真正产生价值的是你愿意把多少实战经验沉淀成那一个个 Markdown 文件。
阅读完成 · 觉得有帮助？
