不知道你第一次听说“superpowers”这个词是在什么场景下反正我是在一次被 Codex CLI 默认行为逼疯的下午顺手刷到一个技能包名字就叫 superpowers。当时心里还犯嘀咕一个给命令行 AI 助手用的技能集也敢起这么中二的代号结果装上跑通之后我承认是我草率了。它解决的问题非常具体默认状态下AI 代码助手更像一个“应答型选手”你问一句它答一句改文件也是一次一个。而 superpowers 做的事情是把 AI 的思考流程拆成可复用的步骤比如自动规划、测试驱动开发、重构前梳理影响面然后让 Codex CLI 按这套流程去执行。说白了就是把“随手写”变成“按章法打”。如果你也在用 Codex CLI并且觉得 AI 给出的改动经常不完整、没有全局观或者想让它真正像个有经验的工程师一样分步骤推进任务那这篇文章就是写给你参考的。我会从技能加载原理讲起覆盖 Codex CLI 与 Trae Work CN 环境下的三种安装方式再加上我实际跑了几个任务之后踩过的坑和调校建议通篇都是可以直接照着操作的内容。1. 先搞清楚Superpowers 到底是什么玩意1.1 一个让我改变工作流的发现先说我自己的使用场景。我负责一个中等规模的前端项目代码量不大但模块之间引用关系复杂。以前用 Codex CLI最让我难受的一点是它处理“改一个函数”这种小需求很利索但一旦任务变成“把这个模块的请求逻辑全部迁移到新 API 上”它就会东一榔头西一棒子改完 A 文件忘了 B 文件甚至改出循环依赖。后来我同事甩给我一个链接说有一个叫 superpowers 的技能集专门治这种“局部聪明、全局短视”的问题。我装上之后第一次试运行明显感觉到它的行为逻辑不同它先自己列了一个计划然后逐个步骤确认每个步骤里还会主动跑测试验证。那一刻我理解了superpowers 本身不是一个模型也不是一个第三方 API而是一套预先写好的 prompt 工程和技能脚本通过 Codex CLI 的技能加载机制把大任务拆解成有纪律的执行流程。1.2 superpowers 的本质一套让 AI 助手动起来的技能包说实话从技术架构上看superpowers 并没有多么玄幻。它本质上就是一组结构化的技能文件通常放在 Codex CLI 约定的技能目录里。每个技能包含一套明确的指令模板告诉 AI 在什么场景下应该采用什么工作流。比如它内部常见的技能分类就有计划规划、测试驱动开发、代码重构、影响面分析、文件批量操作等等。你可以把它理解为给 AI 助手配了一本“标准作业手册”。比如你提出“升级某个依赖并修复破坏性变更”如果没有技能包AI 可能直接开干用它的直觉去猜测。而有技能包时它会调用计划技能先做影响面分析再调用重构技能逐个模块推进每步跑测试最后汇总变更。这种流程化能力正好弥补了大模型在长任务上的注意力漂移问题。1.3 为什么默认 Codex 不够用这个包能补什么我见过很多刚接触 Codex CLI 的人抱怨为什么 AI 总是答非所问其实不全是模型的问题而是你没有一个机制去约束它的行为。默认的 Codex CLI 就像一个聪明的实习生能力有但没人告诉他公司的代码规范、测试流程、提交规则他只能自由发挥。superpowers 的价值恰恰在这里。它在 AI 和代码仓库之间加了一层“项目执行规范”让 AI 遵循固定的 SOP。比如它会要求 AI 在动手前先列计划要求 AI 用 TDD 思路先写失败用例再写实现代码要求 AI 在重构时保留旧接口的兼容层。这些规则单独看都很朴素但组合在一起就是把“野生 AI”驯化成“规规矩矩的团队协作者”。所以我的判断是你在考虑把它装进 Codex 之前应该先想清楚自己到底缺什么。缺的不是更多模型能力而是更稳的执行方式。2. 装之前先看懂 Codex CLI 的技能加载机制2.1 Codex CLI 的版本与技能目录在动手装 superpowers 之前我建议你先花五分钟确认一下自己的 Codex CLI 版本和信息否则后面很容易出现“装了但没生效”的情况。因为我一开始就在这上面吃过亏技能文件放进去了但 Codex 完全没识别到最后发现是目录放错了。不同时期的 Codex CLI 对技能目录的默认路径略有差异。以我手头这个版本为例它约定的技能目录是在用户主目录下的.codex/skills文件夹里。每个技能是一个独立的子文件夹技能说明文档通常叫SKILL.md里面用结构化格式描述技能的用途、使用场景、调用参数和具体步骤。你可以用一条命令快速确认目录结构ls -la ~/.codex/skills如果这个目录还不存在没关系手动创建就好mkdir -p ~/.codex/skills需要特别注意的是Codex 加载技能时非常依赖文件夹命名和文件命名。我之前把技能文件夹命名为superpowers-main从压缩包解压出来的默认名结果 Codex 直接无视了它。后来把文件夹重命名成superpowers重新加载才正常。所以命名规范不是小事。2.2 AGENTS.md 在技能加载中扮演的角色还有一个容易忽略的文件叫AGENTS.md。如果你在自己的项目根目录放了这个文件Codex CLI 每次运行时会优先读取它把它当作项目级上下文。superpowers 这类技能集往往也会建议你在AGENTS.md里声明需要启用哪些技能。打个比方技能文件本身是“工具”而AGENTS.md是“工具使用说明书”加“现场调度员”。例如我项目里的AGENTS.md会写明本项目的测试命令是npm test提交流程必须通过 lint 检查修改公共接口前需要先搜索所有调用方当 Codex 有了这些信息再叠加 superpowers 里的执行流程AI 才会真正像一个熟悉这个项目的老手。如果少了这一步即使技能装在全局目录里它也缺少关键的项目约束执行结果仍然是“通用答案”。2.3 仓库来源与本地备份的准备superpowers 这类的技能集通常会托管在公开的代码仓库上安装前需要确保你的终端具备拉取该仓库的网络条件。我个人的习惯是先克隆到本地检查一下目录里的文件结构确认包含SKILL.md之后再进行复制或软链接这样比较稳妥。git clone superpowers技能集仓库地址 ~/downloads/superpowers克隆完成后看一眼它的目录结构常见的形态是这样的superpowers/ ├── SKILL.md ├── skills/ │ ├── plan/ │ ├── refactor/ │ └── tdd/ └── README.md我建议在安装前先备份自己原有的技能目录。因为技能包迭代速度不快但偶尔也会覆盖同名文件备份能让你在出问题时快速回滚cp -r ~/.codex/skills ~/.codex/skills.bak.$(date %Y%m%d)3. 三种安装姿势按场景选3.1 最省事Codex CLI 一键引入技能目录如果你用的是较新版本的 Codex CLI最简单的方式是利用它自身的 skill 命令。例如有些版本支持类似codex skill add的指令可以直接从仓库把技能安装到默认目录。我在实际使用中更多地采用手动方式因为各个版本的 CLI 对子命令的支持不太一致。如果你不确定自己的版本支不支持可以先执行codex --help看看输出里有没有 skill 相关子命令。如果有直接按提示安装即可如果没有就使用备选方案将技能目录复制到~/.codex/skills/下。cp -r ~/downloads/superpowers/skills/* ~/.codex/skills/复制完之后重新打开一个 Codex 会话让它重新扫描技能目录。正常情况下它会自动加载。3.2 Trae Work CN 环境下安装 skill 的路径差异有一部分读者是在 Trae Work CN 这类桌面工作区里使用 Codex CLI 的安装路径会和纯命令行环境有区别。Trae Work CN 本质上把 Codex CLI 嵌进了一个可视化界面但它读取技能目录的逻辑仍然是读取用户目录下的配置而不是读取项目目录。我在 Trae Work CN 里踩到过的坑是它有时候会缓存旧的技能列表。即使你已经把 superpowers 放进了~/.codex/skills在界面里依然看不到。解决方法并不复杂找到工作区设置清掉技能缓存或者直接重启工作区让它重新扫描。如果你在 Trae Work CN 设置里看到了“技能路径”或“Skills Path”之类的选项记得把它指向你实际放置技能的目录。有些版本默认指向的是内置目录而不是用户目录所以安装不生效时优先检查这个配置项。3.3 离线/手动安装拷贝文件目录还有一种常见场景是离线安装比如内网开发环境或者你的网络拉取不了外网仓库。这种情况下只要你能拿到技能包的文件压缩包安装方式反而最简单。解压之后把里面包含SKILL.md的顶层文件夹复制到~/.codex/skills目录下。这里有几个细节要注意解压出来的文件夹如果是superpowers-main强烈建议改名为superpowers不要多套一层目录也就是说~/.codex/skills/superpowers/SKILL.md这个路径才是正确的检查SKILL.md文件是否损坏最简单的办法是用文本编辑器打开确认里面有内容而不是空文件离线安装完成后同样是重启会话或者运行扫描命令让 Codex 识别。识别成功的标志是你可以在一个新的会话中直接提到“使用 plan 技能分析这个任务”看它是否按照技能要求执行。4. 安装后别急着用先做这三件事4.1 验证技能是否被正确识别很多人装上技能包就直接开始干活结果发现 AI 行为和以前一模一样就断定“没用”。实际上大部分情况是技能根本没被加载或者加载了但没被触发。我自己的验证方法是用一个极简会话去测试请列出你当前可用的技能并说明你将如何在以下任务中使用它们重构这个项目里的 utils 模块。如果 superpowers 生效AI 的回复通常会说它打算先分析 utils 模块的影响面再制定重构计划最后分步骤实施。如果它的回复依然是那种“好的我准备开始改代码了”的状态说明技能没有激活。这时候我一般会检查两个地方一是技能目录里是否有重复的文件夹导致加载冲突二是项目根目录的AGENTS.md是否写入了启用声明。另外部分版本还支持在会话中手动执行/skills这样的命令来查看技能状态具体以你本机版本的帮助信息为准。4.2 给超级权限划好边界superpowers 名字听着霸气但你要清楚它给了 AI 更多的自主操作空间也就意味着你需要给权限设好边界。我见过有人把技能包装好后顺手开启了自动执行所有文件的权限结果 AI 一次性格式化了多个非目标文件虽然项目有版本控制没有造成实质损失但还是吓出一身冷汗。我的建议是分三步设置权限在 Codex CLI 里保持默认的“每次操作前询问”模式不要图省事开启全自动在AGENTS.md里明确哪些目录 AI 不能动比如docs/下的人工维护文档、scripts/下的构建脚本等第一次在实际项目上使用前找一个临时分支做全流程试跑确认它在技能驱动下的行为在一个可接受的范围内技能包只是给了 AI 方法真正决定它能不能在你的项目里安全工作的是你划定的边界。4.3 用一条真实任务感受前后的差异验证完技能加载和权限设置我建议你找一条真实但风险低的小任务感受一下安装前后的差别。不要一上来就让它做大型重构因为你还需要时间适应它的节奏。我当时选的任务是把一个工具函数从utils/format.js迁移到utils/string/format.js同时更新所有引用它的文件。在未安装 superpowers 时AI 的做法大概率是直接搜索字符串然后批量替换它不会告诉你它搜到了哪些文件也不会做 import 路径的验证。而安装之后它调用重构技能输出结果里有明显的步骤感先扫描所有 import 来源再逐文件修改最后跑测试和构建验证。这个过程给我的感觉是它终于像一个需要对我负责的同事而不是一个只知道执行当前指令的终端。跑完这个任务你基本就能判断自己是否需要进一步调整技能包的配置了。5. 实际跑起来典型场景与翻车记录5.1 多文件重构从各自为战到全局联动我最有体感的多文件重构场景是把一个老模块从回调风格改造成 async/await 风格。这个任务牵涉到十几个文件调用链长而且各个文件的改动顺序有依赖关系。如果用传统方式直接让 Codex 做它经常会陷入“见一个改一个”的状态。改到中间遇到一个异常分支它可能就停下来问你是想换种写法还是继续按原计划。不是它能力不行而是缺少一个全局计划框架的时刻约束。superpowers 的 plan 技能会在最开始生成一个多步骤计划并将这个计划注入到会话上下文中。后续每一步AI 都会回顾这个计划标注当前进度然后继续推进。哪怕中间被打断你也可以让它重新加载计划它会回到正确的进度节点而不是从头再来。这个“进度标注”机制是我认为它最值钱的设计之一。5.2 TDD 模式带来的工作方式变化另一个让我印象深刻的技能是 TDD 模式的引入。说实话我平时自己写业务代码并不算一个严格的 TDD 信徒但用 superpowers 跑过一次测试驱动开发之后我开始重新审视它的价值。当你在 Codex 会话里要求它按 TDD 执行一个功能开发时它的行为顺序会变成这样先根据你的需求描述列出需要覆盖的测试用例再为这些用例编写测试代码然后运行测试确认它们是失败的接着再写实现代码让测试通过最后跑一次完整测试套件确认没有回归。这套流程跑下来最大的变化是 AI 生成的代码边界意识更强了。它不会为了实现一个函数而顺手改掉另一个函数的逻辑因为测试用例已经把预期的行为钉死了。虽然这个过程比直接让它写代码要慢一些但对于那些你不想后面返工的核心模块慢即是快。5.3 我的踩坑记录权限拒绝、路径冲突、版本不一致有收获自然也有翻车。我遇到的第一个坑是权限拒绝。在某次运行中AI 试图修改一个只读目录下的文件由于我的权限设置是询问模式它停下来问我是否要提升权限。这里我没注意一路敲了 yes结果它把只读目录里一个配置文件也给改了后面排查了很久才发现是那次误操作。所以现在我的策略是询问模式下每一次权限申请都看清楚路径再确认不要习惯性回车。第二个坑是路径冲突。我在项目里同时保留了skills目录和~/.codex/skills但两者内容版本不一致导致 Codex 在会话中加载了旧版技能产生了一些莫名其妙的行为。排查方法也很原始逐个环境变量检查最后发现是项目根目录下隐藏的技能配置优先级更高。去掉项目内的重复技能目录之后行为恢复正常。第三个坑是版本兼容。superpowers 的技能文件如果有更新而你的 Codex CLI 比较老可能无法理解新技能里的某些字段。这种情况通常会表现为技能加载失败但没有任何报错只是行为退化成默认状态。解决方案是看技能仓库的 README里面一般会写明最低支持的 Codex 版本。6. 如何真正用好它几个关键心法6.1 技能包不是越大越好新手刚接触 superpowers 这类东西很容易产生一个误解技能越多AI 越强。实际上完全不是这样。技能太多会让 AI 在多个流程之间摇摆本来一个简单的任务它非要套一个重型的计划流程输出变得非常啰嗦效率反而更低。我现在只保留了项目最常用的几个技能计划、重构、TDD 和影响面分析。其他不常用的技能统统从技能目录移走需要的时候再临时放进去。这个思路类似收纳的“断舍离”保持技能目录的克制会让 AI 对已启用技能的响应更准确。6.2 写清需求边界比会装更值钱装完技能包之后我最大的体会是技能包解决的是“怎么干活”但“干什么活”还是得你想清楚。如果你给 AI 的需求本身含糊不清比如“优化一下这个项目”即使有 superpowers 在手它也只能列出一些泛泛的优化点最后挑一个它觉得合理的去执行而这个“它觉得合理”不一定是你想要的。我现在会在需求描述里强制自己写清楚三件事背景、范围、完成标准。背景告诉 AI 为什么要做这件事范围告诉 AI 哪些文件、哪些模块算在这个任务内完成标准告诉 AI 做到什么程度可以算结束。大多数情况下需求描述越清晰superpowers 里那些技能流程发挥的作用越大。6.3 版本回溯与后续更新最后说下技能包的更新问题。我在前文提到安装前会做备份其实更重要的是形成“更新前先备份”的习惯。因为技能包通常更新不频繁但每次更新可能调整核心流程如果你不备份更新后发现新版本的行为反而和你的项目习惯冲突想回滚就只能靠记忆了。我的做法是在技能目录里保留一个versions/文件夹里面存着每次更新前的压缩包。遇到新版本出问题时直接解压覆盖回去一条命令都不用多想。更新之后我会重新跑一遍第 4.3 节里的真实任务用同样的需求验证新版本有没有行为回退。越依赖这套技能流程我越意识到一个事实superpowers 的价值不是让 AI 从笨变聪明而是让它从不稳定变得稳定。它把你验证过的执行策略固化下来让 AI 每次执行都保持同样的水准。我在实际项目中体验到的效率提升不只是来自 AI 写代码的速度更来自它少犯的那些低级错误。如果你已经被 Codex CLI 默认行为折磨过几次不妨按照上面的步骤装上试试然后选一个你项目里最常见的场景用同一根需求分别跑一次有技能和没技能的版本对比一下过程与结果。我相信你会回来感谢那个下午花了半个小时读懂了这套技能包。