如果你最近在折腾 Codex CLI应该已经不止一次听到 “superpowers” 这个名字了。这个项目本质上是一套给 Codex 用的技能与子智能体插件让原本“什么都会但什么都不精”的 AI 编程助手摇身变成有明确专长、懂得拆分任务、甚至能记住项目上下文的全栈开发搭子。我花了两个周末把它跑通又陆续在几个真实项目里试了 Java、Web 和 Android 相关技能这里把完整的使用心得、安装步骤、踩坑记录都整理出来给想上手的朋友一份可以直接照着操作的参考。它适合什么人如果你已经用 Codex CLI 写过脚本、补过测试但觉得它在多文件架构调整、框架级开发、文档维护这些场景下还是太“飘”那 superpowers 就是为补这块短板设计的。它解决的核心问题是默认 Codex 只会对着你的指令逐句响应不会主动构建上下文、不会按专业最佳实践拆解任务而 superpowers 通过注入大量领域专家的思维模板让 Codex 在你的项目里表现得像一个真正写过多年 Java、或者真的维护过安卓工程的老手。1. 先搞清楚 superpowers 的核心设计技能就是提示词工程在动手安装之前我建议你先花十分钟理解它的工作原理否则后面排查问题容易一头雾水。superpowers 的本质不是一个新的模型也不是一个新编译器它就是一套高度结构化的提示词集外加一套让这些提示词按需加载的管理机制。1.1 技能文件是什么每个技能对应一个 Markdown 文件文件名就是技能的名字比如java-reviewer.md、android-architect.md。文件内容不是给人看的文档而是给 Codex 看的工作手册——里面详细写明了这个技能适用的场景、在执行任务时需要遵循的步骤、需要重点检查的代码特征、输出结果时应该按什么格式组织等等。Codex 在读取这些文件之后会按照手册的指引来决定自己该以什么“身份”和“流程”来完成你交办的任务。这个设计的聪明之处在于它把“如何做一个合格的 Java 开发者”这种抽象的、难以言传的经验拆解成了一串可执行的动作。比如针对 Java 项目的代码审查技能文件里会明确写先检查 Maven 或 Gradle 依赖是否有冲突、再检查异常处理是否吞掉了关键信息、检查集合遍历时有没有发生并发修改异常、最后按严重程度分级输出问题清单。这比你对 Codex 说一句“帮我 review 一下代码”要可靠得多因为模型不再需要自己猜测“该怎么 review”而是照着硬性的检查清单逐项过。1.2 AGENTS.md 和动态加载机制superpowers 在项目里真正生效靠的是一个位于根目录的AGENTS.md文件。Codex CLI 原生会读取这个文件作为项目上下文的入口而 superpowers 利用这个机制在AGENTS.md里写入了技能索引和触发规则。索引文件会告诉 Codex你拥有一个技能库里面有哪些领域的技能每个技能大概负责什么当用户在对话中提到某些关键词时你就去加载对应的技能文件。操作上很多时候你并不需要显式地输入“加载 java 技能”这种指令。你可以直接说“用 Java 后端的视角审查这个 Service 层的实现”或者“按安卓最佳实践帮我把这个功能模块重新组织一下”Codex 在读到AGENTS.md的索引后会自己去找对应的技能文件来加载。这就像你给团队新成员发了一本操作手册他干活之前先翻对应章节而不是每次都跑过来问你怎么办。1.3 子智能体的概念技能不只是静态的提示词还引入了“子智能体”的行为模式。一个技能文件可以约定在开始正式任务前先让 Codex 做信息收集信息收集完成后再进入方案设计方案设计确认后再开始写代码。这种分阶段的执行方式避免了你在对话里反复说“你先把代码读完再动手”技能文件已经把这类惯例固化成规则了。我实际用下来最明显的感受是同样的需求和同样的模型接入了技能库之后Codex 的代码产出质量确实提升了尤其是在涉及多文件改动、需要保持架构一致性的任务上它不再像以前那样“指哪打哪”而是会先向你确认设计方向再动手改代码。这一点正是它区别于普通 Codex 插件、普通提示词模板的核心价值。2. 安装配置全流程不费劲但容易漏细节superpowers 的安装逻辑并不复杂本质就三步下载技能库、建立 Codex 对技能库的索引、在项目里放好AGENTS.md。但我见过不少人在安装那一步就卡住了最常见的原因是网络、路径填错、以及忘记把 Codex 指向正确的模型配置。2.1 前置条件安装 superpowers 之前你要确保 Codex CLI 已经在本机正常跑起来。这里不复述 Codex 安装的过程只说两个和 superpowers 强相关的点第一Codex 的登录状态必须有效codex login不能是失效状态第二Codex 的模型配置建议选用能力足够强的版本上下文窗口越大越好因为技能库文件本身会占用不少 token如果模型只支持很小的上下文技能内容可能还没读完就开始截断了后面干活会明显变差。我在一台低配的旧笔记本上试过用较弱的模型跑 superpowers结果技能文件里的上下文塞进去之后留给实际代码分析的 token 空间就所剩无几回答质量大打折扣。为了让你有更好的完整体验我强烈建议评估完前置条件再继续这并不复杂却是后面所有环节的基础。2.2 安装技能库superpowers 项目的技能库是通过 Git 仓库发布的。你只需要把仓库克隆到本机即可。选择一个你方便记忆的目录我放在~/.codex/skills下面这样结构比较清晰mkdir -p ~/.codex git clone https://github.com/oborber/superpowers.git ~/.codex/superpowers克隆完成后技能文件通常位于仓库里的skills/目录下里面会有几十甚至上百个 Markdown 文件按领域分了子目录比如 Java、Android、iOS、Python、Web、Docker、Kubernetes 等。你可以直接把这些文件原封不动保留暂时不要去改动它们的内容因为索引文件名和内部的自引用路径可能有关联改乱了会导致加载失败。2.3 配置项目级 AGENTS.md每个要用到 superpowers 的项目都要在项目根目录放一份AGENTS.md。如果你有多个项目每个项目的AGENTS.md内容是基本一样的它主要是负责加载索引和技能库路径信息的# Project Context This project uses the Superpowers skills system. Read the available skills and their triggers from ~/.codex/superpowers/SKILLS.md. When encountering a task from a domain covered by a skill, load the corresponding skill file from ~/.codex/superpowers/skills/ before responding.我建议把这一段内容作为基础模板保存起来每次新建项目时直接复制过去再根据项目实际情况做少量调整。注意路径不要写错尤其不要省略主目录前的~Codex 不一定会帮你自动展开环境变量或波浪号。2.4 验证是否加载成功验证方式很简单在项目目录下启动 Codex直接问一个问题“基于当前项目的 AGENTS.md告诉我你有哪些技能可以使用”如果配置成功Codex 会列举出技能清单比如安卓开发、Java 代码审查、Python 重构等。如果没有列举出任何技能基本都是路径配置或者AGENTS.md内容没被正确读取回到上面两步检查。我自己的经验是不要急着一上来就让 Codex 跑大任务先用一个最小化的验证问题确认技能加载链路是通的这一步能帮你省下后面大量排查时间。3. 核心技能拆解和实战用法以 Java 为例很多人检索“superpowers java”就是想看看它在 Java 项目里到底能干嘛。我挑两个最常用的场景来拆解代码审查以及 Spring Boot 项目模块重构。这两个场景能比较充分地展示技能文件是如何改变 Codex 的行为方式的。3.1 Java 代码审查技能在原生 Codex 下你说“帮我审查一下这个 Service 类的代码”它给你的结果可能是一段笼统的建议比如“注意空指针”“建议加日志”——这些建议不能说错但很难直接落到代码里。加载 Java 技能后整个流程就变了。Codex 会先读取技能文件里的审查清单然后对照清单去检查具体的方法实现最后输出一份带着文件路径、行号、问题分级和修改建议的报告。这里我打一个比方。原生 Codex 像一个没做过 code review 的实习生他看代码只能看到表层问题superpowers 里的 Java 技能则像一个带过无数项目的架构师他会先看事务边界、再看异常处理、再看并发安全和性能瓶颈。如果你自己就是资深开发者可以把技能文件里的审查清单理解成你们团队的 Checkstyle 规则升级版——它约束的不只是格式而是设计与健壮性维度。从实际操作上讲你在 Codex 里输入这样一句“用 Java 技能里的代码审查流程审查src/main/java/com/example/service/OrderService.java”随后 Codex 会在回答开头简单说明它正在加载 Java 代码审查技能并列出即将检查的维度。这不是性能展示而是技能文件要求的响应格式。3.2 Spring Boot 项目重构场景重构一个模块比审查单文件复杂得多。你需要先理解既有模块的职责边界、依赖关系再决定拆成哪个子模块最后还要保证 Maven 构建不挂。原生 Codex 很难独立完成这整套流程因为它缺乏对“重构前必先建立模块边界认知”这一习惯的强制性约束。superpowers 的 Java 技能里包含了一套重构工作流先扫描目录结构、梳理依赖关系产出模块划分建议在得到你确认后才启动代码迁移迁移过程中会检查 import、bean 注册、配置文件等需要同步调整的部分。我实际跑过一次一个订单模块的抽取Codex 在技能引导下输出了明确的迁移步骤并且每一步都给出来了具体的受影响文件清单这和以前“你问一句它答一句”的体验完全是两个档次。3.3 技能覆盖范围一览关于技能覆盖范围我这里列一个常见的领域表因为不同的仓库版本覆盖范围略有不同具体以你克隆到的版本为准技能领域典型用途触发关键词示例Java 后端代码审查、Spring Boot 重构、性能排查审查 Service、重构模块、检查事务Android架构审查、Compose 迁移、性能优化检查 ViewModel、Compose 重构Web 前端React/Vue 组件审查、状态管理优化审查组件、拆分状态Python代码质量、依赖排查、异步重构审查 async 逻辑、整理依赖Docker/K8sDockerfile 优化、部署文件审查优化镜像、检查 Deployment这张表的价值在于你不需要记住每个技能的具体文件名只需要知道触发的关键词大概长什么样Codex 会自动通过SKILLS.md完成匹配。4. 自己动手定制技能把团队规范写进提示词如果 superpowers 里自带的技能不能满足你的需求动手写一个适合自己团队的新技能并不复杂而且这才是这个工具最值得投入的地方。因为每个人的项目领域、代码风格、团队规范都不同通用技能是够用但定制技能才能真正贴合自己项目的特定上下文氛围。4.1 技能文件的结构一个技能文件通常由几个部分组成我建议你用固定的模板来组织技能名称和用途描述第一句话就要写清楚“这个技能负责什么”适用场景也就是什么时候该加载这个技能执行流程这是核心需要把步骤一步步写清楚输出格式比如要求按问题清单、按严重程度、按文件路径来输出结果注意事项哪些是不能做的比如“不要在没有获取用户确认前修改 pom.xml”下面是一个最小可用的自定义技能示例目标是规范项目中的日志打印# 日志规范审查技能 ## 适用场景 当用户要求检查日志代码或者调整日志输出时加载此技能。 ## 执行流程 1. 扫描项目中所有 Java 文件的 logger 调用。 2. 检查是否使用 slf4j 占位符而非字符串拼接。 3. 检查是否打印了敏感信息如手机号、身份证号。 4. 检查日志级别是否合理禁止在循环内打印 info 以上级别日志。 5. 输出问题列表标注文件路径和行号。 ## 输出格式 按严重程度分级输出高、中、低。 ## 注意事项 - 不修改代码只输出问题报告。 - 如果日志代码涉及业务逻辑变更提示用户确认后再执行。写好后把文件放到技能库的skills/目录下然后在AGENTS.md或SKILLS.md的索引里登记一行告诉 Codex 这个技能的存在和关键词。之后在对话中输入“按团队规范检查日志”或类似描述Codex 就会加载你刚写的技能文件。4.2 提示词设计的心得写技能文件本质上是在写提示词我自己从实践里提炼了几个值得注意的点。一是少用模糊形容词。“提升代码质量”这种话没有操作价值但“检查是否有未关闭的 Statement”就是可执行的指令。技能文件里每一句话都应该能转译成一个具体动作。二是明确边界。技能文件里一定要写清“哪些事不做”。如果你不限制 Codex 的发挥空间它很可能在审查代码时顺手把你整个项目结构都重构了这未必是你想要的。三是控制技能文件体积。一个技能文件不要写得越长越好控制在 80 行以内比较合适。太长的技能会让 Codex 在加载时占用大量上下文空间反而可能挤占实际执行环境。把真正必要的内容写清楚冗余解释一句都不要有。四是要定期迭代。我在团队里推行了一段时间之后会根据 Codex 实际犯过的错误反向补充技能文件。比如它有一次在报告里没有标注行号我就把“所有问题必须标注文件路径和行号”写进了输出格式。技能文件是活文档持续打磨才有价值。5. 常见问题排查和避坑实记superpowers 装好容易用顺不容易运行过程中会遇到一些比较有共性的问题我把它们集中整理一下供你排查时参考。5.1 技能不生效回答还是普通 Codex 风格这是遇到最多的情况。你发现不管你怎么说Codex 好像完全没有读取技能文件里的要求还是像以前一样泛泛而谈。这类问题九成出在AGENTS.md没有被正确读到或加载。排查时先确认你启动 Codex 的目录就是项目根目录然后再确认AGENTS.md的路径写的是不是技能库的真实位置。另一个容易忽略的点是Codex 在已有对话上下文里可能不会主动重新读取AGENTS.md如果你已经处于一个长对话中中途才放入了AGENTS.md文件那当前对话里的 Codex 很可能还不知道有这个东西存在。这种情况下最直接的处理方式是新开一个对话会话再验证技能是否生效。5.2 技能文件加载了但执行结果还是达不到预期很多时候技能确实加载成功了——你可以在 Codex 回答的前缀里看到它提到了技能名称——但执行结果依然偏弱。这通常不是技能加载问题而是因为上下文空间不够。技能文件、索引、加上项目代码片段一起塞入之后留给模型推理的余量不足。遇到这种情况可以尝试精简当前任务的范围一次只让 Codex 处理一个模块而不是丢给它一整个服务端的代码让它做全面审查。5.3 模型“自作主张”越过你确认的边界我遇到过几次比较头疼的情况技能文件里明确写“只在获得用户确认后再修改构建文件”但 Codex 还是自作主张改了 pom.xml导致构建失败。这种事只能靠两方面去约束一是把技能文件里的注意事项写得更加明确并且放在显眼的位置二是在关键任务开始前用单独的指令把边界重新强调一遍。比如你可以说“在修改 pom.xml 之前必须停下来等你确认”。你这就要看到一个现实状况了技能并不是魔法它们只是提高了模型遵循规则的概率而不是把概率变成 100%。所以关键流程上还是不能完全放松警惕要让 Codex 在执行关键动作前先展示方案你确认后再继续。5.4 Token 消耗明显增大技能系统确实会带来更多的 token 消耗因为每次加载技能文件都要把完整的 Markdown 内容读进去。如果你的预算比较紧张我建议不要加载所有技能而是把不常用的技能文件转移到单独的目录只保留当前项目常用的十几个技能。特别是那种文件很大但实际很少用到的技能转移出去能省下不少 token。5.5 多个技能之间的冲突问题最后还有一个比较隐蔽的问题如果你的技能库里有两个技能覆盖的场景非常接近Codex 可能同时加载两份技能文件里面的执行流程如果有冲突行为就会变得不可预测。比如一个技能要求“输出问题清单不要附带修改意见”另一个技能要求“输出问题时附带修改示例”它们就可能打架。我自己的处理方式是在SKILLS.md索引里给每个技能明确标注适用范围和关键词尽量避免重叠。角度不同也要注意同类技能保留一个最完整的版本就够了。从整个使用过程来看superpowers 并不是一个让 Codex “一夜变成资深架构师”的魔法插件而是通过精心设计的技能系统把那些优秀开发者潜意识里的工作方式显性化、结构化再交给模型去执行。我自己的体会是它真正的价值不止于那几十个现成技能文件更在于给了你一套“如何与 AI 协作”的新思路与其反复用自然语言去引导模型不如把引导过程沉淀成文件让 AI 在每一次任务里都自动按最佳路径前进。后面我还在继续探索把团队内部的代码规范、发布流程逐步沉淀成自定义技能这个过程本身就已经变成项目效率提升的一部分了。