最近我一直在折腾一个叫superpowers的项目。起因很朴素我用 Codex 写代码每开一个新对话都要把项目结构、代码规范、测试命令这些事重新交代一遍稍微漏一句它就给我写出一个风格突兀的模块。后来有人告诉我你缺的不是更好的模型是一个能让 AI 带上“记忆”和“技能”的增强层。Superpowers 就是干这个的。这篇文章不是官方文档是我把 superpowers 装进日常开发流程之后的一次完整复盘。内容包括它解决了什么问题、怎么安装、怎么在 Codex 里调用以及在 Java 项目里的一个实战例子。如果你用的是 WorBuddy 这类图形客户端我也会分享怎么把技能库接进去。不管你是第一次听说还是已经装了但用不起来应该都能在里头找到点有用的东西。1. Superpowers 到底补上了哪块短板AI 对话里的“失忆症”1.1 默认状态下Codex 为什么总在重复踩坑用 Codex 写过项目的人都懂一个奇特的体验同一个仓库上午让它写工具函数下午让它改测试它就像换了个新人来干活。模块命名不对、日志风格不统一、明明项目里已有工具类它还要重新造一个轮子。问题不在模型笨而在大多数对话型编程助手都是“无状态”的。所谓的无状态指的是每次对话只保留你当前窗口里的内容。模型确实能看代码上下文但它不会自动记住你昨天在配置文件里约定过的东西也不会主动翻你三个月前写的那份编码规范。你给它的 prompt 里没有它就按照网络上的通用风格自由发挥。这跟带实习生有点像你招了个底子不错的新人但每天上班都要重新告诉他一遍“我们这边变量名用驼峰、异常必须包一层业务错误码、改动前先跑下这两条测试”新人一听就懂隔天又忘了。靠反复提醒不是长久之计尤其当你同时维护两三个项目的时候。每个项目的规范不同A 项目用 Maven 多模块B 项目全是 Gradle Kotlin DSLC 项目连 JDK 版本都不一样。这堆信息不可能塞进每次对话的第一条消息里而且塞进去也未必会被模型认真对待。我们需要一种机制让 AI 在“开工之前”就把项目约定和操作流程加载好而不是靠你一遍遍说。1.2 技能包机制把经验从对话里拿出来放进文件里Superpowers 的核心做法是把“经验”从对话里抽出来放进结构化的技能文件里。每个技能文件一般用 Markdown 写开头带一段 YAML 格式的元信息包括技能名称、作用描述、什么情况下会自动触发、具体执行步骤、一个例子甚至还有一个检查清单。比如你可以定义一个code-review技能描述是“用 SonarQube 规则扫描当前改动识别空指针风险和资源泄漏”。那么在你的对话里提到“帮我 review 一下刚改的这段代码”时Codex 会先加载这个技能再按照技能里写的步骤去执行。它不再是自由发挥而是有一份“操作手册”在约束它。技能文件的加载并不是把所有内容一次性吞进上下文那样太占 token 了。通常的做法是先加载所有技能的“目录页”也就是名称和描述当用户需求命中某个技能的描述或触发词时才把完整的技能正文放进来。这很像 IDE 里的插件平时安安静静躺着用到的时候才激活。1.3 Superpowers 和普通提示词模板的差别可能有人会觉得这不就是把提示词模板写进文件吗我自己一开始也这么想实际用下来差别还挺明显的。普通提示词模板是“一次性”的你复制粘贴到对话框里AI 执行完就完了它不知道自己当前正在使用什么技能也不会在流程中途停下来检查是否偏离了目标。技能文件不一样它是一等公民AI 能感知到“当前启用了哪个技能”能按照技能里定义的步骤分阶段执行还能在多个技能之间编排切换。举个例子一个稍大的 Java 重构任务你可以先启用plan技能做任务拆解等方案确认后再启用refactor技能做具体代码修改最后用test技能生成测试并验证。这个流程本身也是技能定义的plan 技能的输出会成为 refactor 技能的输入。这种组合能力和可维护性是单纯堆提示词给不了的。另外技能文件天然适合进 Git。团队里谁改了什么技能评审一下合并进去新人拉下来就能用。提示词模板能做到吗也能但大家基本不会给模板写测试、写版本说明因为它的形态决定了它会被当成“一次性的东西”。2. 安装与初始化从零把技能库跑起来2.1 先搞清楚自己缺的是哪一层第一次装 Superpowers 的人很容易有一个误解觉得它是一个独立软件装完就有个图形界面能点。实际上它更像一个技能加载器做的事情是让 Codex 这类编码助手学会“看技能文件并按技能内容干活”。所以安装要分两步走先把技能库下载到本地再让 Codex 知道技能库在哪。环境方面我建议至少满足三个条件有 Git用来拉取技能库装了 Node.js 18 或更高版本部分安装脚本依赖它Codex 或兼容客户端的版本别太老老版本可能不认识技能目录配置后面会单独说。我用的是 macOS路径都能跑通Windows 上需要注意的坑我会放到第五节展开。2.2 安装步骤安装命令在不同维护版本里会有一点差异最好以你拉取到的仓库 README 为准。我这里分享的是我认为最稳的一条路线# 1. 把技能库克隆到固定目录我习惯放 ~/.superpowers git clone 官方仓库地址 ~/.superpowers # 2. 进入目录跑安装脚本 cd ~/.superpowers node setup.js # 3. 把技能目录写入 Codex 配置 codex config set skills_dir ~/.superpowers/skills第一步如果网络不行就手动下载压缩包解压到~/.superpowers效果一样。第二步不是每个版本都有如果提示找不到setup.js直接打开目录看看有没有说明文件通常会有install.sh或npm run setup这类入口。第三步最核心skills_dir这个配置项指向的是包含各个技能 Markdown 文件的父目录不是技能文件本身。装完之后我还建议把技能库路径加到 shell 配置文件里这样 WorBuddy 这类图形客户端启动时也能继承环境变量# 在 ~/.bashrc 或 ~/.zshrc 里追加 export SUPERPOWERS_DIR$HOME/.superpowers export SKILLS_DIR$SUPERPOWERS_DIR/skills2.3 验证安装第一次运行配置完不要急着写代码先确认技能库真的被读到了。我的做法是跑一下这条命令superpowers list如果能输出一组技能名称和说明说明 CLI 层面的安装没问题。如果你用的是 Codex 自带的环境也可以直接在对话里问一句“你现在能使用哪些技能”它会把已加载的技能目录展示出来。常见的情况是命令成功但列表是空的。这通常是因为SKILLS_DIR指向的目录里没有技能文件或者技能文件的头部 YAML 格式写错了。有一个笨办法百试百灵直接手动把技能目录路径告诉 Codex不给环境变量也不依赖默认值而是在对话开头写“请从/home/me/.superpowers/skills加载技能”然后再问技能列表。能加载说明路径配置有问题还是空说明技能文件本身有问题。3. 在 Codex 里调用技能的正确姿势3.1 两种触发方式技能加载好了不代表你非要手动喊它。Superpowers 支持两种触发方式。第一种是显式触发适合你很清楚自己要用什么技能的场景。在输入框里写斜杠命令就行/superpowers:plan 目标拆分 UserService 约束保持现有接口不变这种触发方式的优点是明确AI 不会理解偏而且参数可以直接写在命令后面。我建议刚开始接触时全部用显式触发把每个技能的真实效果摸一遍建立直觉。第二种是隐式触发也就是让 AI 根据你的描述自动匹配技能。比如你定义了一个spring-boot-test技能它的触发词包含“测试”“JUnit”“覆盖率”那么当你在对话里说“给这块逻辑补点单测”时AI 会自动加载这个技能。这个模式的体验最好但也有代价触发词设计得宽泛容易误触发设计得太窄该触发的时候又没反应。所以我的原则是核心流程用显式日常小需求用隐式。3.2 给技能传参数的技巧技能和函数有点像参数给得好不好直接决定输出质量。刚开始我只会在命令后面跟一句话比如“帮我做代码审查”结果 AI 加载了技能但不知道该把力气用在哪儿最后给了一堆通用建议。后来我学会把参数写得像验收标准/superpowers:code-review 范围UserService.java 重点并发安全 过滤格式化噪音这几个参数的作用分别是指定审查对象防止它全仓库乱翻告诉它当前最关心的问题让它忽略空行、注释、缩进这类无关紧要的改动。技能内部如果定义过参数解析规则AI 会按规则执行如果没定义它也会把范围、重点、过滤当成约束条件来理解。反正比一句“review 下代码”强多了。3.3 一次会话里只加载 2~3 个技能Superpowers 给你配置了很多技能不代表你要一次性全塞进对话里。我踩过一个很典型的坑在一个重构任务里同时启用了plan、review、refactor、test四个技能结果 AI 的回复开始“四不像”——一会儿在列计划一会儿又在写测试中场还跳出来做代码评审。上下文被技能文档塞得很满模型的注意力被分散输出质量反而下降。现在的习惯是一个阶段最多激活两个技能完成一个再叫下一个。大的重构流程最多用到 plan、refactor、test 三个技能而且 review 技能通常留在 refactor 完成之后单独跑。这个取舍很重要技能是给你续命的工具不是越多越好的装饰品。4. 实战在 Java 项目里让 Superpowers 帮我重构老代码4.1 场景与目标说一个我最近实际处理的例子。项目是一个 Spring Boot 2.x 的老服务里面有个UserService七百多行里面既做参数校验、又做权限判断、还负责发通知和保存用户信息。每次加需求都要在这个类里改半天测试覆盖率还特别低。我的目标是用 Superpowers 把重构过程跑顺具体是三步先拆任务、再做代码修改、最后补测试。前提是外部接口不能变不能因为重构让调用方跟着改。先贴一段简化后的原代码方便你理解场景public class UserService { public User register(String email, String password) { validateEmail(email); validatePassword(password); checkDuplicateEmail(email); sendWelcomeEmail(email); User user new User(email, password); userMapper.insert(user); return user; } private void validateEmail(String email) { /* 100 lines */ } private void validatePassword(String password) { /* 100 lines */ } private void checkDuplicateEmail(String email) { /* 80 lines */ } private void sendWelcomeEmail(String email) { /* 80 lines */ } }4.2 技能编排plan、review、test 三段式我先用 plan 技能把任务拆开。命令是这样写的/superpowers:plan 目标拆分 UserService 约束接口不变 输出重构步骤AI 加载 plan 技能后给的输出大致包括把校验逻辑抽成独立的UserValidator把邮件通知抽成UserNotifier把用户创建和检查重复的操作收敛到UserRepository内UserService只保留注册流程的编排。每步都标出了影响面还给了风险点提示比如sendWelcomeEmail的失败处理要保留原逻辑。方案确认后我调 refactor 技能让它动手改/superpowers:refactor 计划上一步输出 保持接口签名不变 不用改动测试代码这一步 AI 生成了新的类结构并保留原有调用入口。期间我发现一个细节plan 技能说的是“抽成 UserRepository”但项目里原本已经有一个UserRepository接口如果直接抽类会出现命名冲突。所以我在参数里补了一句“如果命名冲突使用 UserQueryRepository”。这个补充提示非常重要能避免 AI 在命名上自作聪明。最后调 test 技能来补测试计划/superpowers:test 目标UserService 框架JUnit5 Mockito 要求覆盖重构后的核心分支test 技能没有直接生成几百行测试而是先给了一份测试策略表格列出需要覆盖的用例注册成功、邮箱重复、密码弱、邮件发送失败。每个用例标出 mock 哪些依赖、断言哪些行为。我觉得方向没问题才让它继续生成具体测试代码。Test void register_shouldCreateUser_whenInputValid() { when(userMapper.findByEmail(ab.com)).thenReturn(Optional.empty()); User user userService.register(ab.com, StrongPass1!); verify(userMapper).insert(argThat(u - u.getEmail().equals(ab.com))); }4.3 实测效果与翻车现场流程走到这一步看起来顺利但第一次实际跑测试时直接红了一片。报错信息指向UserService构造方法里的依赖注入AI 把EmailSender换了个名字但applicationContext.xml里对应的 Bean 还是老名字启动就失败了。这个坑其实很有代表性。Superpowers 把重构步骤执行得很规范但它只知道自己生成的代码不知道你项目配置里那些隐式约定。哪怕它已经读了一部分项目文件也没法像老开发那样对每个 Bean 名字都门清。我的排查过程是这样的先看测试日志确认是依赖注入失败再打开改动记录对比 AI 改过的类名和 Bean 定义发现问题后没让 AI 直接改而是回滚了那一个类的改动在命令里明确告诉它“项目里 Bean 名是 emailSender保持这个不动”重新生成后才通过。这个翻车也给我提了个醒技能文件里应该加一条固有约束——所有注入点和 Bean 名称必须从现有配置里读取不允许自己命名。技能给出的流程再漂亮最终检查漏洞的人还是你。5. 在 WorBuddy 等图形客户端里配置 Superpowers5.1 WorBuddy 和 Codex 的关系经常有人在搜“WorBuddy 怎么用 superpowers”我猜你是把 WorBuddy 当成一个独立的 AI 编程产品了。按我目前的理解WorBuddy 更像是把 Codex 这类编码助手包了一层图形界面的客户端底层还是调用 Codex 的能力。也就是说Superpowers 不能单独“装进 WorBuddy”而是要让 WorBuddy 背后那个 Codex 进程找到技能目录。这听起来绕其实就一句话你在 Codex CLI 里怎么配在 WorBuddy 里就怎么配只不过多了一道入口。如果 WorBuddy 提供了设置面板直接搜skills相关选项如果找不到那就得手动改配置文件。5.2 图形界面里的三种配置入口我见过三种常见情况。第一种设置面板里有Skills Directory字段直接填~/.superpowers/skills就行。第二种设置面板里没有技能选项但提供了“自定义环境变量”区域那就把SKILLS_DIR加进去。第三种两者都没有只能手动编辑客户端的数据文件。这类客户端一般会把配置放在用户目录下文件名类似config.json或settings.json找到后往里面塞一段{ codex: { skillsDir: ~/.superpowers/skills, disabledSkills: [] } }改完重启客户端再用“你现在能使用哪些技能”来验证。有时候界面里配置文件默认是隐藏的可以用文件管理器开启“显示隐藏文件”或者直接在配置目录里用 CtrlL 输入路径跳转。5.3 一条最容易踩的路径坑图形客户端配置里最常翻车的是路径问题。在 Windows 上默认路径是C:\Users\你\.superpowers\skills如果\没转义或者路径中间带空格AI 在读取技能目录时就会解析失败表现是“技能列表为空”。解决办法是统一使用用户目录的~缩写或者把技能库放在一个不带空格的路径下比如D:\tools\superpowers-skills。如果你看到报错信息里有unexpected token或ENOENT多半就是路径没写对别急着怀疑技能文件坏了。另一个很多人忽略的点是图形客户端往往不会自动刷新技能目录。你新增了一个技能文件客户端里立刻用是没用的需要先重启会话或重新初始化客户端让它重新扫描目录。这个“重启会话”的动作放在命令行里就是新开一个 Codex 对话放在 WorBuddy 里就是点新建对话。6. 技能文件组织与排错清单6.1 技能文件的结构长什么样自己动手写技能之前建议先拆一个内置技能看看结构。一个标准的技能文件长这样--- name: spring-boot-test description: 为 Spring Boot 模块生成测试策略与 JUnit 代码 triggers: - 测试 - junit - 覆盖率 --- ## 执行步骤 1. 读取当前模块的 pom.xml确认 Spring Boot 版本。 2. 定位待测类列出公开方法和依赖。 3. 按方法分支生成测试用例覆盖正常与异常路径。 4. 使用 Mockito 隔离外部依赖。 ## 约束 - 不修改被测类的原有逻辑。 - 测试方法命名使用 given_when_then 风格。 - 每个用例必须写清楚断言目标。头部name是技能的唯一名字description用于让 AI 判断什么场景该激活它triggers是隐式触发的关键词列表。正文部分可以自由发挥但最好把“步骤”和“约束”分开写。约束是给 AI 画的红线没有了它技能就退化成一个普通的提示词。6.2 高频报错与解决我用表格整理一下自己遇到的高频问题方便你直接对照现象可能原因解决办法技能列表为空SKILLS_DIR没生效重新设置环境变量或在新对话里显式指定目录命令敲了没反应Codex 版本太旧更新 Codex或换成显式触发方式技能激活后回答很泛技能文件缺少步骤和约束补上执行步骤与禁止事项多个技能互相干扰一次加载技能太多同一阶段最多保留 2~3 个技能Windows 下无法加载路径带空格或编码异常把技能库挪到纯英文无空格路径6.3 维护策略别让技能库变成垃圾场Superpowers 用顺手之后很容易陷入另一种状态见什么都想封装成技能过两周回头一看目录里躺着几十个从没用过的技能。技能文件不是越多越好每多一个技能AI 在启动时就要多扫描一次误触发的概率也多一分。我现在会做三件事控制技能库规模。第一把技能分成“稳定区”和“试验区”。稳定区是已经验证过、真正能提升效率的技能放主目录试验区是新写的、还不确定效果的技能放在单独文件夹里。验证通过再升到稳定区。第二给技能文件带上前置条件。比如某个技能只适用于 Maven 单模块工程就在description里写清楚适用范围避免在 Kotlin DSL 项目里被误激活。第三定期用superpowers doctor一类的诊断命令检查技能文件格式能自动发现 YAML 语法错误和缺失字段。维护技能库和写代码很像少一点、精一点长期收益才高。我自己的体会是别把技能当成“把网上的最佳实践抄进来”的东西而是把它当成你自己团队的开发约定。真正好用的技能描述里写的是目标和边界而不是一步步教 AI 怎么写代码。这个思路反过来也帮我理清了日常开发里哪些规则是反反复复靠人肉提醒的全把它们固化下来之后新对话再也不会从零开始。
Superpowers技能库实战：让Codex告别对话失忆，提升AI编码效率
最近我一直在折腾一个叫superpowers的项目。起因很朴素我用 Codex 写代码每开一个新对话都要把项目结构、代码规范、测试命令这些事重新交代一遍稍微漏一句它就给我写出一个风格突兀的模块。后来有人告诉我你缺的不是更好的模型是一个能让 AI 带上“记忆”和“技能”的增强层。Superpowers 就是干这个的。这篇文章不是官方文档是我把 superpowers 装进日常开发流程之后的一次完整复盘。内容包括它解决了什么问题、怎么安装、怎么在 Codex 里调用以及在 Java 项目里的一个实战例子。如果你用的是 WorBuddy 这类图形客户端我也会分享怎么把技能库接进去。不管你是第一次听说还是已经装了但用不起来应该都能在里头找到点有用的东西。1. Superpowers 到底补上了哪块短板AI 对话里的“失忆症”1.1 默认状态下Codex 为什么总在重复踩坑用 Codex 写过项目的人都懂一个奇特的体验同一个仓库上午让它写工具函数下午让它改测试它就像换了个新人来干活。模块命名不对、日志风格不统一、明明项目里已有工具类它还要重新造一个轮子。问题不在模型笨而在大多数对话型编程助手都是“无状态”的。所谓的无状态指的是每次对话只保留你当前窗口里的内容。模型确实能看代码上下文但它不会自动记住你昨天在配置文件里约定过的东西也不会主动翻你三个月前写的那份编码规范。你给它的 prompt 里没有它就按照网络上的通用风格自由发挥。这跟带实习生有点像你招了个底子不错的新人但每天上班都要重新告诉他一遍“我们这边变量名用驼峰、异常必须包一层业务错误码、改动前先跑下这两条测试”新人一听就懂隔天又忘了。靠反复提醒不是长久之计尤其当你同时维护两三个项目的时候。每个项目的规范不同A 项目用 Maven 多模块B 项目全是 Gradle Kotlin DSLC 项目连 JDK 版本都不一样。这堆信息不可能塞进每次对话的第一条消息里而且塞进去也未必会被模型认真对待。我们需要一种机制让 AI 在“开工之前”就把项目约定和操作流程加载好而不是靠你一遍遍说。1.2 技能包机制把经验从对话里拿出来放进文件里Superpowers 的核心做法是把“经验”从对话里抽出来放进结构化的技能文件里。每个技能文件一般用 Markdown 写开头带一段 YAML 格式的元信息包括技能名称、作用描述、什么情况下会自动触发、具体执行步骤、一个例子甚至还有一个检查清单。比如你可以定义一个code-review技能描述是“用 SonarQube 规则扫描当前改动识别空指针风险和资源泄漏”。那么在你的对话里提到“帮我 review 一下刚改的这段代码”时Codex 会先加载这个技能再按照技能里写的步骤去执行。它不再是自由发挥而是有一份“操作手册”在约束它。技能文件的加载并不是把所有内容一次性吞进上下文那样太占 token 了。通常的做法是先加载所有技能的“目录页”也就是名称和描述当用户需求命中某个技能的描述或触发词时才把完整的技能正文放进来。这很像 IDE 里的插件平时安安静静躺着用到的时候才激活。1.3 Superpowers 和普通提示词模板的差别可能有人会觉得这不就是把提示词模板写进文件吗我自己一开始也这么想实际用下来差别还挺明显的。普通提示词模板是“一次性”的你复制粘贴到对话框里AI 执行完就完了它不知道自己当前正在使用什么技能也不会在流程中途停下来检查是否偏离了目标。技能文件不一样它是一等公民AI 能感知到“当前启用了哪个技能”能按照技能里定义的步骤分阶段执行还能在多个技能之间编排切换。举个例子一个稍大的 Java 重构任务你可以先启用plan技能做任务拆解等方案确认后再启用refactor技能做具体代码修改最后用test技能生成测试并验证。这个流程本身也是技能定义的plan 技能的输出会成为 refactor 技能的输入。这种组合能力和可维护性是单纯堆提示词给不了的。另外技能文件天然适合进 Git。团队里谁改了什么技能评审一下合并进去新人拉下来就能用。提示词模板能做到吗也能但大家基本不会给模板写测试、写版本说明因为它的形态决定了它会被当成“一次性的东西”。2. 安装与初始化从零把技能库跑起来2.1 先搞清楚自己缺的是哪一层第一次装 Superpowers 的人很容易有一个误解觉得它是一个独立软件装完就有个图形界面能点。实际上它更像一个技能加载器做的事情是让 Codex 这类编码助手学会“看技能文件并按技能内容干活”。所以安装要分两步走先把技能库下载到本地再让 Codex 知道技能库在哪。环境方面我建议至少满足三个条件有 Git用来拉取技能库装了 Node.js 18 或更高版本部分安装脚本依赖它Codex 或兼容客户端的版本别太老老版本可能不认识技能目录配置后面会单独说。我用的是 macOS路径都能跑通Windows 上需要注意的坑我会放到第五节展开。2.2 安装步骤安装命令在不同维护版本里会有一点差异最好以你拉取到的仓库 README 为准。我这里分享的是我认为最稳的一条路线# 1. 把技能库克隆到固定目录我习惯放 ~/.superpowers git clone 官方仓库地址 ~/.superpowers # 2. 进入目录跑安装脚本 cd ~/.superpowers node setup.js # 3. 把技能目录写入 Codex 配置 codex config set skills_dir ~/.superpowers/skills第一步如果网络不行就手动下载压缩包解压到~/.superpowers效果一样。第二步不是每个版本都有如果提示找不到setup.js直接打开目录看看有没有说明文件通常会有install.sh或npm run setup这类入口。第三步最核心skills_dir这个配置项指向的是包含各个技能 Markdown 文件的父目录不是技能文件本身。装完之后我还建议把技能库路径加到 shell 配置文件里这样 WorBuddy 这类图形客户端启动时也能继承环境变量# 在 ~/.bashrc 或 ~/.zshrc 里追加 export SUPERPOWERS_DIR$HOME/.superpowers export SKILLS_DIR$SUPERPOWERS_DIR/skills2.3 验证安装第一次运行配置完不要急着写代码先确认技能库真的被读到了。我的做法是跑一下这条命令superpowers list如果能输出一组技能名称和说明说明 CLI 层面的安装没问题。如果你用的是 Codex 自带的环境也可以直接在对话里问一句“你现在能使用哪些技能”它会把已加载的技能目录展示出来。常见的情况是命令成功但列表是空的。这通常是因为SKILLS_DIR指向的目录里没有技能文件或者技能文件的头部 YAML 格式写错了。有一个笨办法百试百灵直接手动把技能目录路径告诉 Codex不给环境变量也不依赖默认值而是在对话开头写“请从/home/me/.superpowers/skills加载技能”然后再问技能列表。能加载说明路径配置有问题还是空说明技能文件本身有问题。3. 在 Codex 里调用技能的正确姿势3.1 两种触发方式技能加载好了不代表你非要手动喊它。Superpowers 支持两种触发方式。第一种是显式触发适合你很清楚自己要用什么技能的场景。在输入框里写斜杠命令就行/superpowers:plan 目标拆分 UserService 约束保持现有接口不变这种触发方式的优点是明确AI 不会理解偏而且参数可以直接写在命令后面。我建议刚开始接触时全部用显式触发把每个技能的真实效果摸一遍建立直觉。第二种是隐式触发也就是让 AI 根据你的描述自动匹配技能。比如你定义了一个spring-boot-test技能它的触发词包含“测试”“JUnit”“覆盖率”那么当你在对话里说“给这块逻辑补点单测”时AI 会自动加载这个技能。这个模式的体验最好但也有代价触发词设计得宽泛容易误触发设计得太窄该触发的时候又没反应。所以我的原则是核心流程用显式日常小需求用隐式。3.2 给技能传参数的技巧技能和函数有点像参数给得好不好直接决定输出质量。刚开始我只会在命令后面跟一句话比如“帮我做代码审查”结果 AI 加载了技能但不知道该把力气用在哪儿最后给了一堆通用建议。后来我学会把参数写得像验收标准/superpowers:code-review 范围UserService.java 重点并发安全 过滤格式化噪音这几个参数的作用分别是指定审查对象防止它全仓库乱翻告诉它当前最关心的问题让它忽略空行、注释、缩进这类无关紧要的改动。技能内部如果定义过参数解析规则AI 会按规则执行如果没定义它也会把范围、重点、过滤当成约束条件来理解。反正比一句“review 下代码”强多了。3.3 一次会话里只加载 2~3 个技能Superpowers 给你配置了很多技能不代表你要一次性全塞进对话里。我踩过一个很典型的坑在一个重构任务里同时启用了plan、review、refactor、test四个技能结果 AI 的回复开始“四不像”——一会儿在列计划一会儿又在写测试中场还跳出来做代码评审。上下文被技能文档塞得很满模型的注意力被分散输出质量反而下降。现在的习惯是一个阶段最多激活两个技能完成一个再叫下一个。大的重构流程最多用到 plan、refactor、test 三个技能而且 review 技能通常留在 refactor 完成之后单独跑。这个取舍很重要技能是给你续命的工具不是越多越好的装饰品。4. 实战在 Java 项目里让 Superpowers 帮我重构老代码4.1 场景与目标说一个我最近实际处理的例子。项目是一个 Spring Boot 2.x 的老服务里面有个UserService七百多行里面既做参数校验、又做权限判断、还负责发通知和保存用户信息。每次加需求都要在这个类里改半天测试覆盖率还特别低。我的目标是用 Superpowers 把重构过程跑顺具体是三步先拆任务、再做代码修改、最后补测试。前提是外部接口不能变不能因为重构让调用方跟着改。先贴一段简化后的原代码方便你理解场景public class UserService { public User register(String email, String password) { validateEmail(email); validatePassword(password); checkDuplicateEmail(email); sendWelcomeEmail(email); User user new User(email, password); userMapper.insert(user); return user; } private void validateEmail(String email) { /* 100 lines */ } private void validatePassword(String password) { /* 100 lines */ } private void checkDuplicateEmail(String email) { /* 80 lines */ } private void sendWelcomeEmail(String email) { /* 80 lines */ } }4.2 技能编排plan、review、test 三段式我先用 plan 技能把任务拆开。命令是这样写的/superpowers:plan 目标拆分 UserService 约束接口不变 输出重构步骤AI 加载 plan 技能后给的输出大致包括把校验逻辑抽成独立的UserValidator把邮件通知抽成UserNotifier把用户创建和检查重复的操作收敛到UserRepository内UserService只保留注册流程的编排。每步都标出了影响面还给了风险点提示比如sendWelcomeEmail的失败处理要保留原逻辑。方案确认后我调 refactor 技能让它动手改/superpowers:refactor 计划上一步输出 保持接口签名不变 不用改动测试代码这一步 AI 生成了新的类结构并保留原有调用入口。期间我发现一个细节plan 技能说的是“抽成 UserRepository”但项目里原本已经有一个UserRepository接口如果直接抽类会出现命名冲突。所以我在参数里补了一句“如果命名冲突使用 UserQueryRepository”。这个补充提示非常重要能避免 AI 在命名上自作聪明。最后调 test 技能来补测试计划/superpowers:test 目标UserService 框架JUnit5 Mockito 要求覆盖重构后的核心分支test 技能没有直接生成几百行测试而是先给了一份测试策略表格列出需要覆盖的用例注册成功、邮箱重复、密码弱、邮件发送失败。每个用例标出 mock 哪些依赖、断言哪些行为。我觉得方向没问题才让它继续生成具体测试代码。Test void register_shouldCreateUser_whenInputValid() { when(userMapper.findByEmail(ab.com)).thenReturn(Optional.empty()); User user userService.register(ab.com, StrongPass1!); verify(userMapper).insert(argThat(u - u.getEmail().equals(ab.com))); }4.3 实测效果与翻车现场流程走到这一步看起来顺利但第一次实际跑测试时直接红了一片。报错信息指向UserService构造方法里的依赖注入AI 把EmailSender换了个名字但applicationContext.xml里对应的 Bean 还是老名字启动就失败了。这个坑其实很有代表性。Superpowers 把重构步骤执行得很规范但它只知道自己生成的代码不知道你项目配置里那些隐式约定。哪怕它已经读了一部分项目文件也没法像老开发那样对每个 Bean 名字都门清。我的排查过程是这样的先看测试日志确认是依赖注入失败再打开改动记录对比 AI 改过的类名和 Bean 定义发现问题后没让 AI 直接改而是回滚了那一个类的改动在命令里明确告诉它“项目里 Bean 名是 emailSender保持这个不动”重新生成后才通过。这个翻车也给我提了个醒技能文件里应该加一条固有约束——所有注入点和 Bean 名称必须从现有配置里读取不允许自己命名。技能给出的流程再漂亮最终检查漏洞的人还是你。5. 在 WorBuddy 等图形客户端里配置 Superpowers5.1 WorBuddy 和 Codex 的关系经常有人在搜“WorBuddy 怎么用 superpowers”我猜你是把 WorBuddy 当成一个独立的 AI 编程产品了。按我目前的理解WorBuddy 更像是把 Codex 这类编码助手包了一层图形界面的客户端底层还是调用 Codex 的能力。也就是说Superpowers 不能单独“装进 WorBuddy”而是要让 WorBuddy 背后那个 Codex 进程找到技能目录。这听起来绕其实就一句话你在 Codex CLI 里怎么配在 WorBuddy 里就怎么配只不过多了一道入口。如果 WorBuddy 提供了设置面板直接搜skills相关选项如果找不到那就得手动改配置文件。5.2 图形界面里的三种配置入口我见过三种常见情况。第一种设置面板里有Skills Directory字段直接填~/.superpowers/skills就行。第二种设置面板里没有技能选项但提供了“自定义环境变量”区域那就把SKILLS_DIR加进去。第三种两者都没有只能手动编辑客户端的数据文件。这类客户端一般会把配置放在用户目录下文件名类似config.json或settings.json找到后往里面塞一段{ codex: { skillsDir: ~/.superpowers/skills, disabledSkills: [] } }改完重启客户端再用“你现在能使用哪些技能”来验证。有时候界面里配置文件默认是隐藏的可以用文件管理器开启“显示隐藏文件”或者直接在配置目录里用 CtrlL 输入路径跳转。5.3 一条最容易踩的路径坑图形客户端配置里最常翻车的是路径问题。在 Windows 上默认路径是C:\Users\你\.superpowers\skills如果\没转义或者路径中间带空格AI 在读取技能目录时就会解析失败表现是“技能列表为空”。解决办法是统一使用用户目录的~缩写或者把技能库放在一个不带空格的路径下比如D:\tools\superpowers-skills。如果你看到报错信息里有unexpected token或ENOENT多半就是路径没写对别急着怀疑技能文件坏了。另一个很多人忽略的点是图形客户端往往不会自动刷新技能目录。你新增了一个技能文件客户端里立刻用是没用的需要先重启会话或重新初始化客户端让它重新扫描目录。这个“重启会话”的动作放在命令行里就是新开一个 Codex 对话放在 WorBuddy 里就是点新建对话。6. 技能文件组织与排错清单6.1 技能文件的结构长什么样自己动手写技能之前建议先拆一个内置技能看看结构。一个标准的技能文件长这样--- name: spring-boot-test description: 为 Spring Boot 模块生成测试策略与 JUnit 代码 triggers: - 测试 - junit - 覆盖率 --- ## 执行步骤 1. 读取当前模块的 pom.xml确认 Spring Boot 版本。 2. 定位待测类列出公开方法和依赖。 3. 按方法分支生成测试用例覆盖正常与异常路径。 4. 使用 Mockito 隔离外部依赖。 ## 约束 - 不修改被测类的原有逻辑。 - 测试方法命名使用 given_when_then 风格。 - 每个用例必须写清楚断言目标。头部name是技能的唯一名字description用于让 AI 判断什么场景该激活它triggers是隐式触发的关键词列表。正文部分可以自由发挥但最好把“步骤”和“约束”分开写。约束是给 AI 画的红线没有了它技能就退化成一个普通的提示词。6.2 高频报错与解决我用表格整理一下自己遇到的高频问题方便你直接对照现象可能原因解决办法技能列表为空SKILLS_DIR没生效重新设置环境变量或在新对话里显式指定目录命令敲了没反应Codex 版本太旧更新 Codex或换成显式触发方式技能激活后回答很泛技能文件缺少步骤和约束补上执行步骤与禁止事项多个技能互相干扰一次加载技能太多同一阶段最多保留 2~3 个技能Windows 下无法加载路径带空格或编码异常把技能库挪到纯英文无空格路径6.3 维护策略别让技能库变成垃圾场Superpowers 用顺手之后很容易陷入另一种状态见什么都想封装成技能过两周回头一看目录里躺着几十个从没用过的技能。技能文件不是越多越好每多一个技能AI 在启动时就要多扫描一次误触发的概率也多一分。我现在会做三件事控制技能库规模。第一把技能分成“稳定区”和“试验区”。稳定区是已经验证过、真正能提升效率的技能放主目录试验区是新写的、还不确定效果的技能放在单独文件夹里。验证通过再升到稳定区。第二给技能文件带上前置条件。比如某个技能只适用于 Maven 单模块工程就在description里写清楚适用范围避免在 Kotlin DSL 项目里被误激活。第三定期用superpowers doctor一类的诊断命令检查技能文件格式能自动发现 YAML 语法错误和缺失字段。维护技能库和写代码很像少一点、精一点长期收益才高。我自己的体会是别把技能当成“把网上的最佳实践抄进来”的东西而是把它当成你自己团队的开发约定。真正好用的技能描述里写的是目标和边界而不是一步步教 AI 怎么写代码。这个思路反过来也帮我理清了日常开发里哪些规则是反反复复靠人肉提醒的全把它们固化下来之后新对话再也不会从零开始。
