最近不少人跑来问我，说自己的 Codex CLI 用起来总觉得差口气——单轮问答还行，让它独立负责一个完整任务，它就浅尝辄止，干一半就停，或者动不动要人确认。我一开始也以为是自己模型选得不对、prompt 写得不够好，直到我把 superpowers 这个技能包装进 Codex CLI，才意识到问题出在"方法论"上：不是模型不聪明，是它没有一套固定的工作流。这篇我就把 superpowers 是什么、怎么装、装上之后有什么变化、以及我踩过的坑，一次性说清楚。
如果你正在用 Codex CLI、Claude Code、或者 Trae work cn 这类 AI 编程代理，又觉得它们"能做但做不透"，那这篇文章应该能帮你把工具真正用起来。
1. Superpowers 到底是个什么东西：从"答题机器"到"能干活"的转变
1.1 它解决的痛点：AI编程代理普遍存在的"浅尝辄止"
你让 Codex CLI 改一个 bug，它可能上来就动手，改完一个文件就跟你说"搞定了"，结果测试一跑，整个报错链路断在一个更深的位置。这不是模型能力不行，而是它缺少一套固定的处理问题的流程。
我们人类工程师看到一个 bug，第一反应是复现、缩小范围、看日志、定位根因，再动手改，最后跑测试验证。AI 编程代理不是天然就懂这套流程的，它默认的行为是"尽快给你一个看起来合理的答案"。superpowers 的核心价值，就是把人类工程师那套工作流程，变成 AI 代理能直接调用的技能（skill）。
具体来说，它不是一个单体程序，而是一组 markdown 技能文件。每个技能文件里定义了：这个技能什么时候启用、要按什么步骤执行、中间要产出什么中间产物。AI 代理读到这些技能文件后，就会按照里面的方法论去思考和处理问题。
我自己的感受是，装上之后 Codex CLI 不再是"我问一句它答一句"，而是会自己规划任务、自己验证结果、遇到失败会自己排查。这种体验上的差别非常明显。
1.2 它的运行机制：技能包=方法论文件夹+触发规则
superpowers 的底层机制说穿了并不复杂。它会往你的 CLI 工具配置目录里装一个 skills 文件夹，里面是几十个 markdown 文件。这些文件不是摆设，它们遵循一套 AI 代理能读得懂的格式约定，大致分三部分：
- 元信息：技能名称、适用场景、触发条件。
- 执行流程：拆成步骤，每一步都有明确指令，比如"先复现问题""再缩小范围""最后做根因分析"。
- 产出要求：规定这个技能跑完后，输出什么格式的结果。
以 debugging 技能为例，它不会直接说"去修 bug"，而是会引导 AI 代理：先让用户提供完整的复现步骤，再检查相关日志和错误堆栈，逐层缩小问题范围，最后定位到根因并验证修复。这个过程其实就是我们平时排障时下意识做的事情，只是现在被结构化了。
AI 代理拿到这些技能文件后，会通过触发规则决定"当前任务到底该用哪个技能"。比如任务描述里带有"为什么""根因"这类词，它就倾向调用分析类技能；出现"实现""完成"这类词，就走执行类技能。
1.3 它和普通插件、prompt 模板的本质区别
很多人会问，这和我把一段"高质量的 system prompt"贴在配置里有什么区别？区别很大。
一段 prompt 模板是静态文本，它告诉 AI"你要好好思考"或"你要一步步来"，但 AI 对这类泛泛提示的遵循程度是有限的。而 superpowers 是动态加载的——不同的任务会触发不同的技能文件，每个文件内部是完整的行动指令，AI 在执行时会把技能内容切实当成操作章程，而不是心灵鸡汤。
另外，它跟 IDE 插件也不是一回事。IDE 插件通常在编辑器和编译器层面做文章，提供补全、跳转、重构等能力；superpowers 则是在"任务组织方式"层面做文章，它指挥的是 AI 代理的工作流程，而不是编辑器本身的功能。
提示：把 superpowers 理解成给 AI 代理装了一套标准作业程序（SOP），会比把它理解成"另一个插件"更准确。
2. 我为什么在几个技能方案里选了它：横向对比与适用边界
2.1 它能接入的工具：Codex CLI、Claude Code、Trae work cn
superpowers 在社区里热度最高的三个使用场景，恰好对应三个主流 AI 编程终端：
第一个是Codex CLI。OpenAI 出的命令行编程工具，它支持自定义的技能目录，superpowers 可以直接住进去。这也是我目前的主要用法，后面安装章节我会重点讲。
第二个是Claude Code。Anthropic 的终端编程代理，它对技能、插件这类扩展机制的兼容性做得比较完善，很多 superpowers 技能的原始设计思路就是先在 Claude Code 上验证的。
第三个是Trae work cn。字节出品的那款 AI IDE 的国内版本，它同样支持以 skill 方式扩展自定义技能，这在国产工具里算走得比较快的，国内开发者想在本地体验 superpowers，这是个绕不开的入口。
这三个环境的技能目录结构和加载方式略有不同，但核心逻辑都是：把你的技能文件放到工具约定好的位置，让 AI 代理启动时能扫描到它们。
2.2 它和其他增强方案的横向对比
我在决定长期使用 superpowers 之前，实际上把几类"增强 AI 代理能力"的方案都试过，给你列个自己的对比感受：
| 方案 | 解决什么问题 | 上手成本 | 我的评价 |
|---|---|---|---|
| 靠 system prompt | 短期约束 AI 的行为风格 | 低 | 效果不稳定，AI 容易"假装遵守"，复杂任务还是会跑偏 |
| MCP 服务器 | 给 AI 接外部工具和数据源 | 中 | 适合接数据库、浏览器这类外部资源，但不管控工作流 |
| 自定义规则文件 | 约束代码风格、提交规范 | 低 | 作用于静态行为，不解决"怎么拆解复杂任务"的问题 |
| superpowers 技能包 | 给 AI 一套完整的问题解决流程 | 中 | 补的正是前几个方案缺失的那一环：方法论 |
我的结论是：MCP、规则文件、superpowers 它们不是竞争关系，而是并存的。MCP 负责让 AI"够得着"外部世界，规则文件负责让它"守规矩"，superpowers 负责让它"有章法地干活"。如果你已经有了 MCP 生态，把 superpowers 加进去并不会冲突，它是叠加的一层。
2.3 谁适合用，谁暂时不需要
先说结论：如果你平时只拿 Codex CLI 写写脚本、改改小 bug，每次任务体量不大，那 superpowers 对你来说可能暂时是多余的。它带来的流程开销反而会让简单任务显得"笨重"。
真正适合的人群是这三类：
- 接到中大型开发任务的人，比如重构一个模块、从零实现一个功能，需要 AI 先规划再动手，中间还要自己做验证。
- 用 AI 代理处理线上问题时的人，问题本身模糊，需要逐步排查根因，而不是直接改代码。
- 想研究"如何把 AI 代理调教成团队初级工程师"的人，技能包本质上就是在沉淀一套可复用的工程方法论。
说白了，superpowers 适合的是那些你本来就会花很长时间去拆解、规划和验证的任务。任务复杂度越高，它带来的稳定性和可控性收益就越明显。
3. 安装前先避坑：环境和目录约定
3.1 Node.js 与 CLI 工具的版本要求
很多人在安装第一步就翻车，问题通常出在版本太旧。superpowers 的技能文件本身是纯 markdown，理论上不挑运行时，但你要把它装进 Codex CLI 或 Trae work cn，依赖的还是这些工具自身对技能目录的支持能力。
我的建议是：安装前先确认你的工具版本是相对新的状态。以 Codex CLI 为例，技能目录的支持是通过命令行参数或配置文件控制的，旧版本可能根本没有这个能力；Trae work cn 对 skill 的支持也是近几个版本才完善的。先跑一下codex --version或者到设置面板里确认版本号，如果太旧就升级到当前稳定版再继续。
另外，安装脚本本身可能依赖 Node.js 环境。仓库里的安装工具通常用 Node.js 编写，如果你机器上连 node 都没有，或者版本停在 16 以下，先把 Node.js 装好再说。我不建议在这种细节上省事，后面所有安装脚本的报错，八成都能回溯到环境版本问题上。
3.2 skills 目录结构和加载逻辑
这个坑我必须单独拿出来说，因为它决定了你装完之后能不能被 AI 代理识别。
superpowers 的加载逻辑是：工具会在固定位置扫描技能文件，然后把技能名称和描述注入到运行上下文中。以 Codex CLI 为例，它默认会读取项目根目录下的.codex/skills，或者用户级目录下~/.codex/skills这类位置；Trae work cn 则有自己的 skill 目录约定，通常在用户配置目录下。
所以安装不只是把仓库 clone 下来就行，关键一步是把技能目录放到工具实际会扫描的位置，或者通过软链接指过去。
还要注意文件夹层级。技能文件不能散在根目录，一般要求每个技能单独一个文件夹，里面放SKILL.md作为主文件，还可以附带 resources 子目录、模板文件这些附加资源。结构大概是：
skills/ ├── brainstorming/ │ ├── SKILL.md │ └── resources/ ├── planning/ │ ├── SKILL.md │ └── templates/ └── debugging/ ├── SKILL.md └── examples/这个结构是技能能被"识别"的基础，少一层或多一层，AI 代理扫描时可能就找不到技能。
3.3 三个容易翻车的前置条件
- 确认仓库版本和分支：superpowers 本身迭代挺快的，不同分支、不同 tag 的技能文件构成可能不一样。别随便 clone 一个旧分支，然后抱怨装上没效果，先看仓库 README 里推荐的安装方式和当前稳定分支。
- 检查终端工具的配置是否干扰技能加载：比如 Codex CLI 的配置文件里如果手动指定了 skills 路径，而你 clone 的位置和它不一致，就会加载失败。这类问题排查起来不直观，建议先保持默认配置，确认装好了再改自定义路径。
- 注意"路径里的空格和中文目录"：技能文件加载如果遇到特殊字符路径，某些 Windows 环境下会出现权限或解析问题。我建议把仓库 clone 到一个纯英文、无空格的路径下，比如用户目录下的
dev文件夹，能省掉一堆莫名其妙的问题。
提示：别小看目录约定，这是整个安装过程中"错误率最高"的一个环节。装完发现 AI 不认识技能，先把路径和结构挨个检查一遍。
4. 实际操作：Codex CLI 与 Trae 场景下的安装全流程
4.1 Codex CLI 安装 superpowers 的两种做法
我常用的方式其实有两种，一种是"全手动"，一种是"半自动"，都没什么难度。全手动方式更可控，也方便你去理解它到底在干什么。
第一步，把仓库拉到本地：
git clone https://github.com/obra/superpowers.git第二步，确认 Codex CLI 的技能目录。你可以在项目里创建.codex/skills目录，也可以放在用户级配置目录，看你想让技能是"只对当前项目生效"还是"对这台机器所有项目生效"。我建议第一次装用用户级目录，全局生效，免得每次换个项目还得再引一次。
第三步，把仓库里的 skills 目录内容复制或软链过去。以 macOS/Linux 为例：
mkdir -p ~/.codex/skills cp -r superpowers/skills/* ~/.codex/skills/Windows 环境下用资源管理器复制粘贴也没问题，只要目录放对即可。
第四步，重新打开 Codex CLI，启动时会自动扫描技能目录。你可以在对话里直接问一句"你当前有哪些技能可以用"来验证，如果它能列出 brainstorming、planning、debugging 这一类的技能名称，说明加载就成功了。
半自动方式则是用仓库里自带的安装脚本。具体命令每个版本略有差异，以官方 README 为准，我这边就不贴有可能过期的命令了。它的本质也是复制文件，只不过帮你把路径配好、链接建好，省掉手动操作。
4.2 Trae work cn 安装 superpowers 的差异点
Trae work cn 这类 IDE 的安装方式和终端工具不太一样。它其实是把 skill 当成 IDE 层面的扩展能力来管理的。
你需要先找到 Trae work cn 的 skill 配置目录。通常在你本机的用户配置目录下，可能是类似.trae/skills或者通过设置面板里"技能管理"入口查看当前技能目录的路径。找到之后，把 superpowers 仓库里的 skills 目录内容复制进去，重启 IDE，让扫描器重新加载。
它和 Codex CLI 最大的差别是：IDE 里可能会有一个"技能开关"或"技能启用"的概念。即使你把文件放对了位置，IDE 也不会默认启用所有技能，你需要在 UI 里手工启用，或者确认配置文件里没有把某个技能禁用掉。
我试下来觉得，IDE 场景更适合把 superpowers 作为"辅助思考框架"来用，因为 IDE 里本身有编译、调试、终端等工具，AI 代理的技能可以更自然地跟这些工具配合。终端场景则更适合做"端到端任务"。两边不冲突，看你习惯哪个环境。
4.3 装完之后如何验证
装完别急着上手干活，先花两分钟确认技能真的被加载了。
第一，直接问。在 Codex CLI 里问一句"你有哪些技能，分别用来干什么"，它会给你列出技能列表和描述。如果它报的目录不对，说明扫描路径有问题，回头检查目录位置。
第二，制造一个"简单触发场景"。比如故意说"帮我对这个思路做一次头脑风暴"，如果它进入 brainstorming 技能的流程，会反过来问你一系列澄清问题，而不是直接给答案。这个表现几乎是判断技能是否生效的分水岭。
第三，看调试输出或日志。有些工具会打印技能加载的日志，启动时能看到类似 "loaded X skills" 这类信息。如果你使用了软链接，确认链接没有断裂。
注意：验证环节最忌"问一次没反应就认定失败"。有些工具的技能触发是基于用户的第一轮描述来匹配的，你输入的任务描述越模糊，AI 越可能直接走通用路线而不是技能路线。多换几种说法试试，再判断是没装上还是没触发。
5. 装完不白装：核心技能逐个拆解
5.1 规划类技能：从"马上写代码"到"先想明白再做"
superpowers 里最让我惊喜的不是写代码相关的技能，反而是规划类技能。装上之后，我再给它派一个中大型任务，它不再撸起袖子就写代码，而是会进入 brain storming 或 planning 流程，先跟我讨论需求、澄清约束、列出风险点，然后产出实现方案，最后才开始动工。
看一组对比你就知道差别有多大：
- 装之前，我说"帮我加一个导出功能"，它可能直接就开始写导出代码。
- 装之后，它会先问"导出的格式是什么？是全量还是增量？前后端谁负责生成文件？异常怎么兜底？"这些问题问完，再给我一份实现计划。
这个体验非常像在跟一个认真的初级工程师协作。它的 planning 技能会建议 AI 代理把大任务拆成小步骤，每个步骤有明确的完成定义，做完一步自我验证一步，而不是一股脑堆到最后。这种流程对控制代码质量、减少返工，效果是肉眼可见的。
其中有个细节我觉得很关键：它内部会引导 AI 代理"区分事实和假设"。在你没有明确说明的情况下，AI 默认把所有东西都当"假设"来处理，而不是当成事实直接写进方案。这个机制极大减少了 AI 自作主张的行为。
5.2 执行类技能：TDD 与 debugging 是怎么被结构化的
执行类技能里，我实际用下来感觉最强的是 TDD（测试驱动开发）和 debugging。
先说 TDD。它会把流程拆成"红-绿-重构"三段：先让 AI 根据需求写失败测试（红），再写最小实现让测试通过（绿），最后做代码清理和重构。每一步都会跟你确认，而且不会跳步。以前我让 AI 直接写带测试的代码，它通常是"写完业务代码再补几个测试意思一下"，马后炮成分很高；在技能约束下，它会老实按照 TDD 的顺序来。
再说 debugging。这个技能给我的印象最深，因为它模拟了一个工程师完整的排障链路。遇到问题，它不会马上下结论，而是先要求用户提供复现步骤和环境信息，再看日志、缩小定位、提出假设、验证假设，最后改代码并回归测试。我拿一个我自己都排查了挺久的内存泄漏问题去试，它在缩小区间时用的方法和人类排查几乎一样，反而因为阅读代码速度更快，帮我省了很多时间。
这两个技能之所以有效，是因为它们把流程写死了。AI 代理在每一次"正确流程"的重复中，产出的项目代码稳健性也在提升，至少不会留下只能跑通主路径的"裸奔代码"。
5.3 检查类技能：code-review 与自省机制
最后一个让我觉得值得长期留在项目里的，是代码评审和自省类技能。
code-review 技能会让 AI 代理以"评审者"视角去读代码，而不是以"作者"视角。它会检查潜在 bug、边界情况缺失、可读性问题、不必要的复杂度等等。关键是它有一套输出模板，评完会把发现的问题按严重程度组织起来，并且给出修改建议，而不是泛泛说"代码质量不错"。
自省机制则是另一种风格。它会在任务完成后让 AI 代理回顾整个过程：哪些步骤是有效的，哪些是绕了弯路，如果再来一次会不会有更优做法。这些内容会沉淀成一条条经验，直接影响到后续任务的处理方式。我的感受是它让 AI 代理有了"长记性"的能力，同类坑踩过一次之后，下回它会主动避开。这比单纯堆模型能力要实用得多。
6. 我实际跑过的任务与踩坑记录
6.1 一个典型任务的完整过程
拿最近一个真实任务来演示。我让它给我现有的一个 Node.js 小工具增加"批量文件重命名"功能，要求包含干跑模式（dry-run）和真实执行模式，并且要有完善的错误处理。
如果没装 superpowers，它大概率会直接开始写代码，可能几轮对话就完成了，但边界情况想得不会很全。装了之后，它的流程大致是：
- 先进入 brainstorming，问我"批量的规则有哪些？重命名冲突时是跳过还是报错？需不需要日志记录？"
- 然后再进入 planning，把它需要实现的模块拆成：命令行参数解析、规则匹配器、重命名执行器、日志输出器，并标出依赖关系。
- 写代码前它还提醒我"是否先写测试"，我确认后它按 TDD 流程推进。
- 中间一次测试失败是因为它预设的规则对文件名长度没做限制，技能引导它回到测试用例，补上"超长文件名提示"的断言再继续。
- 交付时它主动跑了一遍干跑模式给我看结果，再问我要不要真实执行。
整个过程下来，代码改动量并不比之前多多少，但是边界处理、日志输出、测试覆盖明显上了一个档次。我只需要在关键节点确认方向，不需要盯着每一行代码。
6.2 我踩过的几个典型坑
第一个坑是技能没被触发。我一开始装完直接说"帮我写一个功能"，它完全没走技能流程。后来才反应过来，是描述太笼统，没有触达技能触发条件。解决办法是明确说"先用 brainstorming 流程梳理一下需求"，或者把任务描述里的关键行为词讲清楚，让它去匹配对应技能。
第二个坑是技能之间出现"重叠干扰"。有一次我让它"实现一个功能并调试一下"，结果它同时调用了 planning 和 debugging，两边流程打架，规划做到一半开始排查并不存在的 bug。后来我习惯每次对话只聚焦一个主技能，需要切换时明确告诉它"现在进入 debugging 阶段"。
第三个坑是 context 占用变大。superpowers 本质是给 AI 塞入更多方法论上下文，它会消耗更多上下文窗口。任务特别长时，AI 会开始遗忘前面的技能要求。我的应对是拆子任务，让每个对话只处理一个特定技能阶段，不要指望一次会话跑完整个大项目。
第四个坑是版本不一致。有一次我 clone 的是主分支最新代码，目录结构和我本地 CLI 版本支持的约定对不上，装完毫无反应。后来直接按官方 README 指定的版本来，就稳定了。建议不要盲目追新，稳定优先。
6.3 使用技巧：prompt 的几个实用写法
基于上面这些经验，我整理了几个比较顺手的 prompt 模板。第一个是最直白的技能调用：
请使用 brainstorming 技能，帮我梳理一下"配置文件热加载"功能的完整需求边界。第二个是规划加执行一起指定：
先用 planning 技能拆解这个重构任务，等我确认方案后，再按 TDD 流程执行。第三个适合中途切换：
现在停止当前流程，进入 debugging 技能，帮我排查刚才测试失败的根本原因。第四个适合任务收尾：
任务完成后，用 code-review 技能对我改动的代码做一次评审，并给出改进建议。这些写法本质上都是"显式指定技能入口"，省去了 AI 自己猜测的环节。在没有特殊说明时，它靠触发规则判断；你主动点名，它就会走得更稳。
说点个人体会。superpowers 不是那种装上就能"原地封神"的工具，它更像一个训练框架，逼着 AI 代理按规范工作，也逼着我这个使用者把需求描述得更清晰。如果你正处于"AI 编程代理能写代码但不靠谱"的阶段，我建议别急着加更多模型或换更大上下文，先试试把工作流固化下来。技能包本身是免费的，装它最多浪费你半小时，但它能不能改变你的使用习惯，才是真正决定效果的地方。
