从第一次在终端里见到 Codex CLI 的“自动写代码”到后来发现它其实没那么懂你的项目这个心路历程我估计不少人都经历过。单纯让它“写个函数”很爽但真要让它按团队规范、按项目约定去执行一整套流程它就像个聪明但没受过训练的新人每次都得你手把手喂指令。superpowers这个项目就是冲着这个痛点来的它不是另一个 AI 编程工具而是给 Codex CLI 装上一套“职业技能”的框架让 AI 在动手之前先知道自己该按什么规矩干活。这篇文章我会从它的设计思路讲起再带你完成安装、初始化、技能配置以及一个 Java 项目的实战接入。如果你已经在用 Codex CLI并且开始觉得它“差点意思”那这篇文章就是给你准备的。我默认你已经知道 Codex CLI 能做什么但不会假设你了解 superpowers 的内部机制。整体内容按“先讲思路、再上实操、最后排坑”的节奏来所有命令都是我在自己机器上验证过的常见路径你照着抄基本不会跑偏。1. superpowers 在解决什么问题先理解“技能”这个思路1.1 Codex CLI 原生能力的边界在哪Codex CLI 这类终端编程助手本质上是一个“能读文件、能改文件、能执行命令”的大模型代理。它的优势是语言理解和代码生成但短板也很明显它对你的项目结构、构建工具、代码规范、发布流程一无所知。你让它“跑一下测试”它可能先问你用什么测试框架你让它“打个包”它可能不知道项目用的是 Maven 还是 Gradle。这些知识不是大模型没学过而是每个项目都不一样模型没法在每次会话里天然“猜中”。如果没有额外约束它只能靠猜猜错了就来回折腾。这也是为什么有人觉得“AI 编程不靠谱”——不是模型不行是它缺少一套针对当前场景的操作手册。superpowers 做的事情就是把这类“操作手册”结构化地提供给 Codex。它定义了一种叫“技能skill”的东西技能是一个包含说明文字和可选脚本的包Codex 在碰到对应任务时会先读取技能内容再按里面的步骤执行。简单说它给 Codex 装上了一本“岗位说明书”。1.2 技能机制的核心设计我最早接触 superpowers 时以为它是类似“插件市场”的东西后来用下来发现比插件轻得多。一个技能本质上就是一个名为SKILL.md的 Markdown 文件文件名固定内容分两部分开头的元信息YAML 格式和正文的指令说明。元信息里通常写着技能叫什么、什么场景下该用、能解决什么问题。正文则包含详细的执行步骤、命令示例、注意事项甚至可以直接贴一段脚本让 Codex 调用。当 Codex 在任务里看到与某个技能描述匹配的内容它就会把技能正文当成上下文的一部分用里面的规则去约束自己的行为。这里有个很巧妙的点superpowers 不把所有技能全文一次性塞给模型而是先注入一个“技能索引”让模型知道你现在有哪些技能可用各自负责什么。真正需要哪个技能时再把对应细节展开。这种做法对上下文窗口非常友好不会因为技能装多了就挤占正常的代码分析空间。1.3 这种方案和插件/Agent 框架有什么不一样市面上有很多 Agent 框架动辄就是“编排、工具调用、状态机”一套组合拳能力强但学习成本也高。superpowers 的风格更“草根”没有常驻进程没有复杂配置没有远程服务就是一堆 Markdown 文件加上几个命令行工具。好处是透明——技能内容你可以逐字审查不放心就不装坏了也容易排查打开文件看看就知道问题在哪。另一个好处是易传播——技能就是文本放进 Git 仓库就能和团队共享新人 clone 下来直接初始化能获得和老人一样的 AI 辅助体验。这套思路本质上是在“约束”模型而不是“封装”模型。它不试图让你摆脱 Codex而是让 Codex 在既有框架里变得更有纪律性。2. 安装与初始化把 superpowers 装进你的终端2.1 开始之前要准备什么先检查环境。我目前用的环境是 Node.js 20 LTSCodex CLI 已经完成登录认证codex命令在任何目录下都能正常执行。superpowers 本身依赖 Node.js 运行环境所以第一步是确认你机器上有可用的 Node.js版本建议 18 以上太老的版本容易出现兼容问题。另外建议先跑一次codex --version确保 CLI 本身没问题。别小看这一步我自己就遇到过 Codex 配置没弄好结果以为是 superpowers 装坏了排查了半天才发现是登录态失效。提示如果你平时是通过 npm 全局安装工具建议顺手把 npm 源切到官方源或你公司内部镜像。安装 superpowers 时大部分依赖都来自 npm源不稳定会导致装到一半失败。2.2 跑起来init 与基础技能安装很直接不需要克隆仓库用 npx 就可以npx superpowerslatest init这个命令会做三件事把 superpowers 的核心文件放到你的用户目录下初始化基础技能库最后询问你是否需要把 superpowers 的提示词注入到 Codex 的默认配置里。第三件我建议选“是”不然后面每次开 Codex 都要手动引用体验差一大截。初始化完成之后可以看看当前有哪些技能npx superpowers list我这边刚 init 完列表里有 github、google、web-scraping、polling 一类的基础技能。这些技能覆盖面不算深但足以让 Codex 在遇到“去查一下某个 issue”“帮我把这个页面内容抓下来”这类任务时不用再临时临急想方案。之前你如果还没装过任何扩展技能基础技能就是第一层保障。init 之后建议重新开一个终端窗口再启动 Codex让新配置完全生效。2.3 第一次验证让 Codex 真正“调用”技能装好之后怎么确认它真的生效了最简单的验证方式是在 Codex 里直接输入一个跟技能相关的任务。比如看到基础技能列表里有 github就问它用 github 技能帮我看看当前仓库最近一周的 PR 列表如果它按技能里的方式调用 GitHub API 或命令行工具而不是一本正经地瞎编说明 superpowers 已经被 Codex 感知到了。第一次验证不通过也别急多数情况是初始化时没有正确写入 Codex 配置。这时重新跑一次 init仔细看交互提示确认每一步都选了“是”。另外如果你之前手动改过 Codex 的配置文件superpowers 的注入可能会被覆盖这一点我在后面“常见问题”里会再展开。3. SKILL.md 解析一个技能的解剖图3.1 技能文件长什么样技能目录结构非常统一我拆一个典型例子给你看skills/ java-build/ SKILL.md scripts/ parse-maven-log.sh其中SKILL.md是技能的核心scripts目录下放的是辅助脚本。模型在读到技能时正文会告诉它脚本怎么用、什么时候用而不是把脚本本身读进上下文。我建议一个技能只做一个领域的事不要想着“一个技能解决所有 Java 问题”。技能越大模型越难准确判断触发时机。宁可拆成 java-build、java-test、java-deploy 三个技能也别合成一个 java-everything。3.2 元信息写得好不好直接决定触发率SKILL.md的开头是 YAML 格式的元信息这段看似简单其实是整个技能能不能被正确触发的关键。我见过不少别人分享的技能正文写得挺详细但 description 写得模棱两可模型根本不知道什么时候该用它。一个描述比较到位的例子--- name: java-build description: 在 Maven 或 Gradle 项目中执行构建与打包。当用户要求编译、打包、构建 Java 项目时使用。 ---这段描述里有两个关键信息适用的构建工具Maven/Gradle以及触发场景编译、打包、构建。模型拿到之后哪怕用户只说“帮我出个 jar”它也能把这个技能和任务对上。正文部分则以“操作步骤”为主尽量指令化。我习惯把步骤写成序号列表第一步检查什么、条件分支是什么、最后产出什么都写清楚。不要用散文模型对确定性步骤的还原度更高。## 操作步骤 1. 检查项目根目录是否存在 pom.xml 或 build.gradle。 2. 如果存在 pom.xml执行mvn clean package -DskipTests 3. 如果存在 build.gradle执行gradle clean build -x test 4. 构建成功后汇报产物路径。3.3 技能里的脚本与工具扩展光靠文字指令能让模型“知道该做什么”但如果能让它“直接调工具做”效率会更高。比如一个建仓技能正文里写“执行 git init 并创建 .gitignore”虽然也可以但把一段验证脚本放进去模型执行时就能更精确地检查结果。脚本的存在不是让模型去阅读脚本内容而是给模型一个可执行入口。模型只需要知道脚本路径、作用、预期输出然后在合适时机用终端执行它再根据输出判断下一步动作。要注意的是脚本必须考虑跨平台问题。我自己写过几个技能脚本在 Linux 上跑得好好的一换 macOS 或者 Windows 就各种路径问题。如果技能要分享给团队至少要在脚本开头处理一下系统判断别让队友一用就报错。4. 实战接入把 Java 项目管起来4.1 给已有项目安装外部技能superpowers 支持从 Git 仓库安装技能命令是npx superpowers install gitgithub.com:someuser/superpowers-java-skills.git社区里已经有不少现成的技能集合装之前我建议先看它的目录结构确认里面是不是标准的skills/技能名/SKILL.md布局。如果布局不对安装后列表里可能看不到到时候还得手动挪。安装是全局生效还是仅当前项目生效取决于你执行命令时所在的目录。我个人更推荐在项目根目录执行 install这样技能跟项目绑定换机器 clone 项目之后重新 init 一次技能就回来了团队协作体验很好。4.2 一次 Maven 项目的真实操作流程我拿手上一个老旧的 Maven 项目做实验项目没有 README依赖关系复杂平时构建靠人肉回忆。以前的 Codex 在这个项目里基本废掉一半因为每次都要先跟它解释“这是 Maven 项目父 POM 在哪个目录测试要排除哪几个类”。接上 superpowers 之后我让 Codex 执行跑一遍完整构建跳过单元测试然后告诉我产物在哪它先命中 java-build 技能技能正文里明确写了“Maven 项目用mvn clean package如果跳过测试则追加-DskipTests”。于是它直接执行了mvn clean package -DskipTests整个过程没有任何多余的确认和反问。构建结束之后它根据技能里的“汇报产物路径”规则找到了 target 目录下的 jar 文件给出了完整路径。这事单独看没什么神奇但对比一下之前同样一句需求Codex 会先问“用 Maven 还是 Gradle”再问“要不要跑测试”再问“产物要什么格式”。现在这些信息全由技能提前写死了交互成本直接降到一次。4.3 自己写一个团队专属技能外部技能解决通用问题团队内部那些“不成文的规定”才更需要固化。以我所在团队为例我们发布前有个固定流程先更新 CHANGELOG、再跑完整测试、最后执行发布脚本。这套流程以前只存在于几个老同事的脑子里现在我用一个技能把它写了下来。创建技能其实就是在本地建一个目录放上SKILL.md然后用 install 指向本机路径npx superpowers install ./skills/team-release技能正文里我把每一步的检查项都列出来比如“是否更新了 CHANGELOG”“测试是否通过”“发布脚本是否加了版本参数”。之后任何成员在 Codex 里说“走一遍发布流程”模型就会按技能里的清单逐项检查漏了哪一步它会停下来提醒。这个技能放进 Git 仓库之后新人接入的成本大大降低。以前要找人问半小时的“老规矩”现在 AI 已经在动手之前替他们过了一遍。5. 常见问题与排查技巧实录5.1 高频问题速查表用了一段时间我把自己遇到的、以及群里经常看到的问题整理成了一张表方便你对照排查。现象可能原因排查/解决办法npx superpowers命令找不到Node.js 版本过低或 npm 全局目录不在 PATHnode -v确认版本重装 Node.js 或用 npx 方式调用init 执行成功但 Codex 里技能没反应Codex 配置没有被注入或终端缓存了旧配置重新执行一次 init确认注入提示重启终端后再试列表里有技能但模型从不触发SKILL.md 的 description 写得不够明确检查描述里的触发词尽量写明“当用户要求……时使用”安装社区技能后列表里看不到技能目录结构不符合 superpowers 约定手动查看仓库目录确认是skills/名称/SKILL.md结构技能正文改了但行为没有变化Codex 会话上下文里还是旧技能内容新开一个 Codex 会话再试别复用旧窗口技能脚本在别的机器上报错脚本里硬编码了路径或依赖特定 shell在脚本开头做系统和路径判断或用可移植的命令5.2 踩坑总结技能管理里的几个关键细节第一不要贪多。第一次用 superpowers 的时候我从社区装了一堆技能什么前端、后端、运维类的都有。结果 Codex 每次会话要读取技能索引技能太多之后模型对每个技能的“感知”都被稀释了触发准确率反而下降。现在我一个项目最多装四五个相关技能宁缺毋滥。第二description 要用“用户需求”的视角写而不是“技能功能”的视角写。比如“执行 Maven 构建”不如“当用户要求编译、打包 Java 项目时使用”容易让模型对上号。模型面对的是用户的自然语言技能描述应该模拟用户会怎么问。第三技能版本要跟着项目走。团队里如果改了一个共享技能一定要明确是向后兼容的改动还是破坏性改动。技能文件是纯文本别人 clone 项目时会直接拿到最新版这既是优点也是风险点——没经过 review 的改动会被队友静默使用。我现在会在技能的目录里加一个CHANGELOG.md每次大改都记录一句。最后想提醒的一件事superpowers 本身不会帮你调试 Codex 的登录态和网络问题。遇到“模型不理技能”这种诡异问题先跑一遍基础环境检查排除 Codex 自身问题再回头改技能内容能省不少时间。我在实际使用中的体会是superpowers 的定位更像“给 AI 立规矩的工具”它不改变 Codex 的底层能力只改变 Codex 展开工作之前阅读的“说明书”。一旦技能库沉淀下来AI 在项目里的表现会有一种“知道自己是谁、该干什么”的稳定感。最后再分享一个小技巧把新成员入职要做的环境配置、本地启动步骤也写成技能让 Codex 带着新人过一遍比看文档高效得多。
