最近几周好几个技术群里都在聊同一个词superpowers。我刚开始以为是哪个励志类网课点进去才知道这其实是一套给终端里的 AI 编程代理尤其是 Codex CLI用的“技能包框架”。说人话就是它不改变模型本身而是把那些你反复让 AI 干的事——搭项目骨架、按团队规范写代码、跑测试修错误——封装成一个个可复用的技能让代理干活更稳定、更少跑偏。我这两天从零开始装了一遍也用它跑完了几个真实任务踩了几个不大不小的坑。这篇就把整个过程记下来包括安装时的环境判断、技能目录的结构、一次 Java 项目初始化的实操演示还有排查技能不生效的完整思路。如果你正在用 Codex CLI或者想把手里的重复劳动沉淀成模板这篇应该能帮你少走弯路。1. superpowers到底是什么它不是模型是一套“会干活的流程包”1.1 技能包框架的核心思想要理解 superpowers得先放下“AI 助手”这个概念换成“AI 员工”来想。你雇一个人写代码不会每次都说“帮我写个Java项目”然后等他自由发挥你会给他章程、范例、命令脚本让他按流程来。superpowers 做的就是这件事你在项目里挂一个技能文件夹里面每一个技能都包含一份说明文档一般叫 SKILL.md、若干示例、可能还有一些辅助脚本。Codex 在会话里跟你对话时会根据任务描述自动检索并加载对应的技能按照技能里写好的步骤执行。这和普通的“提示词注入”不一样。写死在 system prompt 里的规则内容一多模型注意力就分散而技能包是“按需加载”需要用哪个再读哪个既省上下文窗口又能保持步骤的稳定性。我第一次看到这个设计的时候就想这不就是给 AI 打工人的 SOP 手册吗确实它的工作方式特别像一个资深工程师把自己的经验整理成一个个检查清单交给实习生严格执行。1.2 为什么叫 superpowers项目名很有迷惑性但它其实不是“给模型加能力”那种玄学。我看了不少云文档和演示视频发现它的定位非常务实通过标准化的技能目录让 AI 代理在终端里的行为可控、可复用、可扩展。你装的技能越多代理“会干的事”越多就像给它叠加了一层又一层的超能力。但本质上是流程的累积不是模型的进化。从热词来看大家关注的点也很集中一是 superpowers 的使用指南二是怎么装三是如何在 Java 这类具体项目里用起来还有不少人问它跟 Codex 是什么关系。这正好和我的理解一致——它是一个面向 Codex CLI 的增强框架不是独立模型也不是云端服务。2. 为什么裸 Codex 需要 superpowers先看清差距再动手2.1 裸 Codex 的典型困境先说结论裸 Codex 单论对话能力很强但论“把一件事从头到尾做规范”它经常翻车。我之前的日常是让 Codex 帮忙创建一个 Spring Boot 服务。它确实能写出来但有两个问题很烦一是每个新项目都要我把同样的背景和要求重新描述一遍描述得稍微不那么细它就漏掉日志规范、漏掉异常处理二是它中途很容易“自由发挥”今天用这个包明天用那个写法代码风格不稳定。这不是 Codex 的问题而是“没有给 AI 定义流程”的问题。人写代码的时候脑子里有经验知道“先建目录再写配置再改入口类最后补单元测试”但模型没有这种惯性除非你每次把步骤说全。superpowers 解决的正是这个它把“经验”变成了文件让 Codex 在会话中自动去读。2.2 有技能包和没技能包的差距对比我整理了一个对比表格可以很直观看到两者的差异对比维度裸 CodexCodex superpowers任务描述成本每次都要完整描述流程只需提一句“用 maven-quickstart 技能初始化”代码风格一致性依赖这次对话的上下文由技能文档里的规范统一约束跨项目复用很难换个项目重新说技能文件复制到新项目即可多人协作每个人调出不同的结果同一套技能产出相近的结果上下文占用长流程容易把对话窗口塞满技能按需加载关键信息不丢失你看到差距之后就明白为什么“安装和使用 superpowers”会成为热门搜索词了。它不是锦上添花而是很多 AI 辅助开发流程里“从能用到好用”的一道坎。3. 安装前必须理清的环境细节版本、路径、还有终端习惯3.1 基础环境怎么检查在跑安装命令之前先把环境看清楚。我这次的机器是 macOS用 Homebrew 管理包终端是 iTerm2平时主要用 zsh。不同的系统路径会有差异但判断逻辑是通用的。第一Node.js。superpowers 的加载器本体是一个跑步在 Node 环境里的 CLI 工具所以要确认 Node 版本足够新。我在终端里执行node -v当前输出是 v20.11.1够用。如果你还在用 Node 16 或更早建议先升级否则装依赖的时候会看到一堆 engine 警告甚至直接失败。第二Git。这个不用多说拉取技能仓库和更新技能都靠它。检查方式就是git --version。第三Codex CLI。superpowers 是配合 Codex 使用的所以你得先有一个能用的 Codex 环境。注意检查它的版本和管理方式我这边 Codex 是通过 npm 全局安装的所以安装路径在/usr/local/lib/node_modules附近。如果你是用其他方式装的后面配置技能目录时路径要对应调整。3.2 目录规划的“坑前预警”我在安装前吃了一个亏没有提前把技能目录想好导致后面改了两次配置。建议你在主目录或工作目录下划出一个专用的技能目录例如~/superpowers/skills然后把所有技能都放在里面。这样做的原因有两个第一技能文件会越来越多散落在各个项目里会非常难管理第二Codex 加载技能时一般是去配置里指定的路径扫描而不是满磁盘找路径清晰能减少很多“技能没生效”的误会。另外我建议你把 Codex 的配置文件路径也提前找出来。不同版本配置位置不一样常见的有~/.codex/config.toml或项目内的.codex/目录。你先cat一下看看内容确认里面有哪些字段后面要把技能目录路径挂进去。4. 完整安装流程从拉仓库到跑通首条技能4.1 拉取技能仓库与安装依赖我以当前 GitHub 上最常见的做法为基础来说明具体命令如下# 进入你要放技能的目录 cd ~ git clone https://github.com/超级用户/superpowers.git cd superpowers npm install注意把仓库地址换成实际地址因为不同人 fork 的仓库差异挺大。我一开始拉了一个很早的版本里面连package.json都没有直接npm install报错后来才发现要切到主分支的最新版本。依赖装完后看下目录结构至少要能看到一个skills/文件夹里面每个子目录就是一个技能。技能目录里一般有SKILL.md技能的说明文档也是 Codex 主要读取的文件examples/示例代码或示例会话scripts/可选的辅助脚本比如项目初始化脚本、检查脚本。如果你发现仓库里只有文档没有代码别慌这种框架类项目往往只需要配置加载器不一定要编译什么。4.2 把技能目录挂到 Codex 配置里这一步是“安装”和“能用”之间的关键。找到 Codex 的配置文件后在配置里增加技能目录的指向。以 TOML 格式为例[superpowers] skills_path ~/superpowers/skills enabled true改完后最好在终端里执行一次codex的简单会话输入“列出你所有可用的技能”之类的话看它能不能正确枚举出来。如果你发现它回答“没有可用技能”先别急着怀疑安装八成是路径没配对。从我开始折腾到现在我实际验证过一个取巧的验证方法直接打开技能目录里的SKILL.md读一遍然后人工模拟 Codex 会怎么理解。只要你确保里面的描述足够明确后面会细讲Codex 的检索通常不会太差。5. 实际使用演示让 superpowers 完成一次 Java 项目初始化5.1 场景设定我需要一个标准的 Maven 项目光说原理太飘我实际拿一个 Java 项目试了一遍。目标是初始化一个符合团队规范的 Maven 项目要求包括标准目录结构src/main/java、src/test/java统一的依赖版本管理预设 Checkstyle 规则附带一个简单的主类和一个能跑通的单元测试。在没有用 superpowers 之前我每次都要把这一大段话敲给 Codex 听然后等它自由发挥结果经常出现依赖版本乱飘、测试框架不统一的问题。这次我提前准备了一个maven-quickstart技能里面的 SKILL.md 明确了每一步流程。于是我只需要对 Codex 说一句话用 maven-quickstart 技能初始化当前目录为一个 Java 项目。5.2 技能实际执行的过程Codex 读取技能文档后会按照里面预定义的步骤开始工作。它先创建了pom.xml并参照技能里的依赖清单写了 Spring Boot 3.2 和 JUnit 5 的依赖没有自由发挥版本号。然后生成了目录结构把主类和测试类放到指定位置。最后它按照技能里的要求跑了一次mvn test发现测试通过于是停下来向我汇报。整个过程里我认为最值得注意的变化是“废话变少了”。裸 Codex 在任务中途常会问“你确认要用这个版本吗”“需要我顺便加上 Dockerfile 吗”而加载技能后它像拿着检查清单在干活每一步都在清单内没在清单里的东西它反而不做。这其实让我有点意外也更理解了技能包为什么强调“限制比自由更重要”。5.3 为什么技能文档能约束住模型简单说SKILL.md里如果只写“创建 Maven 项目”那模型还是会自由发挥但如果写了“使用指定的 parent 坐标、使用指定的测试库、按顺序执行下面的命令”模型就倾向于把它当作步骤逐条执行。我们在写技能时要把“要求”写得像一份不可违背的执行协议而不是一句模糊的意图描述。这一条是我踩了两次坑之后总结出来的后面专门展开说。6. 踩坑链路技能不生效时的完整排查顺序6.1 第一站先看配置文件路径我遇到的第一个问题是装完 superpowers 后Codex 完全感知不到技能存在。那个瞬间我的第一反应是“框架没装好”于是重新 clone 了一遍白折腾。后来才反应过来应该先查配置。排查日志思路是这样的先确认技能目录绝对路径没有拼写错误再确认配置里用的是~还是完整路径Codex 所在的进程能否解析~最后看 Codex 有没有自己的缓存目录如果有删除缓存后重启会话再试。我这里真正的问题是配置里写的是skills_path ~/superpowers/skills但 Codex 的进程环境在加载时没有扩展波浪号直接把~当成了字面路径。改成skills_path /Users/你的用户名/superpowers/skills之后一切正常。6.2 第二站技能描述不要起“外号”第二个问题比较隐蔽。我给一个技能起名叫clean-code但技能描述里写的是“帮助用户写出干净的代码”。Codex 能识别到“clean”和“code”但经常在别的任务里也误触发它反而导致真正的任务没人加载。后来我按照惯例改成了更严格的描述这个技能只在用户要求“重构”“代码评审”“坏味道消除”时使用。事实证明描述越聚焦触发越准。技能名字简单没问题但描述一定要像关键词白名单。6.3 第三站技能脚本的权限与安全边界有的技能会带辅助脚本比如scripts/setup.sh。Codex 在执行技能时如果调用了脚本你得确认脚本有执行权限。我在 macOS 上就遇到过permission denied最后用chmod x scripts/setup.sh解决。这里也提醒一句不要往技能脚本里塞高危操作比如直接删库、覆盖文件、静默改全局配置。因为你给技能加的权限本质上是让 AI 代理在无人监督时执行这些命令。一旦写错事故就是自动化的。6.4 第四站worbuddy 这类工具集成时的常见误解热词里出现了一个叫“worbuddy”的词我搜了一下发现不少人把它和 superpowers 放到一起问“怎么用”。我的理解是这是两类不同定位的工具worbuddy 这类工具偏向于在具体业务工作流里做自动化而 superpowers 是底层技能框架。如果你想在某个工作流里使用 superpowers思路是把它当作“可被调用的技能库”让外层工具把任务交给 CodexCodex 再加载对应的 superpowers 技能。我实际遇到的问题是环境变量不共享。外层工具启动 Codex 时没有把技能目录相关的环境变量传递进去导致 Codex 找不到技能。解决办法是在外层工具的启动配置里显式声明export SUPERWERPOWERS_PATH/Users/你的用户名/superpowers/skills这类集成问题大多数时候不是你装错了而是进程环境不一致。7. 写一个属于你的技能包从模板到自动化7.1 一个可用技能的最小结构如果你也想把手里的重复工作变成技能我给你一个可以参考的最小模板。首先创建技能目录然后在里面写一个 SKILL.md--- name: my-custom-task description: 仅当用户要求执行特定任务时使用例如“帮我按规范生成配置”。 --- # 技能目标 在用户指定目录下生成一份符合团队规范的配置文件。 ## 执行步骤 1. 检查目标目录是否存在不存在则创建。 2. 生成 default.conf内容必须包含 server.port 和 log.level 两个字段。 3. 步骤 2 使用项目根目录下的 scripts/gen_conf.sh 生成不要手动改文件。 ## 验收标准 - 文件存在。 - 文件包含两个必填字段。 - 没有多余内容。这个结构非常简单但核心已经具备有名字、有触发条件、有步骤、有验收标准。7.2 从模板到自动化的过程等你习惯了给 AI 下“步骤型指令”就可以往里面加脚本了。脚本的价值不是代替模型思考而是让重复性动作变成确定性执行。比如生成项目骨架这种事手工让模型逐个创建文件虽然也能成但有了脚本就能一键复制模板文件、统一修改占位符。我的个人建议是一步一步加先有描述和步骤跑通了再加脚本脚本稳定之后再考虑把多个技能串成一个更大的技能包。superpowers 最大的优势在于技能的更新是文件级别的你改一个文件全团队都能通过 Git 拉取到最新规则。7.3 一点扩展心得如果你在内容工作流或 WordPress 相关工具里看到 superpowers也别觉得违和。技能包的本质是“把标准流程告诉 AI”这个思路放在任何领域都成立。我甚至见过有人用它管理发帖流程让 AI 先读历史文章风格文档再定标题再写正文再配图最后检查 SEO 关键词。只要每一步都按 SKILL.md 里的验收标准走输出质量就稳定得多。我在实际使用时最大的体会是不要把技能当成“咒语”要把它当成“交接文档”。你希望 AI 稳定做到什么就把验收标准写清楚然后让技能文档成为唯一的执行依据。最后再分享一个实在的小技巧给每个技能都写一句“什么时候不要用”。这句话能挡掉很多误触发。我踩过几次坑之后才明白真正的可控不是让 AI 更自由而是让它清楚地知道“哪些事不归你管”。