上个月我把 Codex CLI 拉起来做一次模块重构模型对代码的理解速度确实快但整个过程给我的感觉就像一个特别聪明但完全没经历过正规团队的新人你让它改哪里它就改哪里改完也不知道跑一遍测试更不会主动去考虑边界情况。后来在 GitHub 上刷到 obra/superpowers 这个项目试了一下午整个使用体验发生了质的变化。Superpowers 并不是什么黑魔法它本质上是给 Codex CLI 装了一套可复用的“技能包”Skills让模型从“你问一句我答一句”变成“先规划、再动手、最后验证”的完整工作流。这篇文章就把我这一周多的真实使用过程、安装方式、核心技能拆解和踩坑记录完整写下来给正在用 Codex CLI 或者对 Agent Skills 机制感兴趣的朋友做个参考。1. 先搞清楚 superpowers 到底在解决什么问题1.1 Codex CLI 本身已经很强缺的是“方法论”Codex CLI 是 OpenAI 出的命令行编程助手它的本事不用我多说能读项目、能改文件、能直接执行命令模型对代码的理解能力非常在线。但如果你像我一样真拿去干活很快就会碰到一个微妙的问题模型知道怎么写代码但它不太知道“什么时候该用什么方法”。我给你描述一个典型场景。你把一个 bug 丢给它“这段解析配置的逻辑有 bug帮我修一下。”它看了一眼大概率直接给出一个修改后的函数然后告诉你“应该没问题了”。它不会先复现问题不会问你要输入样例不会补回归测试更不会去检查这个改动会不会影响其他调用方。换句话说它的代码能力是满格的但工程方法几乎是空的。这不是模型的智商问题而是任务表达方式的问题。Codex 默认的工作模式是“单次对话完成一个请求”你给它什么指令它就沿着最短路径给你结果。它没有内置的“先理解再动手”的流程约束除非你在提示词里写得明明白白。1.2 从 Claude Code 的 Skills 到 Codex 的 SuperpowersAgent Skills 这个概念最早在 Claude Code 生态里被大家熟悉。思路其实很朴素模型不是什么都该在上下文里塞着而是把某一类任务的“操作方法”打包成一个 skill里面包含步骤说明、模板、脚本甚至注意事项模型在需要的时候再去读对应的 SKILL.md 文件。Superpowers 就是把这一套借鉴到 Codex CLI 上的开源项目。GitHub 上可以找到作者维护了一套结构清晰的技能目录里面按照功能分成不同的 skill每个 skill 都是独立目录核心是一个SKILL.md文件外加一些参考模板和脚本。这和直接在系统提示词里写“你要先规划、再写测试、再实现”完全不是一回事。后者是一次性的指令模型读一遍就过去了执行着执行着就忘了而 skill 是一种“按需查阅的操作手册”它把流程固化下来让模型在处理特定类型任务时有一套可以随时回看的标准动作。1.3 一个反直觉的事实装完技能后 token 消耗反而更省说到按需查阅我猜很多人第一反应是配置文件里多挂几个技能说明每个请求不都要多读一堆东西吗那不是更费 token这也是我一开始的顾虑实际用了之后才发现恰恰相反。好的技能系统不会把全部技能文档塞进每次请求。它通常只会给模型一个极简的“技能索引”让模型知道“存在哪些技能、分别解决什么问题、去哪找详细文档”等到当前任务确实需要某一项技能时模型才会主动去把对应的 SKILL.md 完整读一遍。这个机制打一个不太恰当的比方一个修车师傅不会把所有工具都挂在身上出门他是需要拧螺丝的时候才回工具箱拿扳手。Superpowers 干的其实是给 Codex 配了一个工具箱而不是让它把整个工具箱背在身上。2. 安装前需要准备的环境与配置基线2.1 最基础的依赖Node.js 环境与 Codex CLI 本体在碰 Superpowers 之前你得先有一个能正常工作的 Codex CLI。这一步官方 README 写得很清楚我在这里只强调几个容易出问题的点。Codex CLI 的安装通常有两种方式一种是 npm 全局安装一种是 Homebrew 安装我自己的环境用的是 npm 的版本npm install -g openai/codex装完之后先验证版本确保命令能正常跑起来codex --version如果你是第一次用还需要完成登录授权。整个过程在终端里会有交互提示跟着走一遍就行。要注意的是Codex CLI 的配置目录默认在~/.codex/下面后面挂载 Superpowers 的时候要往这个目录里放东西所以心里先有个数。2.2 拿到 Superpowers 项目文件接下来就是把 Superpowers 项目本身拉下来。我建议直接 clone 到~/.codex/superpowers这个固定位置方便后续更新git clone https://github.com/obra/superpowers.git ~/.codex/superpowersclone 完成后项目目录结构大致是这样的我当时拉取的版本superpowers/ ├── _superpowers/ │ ├── personas/ │ │ ├── codex.md │ │ └── ... │ └── skills/ │ ├── brainstorming/ │ │ ├── SKILL.md │ │ └── ... │ ├── planning/ │ ├── tdd/ │ ├── debugging/ │ └── ...这里有个很容易忽略的细节技能文件都在_superpowers这个带下划线的目录下而不是仓库根目录下。很多人第一次配置时路径写错结果 Codex 根本找不到技能问题就出在漏了这一层目录。2.3 和我一样有洁癖的人用一个独立目录管理技能包如果你同时用 Codex CLI 和 Trae 这类 AI 编辑器想在不同工具之间共享同一套技能文件我建议不要往各自的目录里复制粘贴。复制一时爽更新火葬场——上游项目一更新你复制出来的那份就过时了而且你还不知道。我自己的做法是在~/.codex/下建一个skills目录用软链接把 Superpowers 里的技能指过来mkdir -p ~/.codex/skills ln -s ~/.codex/superpowers/_superpowers/skills/* ~/.codex/skills/这样做的核心好处是技能文件永远只有一份git pull更新之后所有引用它的工具自动拿到最新版本。后续你就算要自己写 skill也可以往这个目录里扔统一管理。3. 在 Codex CLI 中挂载 Superpowers两种实际可行的方案3.1 方案一通过 config.toml 的 instructions 字段引入Codex CLI 的配置文件是~/.codex/config.toml默认路径在用户目录下。安装完 Superpowers 之后你需要在这里把技能入口告诉 Codex。我当前使用的配置简化后大概是下面这个样子不同版本可能会有字段差异以你手头版本的官方 README 为准# ~/.codex/config.toml model gpt-5.1-codex instructions [ ~/.codex/superpowers/_superpowers/personas/codex.md, ~/.codex/superpowers/_superpowers/skills/brainstorming/SKILL.md, ~/.codex/superpowers/_superpowers/skills/planning/SKILL.md, ~/.codex/superpowers/_superpowers/skills/tdd/SKILL.md, ~/.codex/superpowers/_superpowers/skills/debugging/SKILL.md, ]这段配置的作用是每次启动 Codex 会话时把这些技能文件和人格文件作为基础指令加载进去。Codex 知道这些技能存在但并不会一口气把所有内容都读一遍而是在实际任务中遇到对应场景时才去完整读取单个SKILL.md的内容。如果你用的是 Codex 的较新版本官方有时会调整指令的加载方式比如把多个指令合并成一个总入口文件。遇到这种情况不用慌在项目里建一个AGENTS.md在文件里统一引用所有技能入口效果是一样的。3.2 方案二使用项目内的 AGENTS.md 引用方案一更适合个人全局配置但如果你是在一个团队项目里协同工作想让所有用 Codex 的队友都自动拥有这套技能我建议用第二种方式在项目根目录放一个AGENTS.md内容里直接指向 Superpowers 的入口文件。# 项目级指令 在执行任何任务前请参考以下技能文档 - 头脑风暴~/.codex/superpowers/_superpowers/skills/brainstorming/SKILL.md - 任务规划~/.codex/superpowers/_superpowers/skills/planning/SKILL.md - 测试驱动开发~/.codex/superpowers/_superpowers/skills/tdd/SKILL.md - 调试排查~/.codex/superpowers/_superpowers/skills/debugging/SKILL.md这种做法的优势是技能跟随项目走谁打开这个项目Codex 都能读到统一的规则不会因为某个人没配置全局环境而导致行为不一致。缺点也显而易见如果团队里有人没有在同样的路径下安装 Superpowers引用就会断掉。所以团队使用的话最好把 Superpowers 也固定到统一的目录约定里。3.3 在 Trae 这类 IDE 中安装 superpowers skill 的思路很多人不只用命令行版的 Codex还会在 Trae 这类 AI 编辑器里干活。通过“trae work cn 安装 superpowers skill”搜到这个项目的人多半是想在编辑器里也用上这套技能。Trae 这类 IDE 对技能skill的支持方式各不相同有的会自动扫描项目下的特定目录有的需要你在自定义规则里手动引用。我当时没有找到一键安装按钮最后用的是最朴素的思路让 IDE 能找到 SKILL.md 文件。一个比较通用的做法是在项目根目录下建一个规则目录具体目录名依 IDE 而定可能是.trae、.cursor或.rules之类然后把 Superpowers 的技能目录软链进去mkdir -p .trae ln -s ~/.codex/superpowers/_superpowers .trae/superpowers接着在 IDE 的规则文件里写一句话告诉模型“遇到对应场景时去读.trae/superpowers/skills/技能名/SKILL.md”。这个方法不能说百分之百适配所有版本但思路是通用的任何支持自定义规则的 AI 编程工具本质上都是通过文本指令让模型感知技能的存在你只要能把这个路径告诉它技能就挂上了。4. 核心技能逐个拆解这些“超能力”到底是怎么工作的4.1 Brainstorming动手之前先把思路摊开Brainstorming 是我实际使用频率最高的一个技能。它的核心价值在于当需求本身还模糊的时候不让模型急着给结论而是先输出多套候选方案再把每套方案的优劣、成本、风险摆出来。我给你一个直观的对比。没有装技能时你问“我想给项目加一个缓存层应该怎么做”它会直接甩给你一个 Redis 集成方案看起来挺专业但它根本没问你现在的架构是什么样的、qps 有多少、数据一致性要求多高。装上 Brainstorming 技能之后它的反应变成先列出三个大方向本地内存缓存、分布式缓存、数据库级缓存每个方向下面补充适用场景、接入成本、潜在问题最后还会反问你要不要基于当前代码库做进一步评估。这个东西本质上是在修正模型的“思维惯性”。模型本身没有“需求分析”这个概念你不告诉它它默认就是从最可能的答案开始。Skill 文档里如果明确写了“当一个请求的目标不明确时先进行多方案头脑风暴”它的行为就会明显改变。不过 Brainstorming 也需要注意节制。有些任务它就是很明确的比如“把这个函数的时间复杂度从 O(n^2) 优化到 O(n log n)”你还让它输出五个方案那就是浪费时间。好的技能文件本身会写清楚适用边界但人工判断还是要跟上。4.2 Planning把大任务拆成可验证的小步骤Planning 解决的则是另一个问题任务太大一步到位容易翻车。你让 Codex 直接“实现一个用户认证模块”它在一次回复里生成的代码量可能非常大中间一旦某个假设错了整段代码都白写。Planning 技能的工作方式是让模型在动手之前先产出一份实施计划。这份计划不是给你看的装饰品而是它后续执行的依据。计划里会包含任务拆解、前后依赖、每个步骤的完成标准以及最后如何验证整体效果。我实际观察到的行为变化很直观。没装技能时Codex 会直接把所有改动一次性铺开装完 Planning 之后它会先跟你说“我计划分三步第一步先建数据库表结构第二步写数据访问层第三步对接接口层。每一步完成后我会运行现有测试确认没有破坏再进入下一步。”然后它真的会按这个节奏来做完一步停一下确认没有问题再继续。这里的机制说起来也不复杂模型在生成了计划之后后续的每一步行动都会参照这个计划。计划相当于给模型一个“工作记忆”中的锚点让它不容易跑偏也让它更容易发现自己是不是漏掉了某个步骤。4.3 TDD先写测试再让实现通过测试TDD 技能是 Superpowers 里面工程价值最高的一个它对应的是“测试驱动开发”方法论。它的目标不是让模型多写几个测试用例而是改变模型的工作顺序先写测试再写实现最后跑测试验证。为什么这个顺序重要因为模型和人类一样如果先写实现它会倾向于认为自己的实现是“对的”然后为了自圆其说去写一些不痛不痒的测试。但如果先写测试测试就变成了一个固定的验收标准实现必须去满足这个标准。举个例子。我之前让 Codex 修一个日期解析的 bug没有 TDD 技能时它直接改了底层解析逻辑然后说“应该好了”。装了 TDD 技能之后它先问我“当前这个 bug 的复现输入是什么我先写一个会失败的测试用例。”然后它真的先把那个失败的测试写出来跑一遍确认红失败再开始改实现最后跑测试确认绿通过。这个“先红后绿”的过程逼着模型把注意力放在“什么行为才是正确的”上而不是“怎么尽快把当前报错消除”。对于任意一个做 AI 辅助开发的团队来说这一点都是最值得引入的。4.4 Debugging 与 Code Review 等其他技能除了上面三个Superpowers 里还有一组看着不起眼但非常实用的技能Debugging 就是其中之一。它给模型设定了一个系统化排查问题的流程而不是让模型凭感觉猜。比如代码报了一个线上异常没有 Debugging 技能时模型可能直接开始猜测原因“这个报错看起来像是编码问题我建议你检查一下文件编码。”而装备了 Debugging 技能后它会按照一个固定的排查链路走先要求提供完整的报错信息和堆栈再缩小问题范围到一个可复现的用例然后通过二分法定位到具体的代码提交最后才是提出修复方案。Code Review 技能也很值得说。它的核心作用是让 Codex 站在审查者视角重新读代码关注点集中在安全问题、边界条件、并发隐患、可维护性等方面。我经常在改完一个 PR 之后让它先过一遍自审发现问题的效率比自己盯着代码看高不少。除此之外还有生成规范 commit message、写解释文档等辅助性技能它们对日常体验的改善不是决定性的但很多个“舒服一点点”叠加起来体感差异就很明显了。5. 实战跑通一个例子用 Superpowers 重构一个遗留函数5.1 场景设定一个又长又臭的旧函数光说不练假把式我拿自己项目里一个真实场景演示一下。项目里有个老旧的parse_config函数大约一百多行干的事情太多它既要做字符串切割又要校验必填字段还要做类型转换最后还得处理各种异常情况。这个函数在多个服务里被调用改动风险非常高。如果按我以前的用法我会告诉 Codex“这个函数太长了帮我拆一下。”它大概率会直接甩一个重构后的版本出来里面可能拆成几个子函数看起来很规整但我根本不敢直接合进去——因为它没告诉我它动了哪些行为也没验证拆完之后的输出和原来是否一致。5.2 让 Codex 调用 Planning 技能后的输出这次我先在对话里明确说“请使用 Planning 技能处理这个重构任务。”然后 Codex 的输出路径完全变了。它没有直接给重构代码而是先要求我提供这个函数的所有输入样例和已知输出还去项目里搜索了所有调用点列出了一份调用关系清单。然后它给出一个计划先提取出分词逻辑保持原有输出格式不变再单独拆出字段校验逻辑所有校验错误仍然统一抛原始异常类型最后把类型转换部分抽成一个独立的映射函数每一步执行完运行原有测试集验证行为没有变化这里面的关键是计划不是走形式。它每拆完一步真的会停下来。我注意到它拆完分词逻辑后并没有立刻继续拆第二部分而是先运行了一遍测试确认通过才进入下一步。这种行为在没有技能之前我一次都没见过模型默认就是一次性把所有改动都做完因为那样看起来更“高效”。5.3 调用 TDD 技能后的行为变化重构到一半我意识到这个函数原来的测试覆盖其实很薄弱于是追加了一句“这部分请用 TDD 技能来处理。”接下来的一幕让我觉得确实值得写下来。它先看了一圈现有的测试文件发现只覆盖了正常路径然后主动补了几个失败用例一个是配置文件缺少必填字段的场景一个是类型转换传入了非法值的场景还有一个是输入为空的边界情况。然后它做了一件让我意外的事先把这几个测试跑了一遍确认它们确实失败了再把重构代码接上去让所有测试转为通过。整个过程它不是“先写实现再补测试来凑数”而是让富余的行为先被测试锁定再动实现。5.4 我的观察技能是“提示词模板”还是“行为契约”跑完这个例程我自己有一个强烈的感受技能不只是一个复杂的提示词模板它更像是一份“行为契约”。提示词模板的核心是“告诉模型你要什么”而技能的核心是“约束模型如何组织自己的行动序列”。单纯写一句“请你先规划再动手”模型可能在当前这一轮会话里遵守但到了下一轮它自己就忘了。而技能把流程拆成了可查阅的文档模型在执行过程中随时可以回读它的每一步行动都有了依据。这才是 Superpowers 和其他“大型提示词”之间最本质的区别。6. 我用了一周之后常见问题与避坑记录6.1 装了技能没生效多半是路径和大小写问题我刚开始配置时折腾最久的一个问题就是技能没生效。Codex 看起来正常启动但让它用 Planning 技能它完全没有任何反应。排查了一圈最后发现是路径大小写的问题superpowers的P在目录名里是大写我在配置文件里写成了小写。类 Unix 系统的路径是严格区分大小写的~/.codex/superpowers和~/.codex/Superpowers是两个完全不同的路径。如果你也遇到技能不生效的问题先别急着怀疑配置格式用下面的命令把路径实际输出一遍对比一下ls ~/.codex/superpowers/_superpowers/skills/planning/SKILL.md如果这个文件能正常列出来再去检查配置文件里引用的路径是不是和它一字不差。另外一个隐蔽的问题是波浪号展开。某些版本的配置解析器不会把~自动展开成用户目录这种情况下需要把绝对路径写全比如/Users/你的用户名/.codex/superpowers/...。6.2 技能文件太多导致上下文爆炸理论上按需加载机制会避免上下文爆炸但如果你不小心把所有技能文件全部塞进了instructions数组而不依赖索引机制那每个请求都会把这些内容全部载入上下文上下文占用会迅速上升。我自己刚配置的时候犯过这个错误我把skills目录下十几个技能的SKILL.md全部加进了配置结果使用起来明显变“笨”而且 token 消耗涨得很快。后来我意识到只需要挂载一个极简的索引文件就够了模型知道有哪些技能可用、去哪里找剩下的事情交给按需读取。这也是为什么我建议大家不要贪多。对绝大多数项目来说Brainstorming、Planning、TDD、Debugging 这四五个就够用了其他的用到再挂。6.3 不要把 Superpowers 当成“一键高手模式”我必须说句实话Superpowers 不是装完就能让你水平飞升的插件。它在实际工程里的价值上限取决于你的任务描述质量。技能能给模型提供工作流程的约束但它不理解你项目的隐性背景知识。比如 TDD 技能让它先写测试再实现但如果你的项目连一个测试框架都没搭好它就不知道该用什么去写测试这时候你得先把测试基础设施补齐。换句话说技能发挥效用的前提是项目的工程基础本身是完整的它更像一个放大器而不是一个从零到一的创造者。6.4 后续维护如何自己写一个最小 skill用了一周之后我最大的收获其实是“手痒”与其等着别人更新技能包不如自己写一个。Superpowers 的 skill 规范本身不复杂一个最小可用的 skill 只需要两样东西目录和SKILL.md文件。--- name: dependency-check description: 当需要评估一个第三方依赖是否应该引入时使用此技能。它会引导模型从维护状态、许可证、体积、安全记录等维度做评估。 --- # Dependency Check Skill 当你被要求评估/引入一个新的第三方依赖时按以下流程执行 1. 列出所有候选库 2. 对比维护活跃度、npm 周下载量、GitHub star 趋势 3. 查询已知安全漏洞 4. 评估依赖体积对打包产物的影响 5. 输出一个推荐结论和备选方案把这个目录放到~/.codex/superpowers/_superpowers/skills/dependency-check/SKILL.md然后在配置的索引文件里加一行指向它新技能就生效了。这个自定义能力让我觉得 Superpowers 真正好用的地方不是它自带的那几个技能而是它把“给模型定义工作方法”这件事变成了一种可以沉淀、可以复用的标准格式。你在某个任务上跑通的优秀流程完全可以固化成一个 skill下次遇到同类任务直接调用不用重新调教一遍模型。
Superpowers技能包实战：让Codex CLI从被动应答到主动工程化
上个月我把 Codex CLI 拉起来做一次模块重构模型对代码的理解速度确实快但整个过程给我的感觉就像一个特别聪明但完全没经历过正规团队的新人你让它改哪里它就改哪里改完也不知道跑一遍测试更不会主动去考虑边界情况。后来在 GitHub 上刷到 obra/superpowers 这个项目试了一下午整个使用体验发生了质的变化。Superpowers 并不是什么黑魔法它本质上是给 Codex CLI 装了一套可复用的“技能包”Skills让模型从“你问一句我答一句”变成“先规划、再动手、最后验证”的完整工作流。这篇文章就把我这一周多的真实使用过程、安装方式、核心技能拆解和踩坑记录完整写下来给正在用 Codex CLI 或者对 Agent Skills 机制感兴趣的朋友做个参考。1. 先搞清楚 superpowers 到底在解决什么问题1.1 Codex CLI 本身已经很强缺的是“方法论”Codex CLI 是 OpenAI 出的命令行编程助手它的本事不用我多说能读项目、能改文件、能直接执行命令模型对代码的理解能力非常在线。但如果你像我一样真拿去干活很快就会碰到一个微妙的问题模型知道怎么写代码但它不太知道“什么时候该用什么方法”。我给你描述一个典型场景。你把一个 bug 丢给它“这段解析配置的逻辑有 bug帮我修一下。”它看了一眼大概率直接给出一个修改后的函数然后告诉你“应该没问题了”。它不会先复现问题不会问你要输入样例不会补回归测试更不会去检查这个改动会不会影响其他调用方。换句话说它的代码能力是满格的但工程方法几乎是空的。这不是模型的智商问题而是任务表达方式的问题。Codex 默认的工作模式是“单次对话完成一个请求”你给它什么指令它就沿着最短路径给你结果。它没有内置的“先理解再动手”的流程约束除非你在提示词里写得明明白白。1.2 从 Claude Code 的 Skills 到 Codex 的 SuperpowersAgent Skills 这个概念最早在 Claude Code 生态里被大家熟悉。思路其实很朴素模型不是什么都该在上下文里塞着而是把某一类任务的“操作方法”打包成一个 skill里面包含步骤说明、模板、脚本甚至注意事项模型在需要的时候再去读对应的 SKILL.md 文件。Superpowers 就是把这一套借鉴到 Codex CLI 上的开源项目。GitHub 上可以找到作者维护了一套结构清晰的技能目录里面按照功能分成不同的 skill每个 skill 都是独立目录核心是一个SKILL.md文件外加一些参考模板和脚本。这和直接在系统提示词里写“你要先规划、再写测试、再实现”完全不是一回事。后者是一次性的指令模型读一遍就过去了执行着执行着就忘了而 skill 是一种“按需查阅的操作手册”它把流程固化下来让模型在处理特定类型任务时有一套可以随时回看的标准动作。1.3 一个反直觉的事实装完技能后 token 消耗反而更省说到按需查阅我猜很多人第一反应是配置文件里多挂几个技能说明每个请求不都要多读一堆东西吗那不是更费 token这也是我一开始的顾虑实际用了之后才发现恰恰相反。好的技能系统不会把全部技能文档塞进每次请求。它通常只会给模型一个极简的“技能索引”让模型知道“存在哪些技能、分别解决什么问题、去哪找详细文档”等到当前任务确实需要某一项技能时模型才会主动去把对应的 SKILL.md 完整读一遍。这个机制打一个不太恰当的比方一个修车师傅不会把所有工具都挂在身上出门他是需要拧螺丝的时候才回工具箱拿扳手。Superpowers 干的其实是给 Codex 配了一个工具箱而不是让它把整个工具箱背在身上。2. 安装前需要准备的环境与配置基线2.1 最基础的依赖Node.js 环境与 Codex CLI 本体在碰 Superpowers 之前你得先有一个能正常工作的 Codex CLI。这一步官方 README 写得很清楚我在这里只强调几个容易出问题的点。Codex CLI 的安装通常有两种方式一种是 npm 全局安装一种是 Homebrew 安装我自己的环境用的是 npm 的版本npm install -g openai/codex装完之后先验证版本确保命令能正常跑起来codex --version如果你是第一次用还需要完成登录授权。整个过程在终端里会有交互提示跟着走一遍就行。要注意的是Codex CLI 的配置目录默认在~/.codex/下面后面挂载 Superpowers 的时候要往这个目录里放东西所以心里先有个数。2.2 拿到 Superpowers 项目文件接下来就是把 Superpowers 项目本身拉下来。我建议直接 clone 到~/.codex/superpowers这个固定位置方便后续更新git clone https://github.com/obra/superpowers.git ~/.codex/superpowersclone 完成后项目目录结构大致是这样的我当时拉取的版本superpowers/ ├── _superpowers/ │ ├── personas/ │ │ ├── codex.md │ │ └── ... │ └── skills/ │ ├── brainstorming/ │ │ ├── SKILL.md │ │ └── ... │ ├── planning/ │ ├── tdd/ │ ├── debugging/ │ └── ...这里有个很容易忽略的细节技能文件都在_superpowers这个带下划线的目录下而不是仓库根目录下。很多人第一次配置时路径写错结果 Codex 根本找不到技能问题就出在漏了这一层目录。2.3 和我一样有洁癖的人用一个独立目录管理技能包如果你同时用 Codex CLI 和 Trae 这类 AI 编辑器想在不同工具之间共享同一套技能文件我建议不要往各自的目录里复制粘贴。复制一时爽更新火葬场——上游项目一更新你复制出来的那份就过时了而且你还不知道。我自己的做法是在~/.codex/下建一个skills目录用软链接把 Superpowers 里的技能指过来mkdir -p ~/.codex/skills ln -s ~/.codex/superpowers/_superpowers/skills/* ~/.codex/skills/这样做的核心好处是技能文件永远只有一份git pull更新之后所有引用它的工具自动拿到最新版本。后续你就算要自己写 skill也可以往这个目录里扔统一管理。3. 在 Codex CLI 中挂载 Superpowers两种实际可行的方案3.1 方案一通过 config.toml 的 instructions 字段引入Codex CLI 的配置文件是~/.codex/config.toml默认路径在用户目录下。安装完 Superpowers 之后你需要在这里把技能入口告诉 Codex。我当前使用的配置简化后大概是下面这个样子不同版本可能会有字段差异以你手头版本的官方 README 为准# ~/.codex/config.toml model gpt-5.1-codex instructions [ ~/.codex/superpowers/_superpowers/personas/codex.md, ~/.codex/superpowers/_superpowers/skills/brainstorming/SKILL.md, ~/.codex/superpowers/_superpowers/skills/planning/SKILL.md, ~/.codex/superpowers/_superpowers/skills/tdd/SKILL.md, ~/.codex/superpowers/_superpowers/skills/debugging/SKILL.md, ]这段配置的作用是每次启动 Codex 会话时把这些技能文件和人格文件作为基础指令加载进去。Codex 知道这些技能存在但并不会一口气把所有内容都读一遍而是在实际任务中遇到对应场景时才去完整读取单个SKILL.md的内容。如果你用的是 Codex 的较新版本官方有时会调整指令的加载方式比如把多个指令合并成一个总入口文件。遇到这种情况不用慌在项目里建一个AGENTS.md在文件里统一引用所有技能入口效果是一样的。3.2 方案二使用项目内的 AGENTS.md 引用方案一更适合个人全局配置但如果你是在一个团队项目里协同工作想让所有用 Codex 的队友都自动拥有这套技能我建议用第二种方式在项目根目录放一个AGENTS.md内容里直接指向 Superpowers 的入口文件。# 项目级指令 在执行任何任务前请参考以下技能文档 - 头脑风暴~/.codex/superpowers/_superpowers/skills/brainstorming/SKILL.md - 任务规划~/.codex/superpowers/_superpowers/skills/planning/SKILL.md - 测试驱动开发~/.codex/superpowers/_superpowers/skills/tdd/SKILL.md - 调试排查~/.codex/superpowers/_superpowers/skills/debugging/SKILL.md这种做法的优势是技能跟随项目走谁打开这个项目Codex 都能读到统一的规则不会因为某个人没配置全局环境而导致行为不一致。缺点也显而易见如果团队里有人没有在同样的路径下安装 Superpowers引用就会断掉。所以团队使用的话最好把 Superpowers 也固定到统一的目录约定里。3.3 在 Trae 这类 IDE 中安装 superpowers skill 的思路很多人不只用命令行版的 Codex还会在 Trae 这类 AI 编辑器里干活。通过“trae work cn 安装 superpowers skill”搜到这个项目的人多半是想在编辑器里也用上这套技能。Trae 这类 IDE 对技能skill的支持方式各不相同有的会自动扫描项目下的特定目录有的需要你在自定义规则里手动引用。我当时没有找到一键安装按钮最后用的是最朴素的思路让 IDE 能找到 SKILL.md 文件。一个比较通用的做法是在项目根目录下建一个规则目录具体目录名依 IDE 而定可能是.trae、.cursor或.rules之类然后把 Superpowers 的技能目录软链进去mkdir -p .trae ln -s ~/.codex/superpowers/_superpowers .trae/superpowers接着在 IDE 的规则文件里写一句话告诉模型“遇到对应场景时去读.trae/superpowers/skills/技能名/SKILL.md”。这个方法不能说百分之百适配所有版本但思路是通用的任何支持自定义规则的 AI 编程工具本质上都是通过文本指令让模型感知技能的存在你只要能把这个路径告诉它技能就挂上了。4. 核心技能逐个拆解这些“超能力”到底是怎么工作的4.1 Brainstorming动手之前先把思路摊开Brainstorming 是我实际使用频率最高的一个技能。它的核心价值在于当需求本身还模糊的时候不让模型急着给结论而是先输出多套候选方案再把每套方案的优劣、成本、风险摆出来。我给你一个直观的对比。没有装技能时你问“我想给项目加一个缓存层应该怎么做”它会直接甩给你一个 Redis 集成方案看起来挺专业但它根本没问你现在的架构是什么样的、qps 有多少、数据一致性要求多高。装上 Brainstorming 技能之后它的反应变成先列出三个大方向本地内存缓存、分布式缓存、数据库级缓存每个方向下面补充适用场景、接入成本、潜在问题最后还会反问你要不要基于当前代码库做进一步评估。这个东西本质上是在修正模型的“思维惯性”。模型本身没有“需求分析”这个概念你不告诉它它默认就是从最可能的答案开始。Skill 文档里如果明确写了“当一个请求的目标不明确时先进行多方案头脑风暴”它的行为就会明显改变。不过 Brainstorming 也需要注意节制。有些任务它就是很明确的比如“把这个函数的时间复杂度从 O(n^2) 优化到 O(n log n)”你还让它输出五个方案那就是浪费时间。好的技能文件本身会写清楚适用边界但人工判断还是要跟上。4.2 Planning把大任务拆成可验证的小步骤Planning 解决的则是另一个问题任务太大一步到位容易翻车。你让 Codex 直接“实现一个用户认证模块”它在一次回复里生成的代码量可能非常大中间一旦某个假设错了整段代码都白写。Planning 技能的工作方式是让模型在动手之前先产出一份实施计划。这份计划不是给你看的装饰品而是它后续执行的依据。计划里会包含任务拆解、前后依赖、每个步骤的完成标准以及最后如何验证整体效果。我实际观察到的行为变化很直观。没装技能时Codex 会直接把所有改动一次性铺开装完 Planning 之后它会先跟你说“我计划分三步第一步先建数据库表结构第二步写数据访问层第三步对接接口层。每一步完成后我会运行现有测试确认没有破坏再进入下一步。”然后它真的会按这个节奏来做完一步停一下确认没有问题再继续。这里的机制说起来也不复杂模型在生成了计划之后后续的每一步行动都会参照这个计划。计划相当于给模型一个“工作记忆”中的锚点让它不容易跑偏也让它更容易发现自己是不是漏掉了某个步骤。4.3 TDD先写测试再让实现通过测试TDD 技能是 Superpowers 里面工程价值最高的一个它对应的是“测试驱动开发”方法论。它的目标不是让模型多写几个测试用例而是改变模型的工作顺序先写测试再写实现最后跑测试验证。为什么这个顺序重要因为模型和人类一样如果先写实现它会倾向于认为自己的实现是“对的”然后为了自圆其说去写一些不痛不痒的测试。但如果先写测试测试就变成了一个固定的验收标准实现必须去满足这个标准。举个例子。我之前让 Codex 修一个日期解析的 bug没有 TDD 技能时它直接改了底层解析逻辑然后说“应该好了”。装了 TDD 技能之后它先问我“当前这个 bug 的复现输入是什么我先写一个会失败的测试用例。”然后它真的先把那个失败的测试写出来跑一遍确认红失败再开始改实现最后跑测试确认绿通过。这个“先红后绿”的过程逼着模型把注意力放在“什么行为才是正确的”上而不是“怎么尽快把当前报错消除”。对于任意一个做 AI 辅助开发的团队来说这一点都是最值得引入的。4.4 Debugging 与 Code Review 等其他技能除了上面三个Superpowers 里还有一组看着不起眼但非常实用的技能Debugging 就是其中之一。它给模型设定了一个系统化排查问题的流程而不是让模型凭感觉猜。比如代码报了一个线上异常没有 Debugging 技能时模型可能直接开始猜测原因“这个报错看起来像是编码问题我建议你检查一下文件编码。”而装备了 Debugging 技能后它会按照一个固定的排查链路走先要求提供完整的报错信息和堆栈再缩小问题范围到一个可复现的用例然后通过二分法定位到具体的代码提交最后才是提出修复方案。Code Review 技能也很值得说。它的核心作用是让 Codex 站在审查者视角重新读代码关注点集中在安全问题、边界条件、并发隐患、可维护性等方面。我经常在改完一个 PR 之后让它先过一遍自审发现问题的效率比自己盯着代码看高不少。除此之外还有生成规范 commit message、写解释文档等辅助性技能它们对日常体验的改善不是决定性的但很多个“舒服一点点”叠加起来体感差异就很明显了。5. 实战跑通一个例子用 Superpowers 重构一个遗留函数5.1 场景设定一个又长又臭的旧函数光说不练假把式我拿自己项目里一个真实场景演示一下。项目里有个老旧的parse_config函数大约一百多行干的事情太多它既要做字符串切割又要校验必填字段还要做类型转换最后还得处理各种异常情况。这个函数在多个服务里被调用改动风险非常高。如果按我以前的用法我会告诉 Codex“这个函数太长了帮我拆一下。”它大概率会直接甩一个重构后的版本出来里面可能拆成几个子函数看起来很规整但我根本不敢直接合进去——因为它没告诉我它动了哪些行为也没验证拆完之后的输出和原来是否一致。5.2 让 Codex 调用 Planning 技能后的输出这次我先在对话里明确说“请使用 Planning 技能处理这个重构任务。”然后 Codex 的输出路径完全变了。它没有直接给重构代码而是先要求我提供这个函数的所有输入样例和已知输出还去项目里搜索了所有调用点列出了一份调用关系清单。然后它给出一个计划先提取出分词逻辑保持原有输出格式不变再单独拆出字段校验逻辑所有校验错误仍然统一抛原始异常类型最后把类型转换部分抽成一个独立的映射函数每一步执行完运行原有测试集验证行为没有变化这里面的关键是计划不是走形式。它每拆完一步真的会停下来。我注意到它拆完分词逻辑后并没有立刻继续拆第二部分而是先运行了一遍测试确认通过才进入下一步。这种行为在没有技能之前我一次都没见过模型默认就是一次性把所有改动都做完因为那样看起来更“高效”。5.3 调用 TDD 技能后的行为变化重构到一半我意识到这个函数原来的测试覆盖其实很薄弱于是追加了一句“这部分请用 TDD 技能来处理。”接下来的一幕让我觉得确实值得写下来。它先看了一圈现有的测试文件发现只覆盖了正常路径然后主动补了几个失败用例一个是配置文件缺少必填字段的场景一个是类型转换传入了非法值的场景还有一个是输入为空的边界情况。然后它做了一件让我意外的事先把这几个测试跑了一遍确认它们确实失败了再把重构代码接上去让所有测试转为通过。整个过程它不是“先写实现再补测试来凑数”而是让富余的行为先被测试锁定再动实现。5.4 我的观察技能是“提示词模板”还是“行为契约”跑完这个例程我自己有一个强烈的感受技能不只是一个复杂的提示词模板它更像是一份“行为契约”。提示词模板的核心是“告诉模型你要什么”而技能的核心是“约束模型如何组织自己的行动序列”。单纯写一句“请你先规划再动手”模型可能在当前这一轮会话里遵守但到了下一轮它自己就忘了。而技能把流程拆成了可查阅的文档模型在执行过程中随时可以回读它的每一步行动都有了依据。这才是 Superpowers 和其他“大型提示词”之间最本质的区别。6. 我用了一周之后常见问题与避坑记录6.1 装了技能没生效多半是路径和大小写问题我刚开始配置时折腾最久的一个问题就是技能没生效。Codex 看起来正常启动但让它用 Planning 技能它完全没有任何反应。排查了一圈最后发现是路径大小写的问题superpowers的P在目录名里是大写我在配置文件里写成了小写。类 Unix 系统的路径是严格区分大小写的~/.codex/superpowers和~/.codex/Superpowers是两个完全不同的路径。如果你也遇到技能不生效的问题先别急着怀疑配置格式用下面的命令把路径实际输出一遍对比一下ls ~/.codex/superpowers/_superpowers/skills/planning/SKILL.md如果这个文件能正常列出来再去检查配置文件里引用的路径是不是和它一字不差。另外一个隐蔽的问题是波浪号展开。某些版本的配置解析器不会把~自动展开成用户目录这种情况下需要把绝对路径写全比如/Users/你的用户名/.codex/superpowers/...。6.2 技能文件太多导致上下文爆炸理论上按需加载机制会避免上下文爆炸但如果你不小心把所有技能文件全部塞进了instructions数组而不依赖索引机制那每个请求都会把这些内容全部载入上下文上下文占用会迅速上升。我自己刚配置的时候犯过这个错误我把skills目录下十几个技能的SKILL.md全部加进了配置结果使用起来明显变“笨”而且 token 消耗涨得很快。后来我意识到只需要挂载一个极简的索引文件就够了模型知道有哪些技能可用、去哪里找剩下的事情交给按需读取。这也是为什么我建议大家不要贪多。对绝大多数项目来说Brainstorming、Planning、TDD、Debugging 这四五个就够用了其他的用到再挂。6.3 不要把 Superpowers 当成“一键高手模式”我必须说句实话Superpowers 不是装完就能让你水平飞升的插件。它在实际工程里的价值上限取决于你的任务描述质量。技能能给模型提供工作流程的约束但它不理解你项目的隐性背景知识。比如 TDD 技能让它先写测试再实现但如果你的项目连一个测试框架都没搭好它就不知道该用什么去写测试这时候你得先把测试基础设施补齐。换句话说技能发挥效用的前提是项目的工程基础本身是完整的它更像一个放大器而不是一个从零到一的创造者。6.4 后续维护如何自己写一个最小 skill用了一周之后我最大的收获其实是“手痒”与其等着别人更新技能包不如自己写一个。Superpowers 的 skill 规范本身不复杂一个最小可用的 skill 只需要两样东西目录和SKILL.md文件。--- name: dependency-check description: 当需要评估一个第三方依赖是否应该引入时使用此技能。它会引导模型从维护状态、许可证、体积、安全记录等维度做评估。 --- # Dependency Check Skill 当你被要求评估/引入一个新的第三方依赖时按以下流程执行 1. 列出所有候选库 2. 对比维护活跃度、npm 周下载量、GitHub star 趋势 3. 查询已知安全漏洞 4. 评估依赖体积对打包产物的影响 5. 输出一个推荐结论和备选方案把这个目录放到~/.codex/superpowers/_superpowers/skills/dependency-check/SKILL.md然后在配置的索引文件里加一行指向它新技能就生效了。这个自定义能力让我觉得 Superpowers 真正好用的地方不是它自带的那几个技能而是它把“给模型定义工作方法”这件事变成了一种可以沉淀、可以复用的标准格式。你在某个任务上跑通的优秀流程完全可以固化成一个 skill下次遇到同类任务直接调用不用重新调教一遍模型。
