最近代码圈里有个词出现得特别频繁——“superpowers”。打开各种开发社区满屏都是“superpowers 使用教程”“Codex CLI 安装 superpowers”“Trae 安装 superpowers skill”这类搜索词。第一次看到的时候我也挺懵以为是什么新出的游戏模组或者效率工具。后来在自己项目里跑通一遍才发现它其实是冲着 AI 编程助手“只会聊不会干”那个老大难问题来的。如果你手头正在用 Codex CLI、Trae 这类 AI 编程工具又总觉得它们平时只能帮你写点零散代码、改几个报错稍微复杂一点的任务就开始自由发挥、甚至反复横跳那这篇东西值得你花十分钟看完。我会从“superpowers 到底解决什么问题”讲起把它在 Codex CLI 和 Trae 两个环境里的安装过程、配置逻辑、常用工作流都铺开最后再聊聊我在实战里踩过的几个坑和目前觉得最稳的用法。1. 先说清楚 superpowers 是什么它不是工具是一套“技能栈”很多人第一反应是去 GitHub 搜 “superpowers”看到一个仓库就以为是某个 CLI 工具拿到手之后反而不知道怎么用。其实 superpowers 更像一个“技能包”或者“工作流定义层”。它本身不直接生成代码而是给 AI 编程助手提供一套可执行、可复用的任务流程。1.1 为什么编码助手会“懂很多但做不成事”用过 Codex CLI 这类工具的人应该都有体会你让它写个排序算法它写得又快又对你让它“重构整个模块”它就开始发挥想象力了。不是模型变笨了而是它缺乏一个明确的“做事方法”。写排序算法这件事人类程序员早就形成肌肉记忆了模型也见过无数遍自然不需要额外引导。但“重构模块”这种任务牵扯到读代码、找依赖、改接口、跑测试、看回归每一步都该怎么做模型心里其实没底只能靠猜。大多数人的解决办法是在提示词里拼命描述步骤——“你先读一下这几个文件然后画个依赖图再列计划最后动手改”。这么做有效但非常累。而且每个人的提示词风格不一样这次写得好下次不一定记得住换个人来写又完全是另一种风格。superpowers 的思路是把这类复杂任务拆成一套标准化的“技能”每个技能都有自己的说明文件、示例、脚本和工作流。AI 助手只要加载了这些技能就相当于脑子里多了一套“操作手册”遇到对应任务时能按手册一步步来而不是现场乱编。1.2 技能栈的基础结构SKILL.md 与配套资源superpowers 底层的技术形态是我个人很喜欢的一种设计——“以文档为中心的技能包”。一个技能本质上就是一个目录目录里最关键的文件是SKILL.md它用结构化格式描述了这个技能是干什么的、在什么场景下触发、具体需要执行哪些步骤。旁边可能还会放scripts/、examples/、reference/这些子目录用来承载更详细的辅助材料。打个比方这就像你给一个新同事写了一份“入职手册”手册第一页写明他的岗位职责后面几页是流程图、常用命令、范例代码。AI 助手看到那份手册之后就知道什么时候该调用什么能力、按什么顺序执行。这套结构的好处是极度透明。普通提示词是藏在对话里的黑盒一样技能则是显式存放在项目目录或者全局目录里的文档你随时能打开看它到底写了什么、引导模型做了什么。版本管理也很方便一个技能文件夹直接丢进 Git 仓库就行团队协作时大家用的是同一套“手册”。1.3 superpowers 真正带来的改变从“生成代码”到“执行任务”我自己用了两周之后的感受是安装 superpowers 之前Codex CLI 像一个很聪明但没什么耐心的实习生你说一步它做一步不问清楚就瞎猜安装之后它更像一个带过几个项目的熟手拿到任务会先梳理范围再制定计划执行过程中还会自己验证结果。这个改变不是说模型变强了而是“流程约束”起作用了。比如代码审查这个场景没有技能时AI 会笼统地扫一遍代码给几条通用建议加载了代码审查技能之后它会按照“先看变更范围→检查测试覆盖→找潜在边界问题→给出按严重程度排序的修改意见”这套流程走输出的质量稳定很多不会再出现那种“这个文件写得很好没有发现问题”之类的敷衍结论。如果你能接受“AI 编程助手不该只是聊天机器人而应该是有方法论的执行者”这个前提那 superpowers 就非常对你的胃口。2. 安装前必须理解的体系结构四个层级别搞混很多人在安装 superpowers 时翻车不是操作有多难而是没搞清楚它到底装在哪一层。这里我先画个简单的分层逻辑后面所有安装步骤都是围绕这几层展开的。2.1 第一层运行时Runtime运行时就是承载 AI 助手的那个程序比如 Codex CLI、Trae、Claude Code 等等。技能不是独立运行的它必须寄生在某个运行时里通过运行时去读取、解析、执行。你没法“单独运行”一个技能就像你没法不通过浏览器就打开一个网页。所以安装 superpowers 的第一步永远是先确认自己手头有一款支持技能机制的 AI 编程工具。2.2 第二层技能加载路径运行时需要知道去哪里找技能。常见的做法有两种一种是放到全局目录比如~/.codex/skills/所有项目都能用另一种是放到项目目录比如.codex/skills/只对当前仓库生效。这个选择会影响后面的一堆配置我建议个人开发用全局目录团队协作用项目目录这个后面细说。2.3 第三层技能描述与执行逻辑这一层是 superpowers 的核心也就是那些技能文件夹里的内容。前面提到的SKILL.md就是这一层的代表。运行时加载技能时实际上是在读这份描述文件然后把里面的步骤塞进模型的上下文。技能好不好用70% 取决于这份文件写得好不好。2.4 第四层触发机制最后一步是触发。技能怎么被“唤醒”有些技能是用户显式要求的比如你在对话里直接说“用 git 工作流技能帮我处理这次提交”有些则是运行时根据对话内容自动判断的比如你让 AI 修一个 bug它发现自己的技能列表里有“调试技能”就会自动加载。理解这四层之后你再去看那些安装教程就不会晕了。网上很多教程喜欢直接甩命令看起来很简单但它没说清楚这些文件该放在哪一层、为什么放那里。一旦目录错位技能加载不上你连排查的头绪都没有。3. Codex CLI 安装 superpowers两条路径我都实际跑过Codex CLI 是 OpenAI 的命令行编程工具也是社区里对 superpowers 支持比较早、比较完整的运行时之一。安装方式不复杂但有不少细节值得注意。3.1 前置准备确认 Codex CLI 版本与环境依赖动手之前先做两件小事。第一确认你的 Codex CLI 版本不是太老至少是支持技能目录的版本。第二确认你本机装了 Git因为后面拉取技能包要用。这一步很容易被忽略很多人装了半天发现技能一直加载不上最后查来查去是 Codex CLI 版本太旧压根不认skills目录。建议直接升级到最新版再开始npm install -g openai/codex codex --version如果之前安装过其他 AI 编程工具记住不要跟 Codex CLI 的全局目录搞混它的配置目录通常是~/.codex/。3.2 路径 A全局安装所有项目通用全局安装适合你自己个人电脑装一次之后不管开哪个项目都能用。操作方法很直白把 superpowers 仓库克隆到 Codex 的全局技能目录里。mkdir -p ~/.codex/skills git clone https://github.com/obra/superpowers.git ~/.codex/skills/superpowers克隆完成之后检查一下目录结构确认SKILL.md确实在~/.codex/skills/superpowers/下面而不是多套了一层目录。接下来是让 Codex CLI 知道技能的存在。这一步取决于你的 Codex CLI 版本老一点的版本会要求你在配置文件里显式声明技能目录路径新一点的版本则会自动扫描默认的技能目录。我建议在AGENTS.md文件里加一段说明这样最稳不管哪个版本都认在开始任何任务之前检查 ~/.codex/skills/ 下是否有与当前任务相关的技能。 如果有请先阅读对应技能目录下的 SKILL.md然后严格按照技能描述的工作流执行。AGENTS.md是 Codex 这类工具的项目级行为说明文件放在项目根目录即可。它的作用就像给 AI 立规矩——先看技能库再干活别上来就直接写代码。3.3 路径 B项目级安装团队协作更可控团队项目不建议把技能放到个人全局目录里因为每个人电脑上都有各自的版本一旦更新不同步行为就千奇百怪。更好的做法是把技能直接放进项目仓库mkdir -p .codex/skills git clone https://github.com/obra/superpowers.git .codex/skills/superpowers rm -rf .codex/skills/superpowers/.git注意最后一条命令复制完之后要把技能目录里的.git删掉否则会变成一个嵌套的 Git 仓库之后提交项目代码时会出现一堆乱七八糟的子模块提示。然后同样在项目根目录的AGENTS.md里声明技能路径优先读取 .codex/skills/ 目录中的技能文件按照其中定义的工作流执行任务。项目级安装的好处有两个一是所有人用同一份技能行为一致二是技能随着代码仓库一起走Code Review 的时候技能变更也能被看到不会有“我这跑得好好的怎么你那边就不行”的扯皮。3.4 启动 Codex 验证技能是否被加载安装完先别急着跑复杂任务。启动一个干净的 Codex 会话输入一句验证指令比如“列出你当前可用的技能并简要说明每个技能的用途”。如果配置正确它会像报菜名一样给你列出一串技能及对应描述说明加载成功。如果它说“当前没有可用技能”或者干脆不知道你在说什么基本就是目录放错或者AGENTS.md没生效回头检查路径即可。第一次加载技能时Codex 会把技能内容读进上下文这个过程会消耗一些 token。这是正常的不用慌。后续同一个会话里再次使用技能时模型通常已经“记住”了一部分不会每次全部重读。4. Trae 里的 superpowers 安装和 Codex 的两个核心差异Trae 是一款自带 AI 能力的编辑器国内用户用得也不少。它的技能机制跟 Codex CLI 不太一样如果你只会 Codex 那套到 Trae 里就很容易找不到北。4.1 差异一Trae 更依赖图形界面但底层仍是技能目录Codex 是纯命令行工具安装技能主要是敲命令、改配置文件。Trae 是 IDE绝大部分操作在图形界面里完成但底层依然离不开“技能目录”这个概念。打开 Trae 的设置面板找到 Skills技能相关入口你会看到它支持从本地目录导入技能也支持从市场安装。如果你已经从 GitHub 拉下来了 superpowers 仓库那就选“从本地导入”直接把superpowers目录拖进去即可。如果你还没下载也可以在 Trae 的界面里直接填仓库地址让它帮你拉取。这里要特别注意的是Trae 国内版和国际版的界面文字略有差异但功能入口基本一致都叫“技能”或“Skills”。如果你没找到这个入口检查一下 Trae 是不是需要登录账号才能解锁技能功能不少 AI IDE 把技能管理做成了账号功能不登录的话那一栏直接隐藏。4.2 差异二项目级技能目录的约定不同Trae 的项目级技能目录约定跟 Codex 不一样。Codex 习惯用.codex/skills/Trae 则倾向于识别项目根目录下的.trae/skills/。所以你在 GitHub 上克隆 superpowers 之后在 Trae 项目里使用之前通常需要复制一份到 Trae 的技能目录mkdir -p .trae/skills cp -r superpowers .trae/skills/多嘴一句不要把同一个技能同时放在全局和项目两个位置Trae 加载时可能会冲突。我的建议是如果是自己的临时项目全局即可如果是多人协作的正式项目放.trae/skills/并提交到 Git。4.3 Trae 里调用技能的两种方式在 Trae 里技能触发比命令行工具更“松弛”一些。第一种方式是手动触发你在对话框里直接描述需求同时加上一句“请使用 superpowers 中的 XXX 技能来完成”。第二种方式是自动匹配Trae 会根据你的问题内容自动推荐或加载相关技能界面里会显示当前会话正在使用哪些技能。我个人的体验是自动匹配方便但不够稳定有时候我明明想要代码审查它却去加载了调试技能。所以关键时刻还是手动指定更靠谱。就像导航软件给你推荐了一条路但你真的赶时间的话还是得自己提前说清目的地。4.4 Trae 装完不生效多半是缓存问题Trae 作为一款桌面应用对技能目录的扫描不是即时的。你刚把 superpowers 放进去马上开一个新会话测试很可能会发现 AI 根本不知道有这个技能存在。这不是你装错了而是缓存没刷新。解决办法简单粗暴重启 Trae。重启之后它才会重新扫描技能目录把新技能加载进来。如果重启还不行那就去设置里找“清除缓存”之类的按钮清完再重启。我在公司电脑上遇到过几次这种怪问题基本都是靠重启解决的没遇到需要重装的情况。5. 真正值钱的是工作流superpowers 里的技能到底怎么用很多教程装完 superpowers 之后就戛然而止告诉你“装好了去用吧”。但真正上手的时候反而傻眼——技能那么多到底该让 AI 用哪个怎么组合这里我挑三个我在日常开发里用得最频繁的工作流说说它们是怎么运转的。5.1 工作流一从模糊需求到测试驱动实现以前让 AI 写功能它拿到一句话需求就直接开写写出来的东西经常跑不通或者功能实现有偏差。superpowers 会引导它先进入“计划模式”把需求拆成可验证的小任务甚至主动要求你补充边界条件。我自己实测的过程大概是这样的。我说“帮我实现一个带过期时间的缓存”它的响应不再是立刻写代码而是先说我理解你的需求是要一个支持 TTL 的键值缓存我准备先用 TDD 方式实现第一步先定义接口第二步写过期判断的测试第三步实现底层存储第四步跑测试确认。整个过程它会一步步做给我看每完成一步还会停下来问我要不要继续。这种体验接近带一个初级开发而不是面对一个只会吐代码的机器。5.2 工作流二调试问题时的“医生模式”AI 最大的毛病之一就是喜欢猜错误原因。你给它一个报错信息它不先查证据就直接开药方。superpowers 的调试技能会把流程改成复现问题 → 收集上下文 → 定位根因 → 提出修复方案 → 验证修复效果。有一次我的 Node 服务线上偶发内存泄漏光靠日志很难定位。我让 Codex CLI 用调试技能来分析它没有立刻给我甩一个“可能是全局变量没清理”的结论而是让我先提供 Heap 快照再对比不同时间点的内存变化。顺着这套流程我们最终定位到一个第三方库缓存了大型对象导致的问题。整个过程它的分析节奏很扎实没有乱跳步。5.3 工作流三代码审查从走过场变成仔细过代码审查这个场景其实是最容易体现 superpowers 价值的。不用技能的时候AI 审查代码是“通读一遍→说几句好话→给两个不痛不痒的建议”。用了 code review 技能之后它会先分析这次变更涉及哪些文件、改了什么逻辑再逐个文件检查测试覆盖、错误处理、边界条件最后才输出一份按优先级排序的 review 意见。我特别留意到一点它会在意见里标注“建议修改”“需要讨论”“可选优化”三个级别。不会像以前那样把所有问题混在一起导致我看的时候不知道该先处理哪个。这个小细节对团队协作很重要毕竟大家在 review 时时间都有限按优先级处理效率高很多。5.4 组合使用把技能连成一条流水线单个技能是“招式”连起来才是“套路”。我目前在个人项目里有一套固定组合流程需求进来之后先用计划技能拆分任务然后把拆分结果交给 TDD 技能去实现写完代码用审查技能过一遍最后用 Git 技能生成规范的提交信息。这一套流程顺手之后我发现自己从“事无巨细地写提示词”里解放出来了。以前每次开新需求都得重新描述一遍流程现在只需要说清楚需求本身AI 自己会按技能库里的“手册”走。那种感觉就像从手动挡换成了自动挡。6. 实战中容易翻车的四个场景及对应解决方案工具是好工具但用起来难免遇到问题。这一节我不写那种大而全的“FAQ”只挑自己真实碰到的、也看到身边同事反复踩的四个场景来聊。6.1 技能加载不到AI 完全不知道 superpowers 是什么如果是 Codex CLI先排查全局和项目目录是否真的克隆对了位置。很多人在终端里一路复制粘贴结果命令执行失败都没注意目录压根没创建成功。如果目录没问题再看AGENTS.md是否写对路径是否跟实际一致。如果是 Trae优先重启。被缓存坑过太多次了我现在养成一个习惯每次往技能目录里丢新文件夹都会顺手重启一次 Trae不折腾。6.2 技能文件太多上下文被占爆superpowers 的技能包如果内容很丰富每个技能都有大量说明和示例加载太多技能会吃掉大量上下文窗口导致真正写代码时模型反而“变笨”。我现在一般只保留 4 到 6 个高频技能在技能目录里其他不常用的放备份目录。Codex 支持按需引用路径未必需要把所有技能都堆在默认目录里。合理做法是把技能库完整克隆到一个统一存放位置然后只在技能目录里做软链接或者通过AGENTS.md按项目需要引用指定技能。这就像工具箱一样不会把家里所有工具都背身上出门带个常用套装就行。6.3 技能里的命令带风险AI 直接执行了superpowers 的技能工作流里经常涉及运行命令比如执行测试、跑构建、Git 操作。这些命令在沙箱环境里没问题但落到本地真实环境就有一定风险。有一次 AI 在执行技能步骤时试图覆盖我本地数据库的测试数据还好我提前设了确认机制才没有出事。解决方案分两层第一层是在AGENTS.md里写明“执行任何可能产生破坏性影响的命令前先向用户确认”第二层是认真阅读技能包里SKILL.md的命令部分自己心里有数它到底会执行哪些操作。技能库是开源的内容可以审这份透明性也是我选择它的原因之一。6.4 团队成员各自为战技能版本不一致如果你的团队决定用 superpowers我强烈建议直接把技能目录纳入项目仓库并去掉嵌套的.git。这样所有人在同一个提交点位上工作永远不会出现你用的是旧版技能、我用的新版技能这种问题。另外技能更新不要在每个人电脑上分别git pull而是在项目里统一更新走正常的代码提交流程。这样做的好处是技能变更跟代码变更一起过 Code Review出问题能追溯不会“莫名其妙 AI 行为变了”。7. 自己动手写一个简单技能其实没有想象中复杂用了一段时间之后你会发现自己有些特殊的团队流程是通用技能包没覆盖到的。这时候就该自己写技能了。别怕写一个技能没有写一个插件那么复杂本质上就是写一份结构化文档。7.1 技能目录结构的设计先建一个目录名字就是技能名目录里放一个SKILL.md必要的话再加辅助脚本和示例文件夹。以下是一个标准技能目录的最小结构my-custom-skill/ ├── SKILL.md ├── scripts/ │ └── generate_report.py └── examples/ └── 示例输出.mdscripts/不是必须的但如果技能涉及重复性操作把操作脚本化会明显提升准确性。模型不擅长心算让它跑一个脚本远比让它推理靠谱。7.2 编写 SKILL.md 的关键步骤要像菜谱SKILL.md的格式没有特别严格的规范但经验法则是描述要具体到“何时做、做什么、怎么做、做完怎么验证”。不要写“分析代码质量”这种空话要写“读取目标文件→检查是否有测试→运行已有测试→按严重程度输出 1-10 的质量评分并列出依据”。我自己踩过的坑是写得“太像人话”——我以为自己描述得很清楚但模型理解出来还是偏抽象。后来我学会了一个技巧每写一步都问自己这一步的输出产物是什么能验证吗如果不能验证说明这一步骤设计得太虚。调试完技能之后可以让 AI 按技能走一遍你准备的真实样例看看它的行为是不是符合预期不行就迭代描述。7.3 把自定义技能接入工作流把写好的技能目录放到全局或项目技能目录然后按照前面的方式让运行时扫描到它。接着在一个新会话里显式要求 AI 使用新技能同时准备好一个中等复杂度的测试任务观察它是否真的按照技能里的步骤在做。如果 AI 无视技能、回复依然很随意多半是SKILL.md前几行的触发条件写得不够明确。你要在技能描述里写清楚“当用户要求 X 时强烈建议使用本技能并按以下顺序执行”它才会在合适的时机主动想起这个技能。8. 关于 superpowers 现状的一点个人感受刷到的搜索词里还有“superpowers github”我相信很多人跟我一样第一反应是去仓库里看它到底更新得勤不勤、社区活跃不活跃。从我这段时间的使用看它的迭代节奏蛮快的技能内容也在不断完善。但说实话这个项目的价值不在于有多少个 star而在于它把“AI 编程助手应该怎么工作”这件事重新定义了一下。之前大家讨论 AI 编程重点都在“模型多大、代码生成准不准”superpowers 让我意识到模型能力只是下限流程设计决定上限。同样一个模型有技能和没技能产出质量的稳定性差很远。模型本身还是会幻觉、会偷懒但一套好的工作流能把这些问题兜住。它就像给一个聪明但散漫的同事配了一套标准作业程序虽然不能保证他百分百不犯错但至少不会毫无章法地乱来。如果你手里已经攒了 Codex CLI 或者 Trae真心建议今天花个二十分钟照着上面的步骤把 superpowers 装起来不用多先挑一个你日常最痛的工作流试一周。我自己用的第一周最明显的变化不是代码写得快了多少而是“返工率”降下来了——AI 交出来的活更贴近可用的状态我不需要再像以前那样逐行盯着改了。这种体感差异比任何 benchmark 数字都更能说服人。