superpowers技能包详解：让Codex CLI从裸奔到有序开发

最近在折腾 Codex CLI 的时候我注意到一个叫 superpowers 的项目频繁出现在各种讨论里。这东西不复杂但确实能让你手头的 AI 编程工具“变强”不少。简单说它是一套专门给 Codex CLI 这类 Agent 用的“技能包”skills通过挂载一批结构化的指令文件让 AI 在回答或写代码时能按更成熟的套路来思考而不是每次都在裸奔状态下“想到哪写到哪”。看到很多人问 superpowers 怎么用、怎么装到 Codex CLI也有问 Trae work 里能不能装我干脆把这段时间的试用和调研整理成一篇完整记录。如果你是做前后端开发、平时依赖 AI 辅助写代码或者正在给团队搭建一套统一的代码助手规则这篇应该能让你少踩很多坑。1. 项目思路拆解一个装进 CLI 里的“技能挂载器”1.1 superpowers 到底解决什么问题先说痛点。直接用 Codex CLI 写代码它就像一个聪明但没什么经验的实习生你问它问题它能答得头头是道但真让它独立完成一整个模块它经常漏掉边界检查、跳过异常处理、不主动补充测试。原因不是模型不够强而是缺少一套稳定的工作方法论。superpowers 想解决的就是这个“有智商但没章法”的问题。它的核心机制是 skill。每个 skill 就是一份 Markdown 文件里面写清楚在某个场景下应该怎么思考、怎么规划、怎么输出。比如“代码审查”这个 skill会要求 AI 先读一遍变更列出风险点再逐条给出修改建议而不是直接甩一段新代码把旧逻辑盖住。这类指令如果你自己一条条写在对话里既啰嗦又容易忘但放进 skill 文件里Codex 每次处理同类任务时都会自动参考。我理解的 superpowers本质上是一套“工作流模板集”。它把工程经验沉淀成了 AI 能持续使用的上下文让 Codex CLI 从“单次回答工具”变成“稳定交付工具”。这比单纯换模型或者堆 prompt 要可靠得多因为技能文件是显式的你可以看到 AI 到底被灌输了什么逻辑也可以自己改。1.2 项目适合谁用不适合谁用就我的实际体验这几类人会很受益日常用 Codex CLI 写业务代码、做重构的开发者尤其是一个人维护多个仓库的情况。需要在团队内统一代码审查标准、提交规范、架构约束的人把规则做成 skill 后所有人都能共享。正在折腾 AI Agent 工作流的效率爱好者superpowers 本身就示范了一套很好的 skill 编写方法。但也有不适合的。如果你只是偶尔让 AI 补个函数、改写几行代码那直接问 Codex 就行没必要额外挂载一堆技能。反而会因为上下文变长让简单问题多绕几步。另外如果你完全不想了解配置文件和目录结构那这项目会有点门槛它不是一个开箱即用的图形界面工具需要你至少能看懂终端和 Markdown。2. Codex CLI 环境准备装 superpowers 之前先把底子打牢2.1 安装 Codex CLI 的两种常用方式在装 superpowers 之前我默认你已经有一个能跑通的 Codex CLI。如果还没有我这里简单说下步骤。官方推荐的方式是直接通过 npm 全局安装打开终端执行npm install -g openai/codex装完以后你在终端输入codex --version如果能输出版本号说明安装成功。还有一种是使用官方提供的安装脚本适合不希望依赖 Node.js 环境的场景不过我平时用 npm 比较多因为后续升级方便npm update -g openai/codex一条命令就搞定了。我第一次装的时候踩过一个坑忘了先确认 Node.js 版本。Codex CLI 要求 Node.js 版本不能太老建议至少 18 以上最好用 LTS 版本。你可以在终端跑node -v看下如果版本过低建议先升级再装否则后面启动时容易报莫名其妙的语法错误。2.2 确认 Git 和网络环境superpowers 本身是个开源仓库你需要通过 Git 把它拉下来。所以 Git 也是前置条件。Mac 上一般自带Windows 需要装 Git for WindowsLinux 可以用apt install git或yum install git装。装完以后执行git --version确认。网络方面拉取仓库时可能会遇到超时或断流这个和网络环境有关系没有统一解法。我个人的经验是尽量在网络状况好的时间段操作或者设置 Git 的 https 缓冲和重试次数git config --global http.lowSpeedLimit 1000 git config --global http.lowSpeedTime 60这个不是必须的但确实能减少一些因为低速断流导致的 clone 失败。如果还是失败多试几次一般也能过。注意不要依赖任何特殊工具那不属于本项目的讨论范围。2.3 建议先建一个统管技能的目录我习惯把这类外部技能统一放在~/.codex/skills目录下而不是散落在各个项目里。这样有几个好处Codex 的配置引用路径清晰不用每个项目单独改。后续更新 superpowers 直接进目录git pull就行。你自己写的 skill 也可以放进去混着用没问题。创建目录的命令很简单mkdir -p ~/.codex/skills如果你用的不是 Mac/LinuxWindows 下可以用%USERPROFILE%\.codex\skills这个路径原理一样。3. 安装 superpowers 的完整操作流程3.1 克隆仓库到本地确认环境没问题之后进入技能目录开始克隆 superpowers 仓库。命令如下cd ~/.codex/skills git clone https://github.com/your-source/superpowers.git仓库地址请以你实际搜索到的项目主页为准我不在这里写死具体路径因为开源项目有时候会迁移。克隆完成后你会看到一个superpowers文件夹里面通常有若干个以技能名命名的子目录每个目录下都有一个SKILL.md文件这就是核心。我建议你进去看一眼目录结构ls -la ~/.codex/skills/superpowers ls ~/.codex/skills/superpowers/*/SKILL.md正常会列出像code-review、debugging、planning这类目录。如果这些文件都在说明仓库内容完整。3.2 配置 Codex 加载技能目录仓库拉下来只是第一步你还得让 Codex 知道要去哪里找这些技能。Codex CLI 会读取项目目录下的AGENTS.md文件也会读取全局配置。我试过两种方案第一种是全局配置方式。编辑~/.codex/AGENTS.md在里面加上一段说明告诉 Codex 技能文件的位置。比如# Skills You have access to a set of skills from the superpowers project. When the users request matches a skills purpose, read the corresponding SKILL.md file and follow its instructions. Skill directory: ~/.codex/skills/superpowers这种写法的意思很直白让 Codex 遇到相关问题时主动去读技能文件。第二种是项目级方式也就是在你当前工程的根目录下放一个AGENTS.md内容类似但只对该项目生效。如果团队协作建议用项目级方式并提交到代码库这样所有人都能统一行为。3.3 验证安装是否成功配置完以后我习惯做一个小验证。直接在终端启动 Codex CLIcodex然后问它“根据你当前可用的技能列出你能帮我做的几类事情。”如果它回答里提到了代码审查、重构、调试规划这些方向说明技能已经开始参与对话了。或者你也可以直接说“用 code review 技能帮我看看当前目录的改动”然后观察它的行为是否明显变得更结构化。这里有个容易误解的点superpowers 不是装完后每次回答都会引用所有技能而是按需触发。它更像一个工具架Codex 判断当前任务需要用哪个就去翻哪个。如果你感觉它没按技能输出先别急着怀疑安装失败可能是任务不够匹配或者需要给出更明确的要求。4. 核心技能拆解superpowers 里的这些能力具体是什么4.1 代码审查与质量提升类技能这类技能基本是我的主力。以前的 Codex 拿到代码会直接给结论“这段代码可以优化”然后扔出一版新代码。但挂载了代码审查技能之后它会强制自己走一套流程先梳理代码的输入输出和边界列出潜在问题再给修改建议而且每一步都要求说明理由。举个例子我让 Codex 审查一个 Python 函数旧版它大概率会直接改写整段函数我现在看到的输出则是先指出这个函数把配置读取和业务计算混在一起再指出异常捕获范围过宽可能掩盖真正的错误最后给出一个分步重构方案而不是直接替代。这种输出方式对我帮助很大因为它逼着我去理解问题而不是无脑接受 AI 的改写。团队协作时这类技能还能保证代码风格的一致性。你完全可以根据团队规范把“必须写单元测试”“错误处理要精确到异常类型”这些要求写进技能文件里。4.2 项目导航与架构理解类技能还有一个我个人很喜欢的技能方向就是让 AI 在改代码之前先“看懂”项目结构。很多人在大项目里让 Codex 加功能它经常改完这边、漏掉那边就是因为它只盯着当前文件没有全局视角。superpowers 里的规划类技能会要求它先列目录、找相关引用、理清依赖关系再输出改动计划。实际执行中它会主动要求你允许它执行类似grep、find、git log之类的命令去搜集信息。你别嫌它慢这一步恰恰能避免很多低级错误。我记得有一次让它改一个 API 接口它先沿着调用链找到了三个上游调用方然后提醒我这次改动会影响别的地方问我是要一起改还是先做兼容。这种主动意识就是技能文件里“先探索后动手”的规则在起作用。4.3 工作流自动化类技能除了代码层面的技能superpowers 还可以包含一些偏工作流的指令。比如自动识别当前分支和提交信息格式在生成 commit message 时遵循 Conventional Commits 规范或者在开始新任务时自动列出“待办清单”和“验收标准”。这些能力看起来简单但非常实用。我试过让 Codex 帮我处理一个跨三天的任务它每天会读之前生成的进度文件接着之前的状态继续而不是每次都从零开始。这种“状态保持”依赖的就是技能文件里约定的工作流程。如果你做的是长期项目强烈建议研究下这类技能的实现方式。4.4 自定义 skill 的基础写法superpowers 的价值有一半在于它是开放的你可以自己加技能。一个最基础的SKILL.md文件长这样# Skill: release-checklist ## Purpose Use this skill when preparing a release, to ensure version bumping, changelog updates, and tag creation are handled correctly. ## Steps 1. Read the current version in package.json. 2. Check the changelog for unreleased entries. 3. Suggest a new version based on semver rules. 4. Summarize the exact commands needed to commit, tag, and push. ## Output format Return a numbered checklist with concrete command proposals.写完之后把文件放到技能目录下的一个新文件夹里比如~/.codex/skills/my-skills/release-checklist/SKILL.md然后在配置文件里把my-skills目录也加上。这样 Codex 就能识别到了。编写技能文件的核心是目的明确、触发条件清晰、步骤可执行。不要写空话AI 需要的是具体指令。5. 在 Trae work 等工具中安装 superpowers skill5.1 Trae 的 skill 目录机制很多人不只用一个工具特别是 Trae work 这类 AI IDE 在国内使用比较顺手大家也会问能不能把 superpowers 装进去。我试过之后可以明确说可以而且思路跟 Codex 是一致的都是通过目录文件来挂载技能。Trae 通常会读取项目级别的规则目录比如.trae/rules或者类似的配置目录。你可以把 superpowers 仓库里对应的SKILL.md文件复制到 Trae 能识别的目录下。具体目录名不同版本可能有差别最简单的方法是在 Trae 的设置或文档里搜一下“skills”或“规则”它会告诉你当前版本支持哪种路径。我实际操作时是把整个技能目录复制进了项目下的.trae/rules/skills/然后在规则主文件里写清楚# Skills The following skills are available. Use them when the users task matches the skills purpose.这样 Trae 的 AI 助手在对话时就会参考这些技能文件。5.2 通用 skill 目录的思路其实不管什么工具底层逻辑都差不多找个地方放 Markdown 指令文件再通过某种规则文件告诉 AI 什么时候读哪个文件。理解了这一点你完全可以把 superpowers 的 skill 迁移到任何支持类似机制的 AI 工具里比如开源的继续Continue、Cline 等。关键在于语法适配。Codex 的AGENTS.md和 Trae 的规则文件可能对 front matter 的解析有差异。superpowers 仓库里的SKILL.md通常自带name和description之类的元信息如果目标工具不识别只需要去掉元信息保留正文指令即可。我迁移后实测80% 的技能文件不用大改。6. 常见问题与排查技巧实录6.1 Codex 加载不到技能文件典型表现是你已经配置好了但让 Codex 使用技能时它表现得很茫然。我遇到过三次基本都是路径问题。尤其在 Windows 上路径中的反斜杠和空格容易让配置解析出错。排查步骤如下先用绝对路径确认技能文件存在ls ~/.codex/skills/superpowers/code-review/SKILL.md如果存在再去配置文件里检查路径是否写的是~。有些版本的 Codex 不会帮你扩展波浪号你需要在配置里写完整路径比如/Users/你的用户名/.codex/skills/...。改完之后重启 Codex不要指望热加载。6.2 技能被加载但 AI 不参考第二种常见问题是AI 明确说找不到对应技能但它仍然用自己的方式回答。这往往是因为配置文件里的触发指令写得不够强硬。我在AGENTS.md里现在是这样写的When a user request matches a skill, you MUST read the corresponding SKILL.md before responding.加了MUST之后情况改善了不少。另外你要确认提问时的关键词是否足够清晰。比如“帮我评审这段代码”比“看看这个”更容易触发代码审查技能。6.3 技能文件太多导致上下文膨胀这是后知后觉的坑。配置里不加限制地指向整个 superpowers 目录会让 Codex 每次都要扫描大量文件既耗时又占 token。我后来只保留自己最常用的几个技能目录code-reviewdebuggingplanningrelease-checklist其他的需要用时再临时加。技能管理就像一个工具箱不是所有工具都放桌子上才好常用的放在手边不常用的收进柜子里。你也可以在配置里写清楚“只在任务匹配时加载”但实际效果还是手动控制更稳。6.4 Windows 与 WSL 的路径差异如果你在 Windows 上运行 Codex CLI同时又把仓库放在 WSL 内部那么路径格式需要格外注意。Codex 如果是在 Windows 原生的 Node.js 环境跑它无法访问 WSL 的\\wsl$\路径。反过来如果 Codex 装在 WSL 里那路径就是正常的 Linux 路径。最好的做法是统一环境不要混用。我自己后来就固定在 WSL 里跑整个开发环境省了很多路径转换的麻烦。6.5 更新 superpowers 时出现冲突这项目迭代速度不慢我经常git pull更新有时候本地改过技能文件更新时就会报冲突。我的应对办法是尽量不改SKILL.md要调整就新建一个自己的技能文件作为覆盖这样仓库一更新就能无痛合并。如果实在改了那就先git stash然后git pull再git stash pop大多数情况下能自动合并。7. 一些实操心得和扩展方向7.1 我在实际使用中的几个体会第一次用 superpowers 时我最大的不适是它让 Codex“变慢”了。以前一个问题三秒就答现在它会先列计划、跑命令、读上下文多花不少时间。但我用了一周之后发现代码返工率明显下降尤其是大型重构改完后要手动修的地方少了很多。这本质上是用时间换质量如果你追求的是最终结果这个取舍很值。第二个体会是技能文件本身就是很好的知识沉淀工具。我以前会把团队规范写在 wiki 上没人看。现在我把规范写成SKILL.md团队里每个人装好自研工具后AI 自动就按规范干活了。比起让人读文档不如让 AI 读文档这个方向我觉得是未来。第三个体会是别迷信默认配置。superpowers 提供的是通用技能你最好根据自己项目的技术栈、框架、团队习惯改一改。比如我们团队的代码审查技能里专门加了一条“禁止在 return 语句中直接调用可能抛异常的方法”这种针对自身项目的约束才是工具融入团队的关键。7.2 后续还可以怎么扩展如果你已经能熟练使用 superpowers我建议你尝试自己写一套“组合技能”。比如把代码审查、测试生成、文档更新三个技能串起来让 AI 在一个任务里完成“修改代码 补测试 改文档”的闭环。我目前正在尝试把项目的部署检查清单也做成技能让 AI 在提交前自动对照执行。另外不要只局限于 Codex 和 Trae。任何支持自定义技能目录的 AI 编程工具都值得拿 superpowers 的思路去试一遍。哪怕最后不用这个仓库你也会收获一套“如何给 AI 定义工作流”的通用方法论。这个收获可能比技能本身还值钱。