superpowers：为AI编码助手打造按需加载的技能库

1. 先搞清楚 superpowers 是什么

1.1 AI 编程助手为什么需要“技能”

你有没有遇到过这种情况：同一个 AI 编码助手，在干净的“hello world”项目里表现得像个天才，一旦扔进一个带历史包袱的企业级 Java 工程，就开始一本正经地胡说八道。它不知道你们的 Maven 仓库有内网镜像，不知道代码规范里禁止 Lombok 的@Data用在 JPA 实体上，更不知道测试运行前要先启动一个特定的 Docker Compose 服务。这些信息不在模型的训练数据里，也不在仓库的代码里，而是散落在团队成员的脑子里。

这就是 AI coding agent 在实际工程环境里的核心痛点：它很强，但它“不熟”。代码模型背下了全世界的开源代码，却背不下你公司内部的构建流程和踩坑记录。早期大家靠什么解决？靠在CLAUDE.md、AGENTS.md里写长篇提示词，把规则一条条喂给智能体。问题是提示词越写越臃肿，而且智能体不是每次都会认真读完。你写了两千字规范，它可能只看了前两百字。

superpowers 这个项目就是冲这个问题来的。它不是又一个编码助手，而是给 Codex、Claude Code、Gemini CLI 这类编码智能体统一提供“技能库”的管理工具。所谓技能，就是一组结构化的 Markdown 指令文件，里面写明“在什么情况下用什么方法做什么事”，然后由 superpowers 帮你安装、更新、组织、注入到智能体的工作流程里。简单说：它把“写在提示词里的项目知识”，变成了“按需自动加载的即插即用技能”。

1.2 项目核心思路与能解决的问题

我第一次用 superpowers 的时候，脑子里浮现的画面是一个老师傅的抽屉：每个抽屉贴着标签，里面有对应的操作手册、检查清单、常用脚本。智能体遇到问题打开对应抽屉，而不是把所有手册都摆在桌面上读。这正是 superpowers 的设计哲学：技能不是一股脑塞进上下文，而是由智能体根据任务描述，自主判断“我现在需要哪份技能”，再按需读取。

这样做有几个很实际的好处。第一，上下文窗口被节省了，智能体不用每次都在几万字的规范里翻找条款，它只需要读取当前任务相关的技能文件。第二，技能是可复用的，同一个“后端代码审查”技能，可以同时用于 A 项目和 B 项目，不需要在每个仓库里复制粘贴。第三，技能是可版本管理的，它就是一个普通目录，放进 Git，团队里所有人都能同步。

在这套体系里，技能跟插件不是一个东西。插件是改写了工具本身行为的代码，技能只是“更聪明的使用说明书”。所以它几乎没有侵入性，卸载了 superpowers，你的项目代码不会受到任何影响。这一点对很多核心系统特别友好——你不需要让 AI 拿到代码执行权限，只需要让它更懂你的工程上下文。

2. 安装与初始化：从零接上 superpowers

2.1 环境准备与安装

在动手之前，先确认你本地的环境。superpowers 是一个基于 Node.js 的命令行工具，所以前提是机器上有 Node.js 环境，建议版本在 18 以上。可以用node -v快速确认。没有 Node.js 的话，先去官网装一个 LTS 版本，这一步没有捷径。

安装用的命令是 npm 全局安装，以我写这篇博客时的常见发布方式来看，入口是 npm 包superpowers。不同版本、不同仓库源的包名可能略有差异，有的教程里会看到@superpowers/cli这样的写法，这属于正常的包名命名差异，实际以官方文档为准。我自己执行的是：

npm install -g superpowers

装完之后验证一下：

superpowers --version

如果能看到版本号，说明装好了。这里有一个新手很容易踩的坑：如果你用 macOS 并且之前装过 Python、Ruby 之类的东西，npm 全局目录的权限经常出问题。我在 Linux 服务器和 macOS 上都碰到过EACCES权限报错，解决办法是用nvm管理 Node.js，而不是用系统自带的 Node，这样全局安装目录在你的用户目录下，权限清爽很多。

2.2 初始化并接入 Codex

安装好命令行工具之后，接着要在你的项目里初始化 superpowers。进入项目根目录，执行：

cd your-project superpowers init

初始化过程会做几件事：创建一个.superpowers/目录，用来存放技能文件；扫描项目当前使用的编码智能体类型；自动改写或生成AGENTS.md（Codex 使用的项目级指令文件）或者CLAUDE.md，在里面写入一段“调用技能”的指引。

