Superpowers实战：给Codex CLI装上可复用的AI编程技能包

最近很多人问我：为什么同一个 Codex，别人用得跟资深架构师一样，我用起来就是个打字机？答案往往不在模型本身，而在你给它的"辅助装备"。我最近在项目里全面用上了一套叫Superpowers的技能扩展框架，把它接进 Codex CLI 和 WorkBuddy 之后，AI 写 Java 的姿势直接换了个人——不是那种"乱写一通再让你改"的路线，而是先理解项目约束、再按规范产出、最后自检的那种干法。这篇就是我的 Superpowers 使用指南，从安装、配置、技能包编写到踩坑排查，全是我实际跑过的流程和教训，适合正在用 Codex、Claude Code 这类 AI 编程助手，又觉得"模型懂很多但用不顺手"的开发者。

1. 先想清楚：Superpowers 解决的到底是“不会写”还是“写不对”

很多人在安装 Superpowers 之前，压根没想过一个问题：AI 编程助手的瓶颈在哪儿？

1.1 为什么 Codex 有时候像“顶级实习生”

模型本身的知识量是够的，它知道 Java 的ConcurrentHashMap怎么用，也知道 Spring Boot 的自动装配原理。但它在你的项目里表现像顶级实习生：基础知识扎实，却不了解你们团队的代码风格、不知道这个模块的历史包袱、不清楚哪些目录是生成代码别乱碰、也不晓得接口命名要用什么前缀。

普通提示词能解决一部分问题，比如你在对话里写"请遵守阿里规约、用 SLF4J 打日志"。但问题在于：对话上下文一长，这些约定就逐渐被稀释；换一个新会话，又得重新解释一遍。Superpowers 解决的就是这个"上下文不落地、规则不固化"的问题。

1.2 技能包和普通提示词的本质差异

Superpowers 的核心概念是"技能包"（Skill Pack）。你可以把它理解成给 AI 助手装了一本《项目操作手册》，手册里不是空泛的原则，而是可被自动触发、按需调用的结构化指令。

普通提示词是"一次性消费"，技能包是"可复用资产"。两者的区别，用做饭类比最清楚：

• 普通提示词：你站在厨师旁边说"少放盐、多放葱、别用豆瓣酱"。
• 技能包：你提前给厨师一本《本店菜品标准》，里面有每道菜的操作流程、调料克数、摆盘要求。厨师上岗第一天就按这个标准做，不用你每次重复。

具体到技术实现，Superpowers 通过一套文件结构，把"什么时候用这个技能"（触发条件）、"怎么用"（执行步骤）、"遵守什么约束"（检查清单）固化下来。AI 代理在接到任务时，会根据技能包的描述自动匹配并加载对应内容，而不是把整个项目历史都塞进上下文。

1.3 一个技能包的内部长什么样

先看一个最简技能包的目录结构，这是我在~/.superpowers/skills/下建的真实例子：

~/.superpowers/skills/ └── code-review-java/ ├── index.md └── rules.yaml

index.md是技能的主文件，里面有 YAML 头信息和正文指令；rules.yaml放结构化的检查规则，方便 AI 在自检阶段逐条对照。

index.md的头信息长这样：

--- name: code-review-java description: 对 Java 代码进行评审，重点检查空指针、异常吞掉、并发安全、资源泄漏问题。当用户要求"审查/检查/review Java代码"时使用。 model: codex ---

后面的正文我放在 Java 实战章节里细讲。现在你只需要记住一件事：Superpowers 不是靠魔法，而是靠一套严格的目录约定和描述机制，让 AI 在正确的时机读到正确的内容。

2. 安装与初始化：把 Superpowers 跑起来的完整流程

安装这块，网上各种教程写得七零八落，我直接给你一套我实测过的完整步骤。

2.1 前置环境：Node.js 版本与 Codex CLI 准备

Superpowers 的 CLI 是基于 Node.js 的，所以第一件事是确认环境：

node -v npm -v

