superpowers技能框架：为Codex CLI打造可复用AI工作流

1. 从"能用"到"好用"：Codex CLI 缺的那块拼图

先说个背景。我大概从去年底开始把 Codex CLI 当成日常主力编码工具，用得越深越发现一个尴尬：它很强，但它的"强"是散的。每次开新会话，它都像一个记忆只有几秒的天才程序员——你告诉它今天要做什么，它能做得非常漂亮，但第二天你换了任务，它就把昨天的约定、你的项目规范、你反复强调的代码风格全忘了。我一度以为这是模型的通病，后来才意识到，问题出在"没有外部记忆"这件事上。

superpowers 就是冲着这个痛点来的。它是一个开源的技能框架，本质上是给 Codex CLI 装一套"可复用的能力包"，让它在每次会话开始时就知道你积累了什么技能，然后在合适的场景自动调用。配合 Codex 的配置文件与技能目录机制，superpowers 把"每次都从零交代"变成了"按需加载、随取随用"。这篇文章我用自己的实际使用过程，把安装、原理、写技能、踩坑四条线完整讲一遍，适合已经在用 Codex CLI、或者正准备把 AI 编码助手往项目深处推的开发者。

1.1 我为什么盯上 superpowers

因为我受够了重复交代。举个例子：我的 Java 项目里有几条铁律——Controller 层禁止写业务逻辑、所有外部接口调用必须包超时和重试、数据库操作一律走 MyBatis 的 Mapper 接口。这些话我几乎每隔几天就要跟 Codex 说一遍。遇到代码审查、生成单测、修 Bug 这些高频任务，每次的交代内容还不一样，会话一长，前面的约定还会被后面的对话冲淡。

superpowers 解决的就是这个场景：把"铁律"和"做事流程"固化成技能文件，技能文件放在指定目录里，Codex 启动时读一次索引，遇到匹配的场景就自动加载完整指令。它让我从"每次给 AI 做岗前培训"变成"培训一次，长期复用"。而且它不只是个配置模板，还带了一套方法论——比如 TDD、调试、子代理协作这些技能，都是可以直接拿来用的。

另外说句公道话，superpowers 的定位不是替代 Codex，而是给 Codex 补上"长期记忆 + 结构化工作流"。模型本身的能力没变，变的只是它每次开工前多看了几份"操作手册"。这个思路对任何用大模型写代码的人都值得参考。

1.2 superpowers 到底是什么

它是 GitHub 上的一个开源项目，作者是 Jesse Vincent，仓库名就叫 superpowers。核心思路一句话：把能力封装成 Markdown 格式的"技能文件"，每个技能文件包含一段前置说明（什么时候用这个技能）和一段正文（具体怎么做事），再把一堆技能文件组织成目录，最后通过一个 SKILLS.md 索引文件把整个技能库暴露给 Codex。

这个架构听起来简单，但它踩中了 Codex CLI 的一个关键设计：Codex 本身支持在配置里挂载技能目录，启动时会读取技能索引。superpowers 做得更彻底的地方在于，它自带一个叫 superpowers 的引导技能，这个技能负责告诉 Codex"你应该先浏览一下技能库，再决定用哪个技能"。所以即使你完全不熟悉它的内部机制，只要装好，Codex 也能自己摸索着用起来。

对 Java 开发来说，这个框架特别实用的点在于：语言无关。技能文件里写的全是自然语言指令，你可以写"用 Maven 的 spotbugs 检查潜在 Bug"，也可以写"所有 DTO 必须实现 Serializable"，完全围绕你自己的技术栈来定制。我后面会专门讲一个 Java 代码审查技能的例子，你可以直接抄。

2. 安装：把技能目录挂到 Codex 配置里

安装这块说难不难，但有几个细节没处理好会让人折腾一晚上。我按自己实际操作过的路径来梳理。

2.1 环境准备

装之前先确认三件事：

• Codex CLI 已安装并能正常登录。superpowers 很多特性依赖新版 Codex 的技能自动发现能力，老版本可能缺少对应的解析逻辑，所以建议先把 Codex 升到最新版。
• 系统里有 git。虽然也可以直接下载压缩包，但用 git 克隆的好处是后续拉取技能更新方便。
• 确认你的用户主目录下有 .codex 目录。如果没有也不用急，先随便跑一次codex命令让它完成初始化，或者手动建目录。