如果你是 Codex 用户，这一步很关键。Codex 官方支持读取仓库根目录的AGENTS.md，把它作为项目上下文的强制输入。superpowers init 做的事情本质上就是：帮你把“技能库的索引”注入到 Codex 每次启动都会读的这份文件里。之后再运行codex，它就已经知道自己旁边有技能库这个东西了。

注意：有些项目里已经手工维护了一份AGENTS.md，初始化前最好先备份。superpowers 在改写文件时通常不会删除你原来的内容，而是在末尾追加，但我见过某些旧版本处理得比较粗暴，所以有备无患。

2.3 目录结构说明

初始化完成之后，你会看到类似这样的结构：

your-project/ ├── .superpowers/ │ ├── skills/ │ ├── templates/ │ └── config.json ├── AGENTS.md ├── package.json └── ...

.superpowers/skills/就是技能库的存放位置。每一个技能可以是一个 Markdown 文件，也可以是一个目录，目录里除了主文件还能附带脚本和资源。config.json记录当前项目的配置，比如启用了哪些技能包、自动更新策略之类的。AGENTS.md是被注入的索引文件。

我个人的习惯是把这个目录也提交进 Git。有人会觉得项目里的“AI 配置文件”不该进版本库，但我的经验相反：技能库本质上是团队知识的沉淀，是文档的一部分，不进 Git 的话，每个人本地的技能版本会越来越不一致，最后变成“在我机器上是好的”。

3. 使用指南：技能怎么写、怎么被调用

3.1 技能文件的基本格式

superpowers 的技能文件不是随便写写就行的，它有固定的结构。一个标准的技能文件包含两部分：YAML 格式的 frontmatter 元数据，以及正文部分。frontmatter 里最重要的两个字段是name和description。

--- name: java-build-debug description: 分析 Java Maven 项目构建失败的原因，包括依赖冲突、编译器错误、测试失败三类常见场景。 when_to_use: 当 Maven 构建失败、编译报错、测试不过且需要诊断根因时使用。 ---

重点说说description字段。这个字段是智能体判断“要不要使用该技能”的唯一依据，写得好不好直接影响技能能不能被正确触发。你要是写成“这个技能用于 Java”，那等于没写，智能体在任何 Java 任务里都可能去加载它，浪费 token 不说，还可能因为内容不匹配而误判。我的建议是描述里至少包含三层信息：适用场景、技术栈、具体触发条件。参考上面的例子，“Maven 构建失败”是场景，“依赖冲突、编译器错误、测试失败”是具体信号，“诊断根因”是任务目标。

正文部分就是技能的主体内容，通常包括操作步骤、注意事项、检查清单。和普通文档不同，技能文件更接近“标准操作流程”，语言要指令化，少废话。比如你可以写“先执行mvn dependency:tree -Dverbose检查依赖树，再根据冲突报错定位 pom.xml 中的排除项”，而不是写一大堆“依赖管理是 Maven 的核心功能之一”。

3.2 写一个 Java 技能实例

光说格式不够直观，我这里给一个完整的、可以直接抄的 Java 技能示例。这个技能解决的是“Java 项目代码审查”问题——我实际在团队里就是靠它统一了 Codex 做 code review 时的关注点。

--- name: java-code-review description: 对 Java 代码进行审查，重点检查空指针风险、并发安全问题、资源泄漏、异常被吞、SQL 注入隐患。 when_to_use: 当用户要求审查 Java 代码、提交 merge request 前检查、或者询问某段代码是否存在隐患时使用。 --- # Java 代码审查技能 ## 审查范围 1. 空指针风险：检查所有链式调用、Optional 的 orElseGet/orElse 使用、方法入参是否可能为 null。 2. 并发安全：检查共享变量是否有 volatile 或 synchronized 保护，线程池使用是否规范，是否使用 ConcurrentHashMap 代替 HashMap。 3. 资源泄漏：检查 InputStream、Connection、Statement 是否在 finally 或 try-with-resources 中关闭。 4. 异常处理：检查 catch 块是否吞掉异常，是否打印了足够上下文的日志，是否抛出了可读性强的业务异常。 5. 安全性：检查字符串拼接 SQL、反射调用、不安全的反序列化。 ## 审查输出格式 对每个问题按以下格式输出： - 文件位置 - 问题类型（严重/建议） - 问题描述 - 修改建议 ## 禁止事项 不要为了建议而建议，不要修改和当前任务无关的代码格式。