建议 Node.js 版本不低于 18。我一开始在 Node 16 的旧机器上跑，安装没问题，但执行技能时偶尔报原生模块兼容错误，升级到 Node 20 之后一切正常。

另外，你本机需要已经装好 Codex CLI，并且完成过登录认证。验证方式很简单：

codex --version codex login status

如果codex命令都找不到，先别急着装 Superpowers，去 OpenAI 官方文档把 Codex CLI 装好。这一步卡住的人最多，但互不相关，所以别跳过。

2.2 通过 npm 全局安装 Superpowers

核心安装命令如下：

npm install -g @superpowers/cli

装完以后检查版本：

superpowers --version

如果提示命令找不到，多半是 npm 全局 bin 目录没进 PATH。Windows 上跑npm config get prefix，把输出的路径加进系统 PATH；macOS/Linux 上检查/usr/local/bin或~/.npm-global/bin是否在 PATH 里。

2.3 初始化工作区：初始化仓库结构

全局安装只是把 CLI 装好了，真正的技能包需要落在某个工作目录里。执行：

superpowers init

它会问你初始化到哪里，默认是~/.superpowers/，我建议直接默认。初始化完成后会生成：

~/.superpowers/ ├── config.yaml ├── skills/ ├── commands/ ├── context/ └── logs/

每个目录的作用，我在下一章详细说。这里要提醒一句：init只创建骨架，不会给你装任何技能包。很多人以为初始化完就能用了，结果一执行技能发现什么也没有，然后在评论区骂"垃圾工具"——其实只是没理解它的机制，技能包得自己写或者从社区拉。

2.4 验证安装：第一个内置技能跑通

Superpowers 自带几个示例技能，初始化后你可以先跑一下内置的skill-list（不同版本命令略有差异，我这里以常见的 0.2.x 版本为例）：

superpowers list

能看到skills/目录下的技能清单就说明环境没问题。接着跑一个最简单的内置技能：

superpowers run explain-project

如果配置没问题，Codex 会启动，并根据explain-project技能的指令解释当前目录的项目结构。看到输出内容就说明整套链路已经打通了。

这里有个容易踩的坑：superpowers run默认会调用 Codex，但如果你同时装了多个 AI 后端（比如 Claude Code），可能需要在config.yaml里显式指定：

default_backend: codex

不指定的话，可能出现"技能找到但后端不知道发给谁"的尴尬局面。

3. 核心调用机制：技能注册、路由与上下文注入

安装跑通之后，最重要的事情是搞清楚 Superpowers 的调用机制。我见过太多人，技能文件写了一大堆，结果 AI 压根不用，然后就开始质疑工具。其实九成是没理解它的路由逻辑。

3.1 三个关键目录：skills、commands、context

初始化生成的那几个目录，各管一摊事：

你不需要每个目录都用得很重。我的习惯是：context/里放一份project-conventions.md，把团队的东西写进去；skills/里放每个具体技能；commands/只在需要组合技能时才用。

3.2 技能如何被自动路由

Superpowers 的路由机制，简单说就是：当 AI 接到一个用户请求时，它会读取所有技能的description字段，判断当前请求跟哪个技能的描述最匹配，匹配上了就把该技能正文作为系统指令的一部分注入。

所以description写得越精确，路由越准。下面是我总结的写描述的三个原则：

1. 明确触发场景：不要写"用于代码审查"，要写"当用户要求审查 Java/Maven 项目中的代码时使用，重点检查空指针、并发、资源泄漏"。
2. 标明适用范围：如果技能只针对 Java，不要写泛泛的"代码审查"，否则 Python 项目也会被误触发。
3. 控制长度：有些版本对描述长度敏感，太长了可能解析异常，我一般控制在 200 字以内。

3.3 自定义技能的 YAML 头信息与命名规则

技能文件的头信息是路由的核心，我见过的最标准的格式是：