我自己的环境是 macOS，Linux 和 Windows（WSL 下）也兼容。Windows 原生环境我没试过，如果你用 PowerShell 装，遇到脚本执行策略的问题，用 WSL 会更省心。

2.2 安装步骤：克隆、执行、验证三步走

官方仓库的安装方式很直白，我在终端里执行的是：

git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh

install.sh 脚本做的事，我拆开看了一下，主要是这几步：

• 把技能目录复制或者软链到 Codex 能扫描到的位置。
• 备份并更新~/.codex/config.toml，在配置里注册 superpowers 相关的路径。
• 放置 SKILLS.md 索引文件，让 Codex 每次启动都能读到技能清单。

这里提醒一句：不同 Codex 版本对技能路径的配置字段名称不完全一样，有的版本用 skill_paths，有的版本挂在某个扩展节点下。你装上之后别急着关终端，先打开~/.codex/config.toml看一眼，确认多出来的配置行指向的目录确实存在。这一步能省掉后面一多半的排查时间。

如果你拉到的版本没有 install.sh，或者你想手动装，思路也一样：把仓库里的 skills 目录放到固定位置，把 SKILLS.md 放到 Codex 配置能识别的地方，然后在 config.toml 里把路径指过去。本质上就这三件事。

2.3 安装后必须做的验证

装完别急着写技能，先验证"技能系统是否真的活了"。我的验证方法很简单：新开一个 Codex 会话，直接问它：

你有哪些技能可以用于这个项目？如果我想做代码审查，你会怎么处理？

如果安装成功，它会提到 superpowers、SKILLS.md，或者说"让我先查看技能目录"。如果它一脸茫然，甚至说不知道什么技能，那基本可以断定配置没生效，直接跳到后面第 5 节的排查清单。

另一个验证方式是看启动日志。Codex 启动时会打印加载的配置和技能索引信息，你在启动命令后留意输出里有没有 skills 相关路径。这一步虽然不起眼，但能让你确认技能文件是被"系统级加载"而不是"碰巧被对话内容提到"。

3. 技能机制拆解：Codex 是怎么"学会"新技能的

很多教程一上来就让你写技能文件，但我建议先花十分钟搞清楚机制，否则你写出来的技能十有八九不触发。

3.1 技能文件的骨架

一个技能文件就是一个 Markdown 文档，最前面带一段 YAML 格式的 frontmatter。我用自己写的 Java 审查技能来举例：

--- name: java-code-review description: 用于 Java 项目的代码审查，重点检查空指针、资源泄漏、并发安全与分层规范 --- # Java 代码审查流程 当用户要求审查 Java 代码时，你是一位有 15 年经验的 Java 架构师。 先通读代码，再按以下清单逐项检查，最后输出分级结论。 ## 审查清单 1. 空指针风险：所有可能为 null 的返回值与参数。 2. 资源管理：IO、数据库连接是否在 finally 或 try-with-resources 中关闭。 3. 并发安全：共享变量是否有 volatile / synchronized / 锁保护。 4. 分层规范：Controller 是否直接调了 Mapper 或写了业务逻辑。

这里面最关键的是 description 字段。Codex 不会在每次会话里都把所有技能文件读一遍，那样上下文会撑爆。它的策略是：先读 SKILLS.md 索引，索引里是每个技能的名称 + 一句话描述。当用户请求与某条描述匹配时，它才去读对应的完整技能文件。

所以 description 写得准不准，直接决定技能会不会被触发。写得太窄，需要时想不起来；写得太宽，不该用时乱入。我见过最典型的失败案例，是把 description 写成"用于写代码"，结果每次会话都触发，反而干扰了正常编码。

3.2 一次完整的技能调用链路

我把它拆成四步，理解了这个，后面调试就简单了：

1. Codex 启动，读取 SKILLS.md 索引，把技能清单放进上下文。
2. 用户发出请求，模型根据索引里的描述，判断哪个技能匹配。
3. 模型读取匹配的完整技能文件，把里面的操作规范并入当前推理。
4. 模型按技能文件的步骤执行，并在对话里体现"正在使用 xx 技能"。