你可能会问：这跟手工在 Codex 的提示词里写一段“请按以下规范审查”有什么区别？区别在于触发机制。提示词需要你每次重复，技能是靠description自动匹配的。你只要说一句“帮我把改动 review 一下”，Codex 读到任务描述里有 review、Java 这些词，就会主动去加载这个技能文件，不需要你再贴一遍规则。一次编写，所有后续会话持续生效。

3.3 技能调用机制剖析

这背后究竟发生了什么？我一开始也觉得神奇，后来扒了一下实现思路才弄明白。superpowers 本质上是给编码智能体提供了一个“按需阅读索引”。它在AGENTS.md里写入的指引大致意思是：

1. 当接收到任务时，先检查.superpowers/skills/目录下有哪些技能文件。
2. 阅读技能文件 frontmatter 里的name和description，判断是否与当前任务相关。
3. 如果相关，读取该技能文件正文，并严格按正文指示工作。
4. 如果多个技能都相关，按任务的主次顺序加载。

这个机制生效的前提是智能体本身具备“工具调用”或“迭代式阅读文件”的能力。Codex、Claude Code 这类智能体在执行任务时，天然会去读项目里的说明文件，superpowers 只是在说明文件里精确地埋了“钩子”，告诉它往哪里翻。所以它不是一个后台守护进程，也不是魔法。它的高明之处在于极其克制：不抢智能体的执行权，只负责把知识和规则整理到“伸手就能够到”的位置。

实操心得：技能文件不要让智能体一次性全读。我见过有人在一个技能文件里写了三千行，结果智能体读取大量内容后，反而忽略关键技术点。一个技能解决一件事，每个文件控制在 100 行上下，效果是最好的。复杂问题拆分技能包，比如 Java 的审查、构建、测试分成三个独立技能。

4. Java 项目实战：用 superpowers 管好构建和测试

4.1 实战前的 Java 项目准备

前面讲了通用用法，这一节我拿一个真实场景——Java 单体应用项目——来完整演示一遍。我手头有一个 Spring Boot 项目，Maven 构建，模块化结构，测试分单元测试和集成测试两层。在这个项目里，AI 编码助手以前的表现不太稳定，主要是三个问题：不知道集成测试需要先启动 Testcontainers；遇到 Maven 依赖冲突时只会建议升级版本，不会分析依赖树；写单元测试时经常写出依赖 Spring 上下文的“伪单元测试”，跑一次要十秒。

接入 superpowers 之前，我在AGENTS.md里写过一大段项目规范，但效果一般。后来我把这些规范全部改成了技能文件，每个问题一个独立技能。这里要说明一下：改造不是把原来的文档拆开就算完，而是要站在“智能体会怎么触发”的角度重新组织内容。

4.2 设计一组 Java 技能包

我最终给这个项目设计了四个技能，放在.superpowers/skills/下：

这里最值得聊的是spring-test-guideline.md里面的一条规则。之前智能体写测试经常直接@SpringBootTest一把梭，启动整个应用上下文，慢得要命。我在技能文件里明确写了触发条件：

## 测试类型选择 - 如果测试只涉及一个 Service 类，优先使用 Mockito 直接 mock 依赖，不要启动 Spring 上下文。 - 如果必须校验 MyBatis 映射或 JPA 查询，再使用 @MybatisTest 或 @DataJpaTest 切片测试。 - 只有完整的接口/集成测试才允许使用 @SpringBootTest，且必须配合 Testcontainers。

这条规则写成技能之后，Codex 写出的测试文件风格明显变了。倒不是它忽然变聪明了，而是因为技能文件把“什么场景用什么策略”写成了明确的决策树，智能体只需要照着选项走。

Maven 依赖冲突那个技能我写得最简单，核心就是先执行诊断命令，再根据输出决定处理方式：

mvn dependency:tree -Dverbose mvn dependency:analyze

这个动作本身不复杂，但很能说明问题：智能体在遇到依赖冲突时，默认行为往往是去 Maven 中央仓库找“最新版本”然后升级。有了技能文件，它才会意识到先看依赖树、确认冲突来源，再用排除依赖或者调整 import 顺序来解决问题。行为路径变了，结果完全不一样。

4.3 实战效果与我的体感

跑了两周之后，这个项目里 Codex 的表现变化我觉得是质变。以前提交代码前让 AI 做一轮 review，它的关注点经常漂移，喜欢挑代码风格、变量命名的毛病，对真正的风险点——比如一个catch (Exception e)把异常吞了的隐患——反而视而不见。有了java-code-review技能之后，它的检查顺序稳定下来了，先看空指针、再检查资源释放、最后才看安全漏洞，确实像“见过世面的老手”。

