先从一个真实的使用场景说起我刚开始用 Codex CLI 的时候总觉得它像个聪明但毛躁的实习生问它“这个报错怎么回事”它能答得头头是道但让它“帮我把这个模块重构一下”它就容易一头扎进代码里改到一半才发现需求理解有偏差。后来我在 GitHub 上刷到 superpowers 这个项目思路非常直接不给模型硬塞知识而是给它一套可执行的“技能包”让它像有经验的工程师一样按步骤把一件事从头到尾做完。这篇文章就围绕 superpowers 的实际使用聊聊它到底是什么、怎么装进 Codex CLI、在真实开发里怎么用以及我踩过的几个坑。如果你正在折腾 Codex CLI 或者类似的 AI 编程 agent这篇应该能帮你省不少时间。1. superpowers 到底是什么从“问一句答一句”到“按流程干活”1.1 一句话讲清楚它是“技能的技能”superpowers 不是一个普通插件也不是某个单独的提示词而是一套以SKILL.md为核心结构的技能集合。每个技能都是独立的目录里面有说明文件、示例模板和可执行脚本目的是让 Codex CLI 这类 agent 工具在接下任务时能够主动调用对应技能按照一套编好的工作流去行动。我举个容易理解的类比普通提示词就像你给新同事口头交代一句“这个 bug 你查一下”他可能凭感觉去查而 superpowers 里的技能就像把公司里“资深工程师排查 bug 的完整方法论”写成了标准作业手册里面规定了要先看什么、要验证哪些假设、改完代码之后要跑哪些回归测试。新同事拿到手册哪怕没经验也能按步骤走出靠谱的结果。1.2 为什么叫 superpowers把“经验”变成“装备”项目取名 superpowers意思是给 AI 助手“加技能点”。里面内置了一批实用技能我实际用过并觉得比较核心的有这几个brainstorming需求不明确时先引导模型列出问题、边界条件和候选方案planning把大任务拆成可执行的步骤输出清晰的实施计划debugging按照“收集信息 → 建立假设 → 小步验证 → 修复 → 回归”的顺序处理 bugcode review带着检查清单去审查代码关注安全性、可读性、边界条件和测试覆盖writing tests根据模块行为生成测试用例而不是简单补几行覆盖率。这些技能不是让人一次全用上而是让模型根据任务性质自动选择合适的流程。正因为每个技能都封装了一套工作方法论使用它的感觉就像给终端里的 AI 助手装了“职业模块”从“知道很多”变成“知道在什么场景下该怎么做”。1.3 哪些场景适合引入 superpowers从我个人的使用体验来看它最适合以下三类场景一类是需求模糊的功能开发。比如老板丢过来一句“做个用户通知功能”普通 AI 可能会直接开写接口而 superpowers 的 brainstorming 技能会先逼着模型列出问题、假设和边界再进入计划阶段最终产出的是“开发方案”而不是一团代码。二类是 bug 定位和修复。尤其是那些复现路径不明确、日志信息混乱的问题普通对话常常会停在“可能是这里有问题”的猜测阶段而有 debugging 技能在手Codex 会被要求一步一步验证假设而不是拿着一个猜测去改代码。三类是代码审查和重构。它会按检查清单逐项过不会因为只盯着某个功能点就漏掉安全性和异常处理。一句话总结如果你的使用方式还停留在“问一句、答一句”superpowers 的作用不明显一旦你希望 AI 真正“负责一件事”它就变得非常值得装。2. 安装前的准备先摸清 Codex CLI 的技能机制2.1 Codex CLI 如何识别 skillAGENTS.md 是总入口想顺利安装 superpowers首先要理解 Codex CLI 的 skill 机制。Codex 读取技能目录时会扫描~/.codex/skills这种全局目录以及项目下的.codex/skills局部目录。每个技能都必须是一个独立文件夹里面含有一份SKILL.md文件头部通常带有 YAML 格式的元信息比如技能名称、适用场景、触发条件等。而AGENTS.md是模型的行为总入口。它告诉 Codex CLI 当前工作环境里有哪些可用的技能、每个技能大致负责什么、什么情况下调用哪个技能。简单说AGENTS.md相当于技能的总目录和调用规则表SKILL.md是每个技能的详细手册两者缺一不可。我第一次安装时犯过一个低级错误只把技能目录复制到了~/.codex/skills却忘了更新AGENTS.md结果 Codex 完全没有感知到这些技能接待任务时还是老一套行为。所以安装时一定要把“目录 注册”两步都做完。2.2 准备环境Node、Git 与 Codex 版本superpowers 里的不少技能依赖本地脚本比如处理文本、搜索代码、统计测试结果等通常需要 Node.js 环境。我自己用的是 Node.js 20 LTS日常跑下来没有遇到兼容问题。如果你还没装 Node建议直接用 nvm 装 LTS 版本避免权限和路径问题。Git 是基本的因为安装过程需要 clone 仓库。Codex CLI 本身也需要更新到较新版本越新的版本对 skill 目录的扫描越稳定。我在升级前一度遇到过“技能偶尔生效、偶尔不生效”的问题升级之后就好了。2.3 目录结构设计全局技能与项目技能怎么选superpowers 的技能可以放在两个位置各有各的考量全局位置~/.codex/skills/适合装通用技能比如 code review、debugging。好处是任何项目都能用不占用项目仓库体积缺点是所有项目共享同一套技能不同团队如果要求不同会显得不够灵活。项目位置.codex/skills/适合放团队专属技能比如“本项目发布前必须跑哪些检查”“数据库迁移必须经过哪两级审批”。这类技能跟着仓库走团队成员 clone 下来就能用。我的建议是第一周先用全局位置跑通流程后再把真正沉淀下来的团队规则放到项目位置。别一上来就搞得很复杂否则排查问题时变量太多。3. 实操记录两种方式把 superpowers 装进 Codex CLI3.1 方式一手动 clone 复制5 分钟内完成我采取过的比较稳妥的方式是手动安装因为每台机器的环境不一样自动脚本不一定能覆盖所有情况。操作步骤大致如下# 1. 克隆仓库到本地临时目录 gh repo clone repo-owner/superpowers ~/superpowers-src # 如果你不习惯 GitHub CLI也可以直接用 git clone 仓库地址 # 2. 查看仓库结构找到 skills 目录 ls ~/superpowers-src # 3. 复制技能到 Codex CLI 的全局技能目录 mkdir -p ~/.codex/skills cp -r ~/superpowers-src/skills/* ~/.codex/skills/ # 4. 查看复制后的目录 ls ~/.codex/skills复制完成后还要检查~/.codex/AGENTS.md是否存在。如果不存在就手动建一个并在里面类似这样写# Codex 使用说明 本环境已安装 superpowers 技能集包含以下技能 - brainstorming需求分析、方案设计阶段使用 - planning任务拆解和排期阶段使用 - debugging定位和修复 bug 时使用 - code review代码审查时使用 - writing-tests编写测试用例时使用 当任务涉及以上场景时请主动读取对应技能目录下的 SKILL.md按其中的步骤执行。保存之后重新打开 Codex CLI 会话让它读取新的配置。注意某些版本可能需要完全退出终端再重开只开新会话不一定能加载新配置。3.2 方式二使用仓库自带的安装脚本有些版本的 superpowers 仓库会提供自动安装脚本目的是省去手动复制和注册的繁琐步骤。使用前先看一眼 README确认它是否支持 Codex CLI以及具体命令是什么。我见过类似这样的形式cd ~/superpowers-src ./install.sh --target codex脚本通常会帮你完成三件事复制技能目录到正确位置、检查AGENTS.md是否存在、把技能说明追加进去。看似方便但我在实际使用中遇到一个坑脚本可能会覆盖掉我原本写好的AGENTS.md自定义内容。所以跑自动脚本之前建议先备份cp ~/.codex/AGENTS.md ~/.codex/AGENTS.md.bak如果你只想体验单个技能比如只装 debugging也可以手动只复制那一个目录不复制整个技能集。这不叫偷懒反而是一种克制——技能装得越多模型的决策负担就越重反而可能在不合适的场景里调用错技能。3.3 安装后的验证清单怎么确认它真的生效了装完之后不要急着开工先花两分钟做次深呼吸式的验证。我一般会按下面这个清单过一遍检查目录ls ~/.codex/skills能看到对应技能文件夹且每个文件夹里都有SKILL.md检查注册打开~/.codex/AGENTS.md确认技能名称和触发场景描述没有拼写错误交互验证在 Codex CLI 里输入一句类似“我要排查一个偶现的线上问题请选择合适的工作流”然后观察它在动手之前是否真的读取了 debugging 或 brainstorming 技能并描述了步骤。如果模型没有提到任何技能很可能是AGENTS.md里的描述不够明确。这时候我会把描述改得更直白比如“遇到 bug 必须先调用 debugging 技能”模型听从的概率会提高很多。4. 实战环节用 superpowers 驱动 Codex 完成一次功能开发4.1 实战一用“头脑风暴 计划”把模糊需求变成开发方案我拿一个很常见的需求做示例想写一个简单的“用户收藏列表”功能。直接问 Codex “帮我写收藏功能”它大概率会给出接口和数据库表结构的初稿但未必考虑到分页、重复收藏、性能边界等问题。而装上 superpowers 之后正确的打开方式是先给它一个指令“请先运行 brainstorming 技能再运行 planning 技能最后给我一个开发方案先不要写完整代码。”我实际观察到的执行流程大致是这样的先加载 brainstorming列出问题“收藏的粒度是什么是收藏文章还是商品”“用户未登录时是否允许临时收藏”“收藏列表是否要求实时排序”“是否需要取消收藏”然后进入 planning把任务拆为设计数据表 → 实现新增/删除接口 → 实现列表查询接口 → 补充前端入口 → 编写测试。最后输出的是带有优先级的实施计划以及每个步骤的验收标准。这套流程真正解决的是“需求不明确但没人追问”的问题。模型不是为了讨好你直接生成代码而是先逼着双方把需求补全这对项目质量的提升是肉眼可见的。4.2 实战二让 debugging 技能替代“瞎猜式修 bug”我印象比较深的是有一次排查一个偶发的内存占用问题。之前我直接问 Codex“为什么内存会一直涨” 它会立刻列出一堆可能原因内存泄漏、缓存未清理、第三方库异常…… 回答很全面但全都是猜测。使用 debugging 技能之后它会把过程改成先要求我提供复现步骤和监控数据根据信息建立第一个可验证假设建议在代码里加日志或使用性能分析工具而不是直接改逻辑验证完成后再针对根因做最小改动最后要求跑一次回归测试确认没有引入新问题。这种流程看起来很基础但关键的差别在于没有技能时模型会“跳过验证步骤直接给答案”有技能时它会按照工程师的思维链一步一步逼近真相。对我这种常年被各种“玄学 bug”折腾的人这个技能带来的可靠性比“回答准确”更重要。4.3 对比普通提示词差异不是“答得更好”而是“流程更稳”可能有人会觉得这些步骤就算不装技能我手动在提示词里写“请先分析原因再修改”也能做到。确实单次对话可以做到但问题是你无法保证模型每次都记得这个要求。普通提示词和技能包的差别有点像我以前用命令行工具和写 Makefile 的差别。前者依赖你每次都敲对参数后者把流程固化成一个可复用的目标。superpowers 的价值在于它让 Codex 的行为有一套“默认值”不再是每次都要重新调教的临时状态。对比维度普通提示词使用 superpowers 技能包行为稳定性时好时坏取决于模型的临场发挥相对稳定按固定流程执行需求分析容易跳过直接写代码会先做问题梳理和假设调试方式倾向于直接给“可能原因”倾向于先验证再下结论团队复用靠个人复制粘贴靠目录结构统一扩散维护成本低但每次要重新写中需要维护技能描述所以我的结论是superpowers 没有让 Codex 变得更“聪明”而是让它变得更“稳”。这个“稳”在复杂任务里比模型一时开窍更加值钱。5. 常见问题与避坑实录5.1 技能没有被识别先查路径再查描述这是安装后最常见的状况。Codex 完全没反应代码该怎么写还是怎么写。我排查了三次总结出最可能的几个原因路径不对技能目录没放进~/.codex/skills而是误放到了~/.codex根目录大小写不一致技能文件夹名和AGENTS.md里的引用名对不上AGENTS.md没生效有些版本要求文件必须放在项目根目录或指定的配置位置不能乱放没有重开终端配置读取发生在启动阶段新会话不一定能识别最新配置。排查思路也很简单先用ls确认目录再用cat确认AGENTS.md内容最后删掉旧的~/.codex缓存目录后重开终端。按这个顺序查一般十分钟内能定位问题。5.2 多个技能互相打架给每个技能写清楚触发条件superpowers 一次性提供很多技能如果你全部装上模型偶尔会在“这个任务应该用哪个技能”上犹豫。我遇到过它把 brainstorming 和 planning 混在一起执行导致输出结构混乱。解决办法不是少装技能而是把每个技能的描述写得更“挑剔”。比如AGENTS.md里明确写“只有需求信息严重不足、需要向用户提问时才使用 brainstorming一旦需求确定禁止重新进入头脑风暴直接执行 planning”。描述越具体模型误调用的概率越低。更极端的做法是只保留 23 个你当前最需要的技能目录把其他目录暂时移出。技能包这个东西属于“少即是多”装多了反而干扰决策。5.3 上下文消耗变高从“全量加载”改成“按需触发”有一段时间我发现 Codex 的对话上下文涨得很快后来定位到是技能文档被模型一次性读进去导致的。尤其有些技能目录里还附带了大量示例代码token 消耗一下子就上去了。缓解手段有三个精简技能目录把SKILL.md里冗余的示例删掉只保留步骤说明缩小触发面在AGENTS.md中强调“先读取技能名称和简介确认需要后再读取完整内容”手动控制不需要某个技能时把对应目录临时改名等需要时再改回来。这些操作不会影响技能本身的可用性但能把单次任务的 token 成本降下来不少。做法上虽然不够“自动化”却是最可控的。5.4 其他工具如何迁移不要把思路局限于 Codex CLIsuperpowers 的核心资产是SKILL.md这套结构。只要你的工具支持“按目录加载技能”或“读取 Markdown 指令”通常就能迁移过去。比如有些基于 Trae 的版本或者类似支持 AGENTS 机制的编程助手安装思路都差不多先找到对应的全局配置目录然后把技能复制进去再注册说明。如果你用的工具不支持AGENTS.md还有一个临时替代方案把SKILL.md的内容手动粘贴到项目的说明文件或系统提示里。虽然丢失了自动触发的便利性但至少工作流本身还能用。我个人在实际操作中的体会是superpowers 最值得借鉴的并不是某一个技能里的具体提示词而是“把一份成熟的工作方法论固化成结构”这件事本身。你可以不用它的技能但完全可以照这套思路把自己平时开发中的检查清单、复盘模板、代码审查项整理成自己的技能包目录。那样的话你得到的就不只是一个开源项目而是一套能持续沉淀的 AI 工作流。我建议你先装 brainstorming 和 debugging 这两个技能用两周观察一下效果再决定要不要继续扩展。