这四步里，最容易被忽略的是第一步。SKILLS.md 本身是静态文件，如果你新增了技能但忘了更新它，Codex 永远不知道你多了个新技能。所以每次新增技能后，要么手动把新技能追加进 SKILLS.md，要么就用 superpowers 自带的"创建技能"流程——它会自动帮你维护索引。这也是为什么我说它是框架而不只是文档集合：索引维护这个脏活，它帮你干了。

3.3 内置技能里值得优先用的几个

superpowers 仓库自带的技能覆盖了编码工作流的高频场景。我列一下自己常用的几个：

TDD 技能是我觉得最值的一个。以前让 Codex 写测试，它总是先写一堆实现再补测试，顺序完全不对。加载 TDD 技能后，它会严格遵守"先写失败测试 → 跑红 → 最小实现 → 跑绿 → 重构"的循环，产出的代码质量明显不一样。这就是技能的价值：它不只是给模型加知识，而是把一种工程纪律注入到模型的执行过程中。

4. 实操：从零写一个技能并在 Java 项目里用起来

光讲原理不过瘾，我拿一个真实场景走一遍完整流程：给一个 Spring Boot 项目定制"代码审查"技能，并让它和现有的 Java 工具链结合。

4.1 先跑通内置技能的调用

我第一次用 superpowers 时，先没急着写自定义技能，而是直接试内置的 TDD 技能。我打开一个 Java 项目，新开会话，输入：

用 TDD 的方式给 OrderService 的 createOrder 方法补一个下单流程。

Codex 回复里出现了"我将使用 test-driven-development 技能"之类的措辞，然后真的先写了 OrderServiceTest，再写实现。那一刻我就确认了机制是通的。

这里有个小技巧：如果你不确定该用哪个技能，可以直接说"用 superpowers 的思路来处理这个问题"。引导技能会帮 Codex 先浏览技能库，选出最匹配的一个，再告诉你它选了什么。这个交互方式对新手特别友好，相当于给 Codex 装了一个"技能路由器"。

4.2 给 Java 项目写一个"代码审查"技能

内置技能没有针对 Java 分层规范的现成版本，所以我决定自己写。我在 superpowers 的 skills 目录下新建了一个java-code-review.md文件，内容就是前面 3.1 节里那个骨架，但我又往下补充了几段针对工具链的指令：

## 工具使用 - 检查 POM 依赖时，用 `mvn dependency:tree` 确认是否有冲突或冗余。 - 高优先级问题必须给出文件路径、行号与修改建议。 - 输出格式：按"严重 / 建议 / 疑问"三级分类。 ## 项目铁律 - Controller 层禁止写业务逻辑，只能做参数校验与路由。 - 所有外部接口调用必须配置连接超时与读取超时。 - DTO 字段禁止直接暴露给内部实体，需手动映射。

写完文件后，我用 superpowers 的创建技能流程更新了索引。然后测试效果：打开项目，对 Codex 说"审查一下 PaymentController 这段代码"。它自动加载了 java-code-review 技能，输出里明确提到了 Controller 层是否违规、Mapper 调用位置是否合理、超时配置有没有漏，而且每条都带了文件路径。跟之前"自由发挥式"的审查完全不是一个层级。

4.3 把技能固化到日常流程

技能写好了，怎么让它成为团队流程的一部分？我目前的做法是把它和 Git 仓库绑定：superpowers 的技能目录本身就在一个 git 仓库里，我 pull 上游更新，同时把自定义技能推到自己团队的私有仓库。同事克隆下来跑一次 install，就能拿到同样的 Java 审查规范。

这样做还有一个好处：code review 时，AI 的审查标准和团队负责人定的规范完全一致，因为都是从同一个技能文件读出来的。以前"规范写在不存在的文档里"的问题，算是用技能文件变相解决了。当然，技能文件本身也需要维护，代码规范变了我改一次，所有人下次拉取就同步了。

5. 踩坑实录：技能没生效、乱触发、上下文爆炸

这个部分是我最想写的。superpowers 用起来顺手，但有几个坑几乎每个人都会踩一遍。我按排查顺序记录。

5.1 技能目录没被识别

症状是：装好了，你问 Codex"你有什么技能"，它说不知道。排查链路如下：

