1. superpowers 是什么给 Codex CLI 装上“技能面板”最近在开发者圈子里“superpowers”这个词出现得越来越频繁。如果你平时用 Codex CLI 或者其他命令行编码代理大概率能明显感受到一件事这类工具做简单任务很利索但一旦涉及具体项目的代码规范、目录习惯、框架版本差异就得反复调教。模型不是不行是缺少上下文缺少对工程经验的封装。superpowers 的出现正好切在这个位置上。它是一套面向 CLI 编码代理的增强配置框架核心是“技能skills”机制。你可以把技能理解成一个带输入输出规范的提示词单元里面不仅写清楚了任务怎么做还能附带脚本、模板、校验规则。比如项目里常见的“代码审查”“测试用例生成”“依赖升级”这类高频操作原本每次要敲一大段说明现在可以封装成一个技能让整个团队复用。这套东西火起来和 Codex CLI 的走红是同步的。很多人都在搜“codex superpowers”就是因为 Codex 本身提供了 Agent 式的命令行交互但缺少成熟的工程化脚手架superpowers 正好补上这一环。更有意思的是不少主做 AI 工程化工具教程的自媒体比如 worbuddy 这类讲“怎么用 superpowers”的内容也开始把它当做一个独立章节来讲解这说明它已经从个人脚本进化成一套可传播的方法论。从我这个常年赖在命令行干活的人的角度看superpowers 的核心价值不在于多了一个命令而在于它让 AI 协作从“临时对话”变成了“可积累的资产”。代码写多了你会意识到真正值钱的不是某一次生成结果有多好而是你能否把一套有效的做事方式沉淀下来让下一次、下一个人也能稳定复现。superpowers 的目录结构、技能注册、触发规则本质上都在做这件事。1.1 为什么常规的 AGENTS.md 不够用很多项目已经在用 AGENTS.md 给 Codex 提供项目说明这种方式是不是够用说实话在小项目里是够的我也见过不少团队靠一份精心维护的 AGENTS.md 就能把模型调教得很好。但项目一复杂AGENTS.md 越写越长最后变成一本没人想读的说明书。模型每次都要把整份文件塞进上下文既浪费 token又抓不住重点。superpowers 的思路恰恰是反过来不再给模型一份大而全的说明而是把任务拆成一个个可独立加载的技能包。模型碰到具体场景只加载对应的技能。用的时候取不用的时候不占上下文。这个思路和平时整理代码库时的模块化思想一脉相承但真正落实到 CLI 代理上效果要远好于“一段提示词打天下”。我见过不少团队把 AGENTS.md 当成万能池什么规范都往里扔。结果项目一迭代文件里既有过时的库名又有前后矛盾的规则。模型在混乱上下文里挑挑拣拣输出质量非常看运气。技能机制强制你按场景组织知识一次一次加载思路会清晰得多。1.2 一次真实体感从“没头没尾”到“有板有眼”我第一次跑通技能时的体感至今记得很清楚。当时在一个 Spring Boot 项目里我用 Codex 让它做一次 service 层的代码审查。没装 superpowers 之前我必须手动补一大段背景说明项目用的 Java 17、Spring Boot 3、Controller-Service-Mapper 三层结构、异常处理走全局 advice……光是这段话就要写一百多字而且每次都要重写。把这段逻辑写成技能之后在 Codex 里只需要说“review-java 一下 UserServiceImpl”模型会自己按技能里的步骤走先读文件再对照分层规范最后按固定格式输出问题清单。前后对比就像请了一位“只带了笔记本的新人”和“提前看过项目资料的临时工”的差别后者明显更靠谱。2. 安装前必须搞定的环境版本、网络与目录权限打开终端做的第一件事不是装包而是检查环境。我见过太多人一上来就 npm install然后被各种报错劝退最后得出结论“这工具不行”。其实大部分问题都出在环境上按这个顺序检查能省非常多事。2.1 Node 版本要够新superpowers 的运行时依赖现代 JavaScript 特性。按目前社区项目的通用要求Node 18 以下基本跑不起来而且报错还很隐晦。如果你看到类似 “Unexpected token ?” 或 “SyntaxError: Cannot use import statement outside a module” 的报错大概率就是 Node 版本太老。装好之后先执行node -v如果你还在用 14、16趁早升级到 Node 18 或更高。我自己的开发机是 Node 20 LTS用到现在没遇到什么兼容问题。Windows 用户建议用 nvm-windows 管理版本macOS 用户可以用 nvm 或直接 homebrew大家按各自习惯来就好。2.2 Codex CLI 要先能跑通superpowers 不是独立解决所有问题的工具它的定位是给 Codex 这类 CLI 代理增强能力。换句话说前提是你本机的 Codex CLI 已经能正常使用。安装前先确认一下codex --version如果显示 command not found先回去把 Codex CLI 装好再继续。另外建议尽量用最新稳定版。superpowers 对 CLI 的输出解析依赖某些较新的参数格式旧版本容易出现“技能执行了但执行结果没有回灌给模型”的诡异问题这种问题查起来非常玄学。2.3 全局安装时的 npm 权限npm 全局安装会遇到一个老生常谈的问题EACCES 权限报错。这种问题通常不是 superpowers 的锅而是 npm 的全局目录没有给普通用户写权限。网上有各种极端做法比如直接 chmod -R 777 某个 node 目录我不是很建议这么干改系统目录权限的风险太高了。相对干净的方案是让 npm 使用用户级目录。执行npm config set prefix ~/.npm-global然后把下面这行加到你的 shell 配置文件~/.bashrc 或 ~/.zshrcmacOS 上是 zshrcLinux 上一般是 bashrcexport PATH$HOME/.npm-global/bin:$PATH重新加载配置后再执行 npm install。实测下来这个方案在 Linux 和 macOS 上都很稳。Windows 用户通常用 nvm-windows 管理 Node全局目录默认就在用户空间基本不会撞上权限问题。注意安装前用 npm config get prefix 看一眼当前路径。如果显示的是 /usr/local 这类系统级目录优先改成用户级目录再继续。2.4 初始化模板与本地网络问题superpowers 安装后首次初始化会从默认仓库拉取模板内容。这个过程在网络不稳的情况下偶尔会卡住。如果你发现 init 命令一直停在 fetch 阶段不要傻等直接 CtrlC 中断。我的做法比较直接本地预先准备一个最小模板目录用 init 参数指定本地模板路径。好处很明显完全不依赖网络而且能保证第一次跑通是在完全可控的环境里。后续排查问题也会简单很多。3. 从零安装到第一个技能跑通的全过程前置环境都搞定之后安装过程本身其实很快。这里写一个完整的操作路径方便你对照着做。3.1 全局安装命令npm install -g superpowers安装完成后用一个命令验证是否成功superpowers --version如果输出版本号说明安装正常。这一步通常不到一分钟。如果这一步就报错大概率是前面讲的 npm 权限或 PATH 配置问题回到第 2 节再检查一遍。3.2 初始化技能目录superpowers init执行完之后它会在你的用户目录下创建一个名为 .superpowers 的配置目录同时会在当前项目里生成一个 .superpowers 的隐藏文件夹。前者放全局技能包后者放项目专属技能包。这个设计非常贴合日常的项目管理习惯全局技能是自己的“军火库”项目技能是团队共同维护的“规矩”。我个人的习惯是尽量把通用能力放到全局技能里把和业务强相关的规范放在项目技能里这样换新项目时全局技能可以直接带走不用重新配置。3.3 初始化后的目录结构我截取了一个比较有代表性的目录树方便你对照~/.superpowers/ ├── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── unit-test-gen/ │ ├── SKILL.md │ └── templates/ └── config.json ./.superpowers/ ├── skills/ │ ├── api-design/ │ │ └── SKILL.md │ └── changelog/ │ └── SKILL.md └── triggers.json可以看到技能都是以目录为单位组织的每个技能目录里至少要有一个 SKILL.md 文件。如果技能依赖脚本或模板也可以放在同一个目录下方便整体迁移。3.4 从最小的 hello-skill 建立体感不用一上来就研究模板技能直接手写一个最简技能能最快建立感性认识。在项目里创建 .superpowers/skills/hello-skill/SKILL.md内容如下--- name: hello-skill description: 用于验证 superpowers 技能是否正常加载的最小技能 triggers: - 打个招呼 - 输出 hello --- 请用一句话回应并说明当前项目使用的语言和框架。然后在 Codex 会话里输入“我是这个项目的新手先打个招呼”。如果技能加载成功了Codex 的回应会变得有结构而不是一句孤零零的“你好”。第一次跑通技能的时候那种感觉挺奇妙的——不再是一个空荡荡的对话开场而是像你日常带新人时先递给他的一页项目速览。3.5 验证技能是否真的被加载有些人跑完 hello-skill 后不确定技能到底有没有生效因为模型的回应可能比较随机。这里有一个非常实用的验证技巧在 SKILL.md 里加一个明显的 side effect。比如在 hello-skill 的正文末尾加上一句回答结束后请额外输出当前目录下的文件数量。如果 Codex 照做了说明技能确实进入了上下文。如果没做就需要检查技能名称是否匹配、触发词是否写对、目录路径是否正确。这个办法看起来土但比 debug 一个不可见的加载过程高效得多。4. 核心机制拆解技能文件的写作语法与触发规则要真正把 superpowers 用好必须理解技能文件的写法。和很多人想的不一样SKILL.md 不是普通的 Markdown 文档。前面的 front matter 承担元信息声明的作用正文部分才是给模型的具体指令。两者缺一不可。4.1 front matter 里的四个关键字段字段作用注意事项name技能的全局唯一名称多个技能重名会静默覆盖特别难排查description描述技能适用的场景要具体模型主要靠它检索技能triggers触发词或匹配模式可以配置正则但别写太宽dependencies依赖的其他技能或脚本按需加载避免循环依赖description 字段是最容易被低估的。模型判断一段任务该不该用某个技能主要看 description 与用户输入的语义匹配度。写“对 Java 代码进行面向可维护性的代码审查”就比写“代码审查”好得多因为前者包含明确的场景语义后者可能匹配到一堆无关技能。triggers 字段稍微特殊它负责的是“用户提到这个词时强制加载这个技能”的机制。但注意触发匹配不是万能的模型如果判断技能与当前任务无关即使触发了也不一定会采用。所以触发词最好是动作加场景的组合比如“java review”或“生成单元测试”而不是单个“检查”这种泛词。4.2 正文的指令设计原则正文部分我强烈建议按“背景 - 目标 - 步骤 - 产出物”四个层次组织。背景交代为什么做目标明确做到什么程度步骤给出固定执行路径产出物规定最终交付格式。这里举一个真实用过的技能示例--- name: review-java description: 对 Java 代码进行面向可维护性的代码审查 triggers: - java review - 代码评审 --- 背景当前项目采用 Spring Boot 3遵循 Controller-Service-Mapper 分层规范。 目标找出代码中影响可读性、可测试性和潜在性能的问题。 步骤 1. 阅读目标文件的全部内容梳理核心逻辑 2. 对照项目分层规范标记架构层面的越权调用 3. 检查主要方法是否缺少异常处理或边界判断 4. 输出问题清单 产出物按“严重程度 - 位置 - 问题描述 - 修改建议”四栏表格输出。这份技能看起来简单但真正跑起来会发现它比在会话里反复强调“注意分层规范”要稳定得多。因为技能里的上下文是固定的不会随着对话推进被稀释。每次调用都是一套同样的高质量逻辑。4.3 触发规则的范围与优先级superpowers 的触发机制分两层项目级配置和用户级配置。项目级 .superpowers/triggers.json 里定义的规则优先级高于用户级同名词条。这个设计很合理——团队想覆盖个人习惯时直接在项目配置里压制即可。我踩过的坑是把 triggers 写得太泛。比如之前写了一个“检查代码质量”的技能triggers 里有“检查”两个字结果所有涉及检查的请求都会命中这个技能导致模型频繁误加载无关技能。后来改成“code review java”这种动作加场景的组合命中准确率明显提升。4.4 公共技能包的使用与二次修改从默认仓库拉来的公共技能包建议先通读一遍再投入使用。公共技能包的作者有自己的项目背景写得再通用也未必契合你的工程环境。我拿到一个新技能后的标准动作是先复制到项目技能目录再按项目规范删改最后才激活。这个过程不会花多少时间但能避开很多“技能很厉害生成的东西却不能用”的尴尬。网上不少教程会把技能包当成“装上就能用”的黑盒我持保留态度。任何关于代码库的抽象都需要在你自己的代码库里重新校准一次。5. Java 项目实战一次 Spring Boot 代码审查的全程复盘搜索词里出现“superpowers java”一点都不意外。Java 项目体量大、规范多、模型上下文容易爆炸正好是技能系统最能发挥价值的场景。前几个月我在一个 Spring Boot 项目里做了一次完整的技能化改造把整个代码审查流程沉淀成了一个技能。整个过程的经验值得展开讲讲。5.1 痛点跨文件审查的上下文断裂那个项目大概有 30 多个 Maven 模块代码审查如果只看单个文件经常漏掉跨模块的耦合问题。以前我手动写审查提示词写少了模型不懂业务背景写多了 token 烧得飞快。一个 service 类大概 500 行手工写提示词可能要花 10 分钟生成的结果还不一定符合团队规范。后来我把“Spring Boot 项目代码审查”封装成技能把 Maven 模块结构、分层规范、命名规范、异常处理原则全部写进 SKILL.md让 Codex 每次审查前自动加载相关上下文。这份技能经过三轮迭代最后稳定在一个 200 行左右的 Markdown 文件里团队同事直接复用不再各自维护一套提示词。整个过程的效率提升远不是一次两次省几分钟的问题而是把“个人经验”变成了“团队资产”。5.2 编写针对 Spring Boot 的专属技能具体编写时我用的是前面讲的分层结构。背景部分写清楚了 Maven 模块划分和核心业务域目标部分限定为“面向可维护性与可测试性”步骤部分要求模型先定位 Controller、Service、Mapper 三层之间的调用链再按层次逐层检查。产出物部分我强制指定输出“问题清单 修改建议”的表格并且要求修改建议里必须附带代码片段。这样产出的审查结果可以直接丢给开发同学照着改不需要再做二次转化。实测下来的效果非常明显。原来临时写提示词审查一个 service 类质量全看运气用技能跑至少每次产出的格式是固定的问题罗列也有据可循。“代码审查”不再是悬浮的指令而成了一套工程检查单。5.3 与项目 AGENTS.md 的配合方式我没有把 superpowers 技能和 AGENTS.md 当成二选一的对立方案而是让两者分工合作。AGENTS.md 只写项目定位、模块结构和构建命令像一本“快速速查手册”技能文件则承载具体任务的执行路径像一本“操作手册”。模型先读 AGENTS.md 建立全局认识再按技能加载局部流程。这样做的好处是上下文占用低逻辑也顺。如果两者内容发生冲突我的处理方式很简单以当前项目的 .superpowers 为准。团队既然费心写了项目技能就不希望再被旧版全局规则干扰。5.4 Java 生态特有的注意点Java 项目的技能里一定要包含构建工具的信息。Maven 和 Gradle 的命令差异很大技能里不写清楚模型很容易给出“现象上成立、实际跑不通”的伪命令。另外Java 技能里建议附带项目中使用 Lombok 的情况说明。很多代码审查问题比如“缺少 getter/setter”“直接访问私有字段”在不了解 Lombok 的项目里是问题在用了 Lombok 的项目里就是误报。这个细节不写进技能审查结果基本没法直接用。越是这种“项目特有知识”越值得沉淀成技能的一部分。6. 常见安装与使用问题我踩过的坑和完整排查链路这部分应该是很多人最想看的。我从报错现象出发给出根因和解决思路再展开讲几个典型的排查链路。报错现象根因解决思路superpowers: command not foundnpm 全局目录不在 PATH重新配置 prefix 并加入 PATHEACCES permission deniednpm 全局目录无写权限使用用户级全局目录避免 chmod 777技能文件写好了但不触发触发词定义过宽 / 路径不对核对 SKILL.md 路径与 triggers 匹配性Codex 不识别项目技能工作目录与 .superpowers 所在目录不一致确保在项目根目录启动 Codexinit 一直卡在 fetching模板仓库网络访问不稳定本地模板目录 init --template6.1 command not found 的完整排查链路遇到 command not found第一步不是疯狂搜索而是按顺序检查。先看包装没装上npm ls -g superpowers如果输出里没有 superpowers说明安装没成功。再看可执行文件的位置npm bin -g或npm prefix -g拿到路径后用 ls 看那个目录里是否有 superpowers 可执行文件。最后一步把那个目录加入 PATH然后重新打开终端。这个链路可以解决我遇到的至少一半 CLI 工具“装不上”问题。而且整个排查过程非常快不会超过五分钟。6.2 npm 官方目录导致的权限困境用过 npm 的人多多少少都撞到过第一次全局安装权限错误。常见建议是改 npm 目录的归属权限但直接改系统目录是很危险的操作。更稳的路子是让 npm 假装自己是用户级工具也就是前面第 2 节提到的 prefix 配置。Windows 用户一般用 nvm-windows 管理 Node全局目录就在用户空间很少撞权限问题。macOS 和 Linux 用户我给的建议始终是 npm config set prefix ~/.npm-global。这个方法我用了一年多从没出过问题。6.3 技能不触发的三种可能技能文件写好了但模型就是不按技能走最常见的就三种原因第一种是路径问题。项目根目录下的 .superpowers 如果和你的启动目录不一致模型根本看不到技能。这一点在 IDE 集成终端里特别容易翻车因为集成终端的工作目录可能不在项目根目录。第二种是触发词问题。前面说过触发词写太宽反而不好用。我遇到过把“检查”作为触发词的情况结果什么任务都往那个技能上靠。改成动作加场景的组合之后命中率立刻正常。第三种是加载开关问题。全局配置 config.json 里有一个 enabled 字段默认是 true。但如果你手动编辑过配置很容易在不经意间把它改成 false。我排查这个问题时翻了半天目录最后发现是自己在改参数时手滑加了一行 enabled: false。那种感觉真是又气又好笑。6.4 模板源拉取超时superpowers init 默认拉取模板源如果你访问那个仓库速度不稳定就会一直卡在 fetch 阶段。这个问题最稳妥的解法不是换各种网络加速而是直接从本地造一个最小模板目录然后superpowers init --template ./my-template这个方法完全绕开网络依赖而且能让你完全控制初始化内容。我在团队内部推广时都是直接分享一个打包好的模板 zip大家导入后各自初始化整个流程非常稳定不受外部环境影响。7. 理性看待 superpowers技能扩展的边界与我的使用心得到了最后一部分想聊点可能泼冷水的内容。superpowers 能带来很多便利但它的边界必须说清楚不然期望管理会出问题。7.1 技能系统的边界在哪里技能机制优化的是“可复现的执行路径”但不会替你思考。项目里最难的架构决策、需求理解、技术选型这些依然需要人来完成。技能只是把“你已经想清楚的流程”固化下来再让 AI 稳定执行。如果你自己都没想清楚流程写出来的技能也就是一团浆糊。公共技能包的质量参差不齐。引用别人的技能前至少要确认三件事维护活跃度、技能文件的产出物格式、是否依赖特定 CLI 版本。否则表面上装了一个“自动生成单元测试”的技能实际跑出来的东西连编译都过不了反而消耗更多时间调试。7.2 上下文预算与技能粒度技能不是越厚越好。一份 5000 行的技能和一段塞满废话的 AGENTS.md 没有本质区别。过度膨胀的技能会让模型在庞大上下文里抓不住重点最终的效果反而不如一份精简的指令。我的经验是单个技能控制在 100 到 300 行之间。超过这个体量就拆成多个下级技能用 dependencies 字段按依赖链加载。这和写代码时“一个函数不要超过一屏”的道理是相通的。另外一个技能尽量只解决一个场景问题。把“代码审查”“测试生成”“文档生成”塞进同一个技能只会让模型在任务切换时晕头转向。7.3 从小白到熟练我建议的成长路径如果你刚开始接触 superpowers我的建议是先别急着下载一堆公共技能包。先用最小的 hello-skill 跑通链路再把你最常做的一件事封装成技能哪怕它非常简单。比如“生成 git commit message”“整理 changelog”这类低风险任务都是非常好的起步场景。从简单技能开始你才能真正理解这个机制的脾气。等理解到位再去扩展就不会迷失在别人的技能库里。工具终究是工具价值仍然取决于使用者对工程问题的判断力。现在这套技能机制已经成了我工作流里像 Git 别名一样自然的部分但它不是银弹只是让有章法的协作变得更稳定。如果你也想试试建议从今天最常做的那件小事开始把它变成你的第一个技能。
查表到纠错3位的完整工程)