--- name: generate-spring-controller description: 在 Spring Boot 项目中生成标准 Controller，包含参数校验、统一返回体、日志埋点。当用户要求"生成接口/controller/API端点"时使用。 model: codex ---

这里有几个细节：

• name必须全小写，用连字符分隔单词。我之前写了一个CodeReviewJava，结果列表里能看见，但通过superpowers run调用时大小写匹配失败，折腾了半小时。
• model字段不是必须的，但如果你同时接 Codex 和 Claude，建议显式指明。
• 头信息和正文之间必须有一个空行，否则解析器可能把正文也当成 YAML 的一部分。

3.4 上下文注入：让 AI 记住项目约定

context/目录是容易被忽略但价值最高的地方。我在context/project-conventions.md里写了这些内容：

# 项目约定 - Java 版本：17，禁止使用 Java 8 语法 - 日志使用 SLF4J，禁止直接 System.out - 所有对外接口必须有统一的 Result<T> 包装 - 数据库操作必须经过 MyBatis-Plus，禁止裸写 JDBC - 新增依赖必须说明理由，禁用无注释的依赖

这些内容不会每次都完整注入，但会在 AI 加载技能时作为"背景知识"随技能一起提供。实际效果是：AI 生成代码时"下意识"遵守这些约定，而不是你事后一条条指出来。

4. 从命令行到编辑器：在 WorkBuddy / VSCode 里接上 Superpowers

很多人不喜欢在终端里跟 AI 交互，更习惯在 IDE 里写代码时顺手唤起 AI。这部分我讲如何把 Superpowers 接进 WorkBuddy 这类聚合工具，以及 VSCode 的常见接法。

4.1 什么是 WorkBuddy，为什么适合接 Superpowers

WorkBuddy 是一款聚合多个 AI 编程后端的桌面工具，支持 Codex、Claude 等后端切换。它解决的最大痛点是：你不用为了用不同模型而切换不同终端或插件。Superpowers 本身不依赖特定 IDE，它只需要能调用 CLI 就行，所以 WorkBuddy 天然适合当它的"宿主"。

我一开始是直接在终端里用superpowers run，后来发现团队里其他同事更习惯图形界面，就统一在 WorkBuddy 里配置。简单说，WorkBuddy 提供一个外部命令/集成面板，你把 Superpowers 的命令挂进去，就能在界面里点按钮触发技能。

4.2 集成方式一：通过 MCP 配置挂载

Superpowers 支持 MCP（Model Context Protocol），这是目前最干净的集成方式。在 WorkBuddy 的配置文件里添一个 MCP 服务：

{ "mcpServers": { "superpowers": { "command": "superpowers", "args": ["mcp"], "transport": "stdio" } } }

配置后，重启 WorkBuddy，它会在 AI 对话中自动感知到 Superpowers 提供的技能列表。你可以直接在对话里说"用 code-review-java 审查一下当前文件"，AI 会通过 MCP 调用技能，而不是靠你复制粘贴。

4.3 集成方式二：Codex CLI 的 agents 配置

如果你不用 WorkBuddy，而是直接使用 Codex CLI，也可以在它的配置里挂载 Superpowers。在~/.codex/config.toml中指定：

[agents] superpowers = { command = "superpowers", args = ["agent"] }

这样 Codex 会把 Superpowers 视为一个可用的 agent。实测下来，这种方式适合"一个技能走一个 Agent"的场景，比如专门让某个 Agent 负责 SQL 审查、另一个负责前端组件生成。

4.4 集成方式三：直接用终端命令调用

最朴素但最可靠的方式，永远是直接命令调用：

superpowers run code-review-java --path src/main/java/com/example/service/

这个方式的好处是路径清晰、日志直观，出问题能立刻看到错误。强烈建议你在折腾 MCP 之前，先在终端把技能本身跑通。我在社群看过太多人：MCP 配置了半天连不上，最后发现是技能文件本身写错了。基础不牢，后面全是空中楼阁。

5. Java 项目实战：给 Codex 装上“能审查代码、能补测试”的技能包