• 先确认 config.toml 里注册的路径和实际技能目录是否一致。我遇到过路径写错一个字符，导致整个目录被忽略。
• 再确认 SKILLS.md 是不是在 Codex 启动时能读到的那一层。如果你手动移动过文件，很容易造成索引和实际目录分离。
• 最后确认 Codex 版本。技能自动发现是相对新的能力，版本太老的话，配置写再多也没用。

这个坑的根治办法：装完立刻跑 2.3 节的验证，别攒到第二天。

5.2 新增技能没写进索引

症状是：技能文件明明建了，手动问 Codex"你怎么不用 java-code-review"，它说仓库里没有这个技能。原因基本就是 SKILLS.md 没更新。因为 Codex 只读索引，不扫目录。

我自己后来干脆养成了习惯：新建技能后，第一件事是去看 SKILLS.md 尾部有没有多一行。如果没有，要么手动补，要么用框架自带的维护命令。手动补的格式很简单：

## java-code-review 用于 Java 项目的代码审查，重点检查空指针、资源泄漏、并发安全与分层规范。

注意，索引里的描述最好和技能文件 frontmatter 里的 description 保持一致，不然模型会看到两个版本，触发时可能犹豫。

5.3 description 写得太宽泛导致乱触发

这是我调了好几次才总结出来的教训。我一开始把 java-code-review 的 description 写成"帮助用户解决 Java 开发中的各种问题"，结果 Codex 写任何 Java 代码时都想加载它。一次简单的新增接口需求，它先给我做了一轮代码审查，浪费了大量时间和上下文。

description 的正确写法是"精确描述触发条件"，比如：

• 触发场景：用户要求审查、检查、评审现有代码。
• 明确排除：用户要求生成新代码时不需要。

这个"明确排除"的写法，能显著减少误匹配。我的经验是描述里至少包含两个部分：什么情况下用 + 什么情况下不用。模型对负向条件的遵循度比我预想的高。

5.4 上下文窗口被塞满的应对

技能文件本身也是要占上下文的。如果 SKILLS.md 里挂了五六十个技能，就算只读描述，也会吃掉不少 token。而且技能正文动辄几百行，一旦触发就全量加载，多触发几个技能，上下文瞬间紧张。

我的应对方案有三条：

• 技能文件保持精简。只写流程框架和铁律，示例代码能省则省。
• 按项目拆分技能库。Java 项目只挂 Java 相关技能，别把前端的、运维的技能全塞进同一个索引。
• 尽量用索引描述匹配，少用"把整个技能库都读一遍"的粗暴方式。默认引导技能是聪明的，别手动强迫它加载所有技能。

关于上下文还有一个很容易忽略的点：会话里已经加载过的技能，如果你不再需要，可以明确告诉 Codex"后面不要继续使用 xx 技能"。这比让它自然遗忘更可靠，能及时释放上下文空间。

6. 我的使用习惯与后续扩展方向

文章最后，分享几个我目前在坚持的做法，不一定适合所有人，但如果你也打算把 superpowers 真正用起来，可以参考。

第一，技能不是越多越好，而是越精准越好。我现在整个技能库不到十个文件，每个都是被真实任务反复锤炼过的。写一个技能，至少要经过三次实际触发、再修改，才敢让它留在正式库里。那些"感觉以后能用"的脑暴型技能，我放在草稿目录里，等真的用到了再转正。

第二，团队共享时一定要有人维护主线。技能文件一旦多人提交，很容易变成大杂烩。我们现在要求每次改动技能后，必须同步更新 SKILLS.md 里对应描述，并且由固定的负责人 review 合并。这其实跟维护代码仓库的纪律一样。

第三，把它当成一个长期积累的"团队操作手册"。我最近在搭一个新的微服务项目，很多约束直接写成了技能文件：接口命名规范、异常处理规范、日志规范、数据库迁移流程。以后不管是 Codex 还是别的 AI 工具来参与这个项目，只要读技能库，就能快速对齐。这套东西的价值会随着项目演进越滚越大。

最后再分享一个我最近在试的方向：把 superpowers 的技能文件和 CI 流程打通。比如提交 PR 时，自动把这段代码丢给 Codex 加载 java-code-review 技能做预审查，再把结果贴在 PR 描述里。目前已经跑通了基本链路，效果比预想的好，至少低级问题在人工 review 前就被筛掉了一大半。技能体系这个东西，玩起来之后你会发现它的边界完全取决于你想把多少工程经验固化下来。