1. 什么是 superpowers一个被低估的 Codex 工作流扩展方案先直接回答最核心的问题superpowers 不是某个超级英雄游戏也不是 System Prompt 花活而是一套面向 Codex CLI 的技能库Skills与工作流增强方案。它通过注入结构化的指令集和方法论让 Codex 在终端环境里不只是“能生成代码”而是真正进入“拆解任务—规划步骤—执行验证”的完整节奏。如果你用过 Codex CLI 但觉得它写出的东西不够稳、遇到复杂任务容易虎头蛇尾那 superpowers 大概率是你缺的那一块。我的第一印象并不太好。项目名太“中二”README 里堆了一大堆概念乍看之下像又一个提示词工程玩具。但真正把它装进日常开发流程之后我才发现它解决的问题非常具体原生 Codex CLI 的上下文窗口和任务执行模式决定了它在“一次性生成一个完整模块”这件事上很强但在需要反复横跳、多文件联动、边改边验的工程场景里容易漏细节。superpowers 做的事情就是把这类工程方法论固化成技能文件SKILL.md让 Codex 在干活之前先走一遍拆解、调研、规划和验证的流程。这篇文章适合谁两类人。一类是已经在用 Codex CLI、但觉得生成结果不够“可维护”的人另一类是刚准备入坑 Codex CLI、想直接用一个相对成熟的配置模板起手的人。我会从安装开始把 superpowers 的目录结构、配置方式、核心技能逻辑和使用技巧全部过一遍最后聊几个我实际踩过的坑。整个流程基于 macOS / Linux 终端环境Windows 下用 WSL 同样适用。2. 安装与环境准备从零跑通 superpowers 需要哪几步2.1 前置条件CLI 工具链与 Node 环境superpowers 本体并不复杂但它的运行依赖 Codex CLI 的本地配置所以第一步永远是先把 Codex CLI 跑起来。我这里不再重复 Codex CLI 的注册和登录流程只强调几个和 superpowers 直接相关的环境要点系统需要能正常执行codex命令。安装方式通常是将 Codex CLI 的可执行文件放到 PATH 里或者通过 npm 全局安装某个兼容包。Node.js 版本建议 18 以上。superpowers 本身是一个纯提示词/技能文件体系但它配套的安装脚本和部分辅助工具是 Node 写的版本太老会出各种玄学问题。终端建议使用支持 ANSI 颜色和交互式选择的现代终端比如 iTerm2、Windows Terminal。这一点看似无所谓但 Codex CLI 的交互模式在很多老终端里会渲染错乱superpowers 的项目结构里也依赖一些可读性较强的输出格式换个终端往往能解决一半的“看起来不对劲”。装好 Codex CLI 并确认codex命令能正常交互之后再往下走。2.2 拉取 superpowers 项目并确认目录结构我自己习惯把它放在~/.codex目录下而不是项目目录里。原因后面会讲这里先按我的路径来。执行cd ~/.codex git clone https://github.com/Pimzino/codex-superpowers.git superpowers如果你和我一样记不住这个仓库地址直接在 GitHub 搜索codex-superpowers也能找到。克隆完成后先别急着装看清楚目录里有什么。一个典型的 superpowers 项目结构长这样superpowers/ ├── skills/ │ ├── codex-superpowers/ │ │ ├── SKILL.md │ │ └── scripts/ │ ├── ... ├── prompts/ │ └── ... ├── install.sh └── README.md这里面最核心的是skills目录。每个子目录代表一个技能Skill而每个技能里必然有一个SKILL.md文件它就是这个技能的“灵魂”定义了触发条件、执行步骤、输入输出格式以及相关的辅助脚本。Codex 在读取这些技能时会把SKILL.md当作系统提示词的一部分注入上下文从而改变它对任务的默认行为。2.3 执行安装脚本并验证注入是否成功接下来运行安装脚本cd superpowers bash install.sh安装脚本做的事情很简单把skills目录下的技能文件复制或链接到 Codex CLI 的配置目录通常是~/.codex/skills/同时把prompts里的内容合并到 Codex 的全局配置中。装完之后检查一下ls ~/.codex/skills/你应当能看到codex-superpowers或其它若干技能目录。如果空无一物多半是脚本里的路径写死了某个版本目录名和你本地解压后的目录名不一致手动把skills/*复制过去即可。这里有一个很容易踩的坑部分版本的 Codex CLI 对技能目录有严格命名限制目录名不能包含短横线以外的特殊字符而且技能目录下必须存在SKILL.md才能被识别。所以复制完之后用find ~/.codex/skills -name SKILL.md再确认一遍防止复制了一层多余的外层目录导致技能未被加载。3. 配置机制拆解Codex 到底是怎么“学会”这些技能的3.1 SKILL.md 的加载原理与目录约定很多人以为 superpowers 是给 Codex 施加了某种神秘魔法其实底层机制朴素得很。Codex CLI 在启动时会扫描特定的技能目录把每个SKILL.md文件内容嵌入到当前会话的上下文头部并附带一个“技能可用”的说明。也就是说它本质上是一套“动态系统提示词注入”。SKILL.md的典型结构通常包含几个部分技能名称与用途描述用来让 Codex 判断何时该调用它。详细的执行步骤例如“先读 README”“列出全部相关文件”“制定测试清单”。对输入输出格式的要求比如“每次修改前先输出 diff 预览”。可选的辅助脚本路径Codex 可以在需要时调用这些脚本来完成自动化操作。正因为加载机制是这样的你完全可以自己手写一个新的技能目录只要格式正确Codex 就会把它当成体系内的一等公民。也就是说superpowers 与其说是个成品不如说是一套设计良好的参考模板这也是它价值所在——你不需要照单全收完全可以裁剪成自己的风格。3.2 技能的激活条件与优先级陷阱实际使用中我发现技能的激活条件和优先级是最让人困惑的部分。Codex CLI 并不会每时每刻都把全部技能塞进上下文那样既浪费 token也会让指令自相矛盾。它通常的做法是根据用户输入和场景特征匹配若干技能作为“活跃技能”。活跃技能的SKILL.md内容被完整注入。如果多个技能同时对同一类任务给出指令以更具体、更靠近用户消息的那条为准。听起来合理但实际操作时有优先级陷阱。比如 superpowers 里有一个技能负责“通用任务拆解”另一个技能负责“重构现有代码”。当你提出“帮我把这段代码重构一下”时两个技能都可能被激活而重构技能如果写得不严谨很容易覆盖掉拆解技能的规划步骤导致 Codex 跳过调研直接动手改代码。解决办法是微调个人需求在自定义技能文件里加入“若任务涉及重构必须先执行拆解技能的步骤一、二”这类显式指令。3.3 配置文件合并策略不要把摊子铺太大superpowers 安装时带来的默认配置往往包含大量技能条目。我见过很多新手直接把全部配置启用结果 Codex 每条指令后都要犹豫很久回答风格也飘忽不定。我的建议是~/.codex/config.toml里只保留 2~4 个最核心的技能其它的等需要时手动指定。我自己长期启用的组合是通用任务拆解 代码审查 测试驱动。这三个技能覆盖了 80% 的开发场景而且互相之间很少冲突。其余的“写提交信息”“写文档”这类技能本质上只是几条提示词而已随时可以在用户消息里直接要求不值得常驻上下文。4. 核心技能实战用 superpowers 跑通一个完整开发任务4.1 场景选择从零实现一个本地工具函数库理论讲太多没用我直接用一个真实任务来演示操作流程。假设我要让 Codex 在空目录里实现一个 JavaScript 工具库包含数组去重、深拷贝、日期格式化三个函数同时要求编写单元测试和 README。如果用原生 Codex CLI它会直接给出文件结构和代码实现一气呵成但大概率只有主代码没有测试、没有异常处理文档。用 superpowers 的流程则是先触发“任务拆解”技能要求 Codex 输出子任务清单然后逐个执行。4.2 第一步显式要求使用技能并观察拆解结果在启用 superpowers 之后执行指令时最好明确带上技能名例如请使用 superpowers 工作流实现一个 JavaScript 工具库包含数组去重、深拷贝、日期格式化并配套测试与 README。Codex 输出的第一步通常不是代码而是一个规划块。它会写出明确交付物清单。需要创建的文件列表。每个文件的技术要点。测试策略。完成定义Definition of Done。如果你发现它直接开始写代码说明技能没有被激活。此时可以手动要求“先输出任务拆解计划再开始编写”这有助于确认是配置问题还是上下文注入问题。另一个技巧是将SKILL.md里的步骤简述直接粘在指令末尾强迫 Codex 按你的步骤来。4.3 第二步让 Codex 读取已有文件后再动手superpowers 的另一个实用价值是它会把“代码现状调研”固化为强制步骤。在生成计划之后你可以问一句读取当前目录文件结构基于实际情况细化上述计划。这个指令在原生 Codex 里通常被忽略但在 superpowers 的技能约束下Codex 会认真列出目录树标注哪些文件已存在、哪些逻辑可以复用。这一点对已有项目特别重要——它能有效降低“覆盖式重写”的风险。空目录场景下没什么好调研的但这个过程的价值在于建立习惯。当你在真实项目里使用时Codex 会主动读取package.json、tsconfig.json等等然后给出针对性方案。我用下来最大的感受就是生成代码前先读文件这句话说起来容易但没有技能约束时 Codex 就是做不到或者做得很敷衍。4.4 第三步分步确认并逐文件落地我习惯在计划确认后分三步要求 Codex 交付先写核心实现文件如src/index.js输出代码时附带简短的实现说明。再写测试文件运行测试并修正失败用例。最后写 README并总结函数 API。每一步之间我都会快速 review 代码如果有异议就当场指出。superpowers 的技能体系并不会让 Codex 变得“完美”但会让每次输出都有足够的上下文支撑减少那种“上下文断裂导致的瞎编”。尤其在进行第三步时Codex 能正确引用前两步里的具体函数名和行为约定这在原生模式下经常翻车。4.5 验证与收尾测试、lint、提交信息一体化任务收尾阶段superpowers 通常包含“代码审查”和“提交信息生成”技能。代码审查技能会要求 Codex 以挑刺视角检查自己生成的代码列出潜在问题。我按照建议把数组去重函数里的NaN处理、深拷贝里的循环引用处理都补上了明显比第一版严谨得多。最后生成 commit message 时技能会自动按 Conventional Commits 格式输出省了我手动整理的时间。整个流程走完不是比原生快而是质量上限提高了。5. 进阶玩法自定义技能与多技能协同的取舍5.1 编写一个属于自己的 SKILL.mdsuperpowers 最大的可玩性是可以自己造技能。别被 “SKILL.md 一定很复杂” 吓到一个最小可用技能文档其实就几十行。一个典型的示例--- name: frontend-refactor description: 适用于前端组件重构场景的专用工作流 --- 当用户要求重构前端组件时必须遵循以下步骤 1. 先读取目标组件及其依赖文件。 2. 列出组件当前的 props、state、副作用逻辑。 3. 输出重构计划草案等待用户确认。 4. 重构时保持公共 API 不变除非用户明确允许破坏性变更。 5. 修改完成后列出所有受影响文件及潜在回归风险。把它放到~/.codex/skills/frontend-refactor/SKILL.md重启 Codex 会话即可在需要时通过关键词“重构前端组件”激活。这里有个细节description字段里的措辞直接影响技能匹配率尽量使用任务描述性词汇而非抽象命名。5.2 技能之间的冲突、引用与合并策略当你同时使用多个技能时一是要注意冲突二是可以利用“引用机制”来组合技能。superpowers 的不少技能在其SKILL.md里直接写明“本技能应在‘任务拆解’技能完成后执行”这便在技能层面形成顺序依赖。一个实践经验把最小可用技能集当作“默认集合”把专案技能当作“临时注入”。日常开发只开默认集合在切换项目类型或面对特殊任务时临时在~/.codex/skills下新增一个专用技能目录用完即删。这样既不会污染全局上下文又能保留 skill 机制的灵活性。5.3 从 superpowers 迁移到自己的技能仓库用熟悉之后你会发现自己真正依赖的其实就那么几个技能。这时候就可以脱离 superpowers 项目目录把核心技能提取到自己的配置仓库用 dotfiles 管理。我个人的组织方式是dotfiles/ └── codex/ ├── config.toml └── skills/ ├── task-decomposition/ ├── code-review/ └── tdd/ └── SKILL.md这样做的意义有两个一是版本可控每次改动都能走 Git 记录二是去中心化不再依赖某个上游仓库的更新节奏。毕竟 superpowers 本身迭代也很快上游参考价值很高但生产环境不该绑死在上游的变更上。6. 避坑记录我在使用过程中遇到的 5 个典型问题6.1 “技能不生效”问题往往出在会话缓存最常见的问题是技能明明配置了但 Codex 没有反应。排查链路如下先确认配置文件里是否启用了skills相关设置。有些 Codex CLI 版本默认不加载任何技能目录需要在config.toml里显式声明。然后确认是否是新会话。技能注入发生在会话创建时如果你在已有会话里修改了技能文件继续对话是无效的必须开新会话。最后看SKILL.md路径是否拼写正确。技能目录大小写敏感Skills和skills在 Linux 下是两个东西。如果以上都对还有一个隐蔽问题部分 Codex CLI 在交互模式下会在用户消息前带上“使用可用的技能”之类的指令但如果你自定义了 system prompt 中其他长段内容会把技能占用空间挤掉。检查一下自己的全局 system prompt是否过长、是否包含与技能冲突的指令。6.2 “回答风格突变”小心技能目录里的旧文件有一次我发现 Codex 突然变得极其啰嗦每条指令都输出大段计划实际代码写得反而少了。查了半天原来是我之前测试用的一个旧技能目录没删而且它在加载顺序上排在官方技能之前把输出格式指令覆盖了。这种问题非常隐蔽因为技能目录里的文件一多你根本记不住每个文件里写了什么。我的解决方案是给技能目录做了严格命名规范——加了zz-前缀作为低优先级技能把最常见的核心技能统一命名为aa-开头。利用字典序控制加载顺序比依赖配置项的优先级更直观。6.3 “总是先写代码再列计划”改技能不如改提问方式如果你遇到的是 Codex 表现得“完全没学过技能”除了检查系统配置也要关注提问方式。技能匹配描述毕竟是文本匹配描述里写的是“重构现有代码”你却说“这段代码太烂帮我改改”激活率自然低。更可靠的提问方式是直接带技能名使用 frontend-refactor 技能处理下列需求。这相当于手工指定加载绕过了匹配环节。6.4 “技能响应太慢”控制单技能文档长度和使用频率superpowers 的部分技能文档非常长动辄上千行。Codex 每次激活都要把整份文档塞进上下文既费 token 又降低响应速度。如果你用下来感觉变慢了仔细审视技能文档里有多少真正有价值的指令。很多时候几百行的文档里真正的约束可能只有二十行其余全是解释说明、示例。这些示例不是没用但放在技能里会让每次调用都背负沉重的上下文。最优解是把技能文档拆成“精简版指令 外部参考文件”--- name: example-skill --- 执行步骤见文件 ./procedure.md本技能只负责分发指令。这样既保证了上下文精简又保留了完整说明文档供 Codex 在需要时读取。6.5 “自己在技能里写的规则不生效”注意用户指令优先级最后一点也是最重要的一点技能文件本质上还是提示词它的优先级不是绝对的。用户在当前消息里的明确指令、最靠近上下文的指令往往有更高权重。所以你在技能里写“每次修改前必须输出 diff 预览”但用户在消息里说“直接改吧不用给我看”用户的指令会压过技能文档。理解了这一点就不会对技能体系的边界产生误解——它是个“默认习惯强化器”不是“铁律”。7. 我最终保留的 superpowers 配置和生产建议经过大半个月的使用和无数次微调我最终保留的配置如下常驻启用任务拆解、代码审查、测试驱动这三个技能临时启用过 TypeScript 类型梳理、API 文档生成等技能用完后立刻移除不再依赖 superpowers 仓库里的全部技能而是从里面提取了对我真正有价值的部分搬进了自己的 dotfiles。如果你也想用我的建议是不要照搬任何一套配置。第一次安装 superpowers 后花半小时逐篇阅读技能文档把里面最符合你工作习惯的内容留下其余的全部关掉。技能文档不是配置越全越好它更像一份“团队规范”——只有真正被执行的那几条才是有意义的规则。就我个人的实际体验来说superpowers 最大的贡献不是让 Codex 变聪明而是让 Codex 的输出风格和我的工作习惯对齐了。它在“指令注入”这个层面解决了很多原生模式下的“上下文断裂”问题。用一句可能有点夸张的话概括它让人感觉你面对的不是一台概率机器而是一个默认按你偏好做事的同事。至于这个同事偶尔还需要你纠正那本来就是工程日常的一部分。
