1. 先从痛点说起为什么我非要用superpowers不可如果你跟我一样每天要跟AI编程助手开七八个新会话那你一定经历过那种崩溃——上个会话里好不容易把项目结构、构建命令、代码规范、注意事项一项项交代清楚AI也干得挺顺手结果关掉窗口再开一个它又什么都忘了。你得像复读机一样把项目背景重新讲一遍讲到一半还得翻聊天记录找之前贴过的配置文件。我最初折腾superpowers就是被这种“会话失忆”逼出来的。superpowers本质上是一套给AI编码代理准备的可复用技能库方案。它不是某个具体功能插件那么简单而是把“调教AI的套路”结构化、文件化、版本化让AI在开始干活前能主动加载一套完整的工作指令而不是靠你现场临场发挥。我当时搜“superpowers使用指南”的时候看到一个说法特别戳我把AI当成一个经验丰富但忘性极大的同事你要做的不是每次重新培训它而是给它一本随时能翻的操作手册。superpowers就是那本手册的管理系统。1.1 AI编码最隐蔽的瓶颈会话失忆先说一个很多人忽视的事实现在主流AI编码代理的生成能力早就不是瓶颈了真正卡脖子的恰恰是上下文连续性。模型单次能记住的信息再多也是有窗口上限的。项目稍微大一点你把核心代码、架构文档、构建脚本、接口定义全塞进去窗口就快满了AI开始顾此失彼前面看过的内容后面就模糊了。更麻烦的是跨会话场景。今天你让AI帮你把A模块重构了明天想让它继续做B模块它根本不知道昨天发生过什么。你要么把昨天的结论重新描述一遍要么把改进后的代码再贴一次要么干脆指望它“聪明地猜”。大多数情况下AI会按照它自己的“默认偏好”来写代码而不是按照你项目的约定来写。比如你们项目统一用Record模式写数据传输对象AI偏偏给你生成一堆带Lombok的类你们约定Controller层只做参数校验AI非要往里面塞业务逻辑。这种问题不是模型不够聪明而是缺少一套能跨会话、跨任务传递“约定”的机制。1.2 superpowers的做法把“调教”变成版本化资产superpowers解决这个问题的思路很直接把一次性的口头交代变成一份份可复用的技能文件Skill。每份技能文件描述一个完整的操作流程包含触发条件、执行步骤、约束规则、验收标准。AI在执行任务前会先扫描技能库看当前任务匹配哪个技能然后按技能里的步骤逐项执行。举个例子。我经常要处理“按项目规范新增一个后端接口”这类重复性任务。以前我得每次跟AI说接口要放在哪个包、要用什么注解、参数校验怎么做、异常怎么处理、单元测试要覆盖哪些分支。现在我把这套流程写成一个技能文件里面把这些规则全部定义好。后续再让AI做类似任务它自己就会去技能库里找到这个技能按里面的规范执行。我发现同样一个任务有没有技能文件的引导最终代码的风格差异巨大。有技能的版本几乎可以直接拿去提交PR没技能靠现场解释的版本经常要来回改好几轮。而且技能文件就是个普通文本文件可以放进git仓库跟着项目走。新成员加入拉下仓库就能让AI立刻按团队规范干活。这里的核心思想是经验不再存在聊天记录的碎片里而是存在可审查、可更新、可追溯的文件里。1.3 它和普通提示词模板的根本区别有人可能会说这不就是提示词模板吗我写个长提示词不也一样还真不一样。提示词模板是“一次性粘贴给AI的文本”技能文件则是一套有结构、有依赖、可组合的“指令系统”。技能文件里除了描述性文字还有参数声明、依赖关系、触发规则、甚至内嵌的校验清单。它背后有一套加载逻辑在决定“什么时候用哪份技能”“多份技能冲突时按什么优先级处理”。另一个区别在维护性上。提示词模板一旦写进某个文档你很难知道团队里谁在用它、哪天改过、现在是不是过期了。技能文件则有明确的目录、命名规范和管理命令改一份文件就是一次可追溯的变更。我个人的体验是把这套机制引入工作流之后最大的变化不是AI变聪明了而是我跟AI配合的“沟通成本”断崖式下降。2. 动手前的环境体检三件容易忽略的事安装superpowers之前我本来以为就是跑两条命令的事结果还是踩了点小坑。这节把环境准备阶段容易忽略的几个点列清楚省得你走弯路。我个人建议先做体检再装东西不然装到一半发现某个依赖版本不对排查起来很闹心。2.1 对照检查表先看你缺什么我整理了一份检查清单你在动手前逐项核对一下比较好检查项要求说明Node.js运行时建议18及以上工具链的CLI是基于Node的版本太老会直接跑不起来目标项目的构建环境按项目实际配置Java项目要JDK前端项目要pnpm/yarn等技能包执行时会调用这些命令AI编码代理CLI环境已安装并完成登录我用的是Codex CLI技能是通过它触发的没有这个环境装了也用不上本地PATH变量能直接执行mvn、gradle、git等命令很多坑其实是PATH配置问题不是superpowers自己的问题网络访问能正常拉取依赖安装过程要从仓库拉包首次运行也要读一些远端资源检查方法很简单打开终端逐条执行一下对应命令看能不能正确输出版本号。不要嫌啰嗦这一步做扎实了后面能省一个小时。2.2 安装命令与离线变量环境没问题后就可以装主程序了。我是从项目的release页拉下来的稳定版本没有用仓库的main分支——这点我单独说一下如果你是想尝鲜用开发分支也行但你要是准备把它当日常工具用务必用release版本。开发分支前一阵出现过技能格式还没冻结就改掉的情况挺折腾的。安装思路大致是这样把仓库克隆到本地的一个固定目录然后执行构建脚本把它链接成全局命令。命令本身不一定非要和我完全一致以你当时拿到的release说明为准。整个安装过程其实就是在本地把CLI编译出来然后把它加入PATH。装完后记得重启终端不然新命令可能不生效。我当时装完后用版本命令验证输出了正常的版本信息这才算第一步完成。如果你在安装过程中遇到权限问题优先检查是不是当前用户对全局目录没有写权限用用户级安装方式解决尽量不要随便sudo装。2.3 装完后第一件事跑自检装完主程序不算完第一件事应该是运行环境自检命令。这个命令会检查技能目录是否存在、依赖的运行时版本、当前AI代理CLI能否正常调用。我当时跑完自检发现它提示Java环境没有加入PATH——我在M1 Mac上用的JDK是通过IDE内置的终端里根本没暴露出来。这就是典型的“IDE里能编译终端一跑就废”的情况。这时候得在shell配置里显式导出JAVA_HOME和PATH不然后面技能包一执行Java构建命令就会报找不到命令。自检通过后它会自动创建一个默认的技能目录并写入一份示例技能。我的建议是先留着这份示例技能跑通一个Demo任务确认整个链路是通的再开始写自己的技能。链路通不通这是判断你环境有没有真正配好的唯一标准。3. 真正跑起来技能包的目录结构与手写第一个技能环境理顺之后接下来就是要理解superpowers的核心工作方式技能包。这节我直接用我的实际操作来拆解。看完你应该能自己动手写一份简单的技能文件并让它真正生效。3.1 默认目录结构里都有什么初始化完成后技能目录下会生成这样的结构具体的名字可能因版本稍有差异但思路一致~/.superpowers/ ├── skills/ │ ├── common/ │ │ ├── code-review/ │ │ │ ├── SKILL.md │ │ │ └── references/ │ │ └── commit-message/ │ │ ├── SKILL.md │ │ └── templates/ │ └── project/ │ ├── spring-boot-api/ │ │ └── SKILL.md │ └── frontend-commit/ │ └── SKILL.md ├── config.json └── logs/ └── superpowers.log每个技能一个目录目录名对应技能标识里面必须有一个SKILL.md作为入口文件。references和templates这两个子目录是可选的用来放参考文档和模板文件。设计上强迫你按目录组织而不是把所有内容塞进一个巨型文件这样技能之间可以互相引用也方便做版本管理。3.2 SKILL.md的格式frontmatter加正文SKILL.md用的是我在各种文档系统里很熟悉的那套格式YAML frontmatter加 Markdown 正文。frontmatter里写技能的元信息正文写真正的执行说明。一个最小的技能文件长这样--- name: simple-greeting description: 当用户要求生成问候语接口时使用按项目约定返回统一JSON格式。 when_to_use: 任务涉及新建或修改问候类API接口 version: 1.0.0 --- # 问候语接口实现规范 1. 接口路径统一放在 /api/v1/greeting 下。 2. 返回结构必须包含 code、message、data 三个字段。 3. data 中的 content 字段由后端拼接前端不参与。 4. 所有参数必须使用 DTO 接收禁止直接使用 Map。 5. 新增接口必须同步补充单元测试覆盖正常入参、空参数、超长字符三个场景。注意几个关键点description是负责“路由”的字段AI会根据它判断当前任务该不该加载这份技能所以描述里要写明这个技能做什么、覆盖什么场景。when_to_use是我个人习惯加的额外提示字段它会出现在AI的决策信息里进一步降低误加载的概率。正文部分就是执行规范写的时候要具体少用“要做好”“要规范”这类模糊表述直接写“必须”“禁止”“覆盖哪些场景”。3.3 写一个最小技能并让它生效工具安装后自带的示例技能会指导你怎么创建我自己写第一个技能时的步骤是这样在skills/project/下新建目录greeting-api。在里面创建SKILL.md填入上面的内容。运行技能列表命令看新技能有没有出现在列表中。在AI代理里发起一个与该技能匹配的任务观察它是否加载了这份技能。第一次测试我就发现一个细节技能描述与用户请求的匹配是模型判断的不是简单关键词匹配。比如我写“问候语接口”AI能正确识别。但如果我把描述写成“当涉及API时使用”那它几乎会在所有任务里加载这份技能导致规则互相打架。所以写description时要克制范围宁窄勿宽一次不要覆盖太多场景后面你可以用多份技能组合起来解决问题。4. 在Java项目里我把什么打包成了技能技能库跑通以后我优先选的试验场是我手头一个Spring Boot Maven的Java服务。这个项目累积了不少约定团队成员流动也大特别适合用技能来做标准化。这一节我分享一下我在Java场景下做的几个技能设计以及Java环境里特别要注意的地方。4.1 选Java场景的原因与技能设计Java项目相比其他技术栈有几个更适合技能包的天然优势一是目录结构和工程规范相对统一二是Maven/Gradle构建流程稳定可脚本化三是代码风格约定一般比较严格。这些特征意味着你可以把相当多的工作流“标准化”成技能一次写好长期复用。我为这个Java项目设计了三个技能分别对应三类高频任务maven-build:负责Maven项目的构建与编译错误排查统一使用项目指定的JDK版本和Maven仓库配置。java-api-controller:负责新增/修改REST接口内容涵盖Controller层规范、参数校验方式、统一异常处理、响应封装格式。pre-commit-check:作为提交前的检查技能会在改完代码后自动跑编译、增量测试、代码规范扫描这三个步骤。这三个技能覆盖了我日常让AI干活的80%场景。最有价值的是pre-commit-check因为以前AI改完代码我总要自己手动跑一遍构建和测试现在它改完会主动按技能里的检查清单执行一遍发现编译错误直接当场修复。4.2 提交前检查技能的具体内容我贴一段pre-commit-check技能里的核心内容你可以感受一下这种“给AI套流程”的写法--- name: pre-commit-check description: 在Java项目代码修改完成后使用确保改动通过编译、测试和规范检查。当任务涉及修改src/main或src/test目录下的Java代码时必须执行本技能。 when_to_use: AI修改了Java源代码或测试代码准备给出最终回复之前 version: 1.2.0 --- # 提交前检查流程 按顺序执行以下步骤任何一步失败都必须自行修复后重新执行直到全部通过 1. 运行 mvn -q compile -DskipTests确认主代码编译通过。 2. 运行 mvn -q test-compile确认测试代码可以正常编译。 3. 运行与被修改模块相关的测试mvn -q test -Dtest模块名.*Test不要运行全量测试。 4. 检查新增的公共方法是否包含Javadoc注释缺少注释时要主动补齐。 5. 检查Controller层返回类型是否使用了统一的ResultT封装发现直接返回实体对象时立即修正。 6. 检查是否存在 System.out.println 调试语句若有则替换为日志框架。这份技能的核心思路是把质量门禁前置让AI在交付前自己把常规问题处理掉。实测下来引入这份技能后我review代码时“编译不过”“测试挂了”“格式不对”这类低级反馈明显变少我只需要看业务逻辑本身。4.3 Java相关的注意事项Java场景下使用技能包有三个点我要特别拎出来讲第一JDK版本必须和项目一致。我那个项目用的JDK 17技能里第一条就写清楚构建时通过JAVA_HOME指定JDK路径。不然AI可能会拿系统默认的JDK 21去编译结果项目里某些依赖在21下行为不一致出现莫名其妙的报错。第二Maven本地仓库的路径问题。团队里如果走私有镜像源一定要把镜像配置信息写进技能正文否则AI在干净环境里拉依赖会失败。我一开始没写这条AI编译时报“Could not find artifact”折腾了半天才发现是仓库源问题。第三Lombok的处理器问题。很多Java项目用了LombokAI生成的代码在IDE里没报错但命令行编译时偶尔会因为注解处理器没配置好而失败。我在技能里加了一个约定出现package lombok does not exist这类错误时先检查maven-compiler-plugin的配置而不是让AI去改代码逻辑。Java项目的技能设计本质上就是把你们团队沉淀下来的“开发规范”“踩坑经验”“构建配置”固化成文字再交给AI严格执行。这比写内部wiki有用的多因为AI是真的会去逐行执行它。5. 和Codex CLI合体后的完整工作流前面这些技能文件如果没有一个执行环境就只是一堆漂亮的文档。我这里用的执行环境是Codex CLI。这节写一写我把技能库接到Codex CLI之后实际工作流长什么样以及和以前相比的体感差异。5.1 Codex CLI的技能加载配置superpowers和Codex CLI的对接方式可以理解成superpowers负责“技能库管理”Codex CLI负责“干活”。每次对话启动时Codex会把技能库里的相关技能注入到上下文里AI在回复前会先“看到”这些技能的存在。我实际配置的路径大概是这样的在Codex CLI的配置文件里指定superpowers技能目录的路径。设置加载策略我选的是“自动匹配”模式AI根据用户请求动态决定加载哪些技能。开启日志输出方便排查“为什么某个技能没有生效”的问题。配置完成后我发起任务的方式和以前几乎没变化就是正常描述需求。区别在于AI的行为模式变了它会先阐述它打算调用哪个技能再按技能的步骤来执行。你甚至可以在对话中看到它读取技能文件过程留下的痕迹透明度和可调试性比纯黑盒提示词高了一个档次。5.2 一次真实任务从启动到交付的过程我拿最近一次“给订单模块增加超时关闭接口”的任务举例。以前这个需求我要口头说一大堆项目里响应都用Result包、订单状态更新要用乐观锁、接口要加幂等校验、测试要覆盖并发场景。现在我在Codex里只打了一行需求描述“新增订单超时关闭接口参考现有超时任务逻辑完成后跑一遍检查。”AI的处理过程分成了明显的几个阶段先是加载了java-api-controller技能确定接口定义、参数结构、异常处理方式。接着加载maven-build技能确认编译环境然后阅读现有超时任务的代码找到可复用的部分。实现过程中它主动检查了幂等性约束技能里写了“涉及状态修改必须加幂等控制”。代码写完后自动执行了pre-commit-check技能里定义的构建和测试流程第一次测试跑挂了它定位到是测试数据时间设置问题修完再跑直到通过。整个过程我只在最后看了一次diff做了一点业务逻辑上的调整。这跟以前“AI写完我改半小时”的体验相比确实省心很多。5.3 这里有技能和没技能的时间对比我做过一个粗略对比同样的接口开发任务没有技能库时我需要先花5到10分钟在对话里补项目背景写完之后再花10到15分钟修风格问题和漏掉的约束总共大概20到30分钟的有效注意力投入。有技能库之后描述需求大约1分钟AI自动加载技能并实现我最后审阅调整大约5到10分钟。虽然绝对时间上省得不算夸张但关键是“我盯着屏幕看AI输出的时间”少了一大半。这种体验只有重度使用AI编码的人才能真正体会到——你从流程执行者变成了流程验收者。另外我建议在Codex CLI里可以用较新的模型版本跑这类带技能库的任务。模型的新版本在“遵循多步骤指令”方面的能力明显更好——旧模型偶尔会跳过技能里的某几条新模型则基本能做到逐项落实。6. 三个坑的完整排查链路工具再好用该踩的坑一个都不会少。这里我记录三个我实际踩过、且花了不少时间排查的问题。我不直接说答案把排查过程也写出来。因为技能库这类系统真正麻烦的地方往往在“链路”排查思路比单个答案更值钱。6.1 坑一技能加载了但AI不当回事现象很诡异日志里显示AI确实读取了技能文件但它给出的代码完全没按技能规范来。立项排查的第一步我看了技能文件本身——发现我的写法有问题我把“规范”写得太抽象了。比如“Controller层不要写业务代码”这种描述AI能读出来但它对自己写的每行代码是否符合这个描述判断是模糊的。后来我把规范改成了可验证的硬约束比如“Controller中禁止出现Service或Mapper的Autowired字段”“Controller方法体内只允许调用一个service方法”AI的执行立刻准确了很多。这说明一个关键点给AI看的技能和给人看的规范是两码事。人的规范可以意会给AI必须尽量写成可机械校验的条款。灰色的描述少写明确的黑白条款多写。另外我没在任务描述里提到“按技能执行”。有些情况下AI虽然加载了技能但它把技能当成“参考资料”而非“执行清单”。我在Codex CLI的使用习惯里加了一句话模板任务结尾带上“完成后按技能内检查清单逐项执行”触发率就高多了。6.2 坑二技能包太多上下文被撑爆技能库能力很强我就开始往里加技能越加越多。结果某天开始对话响应质量明显下降AI经常丢三落四。后来看上下文统计才发现自动匹配模式下它一次会加载好几份相关技能每份技能带一堆正文和参考文献几个技能加起来就把上下文窗口占掉一大块。这个问题的根因是技能系统做的是“自动路由”但我设计的技能粒度太大。比如我有一个“java-web开发总则”里面写了Controller、Service、Repository、异常处理、测试规范十几条内容。AI做任何JavaWeb任务都会加载它大量的规则信息挤占窗口且互相干扰。解决方案是拆技能把总则拆成粒度更小的技能文件每个文件只解决一个子场景。这样AI只加载当前任务真正需要的那部分上下文占用立刻降下来了。另外一个辅助手段是给技能正文写简版和详版AI默认只加载简版需要时再读references里的详版。6.3 坑三升级后旧技能格式失效有一次我手痒升级了superpowers主程序结果第二天发现所有技能都加载不出来了。点开日志发现新版本把技能frontmatter的字段名改了比如把when_to_use换成了triggers而我所有技能文件还停留在旧格式。这种情况最坑的地方在于主程序不会主动报错因为旧文件会被跳过看起来就像“技能没了”。排查过程不算复杂但需要你有看日志的习惯。我先确认技能目录没问题再逐个检查技能文件最后打开运行日志才看到格式解析的警告。修复办法是写了一个小脚本批量给所有技能文件做字段迁移。从此以后我学乖了升级主程序前先备份技能目录升级后第一件事是跑自检自检会提醒格式不兼容的文件。6.4 一套可复用的排查思路总结一下遇到技能库相关的诡异问题我的排查顺序一般是这样的先确认文件还好好待在目录里别急着怀疑逻辑。看运行日志里有没有技能加载记录的报错或警告。确认技能文件的frontmatter格式与当前版本兼容。在对话里强制指定技能绕过自动匹配看问题是否出在路由上。如果自动匹配有问题检查技能description写得太宽还是太窄。最后才怀疑模型本身——新模型遵循指令的能力通常都会更好。按这套顺序走下来绝大多数问题都能定位到具体环节不用瞎猜。我后来所有技能相关的问题基本都是在这几个环节之一找到答案的。这个排查链路本身我觉得比记住某几个报错信息更有长期价值。