理论说再多，不如跑一个实战。我拿最近一个真实的 Java/Maven 项目举例，完整走一遍"定义技能 → 安装技能 → 运行技能"的流程。

5.1 场景拆解：Java 代码审查技能包的需求清单

项目背景：一个 Spring Boot 3 + MyBatis-Plus 的订单服务，团队最头疼的问题是代码合并前没人做系统检查。我们希望 Superpowers 提供一个代码审查技能，必须覆盖以下检查点：

• 空指针风险：Optional使用、可能为 null 的返回值
• 异常处理：catch 块是否吞异常、是否保留了堆栈
• 资源泄漏：数据库连接、文件流是否关闭
• 并发安全：共享变量是否被并发修改
• 日志规范：是否用了 System.out、是否有日志上下文
• API 规范：是否统一返回Result<T>

我把这些点直接写进规则文件。

5.2 编写 review-java 技能的完整过程

先建目录结构：

mkdir -p ~/.superpowers/skills/review-java

然后创建index.md：

--- name: review-java description: 审查 Java 项目的代码质量，聚焦空指针、异常处理、资源泄漏、并发安全、日志规范。当用户要求 review、检查、审查 Java 代码时使用。 --- # Java 代码审查 你是一名资深 Java 后端工程师，请对指定路径下的代码进行体系化审查。 ## 执行步骤 1. 先扫描目录结构，确认是 Maven 还是 Gradle 项目 2. 按 package 逐个审查 Java 文件 3. 对照 rules.yaml 中的检查项逐条核验 4. 输出审查报告，按严重级别排序：BLOCKER / MAJOR / MINOR 5. 每个问题必须给出：文件路径、行号、问题描述、修复建议 ## 硬性要求 - 不得输出泛泛而谈的赞美，必须给出具体问题和修改建议 - 如果某文件没有问题，不要强行凑问题 - 修复建议必须符合 Java 17 语法

创建rules.yaml：

checkpoints: - id: NULL_POINTER severity: BLOCKER desc: 可能引发 NullPointerException 的调用链 - id: EXCEPTION_SWALLOWED severity: BLOCKER desc: catch 块中没有正确处理异常，或吞掉了堆栈 - id: RESOURCE_LEAK severity: MAJOR desc: IO 流、数据库连接未关闭 - id: CONCURRENCY severity: MAJOR desc: 共享变量并发修改，缺锁或原子类 - id: LOG_PRACTICE severity: MINOR desc: 使用 System.out，未使用 SLF4J - id: API_WRAPPER severity: MINOR desc: 接口未统一返回 Result 包装

在context/里补充一下项目约定（前面已经写过），然后运行：

cd ~/workspace/order-service superpowers run review-java --path src/main/java

5.3 跑通效果：一次真实的违规代码扫描实测

我拿一个真实的 Service 类做测试，里面有这么一段代码：

public OrderVo getOrder(Long id) { Order order = orderMapper.selectById(id); return convertToVo(order); }

Superpowers 调 Codex 执行技能后，给出的报告里有这么一条：

BLOCKER | OrderServiceImpl.java:42 问题：orderMapper.selectById(id) 可能返回 null，直接传入 convertToVo 会触发空指针。 建议：使用 Optional.ofNullable(order).map(this::convertToVo).orElse(null)，或在入口校验 id 合法性。

这就是技能包的价值：按预定义的规则逐项扫，不遗漏，不跑题。你可能会说"这我自己也能在提示词里写"。没错，但区别在于：这个技能是固化的，团队谁都能用，不需要每个人都会写这种审查提示词。

6. 踩坑记录：技能半生效、乱回答、路径丢失的排查链路

这章是我最想写的。工具本身不难，难的是出了问题不知道怎么查。

6.1 现象：技能文件存在但 agent 就是不用

典型的崩溃现场：superpowers list能看到技能，但让 Codex 审查代码时，它完全忽略技能，仍然按默认行为回复。我遇到过两次，第一次排查了很久。

