★ FEATURED ARTICLE 每天在终端里跟代码打交道的人多少都会遇到这种时刻——AI助手把代码写出来了但你要的却是一整套“怎么在项目里落地这件事”的答案。我在给Codex CLI找增强方案时发现了superpowers这个开源项目它用一套“技能包Skills”机制把散落在文档、博客和个人经验里的开发流程变成了AI能主动调用的标准化能力。这篇文章我打算把superpowers的来龙去脉讲透它解决了什么问题、内部是怎么运转的、怎么从零装好并跑通以及我在Java项目里实际用下来的体会。如果你想找一份能直接照着操作的中文教程这篇应该够用了。文章不长不短但每一步都是我自己敲过、踩过、验证过的放心往下读。1. 先说清楚superpowers到底是个什么东西为什么非要它不可1.1 从Codex CLI说起一个能写代码但不懂“开发流程”的工具要理解superpowers得先理解它服务的对象——Codex CLI。Codex CLI是GitHub推出的开源AI编程命令行工具它跟一般的自动补全插件不一样不是你在编辑器里敲一个字它帮你补下一个字而是你直接给它一个任务它自己去读代码、改文件、跑命令、甚至做多轮推理然后提交一个完整的改动。听起来很强大对吧但实际用起来你会很快发现一个尴尬的点Codex CLI很会“写代码”但很不擅长“知道该怎么干活”。举个例子你让它修一个bug它可能直接就在源码里改了但完全不会想到先去跑一遍现有测试、检查一下日志、确认复现步骤。你让它加个功能它可能写了主逻辑但忘记补单元测试、忘记跑静态检查、甚至忘记按项目现有的代码风格来组织目录结构。不是模型不够聪明而是它缺少“流程意识”。就像请了一个技术很强的外包但这个外包没在你公司待过不知道你们的代码规范、提交流程、测试要求。而superpowers这个开源项目干的事情就是把这些“流程意识”打包成一套AI能主动读取、主动遵循的技能包。1.2 技能包的核心思路让AI说话前先翻手册superpowers的作者是Jesse VincentGitHub用户名obra一个常年混迹Perl和开源社区的老炮。他最初的痛点是他自己天天用Codex CLI写代码发现AI经常因为缺少上下文而做出一堆“看起来很对但实际很蠢”的操作。于是他搞出了一套东西——把团队、项目甚至个人积累的开发规范写成一个一个的技能包Skills放到特定目录里让Codex CLI在干活之前先去看看这些技能包里写了什么然后照着里面的要求去执行。打个比方这就像你给实习生配了一本《公司做事手册》里面写着“改代码前先跑测试”“提交前先lint”“线上问题先看监控”“发版前先更新CHANGELOG”。有了手册实习生哪怕经验不多也能按着规矩把事情做得有板有眼。superpowers做的就是这本手册的“集装箱”。这套设计真正聪明的地方在于它不绑定任何具体的语言、框架或工具链。技能包天然是为了复用而生——不同的项目可以共享一套基础技能包也可以单独追加自己的项目级技能包。Java有Java的套路Python有Python的规矩前端有前端的检查清单各放各的互不干扰。这就把“AI编程助手”从一个会写代码的机器变成一个“懂规矩、有章法”的协作者。2. 核心机制拆解一次技能调用背后发生了什么2.1 superpowers的组成结构一个目录、三个关键文件跟很多重型的AI框架不一样superpowers本身就是一个目录结构加一套约定理解起来非常朴素。我第一次打开它的仓库时甚至有点意外——没有复杂的插件系统没有必须注册的API核心就是“把文档放在AI能自己找到的地方”。一个标准技能包大体长这样~/.codex/skills/ ├── code-review/ # 技能1代码审查 │ ├── SKILL.md # 技能描述文件包含frontmatter和正文 │ └── references/ # 辅助文档目录可选 │ └── checklist.md ├── writing-tests/ # 技能2编写与运行测试 │ └── SKILL.md └── git-workflow/ # 技能3Git操作规范 └── SKILL.md关键点都写在SKILL.md里。这个文件开头是YAML格式的frontmatter包含技能的名称、描述、适用场景等元信息下面是正文用Markdown写清楚“具体应该怎么做”。这个设计极其聪明YAML的description是给AI判断“什么时候该用这个技能”看的正文是给AI“怎么执行”看的。两个信息维度分工明确不混在一起。skill的目录命名和描述本身也要动脑筋。比如处理Java项目我不会只写“Java知识”而是会拆成“maven-build-flow”“spring-boot-debugging”“junit-test-writing”这种具体场景。AI在判断该用哪个技能时靠的就是这些描述是否与当前任务匹配——描述太笼统它会不知道该怎么选描述太细碎又会频繁误触发。2.2 触发方式与匹配逻辑AI怎么知道该用哪个技能这里可能是大多数第一次用superpowers的人最疑惑的地方技能包放在那里AI真的会自己去看吗答案很简单——会但它不是“看”而是“搜”。Codex CLI在启动的时候会把技能包目录里的SKILL.md元信息加载进自己的系统提示词system prompt里。当你的任务涉及某个技能时模型会从这些元信息中检索到对应的技能然后主动去打开完整的SKILL.md正文按里面的步骤去执行。这个过程并不是“所有技能一次性加载进上下文”而是分两步走的懒加载策略先加载“目录”再按需加载“正文”。这样既能保证上下文窗口不被一堆无关的规范文档占满又能让AI在关键时刻拿到最详细的指导。说实话这个设计我第一眼看到的时候有点被惊艳到——它等于在提示词工程和RAG检索增强生成之间找到了一个极轻量的平衡点。要让你自己的技能包真正“好用”建议遵循这几个原则描述里写明“何时用”和“何时不用”比如“该技能适用于使用Maven构建的Java项目不适用于Gradle项目”避免AI误用。正文步骤尽量量化比如“第一步先运行mvn test确认全部绿灯后再修改代码”命令可以直接给省得AI瞎琢磨。一个技能只解决一个流程问题不要把“写测试”和“改依赖”塞在同一个技能里匹配精度会明显下降。提示技能包的加载是广度优先的。你的目录越扁平、分类越清晰AI的检索准确率就越高。我见过有人在skills目录下套了四五层子目录结果AI经常找不到该用的技能。后来我把子目录摊平匹配成功率立竿见影地涨了一截。3. 安装与环境准备从零开始跑通superpowers3.1 安装前的环境检查与清单对照给你的环境装superpowers之前先确认手头这几样东西是否到位。很多人装到一半卡住回头一看基本都是前置环境没捋顺。我列了一个自查清单挨个过一遍一分钟就能查完检查项要求说明操作系统macOS / Linux / WSL2官方主推Unix-like环境Windows原生终端会有一堆权限和路径坑Node.js18.0及以上Codex CLI是Node包版本太老会直接拒绝安装Git2.30及以上安装脚本要拉取仓库Codex CLI0.x最新版先装好并确认codex --version能跑通AI服务凭据OpenAI API Key 或 GitHub Copilot 订阅没有这个装完也白搭如果你用的是Windows强烈建议直接切换到WSL2再操作别在PowerShell里硬磕。我在Windows里试过一次路径解析和权限模型跟Linux完全是两回事技能包目录的读取经常出幺蛾子后来换到WSL2一次性通过再也没回头。3.2 一键安装步骤curl脚本做了哪些事打开终端执行这条命令curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash官方推荐的安装方式是一条curl管道命令。你可能会担心“这种脚本安不安全”我个人的态度是不放心就看一眼脚本内容再执行但它做的事其实很规矩一共就四件创建~/.codex/skills/目录。克隆superpowers仓库到~/.codex/下的临时目录。把仓库里预设好的技能包复制到~/.codex/skills/。做一次环境检查提示你是否需要配置Codex CLI的模型参数。跑完之后你可以直接看一眼技能包目录ls -la ~/.codex/skills/正常情况下你能看到code-review、writing-tests、git-workflow、debugging等预设技能包每个里面都有一份SKILL.md。到了这一步superpowers本体已经算装完了。3.3 配置Codex CLI并确认技能包被识别装好技能包之后还得让Codex CLI“意识到”这些东西的存在。一个是确认Codex CLI用哪个模型后端另一个是检查Codex CLI是否真的扫描了技能目录。先在终端执行codex --version然后打开Codex CLI的配置一般是~/.codex/config.toml找到模型相关配置。这里我以OpenAI API为例model gpt-5 model_provider openai如果你用的是GitHub Copilot订阅Codex CLI新版通常能自动识别环境变量里的凭据不用额外写model_provider。配置完成之后先跑一个最简单的对话验证整体链路通不通codex 列出当前项目的文件和目录结构看到正常的回复后再试一个跟技能包强相关的指令比如codex 帮我对src目录下的Java代码做一次代码审查如果技能包被正常加载Codex CLI会在思考过程中主动提及并阅读了code-review技能包输出也会明显表现得更有“检查意识”比如主动问你要检查清单、主动去跑静态分析工具等。这时候就说明技能包已经生效了。注意技能包的生效链路是“安装技能包 - Codex CLI扫描skill目录 - 任务触发技能匹配 - 读取SKILL.md正文”。如果你发现AI完全不理会技能包优先排查第一步也就是~/.codex/skills/目录里到底有没有技能包以及你的Codex CLI版本是否更新到了支持技能包机制的版本。4. Java场景实操用superpowers把AI变成老练的Java同事4.1 典型工作流从新需求到提交PR的完整闭环热词里有“superpowers java”看来不少人对Java场景特别感兴趣。我在一个真实的Spring Boot项目里完整跑过一轮“新需求开发”的流程体验相当有代表性。我当时给Codex CLI下达的任务是“在现有的用户模块中增加一个根据手机号查找用户详情的接口要求遵循项目现有的分层结构和异常处理规范。”如果没有superpowersCodex CLI大概率会直接把Controller、Service、Mapper一坨写出来就算完事。但加载了技能包之后它的行为路径发生了明显变化第一步它先调用了类似project-structure-guide的技能包阅读了项目的包结构和分层约定。第二步它读取了项目里现存的Controller代码总结出统一的返回包装类。第三步它调用writing-tests技能包主动补上了Service层的单元测试和Controller层的MockMvc集成测试。第四步它跑了一遍mvn test发现有测试因为一个NPE挂了又回到代码里把Null判断修好然后重新跑到全绿。整个过程下来我只做了一件事向它提出需求。代码、测试、验证、修复它自己串出了一个接近完整工程师的闭环。这就是技能包带来的最大差异——它不只能“写”还能“按流程做”。整条流程走下来我体感上的产出效率比裸用Codex CLI高了不止一倍而且最值钱的部分不是它写代码多快而是它写完之后我可以少改很多地方。测试补了、风格统一了、异常处理也踩中了项目约定改动能直接上PR这在以前是不可想象的。4.2 为Java项目定制技能包的实战写法通用的技能包解决的是“所有项目通用的流程”但要让它真正适配你的Java项目还是得自己动手写定制化技能包。写一个技能包真的不复杂本质上就是写一个带规则的Markdown文件。下面是我在Spring Boot项目里用的一份spring-boot-standards技能包示例--- name: spring-boot-standards description: 适用于Spring Boot项目的分层结构、命名规范、异常处理和接口返回值约定。当任务是新增或修改Controller、Service、Mapper层代码时使用。 --- # Spring Boot 项目开发规范 1. 所有接口必须经过Controller层且返回值使用统一的ResultT包装类禁止直接返回实体类。 2. Service层必须处理业务异常异常类型使用BusinessException禁止在Controller里catch底层异常。 3. Mapper层对应MyBatis的XML文件禁止在接口上直接使用Service注解。 4. 新增接口必须同步补充Swagger注解包含tags、summary、description三个字段。 5. 修改任何一处逻辑时必须同步检查该方法的单元测试是否仍然有效如有变化需一并更新。 6. 禁止使用new关键字手动创建通用组件依赖注入一律用构造器方式。 7. 所有时间字段使用LocalDateTime禁止使用java.util.Date。把这份文件保存到~/.codex/skills/spring-boot-standards/SKILL.mdCodex CLI下次处理你项目里的Java任务时就会自动读取并遵循。自定义技能包的时候我建议你在SKILL.md里多写“禁止项”。模型对否定指令的遵循往往比对肯定指令更严格。我第一条写“禁止直接返回实体类”它就不会给你返回一个裸的User对象如果只写“请使用统一返回包装类”它偶尔还是会犯懒直接返回。别问我是怎么知道的都是试出来的。4.3 处理Maven多模块项目时的特殊技巧很多真实的Java项目是多模块Maven结构比如core、service、web、infra四个模块各占一个目录。技能包虽然能给AI立规矩但面对多模块项目时模块依赖和编译顺序也是个容易翻车的地方。我给一个多模块项目定制技能时会在SKILL.md里明确写出模块依赖关系与构建顺序。例如--- name: maven-module-hierarchy description: 适用于Maven多模块项目当运行mvn命令或修改模块间依赖时必须先查看根pom.xml中的module顺序。 --- # Maven 多模块构建须知 1. 构建顺序infra - core - service - web禁止在编译web模块时直接跳过前置模块。 2. 想一次性构建所有模块使用mvn clean install -DskipTests不要单独在子模块里执行构建。 3. 新增模块间依赖时必须在根pom.xml的dependencyManagement中声明版本子模块不写版本号。 4. 如果单测全跑太慢建议只跑受影响模块的测试命令格式为mvn test -pl module-name -am。我给AI塞了这一份之后它在我那个模块依赖非常混乱的旧项目里居然一次都没有跑错过构建顺序。以前裸用Codex CLI它可真敢直接在某个不依赖别的模块的子目录里乱跑命令白等几分钟就为了看它碰壁那种感觉真的让人血压拉满。5. 常见问题与排查技巧实录5.1 安装与配置环节五个高频报错的处理思路我前后在四五台机器上装过superpowers也帮几个朋友远程排查过问题。这里总结五个最高频的问题及处理思路你可以把这份表存起来遇到问题直接对着查现象常见原因处理方式安装脚本报curl: command not found极简镜像或未装curl先执行apt install curl或brew install curl再重新跑安装命令技能包目录为空仓库克隆失败或网络波动手动git clone仓库再把skills目录里的内容复制到~/.codex/skills/Codex CLI完全忽略技能包版本过旧不支持技能加载更新Codex CLI到最新版执行npm update -g openai/codex或按官方文档升级AI报错Cannot read skill file技能包SKILL.md权限不对或路径有中文确保~/.codex/skills/路径下无中文目录并执行chmod -R 644 ~/.codex/skills/模型回复质量没有变化模型后端配置不对技能包没被系统提示词载入检查model_provider是否与你实际的API服务匹配确认配置文件中没有拼写错误其中“权限不对”这个问题隐蔽性极高。因为技术类项目的用户普遍在服务器上跑任务有时候整个home目录是从别的机器同步过来的文件权限没对准Codex CLI进程读不了SKILL.md但又不会明确报“权限不足”只会默默忽略技能包。遇到这种情况一条find ~/.codex/skills -name *.md -exec chmod 644 {} \;基本能解决。5.2 使用环节技能包“不听话”时怎么办技能包装好了AI也识别到了但实际跑任务的时候它就是不按技能包里的规则来。这种情况我也遇到过不少次原因往往不在技术而在“提示词工程”的细节上。最典型的一个坑是技能包里的规则写得太原则化。比如你写“代码要清晰易懂”模型看了等于没看。但如果你写“每个方法超过30行必须拆分为多个小方法”模型就会严格数行数、触发拆分。AI对模糊指令的理解远没有对量化指令的严格执行。所以每次你觉得“AI不听话”先回头看看自己写的话够不够具体。另一个问题是技能包冲突。当你同时装了多个技能包而它们对同一件事给出了不同意见时模型可能会随机选一个或者把两边的规则混合起来用。比如某个通用技能包说“方法名用动词开头”你自己的项目技能包说“方法名用名词短语”模型就会无所适从。处理方式很粗暴但有效同类职责只留一个技能包或者把冲突的规则统一描述清楚。还有一个经验值得单独分享技能包的正确率不是一次写出来。我建议每个技能包前面都加一个last-reviewed字段每当你发现它引出了一个糟糕的结果就去更新SKILL.md把模糊措辞改成明确规则把缺失场景补进去把不适用的情况写进“禁止”。这其实跟维护一个高标准的wiki一样维护得越勤AI干活越稳。5.3 从现象反推问题三个真实翻车案例复盘案例一某次我在一个Rust项目里用superpowers装好之后AI表现得对技能包“视而不见”。我折腾了半天最后才发现项目里有个.codexignore文件把skills目录给忽略了。Codex CLI在加载上下文时会参考这个文件被忽略的内容自然不会被读取。从那以后我养成了习惯遇到AI不认技能包先检查ignore类配置。案例二有次技能包导致AI在Java项目里反复调整测试代码改了一圈反而弄坏了一个本来通过的测试。排查后我发现在writing-tests技能包里写了一句“保证所有测试通过”模型就真的死磕到所有测试都绿为止甚至不惜去修改业务断言。后来我改成“测试失败时先寻找并修复被测代码的问题禁止修改既有测试断言来规避失败”情况立刻好转。技能包的措辞真的会直接影响AI的行为边界。案例三有个朋友在自己电脑上装superpowers后发现技能包里的Markdown表格被读取得非常混乱。我一看他SKILL.md里用了大量表格去描述规则。虽然Markdown表格是人类阅读的好形式但模型解析表格时确实容易漏行漏列。我建议把关键规则从表格改成逐条列出的无序列表或编号列表解析准确率立刻改善。有时候为了AI读懂稍微牺牲一点我看的舒服程度是值得的。6. 一些进阶玩法把superpowers从“工具”变成“团队资产”如果你已经跑通了基础用法并且平时确实在用Codex CLI辅助开发那我可以分享几个让superpowers进一步发挥价值的进阶方向。第一个方向是“团队规范沉淀”。很多团队有非常细致的代码规范、提交流程、问题排查手册但这些文档往往沉睡在Wiki里工程师写代码的时候根本不会去看。而通过superpowers你的团队可以把这些规范转化成AI能主动遵循的技能包。新成员入职第一天不用死记硬背项目章程Codex CLI已经替他们读了。第二个方向是“跨语言统一工作流”。如果你的团队是Java、Go、Python多语言混用你可以为每种语言建一套独立的技能包再建一套跨项目的通用技能包比如Git提交规范、代码审查清单、安全扫描流程。AI在处理不同语言的项目时会自动选择对应技能包组合。这相当于给整个研发团队配了一个“读过所有内部文档”的AI同事。第三个方向是我自己正在尝试的就是让技能包不只覆盖编码还覆盖“复盘”和“规划”。比如我写了一个retrospective技能包让AI在每个迭代结束前自动总结变更内容、检查未完成事项、生成风险清单。倒不是说AI能替代工程师做项目管理但在信息收集和整理这些耗时耗力的底层工作上技能包确实能帮上大忙。我个人在实际使用中体会到superpowers的价值曲线是“越用越陡”的。初始装好它可能只是让你的AI助手表现得规矩了一点点但当你持续往里面沉淀团队经验和项目知识时它带来的效率提升会越来越明显。技能包就像是你和AI之间的一份“共同语言契约”——你替它把规矩写明白它还你一个真正懂行、靠谱的同事。如果你正在长期使用Codex CLI又苦于它总是“有技术没纪律”不妨按照文章里的思路装一套从写第一个定制技能包开始。
阅读完成 · 觉得有帮助？
