在实际项目里使用 Codex 或 Claude Code最常见的感受是单点问题它能解决得很快但一旦任务是“给用户中心模块补测试”“把这个接口从 REST 改成 GraphQL”“线上偶发报错到底出在哪一层”模型就容易跳步骤。它写出来的代码可能能跑却没有先确认需求边界没有写验证用例也没有留下可回滚的步骤。obra/superpowers这类项目解决的就是这个问题它把 AI 编程助手从“单轮问答”改造成“按 skill 工作”的工程助手。下面从 skill 机制开始讲清楚怎么在 Codex 里安装 superpowers、安装后目录是什么样子、怎么验证是否生效以及常见问题上哪儿排查。1. 先理解 superpowers 是什么Skill 不是一段提示词1.1 AI Agent 缺少的不是模型能力而是工作流程给一个模型输入“帮我改一下这个函数”它能做得不错。但改成“帮我重构这个模块并保证现有测试不挂”它可能直接开始改代码而不是先问清楚现有测试在哪、要不要保持兼容、哪些调用方需要同步修改。原因不是模型变笨了而是 Agent 的默认行为缺少流程约束。superpowers 的核心思路是把工程中常用但又容易跳过的步骤固化成 skill。每个 skill 是一套可复用的工作流例如“先输出计划再写代码”“用最小复现用例排查 bug”“提交前检查变更范围”。当模型判断当前任务匹配某个 skill 时就不再自由发挥而是按 skill 里的步骤执行。这种设计不是为了限制模型而是为了减少上下文丢失和幻觉。真实开发中一个优秀工程师接到复杂任务也会先拆分步骤再逐步验证。Skill 就是把这套方法论变成模型可以读取的指令。1.2 Skill 的文件机制SKILL.md 是入口当前主流的 AI 编码 Agent 里skill 通常以目录形式存在目录入口文件固定命名为SKILL.md。这个文件不是普通 Markdown它需要包含两部分YAML frontmatter描述 skill 的名称、适用场景和触发条件。Markdown 正文说明具体执行步骤、输入要求、输出格式和验收标准。模型在对话中会先扫描技能描述再决定要不要调用。因此description写得是否清晰直接决定 skill 会不会被触发。一个最小示例是这样--- name: plan-first description: 在非平凡编码任务开始前先输出可执行计划并拆解为可检查的小步骤。 --- ## 执行步骤 1. 读取需求列出涉及的文件和接口。 2. 识别风险点确认测试策略。 3. 输出计划等待用户确认后开始编码。可以这样理解没有 skill 时Agent 靠模型直觉做事有 skill 时Agent 靠文件里的标准流程做事。superpowers 的价值就是把一批流程提前写好让你不用从零设计。1.3 superpowers 预设了哪几类能力obra/superpowers不是一个单一功能而是一组能力的集合。社区版本里通常包含以下方向能力分组典型职责最合适的触发场景计划类把需求拆解为任务先出方案再动手多文件改动、接口变更、架构调整编码类按已有代码风格写出可维护代码模块开发、重构、迁移调试类从日志和测试出发定位根因测试失败、偶发 bug、回归问题测试类补单元测试和边界测试新函数、公共接口、工具方法提交类检查变更范围、生成提交说明提交前、PR 前记忆类跨会话保存关键结论和决策长期项目、多轮开发这里特别值得关注的是“子代理”能力。superpowers 的某些流程会让主 Agent 先制定计划再生成多个子代理并行执行不同任务。每个子代理只负责一个模块有自己的上下文避免主上下文被无关代码塞满。这种设计对于仓库级重构非常有用。2. 安装前准备先把运行环境对齐2.1 需要准备哪些工具安装 superpowers 主要依赖 Bun 和 Codex CLI。如果你只使用 Claude Code也需要对应的 CLI。工具作用建议Bun运行 superpowers 的 CLI 安装脚本保持较新版本Node.jsCodex CLI 的运行环境保持 LTS 版本Codex CLI承载 skill 的 AI 编程助手升级到支持 SKILL.md 的版本Claude Code CLI可选另一类 Agent 环境按需安装Git版本管理查看变更常规开发环境必备不需要提前安装 Python、Go 或其他语言运行时除非你打算在 skill 的脚本里调用它们。2.2 安装前先执行一次环境检查打开终端执行下面命令node --version bun --version codex --version git --version如果bun不存在macOS 和 Linux 上常见安装方式如下具体以 Bun 官网当前文档为准curl -fsSL https://bun.sh/install | bash source ~/.bashrc bun --version如果codex不存在可以尝试通过 npm 全局安装npm install -g openai/codex codex --version安装完成后不要急着执行后续命令。先确认所有命令都能返回版本号否则后面即使安装成功也会因为某个命令不存在而中断。2.3 确认 Codex 是否支持 SKILL.mdsuperpowers 的工作依赖 Codex 对 skill 目录的扫描能力。如果你的 Codex 版本太旧不支持SKILL.md约定那么文件装进去也不会被模型读取。验证方式有两个运行codex --help查看是否出现skill相关字样。查看用户目录下是否有~/.codex/并确认是否存在约定目录。注意Skill 的生效依赖 CLI 对 SKILL.md 的扫描机制。不是把文件放在某个目录就能保证被调用需要先确认当前 Codex 版本支持这种格式。如果当前版本不支持先升级 Codex CLI再继续安装。3. 把 obra/superpowers 安装到 Codex3.1 先用 bunx 拉取 CLIobra/superpowers的安装入口通常以 npm 包形式发布社区常见用法是通过bunx直接执行不需要手动 clone 仓库也不需要全局安装。先查看帮助bunx superpowerslatest --help如果网络正常这个命令会拉取最新发布包并输出 CLI 支持的子命令。此时重点看两项子命令是install还是init。是否支持--codex这类目标 Agent 参数。不同版本的 CLI 命令可能存在差异第一次使用时务必先看帮助不要凭记忆直接拼命令。3.2 执行安装并指定 Codex以支持--codex参数的版本为例可以执行bunx superpowerslatest install --codex如果 CLI 不支持参数而是交互式提问就选择Codex选项。安装过程会做三件主要事情创建 skill 目录。从包内复制预设的SKILL.md、脚本和模板。根据当前环境生成必要配置。安装完成后常见的目录结果是~/.codex/skills/ superpowers/ SKILL.md skills/ 01-plan/ SKILL.md scripts/ 02-code/ SKILL.md rules/ 03-test/ SKILL.md scripts/如果安装脚本选择项目级安装则可能出现在.codex/skills/下。你关心的不是路径是否完全一致而是最终是否能看到一批SKILL.md文件。注意安装脚本能创造目录不能代替你检查 Agent 的调用结果。任何 skill 都要用真实任务验证。3.3 安装后是否需要手动配置在大多数情况下superpowers 安装后就完成了配置不需要你再手动编辑配置文件。你可以直接启动 Codex 开始测试。但有两个场景需要手动调整你希望某些 skill 不被使用可以按官方文档的说明禁用。你希望把 skill 放到项目级目录让团队所有成员共享可以把目录复制到.codex/skills/并提交到 Git。不建议在没搞清目录结构之前乱改配置。先跑通最小流程再做个性化定制。4. 读懂 superpowers 的 Skill 包结构和执行流程4.1 一个 Skill 包的最小文件结构无论 superpowers 内置了多少个 skill单个 skill 的基本结构都类似my-skill/ SKILL.md scripts/ verify.sh rules/ coding-standards.md templates/ plan.md各文件的工作划分SKILL.md模型入口负责触发和流程控制。scripts/可执行脚本模型在合适时机调用比如运行测试、生成模板。rules/补充约束比如代码风格、禁止使用某种 API。templates/输出模板比如计划文档、提交说明。这种结构把“提示词”和“可执行逻辑”分开。模型不需要把所有内容放在对话里它可以在需要时读取对应文件或执行对应脚本。4.2 SKILL.md 的 frontmatter 为什么是触发关键Codex 或其他 Agent 在判断是否使用某个 skill 时主要看 frontmatter 中的description。如果描述太抽象模型可能不调用如果描述太宽泛模型可能滥用。一个信息量足够的描述是这样的--- name: debug-with-tests description: 当测试失败或 bug 复现困难时先写最小复现用例再定位根因。 when_to_use: 测试失败、偶现 bug、回归问题、线上异常日志无法直接定位 ---执行正文则可以这样写## 执行步骤 1. 阅读失败信息记录完整输入输出。 2. 创建一个最小可复现脚本或测试用例。 3. 运行失败用例确认能稳定复现。 4. 用日志和二分排除法定位根因。 5. 修复后运行完整用例确认通过。 ## 验收条件 - 至少有一个失败用例变为通过。 - 没有为了快速通过而删改断言。这个示例的核心价值在于“验收条件”。模型执行完步骤后需要自己检查是否满足验收条件而不是写一段代码就说完成。4.3 模型调用 skill 的完整流程了解了文件结构再看调用流程用户提出任务模型先理解任务语义。模型扫描可用 skill 的description。如果任务匹配某个 skill模型读取对应的SKILL.md。模型按SKILL.md的步骤执行需要时运行scripts/下的命令。模型按验收条件检查结果并输出最终总结。这也是为什么安装 superpowers 后第一次使用可能和普通 Codex 表现不同。模型不再直接给最终代码而是先输出计划、步骤和验收方式。4.4 子代理是怎么工作的superpowers 的复杂流程里会使用子代理来分摊任务。以“重构用户中心模块”为例主 Agent 先拆解模块。一个子代理负责接口层重构。一个子代理负责数据层改动。一个子代理负责测试补充。每个子代理只读取自己关心的文件减少主上下文被无关代码塞满的情况。子代理执行完成后主 Agent 汇总结果再统一提交。这种做法的优点是并行度高缺点是如果拆分不合理子代理之间可能出现接口不一致。因此在生产项目中使用时建议先从两个子代理开始不要一上来就开十几个并行任务。5. 在 Codex 中验证 superpowers 是否生效5.1 准备一个最小任务安装完成后不要直接问“你会不会 superpowers”要给它一个真实但可控的任务。下面是一个简单函数缺少边界测试export function resolveDiscount(price, level) { if (price 0) throw new Error(price must be non-negative); if (level vip) return price * 0.8; if (level normal) return price * 0.9; return price; }然后在 Codex 会话中明确要求用 superpowers 的测试工作流为 resolveDiscount 补充边界测试。这里的关键是“明确声明”。因为触发 skill 需要模型自己判断第一次验证时最好把 skill 名称带出来。5.2 启动 Codex 并观察输出进入项目目录启动 Codexcd /path/to/project codex如果 CLI 支持直接执行命令也可以尝试codex exec 用 superpowers 的测试工作流为 resolveDiscount 补充边界测试重点观察三件事模型是否先输出计划而不是直接贴代码。模型是否提到了“测试”“边界”“补丁”等步骤。模型是否在最后运行了测试命令。如果模型完全没提计划直接给出代码说明 skill 没有被加载或没有被触发。5.3 检查 skill 文件确实存在如果任务没有被触发先确认文件在不在ls -la ~/.codex/skills/superpowers find ~/.codex/skills -name SKILL.md | head -20如果目录为空说明安装过程没有把预设文件复制成功需要重新安装。如果文件存在但模型不调用多半是description不匹配或 Codex 版本不支持 skill 扫描。5.4 明确唤醒 superpowers 的方法在调试阶段可以强制指定 skill。例如请调用 debug-with-tests skill 来处理当前测试失败。如果这样能触发而自然描述不能触发说明你要么改一下description的触发条件要么在对话中保持更明确的需求描述。6. 常见安装问题和排查路径6.1 bun 或 bunx 命令找不到现象bun: command not found可能原因Bun 安装完成后没有把安装目录加入PATH或者当前终端没有重新加载配置文件。检查方式which bun echo $PATH处理建议重新执行source ~/.bashrc或source ~/.zshrc然后重新打开终端。如果使用 Windows建议在 WSL 中安装。6.2 bunx 拉取包时超时现象error: Could not find package superpowers ...可能原因网络环境无法访问默认 npm registry或者临时网络波动。检查方式npm config get registry处理建议先重试一次。如果仍失败确认本机的 npm registry 配置是否符合当前网络要求。不要绕过合规限制只做正常开发环境配置。6.3 安装成功但 Codex 不识别 skill现象目录里有SKILL.md但模型没有任何反应。可能原因Codex 版本不支持 SKILL.md。目录路径不在 Codex 扫描范围内。文件名大小写不正确。检查方式codex --help | grep -i skill find ~/.codex -name SKILL.md处理建议确认SKILL.md文件名完全一致不要把后缀写成.md以外的格式。升级 Codex 后重启会话。6.4 frontmatter 写错导致解析失败现象模型报出 skill 不存在或读取 skill 时报 YAML 解析错误。可能原因name或description缺失YAML 缩进错误冒号后面没加空格。检查方式python -c import yaml,sys; yaml.safe_load(open(sys.argv[1])) ~/.codex/skills/superpowers/SKILL.md处理建议修复 YAML 语法保持字段对齐。frontmatter 必须放在文件最顶部前面不要有空行或其他内容。6.5 子代理执行太慢或被限流现象启用 superpowers 并行流程后任务长时间没有回包或中途报 API 限流错误。可能原因拆分的子代理太多每个子代理都在消耗上下文和 API 调用额度。处理建议减少子代理数量把一个大任务拆成两三个小任务。也可以先关闭 superpowers 的并行流程只使用单 skill 工作流。下表汇总了典型问题问题现象可能原因检查方式处理建议bun 命令不存在安装后未刷新环境变量which bun重新 source 终端配置安装命令拉取失败registry 不可达或网络波动npm config get registry重试或修正 registryCodex 不识别 skill版本过旧codex --help升级 Codex模型不调用 skilldescription 不匹配查看 SKILL.md明确唤醒或优化描述并行任务卡死子代理过多查看 API 日志降低并行数量7. 最佳实践把 superpowers 从“插件”用成“团队规范”7.1 学习环境和生产环境要拉开差距个人学习环境可以随便测试各种 superpowers 默认 skill但进入生产项目后需要额外考虑下面几项维度学习环境生产环境安装位置用户级目录即可建议项目级目录并纳入 Git自动执行可以允许脚本自动运行限制模型直接执行高风险命令测试验证只验证能跑通必须验证通过全部相关测试文档不需要团队 README 写明触发方式回滚不需要skill 文件和配置要能回滚7.2 新项目启用 superpowers 前的检查清单在正式使用前按这个清单过一遍[ ] Codex CLI 已升级到支持 skill 的版本。[ ]bunx superpowerslatest --help能正常输出。[ ]~/.codex/skills/superpowers目录存在。[ ] 至少用一个小任务验证 skill 被触发。[ ] 确认模型不会在没有用户确认的情况下执行破坏性命令。[ ] 把自定义 skill 文件提交到 Git避免只存在本机。[ ] 在团队文档里写清楚什么任务应该明确加上 superpowers skill 名称。这份清单同样适用于 Claude Code。核心不是“安装成功”而是“模型能按流程执行并验证结果”。7.3 不要过度依赖预设 skillsuperpowers 默认流程适合复杂任务但并不是所有问题都需要走完整流程。比如一个简单的变量命名调整让模型先写计划再等确认反而浪费时间。建议在你的自定义 SKILL.md 中把when_to_use写清楚。只有满足条件时才触发。这样模型可以保持轻量也能在复杂任务到来时切换成严谨模式。7.4 后续可以扩展哪些方向把公司内部代码规范做成rules/文件让模型在编码前自动读取。把常用脚手架命令封装成scripts/让 skill 不只会说还会执行。把项目历史决策写入记忆类 skill跨会话保留上下文。在 CI 里跑一遍由 skill 生成的测试确保模型输出不破坏已有功能。随着使用的深入superpowers 会从工具集演变成团队开发的“默认工作方式”。这也是它更适合用于真实项目的原因它不是在对话里多几段话术而是让 Agent 按一套可复用、可审查、可回滚的流程工作。8. 最后给新手的练习路线如果这是你第一次接触 superpowers不要急着把所有 skill 都跑一遍。建议按下面路线练习。第一步先跑通 Codex 安装并执行一次“测试工作流”验证。这一步能确认环境、目录和 CLI 版本都没有问题。第二步找一个自己项目里的低风险任务例如“给工具函数补边界测试”观察模型是否先输出计划再写代码再运行测试。第三步读懂一个内置 SKILL.md尝试修改它的描述和验收条件让流程更贴合自己的项目。第四步再尝试子代理并行流程观察它如何拆解任务、如何汇总结果、在哪些场景下会报错。最后当你能熟练修改 SKILL.md 时再把团队规范沉淀成自定义 skill。此时你得到的不是某个插件的使用经验而是一套能让 AI 编程助手真正参与工程交付的方法。