这时候千万别急着改技能内容。先冷静做三件事：

1. 检查description是否用了模糊表达，比如"审查代码质量"——太宽泛，路由匹配时优先级低。
2. 检查触发词是否完整。用户问"review this file"能不能命中"审查 Java 代码"？不一定，因为中英文描述不匹配。建议描述里同时写中英文触发场景。
3. 看日志。

6.2 从日志出发：查看技能加载过程

Superpowers 的日志在~/.superpowers/logs/下，排查时用这个命令会清晰很多：

superpowers trace --skill review-java --path src/main/java

它会输出技能解析、路由匹配、注入上下文的全过程。重点看两个位置：

• Skill matched：是否匹配到了技能
• Context files loaded：context/下的文件是否被正常加载

如果Skill matched显示none，说明描述和用户请求没匹配上，改描述就行；如果显示匹配上了但输出还是不对，那是技能正文写得不够强制，AI 把你的步骤当成"参考"而不是"指令"。

6.3 三个最隐蔽的坑：文件编码、符号链接、包名驼峰

这几个是我实打实踩过的，写在这里帮大家避雷。

坑一：文件编码必须是 UTF-8。index.md如果是 Windows 记事本保存的 ANSI 编码，YAML 头信息里的中文 description 会解析失败，技能直接静默失效。用 VSCode 或直接命令行创建文件，不要用系统自带记事本。

坑二：符号链接导致路径解析失败。我把~/.superpowers软链到了云盘目录，结果技能文件能列表但运行时读不到正文。原因是 Node 的路径解析没有跟着跟踪符号链接。解决方案：superpowers init时选择物理路径，别用软链。

坑三：技能包名用了驼峰。前面提过，name全小写加连字符最稳。实际上，用驼峰在 Linux 上可能没问题，但在 macOS 默认大小写不敏感的文件系统上会出现"看起来存在但读不到"的诡异情况。

6.4 我的固定检查顺序

现在我在群里帮人排查问题时，固定按这个顺序来：

1. superpowers list—— 技能到底有没有被发现
2. superpowers trace—— 路由是否命中
3. 打开日志文件 —— 看是否有解析警告
4. 检查文件编码和命名 —— 排除隐藏问题
5. 最小化复现 —— 临时写一个只输出"技能已触发"的测试技能，看链路通不通

这套流程至今没翻过车。很多时候问题压根不在工具，而是你写技能的姿势不对。

7. 一些个人习惯：给技能包做版本管理与回归测试

最后分享几个我实际工作里的习惯，可能对你有参考价值。

技能包本质上也是代码，是代码就要做版本管理。我把整个~/.superpowers/目录作为 Git 仓库维护，每个技能的新增和修改都提交，并写明 commit message 描述变更原因。团队协作时，直接git clone仓库就能让大家获得同一套技能，确保大家用 AI 的标准一致。

定期做"技能回归测试"是我最推荐的做法。每隔两周，我会把常用的几个技能各跑一遍，检查输出质量是否因为模型版本更新而退化。别笑，真的会遇到：某个技能上周还好好的，这周 Codex 更新后就不遵守某些检查项了。因为模型行为会变，你在技能里的描述也需要及时打补丁。比如你发现模型开始忽略资源泄漏检查，那就把这条在正文里从"请注意检查"改成"资源泄漏检查是最高优先级，未检查时不输出报告"。

另外，不要一次装几十个技能。技能越多，路由越容易误命中。我的原则是：每个技能解决一个具体痛点，覆盖的场景要可描述、可触发。如果某个技能一个月都用不上一次，我会考虑删除或合并。

Superpowers 这套框架给我的最大感受是：它把"提示词工程"从一次性对话变成了可积累的项目资产。以前我写好的审查规则只能躺在某个 markdown 文件里吃灰，现在变成了 AI 每次都会主动执行的技能。你不需要多精通 prompt 技巧，只要肯花时间把项目约束结构化，AI 的能力上限会比你想象的高很多。