先从一个真实的使用场景说起：我刚开始用 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：按照“收集信息 → 建立假设 → 小步验证 → 修复 → 回归”的顺序处理 bug；
- code review：带着检查清单去审查代码，关注安全性、可读性、边界条件和测试覆盖；
- writing tests：根据模块行为生成测试用例，而不是简单补几行覆盖率。
这些技能不是让人一次全用上，而是让模型根据任务性质自动选择合适的流程。正因为每个技能都封装了一套工作方法论，使用它的感觉就像给终端里的 AI 助手装了“职业模块”，从“知道很多”变成“知道在什么场景下该怎么做”。
1.3 哪些场景适合引入 superpowers
从我个人的使用体验来看，它最适合以下三类场景：
一类是需求模糊的功能开发。比如老板丢过来一句“做个用户通知功能”，普通 AI 可能会直接开写接口，而 superpowers 的 brainstorming 技能会先逼着模型列出问题、假设和边界，再进入计划阶段，最终产出的是“开发方案”而不是一团代码。
二类是 bug 定位和修复。尤其是那些复现路径不明确、日志信息混乱的问题，普通对话常常会停在“可能是这里有问题”的猜测阶段；而有 debugging 技能在手，Codex 会被要求一步一步验证假设，而不是拿着一个猜测去改代码。
三类是代码审查和重构。它会按检查清单逐项过，不会因为只盯着某个功能点就漏掉安全性和异常处理。
一句话总结：如果你的使用方式还停留在“问一句、答一句”，superpowers 的作用不明显；一旦你希望 AI 真正“负责一件事”，它就变得非常值得装。
2. 安装前的准备：先摸清 Codex CLI 的技能机制
2.1 Codex CLI 如何识别 skill：AGENTS.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 CLI
3.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”。描述越具体，模型误调用的概率越低。
更极端的做法是：只保留 2～3 个你当前最需要的技能目录，把其他目录暂时移出。技能包这个东西属于“少即是多”，装多了反而干扰决策。
5.3 上下文消耗变高：从“全量加载”改成“按需触发”
有一段时间我发现 Codex 的对话上下文涨得很快，后来定位到是技能文档被模型一次性读进去导致的。尤其有些技能目录里还附带了大量示例代码，token 消耗一下子就上去了。
缓解手段有三个：
- 精简技能目录：把
SKILL.md里冗余的示例删掉，只保留步骤说明； - 缩小触发面：在
AGENTS.md中强调“先读取技能名称和简介，确认需要后再读取完整内容”； - 手动控制：不需要某个技能时，把对应目录临时改名，等需要时再改回来。
这些操作不会影响技能本身的可用性，但能把单次任务的 token 成本降下来不少。做法上虽然不够“自动化”，却是最可控的。
5.4 其他工具如何迁移：不要把思路局限于 Codex CLI
superpowers 的核心资产是SKILL.md这套结构。只要你的工具支持“按目录加载技能”或“读取 Markdown 指令”，通常就能迁移过去。比如有些基于 Trae 的版本，或者类似支持 AGENTS 机制的编程助手，安装思路都差不多：先找到对应的全局配置目录，然后把技能复制进去，再注册说明。
如果你用的工具不支持AGENTS.md，还有一个临时替代方案：把SKILL.md的内容手动粘贴到项目的说明文件或系统提示里。虽然丢失了自动触发的便利性，但至少工作流本身还能用。
我个人在实际操作中的体会是，superpowers 最值得借鉴的并不是某一个技能里的具体提示词，而是“把一份成熟的工作方法论固化成结构”这件事本身。你可以不用它的技能，但完全可以照这套思路，把自己平时开发中的检查清单、复盘模板、代码审查项整理成自己的技能包目录。那样的话，你得到的就不只是一个开源项目，而是一套能持续沉淀的 AI 工作流。我建议你先装 brainstorming 和 debugging 这两个技能，用两周观察一下效果，再决定要不要继续扩展。
