最近不少人跑来问我说自己的 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 cnsuperpowers 在社区里热度最高的三个使用场景恰好对应三个主流 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 编程代理能写代码但不靠谱的阶段我建议别急着加更多模型或换更大上下文先试试把工作流固化下来。技能包本身是免费的装它最多浪费你半小时但它能不能改变你的使用习惯才是真正决定效果的地方。