另一个体感是在上下文占用上。以前为了让 AI 遵守项目规范，我在提示词里夹带各种约束，一次会话要多花好几千 token。技能机制是“用到才读”，大部分会话它根本不加载相关技能，省下来的 token 很可观。当然这不是 superpowers 这个工具直接省出来的，而是“按需加载”这个模式带来的效率红利。

避坑提醒：技能文件里写的命令，一定是当前项目真正可用的命令。我同事曾经把mvn clean install -DskipTests写进技能，结果团队的 CI 里必须跑测试，这个技能反而干扰了 Agent 的判断。技能是给 Agent 用的“默认行为”，里面的每条指令都要对当前环境负责。

5. 常见问题与排查记录

5.1 技能不被加载

用这类工具最烦的一件事就是：明明技能写得没问题，智能体就是不理它。我排查过几次，大部分情况下是description写得不够“可匹配”。智能体判断要不要读技能，本质上是一个语义匹配过程，描述里缺关键词或者描述得太大而空，匹配率就会很低。

比如有人把description写成“Java 相关”，结果智能体在做一个 Spring Boot 接口开发任务时，根本不会把这个技能跟眼前代码联系起来。改成“开发 Spring Boot RESTful 接口，包括 Controller、Service、Mapper 三层结构与异常处理”之后，匹配率瞬间提高。

还有一种情况是AGENTS.md没有被正确读取。Codex 对AGENTS.md的读取位置有约定，除了项目根目录，还有用户目录下的全局配置。你的技能索引如果写错了位置，智能体自然看不到。排查时先确认初始化指令生成的索引文件在哪个目录，再确认里面有明确指向.superpowers/skills/的路径。

5.2 命令找不到或版本不对

有些朋友装完 superpowers 之后，第一次执行就报command not found。这个事 90% 是因为 npm 全局安装目录不在系统的 PATH 里。用 nvm 安装 Node.js 的情况下，全局二进制通常软链到了~/.nvm/versions/node/xxx/bin/，正常来说不会被漏掉。如果是自己编译的 Node 或者用 apt 装的，就可能踩这个坑。

我的建议是装完立刻验证：

which superpowers superpowers --version

如果which有结果但--version报错，大概率是版本太旧或者包名搞混了。卸载重装时记得清一下 npm 缓存：

npm uninstall -g superpowers npm cache clean --force npm install -g superpowers

这种基础问题看着简单，实际在新环境里最容易卡住人。

5.3 和团队协作时的细节

最后说一个多人协作的细节。技能库进 Git 之后，理论上全团队共享，但实际运行的智能体类型可能不一样——有人用 Codex，有人用 Claude Code，还有人用 Gemini CLI。不同智能体对技能文件的读取方式有细微差异，有些对 frontmatter 的字段要求更严格，有些会自动把技能文件当成工具来调用。

我在多智能体共存的团队里试过一段时间，结论是：技能文件尽量写得“口径统一”，不要依赖某个特定智能体的私有特性，只在技能正文里使用通用的 Markdown 结构。这样同一个技能目录，三款智能体都能使用。至于 superpowers 的版本更新，建议固定在一个经过验证的版本上，不要逢更新就升，等你确认新版本没有破坏技能索引结构再升级不迟。

对于 Java 项目，还有一个特殊建议：技能文件里提到的包名、类名、模块路径如果经常变，最好用相对路径而不是绝对路径，不然项目重构一次，技能文件里的命令就失效一次。我在一个多模块 Maven 项目里吃过这个亏，后来统一约定技能里的命令都从仓库根目录执行，并写明-pl参数指定模块，再没报过路径错误。

写在最后：一点个人经验

用 superpowers 这段时间，我最深的感觉是：这类工具真正解决的其实是“知识管理”的问题。AI 编码助手的能力上限，不仅仅取决于模型本身，还取决于我们有没有把工程知识用它看得懂的方式喂给它。技能文件就是一种让知识结构化、可复用、可检索的形式。我个人现在不管项目大小，初始化之后的第一件事就是先给 AI 建两三个最核心的技能文件，一个管构建，一个管测试，一个管代码审查。这三个跑顺了，日常开发能省下大量沟通成本。

最后再分享一个小技巧：技能的编写不要追求“一劳永逸”。我的习惯是每次 AI 在项目里犯了明显的错误，就把错误场景和正确做法补进对应技能文件里。这相当于让 AI 手里那本“操作手册”持续迭代，越用越顺手。整个项目团队的工程经验，也就这样一天天沉淀进了那个.superpowers/目录里。