最近在折腾 Codex CLI 的时候发现一个叫 superpowers 的项目频繁出现在 GitHub 热榜和开发者的讨论群里。它不是编程语言也不是框架而是一套专门为 Codex CLI 这类 AI 编程助手准备的“技能包”。简单说装上它之后AI 助手不再只会“听一句答一句”而是能主动拆解任务、做代码审查、写测试、甚至跨文件重构。很多刚接触的朋友会问Codex CLI 本身已经很好用了为什么还要装 superpowers这个问题的答案也是我写这篇指南的初衷。如果你正在用 Codex CLI又不想每次跟 AI 对话时把项目背景、编码规范、任务约束反复粘贴一遍那 superpowers 就是专门解决这件事的。它把常见的工程实践固化成一组可复用的技能文件让 AI 在动手之前先进入对应角色再按照既定的流程输出结果。这篇文章我会从原理讲到实操覆盖安装步骤、核心功能、不同工具链的挂载方式以及我在实际使用中踩过的一些坑尽量让看完的人能直接上手。1. superpowers到底是什么给AI编程助手的一份“能力清单”1.1 从Codex CLI说起为什么AI助手还需要“技能包”Codex CLI 是 OpenAI 推出的终端 AI 编程助手可以直接在命令行里让它读文件、改代码、跑命令。它比大多数编辑器插件更“原生”因为它天然贴近开发者的工作流。但默认情况下它本质上还是一个对话模型你给它一个任务它根据当前的上下文直接回答。这意味着所有关于项目结构、代码风格、测试规范、发布流程等信息都需要你手动补充。这就带来一个问题一套通用的模型能力无法覆盖每个团队、每个项目的特殊约定。前端项目要遵循组件规范后端项目要处理数据库事务嵌入式项目要考虑内存限制。如果每次都要重新描述这些上下文AI 的回答质量就很不稳定。superpowers 的出现就是为了把这种“上下文管理”系统化。它做的事情说起来其实很简单准备一堆结构化的 Markdown 文件每个文件对应一个“技能”比如“任务规划”“代码审查”“编写测试”“安全审计”。当你需要某项能力时Codex CLI 会加载对应文件里的指令AI 就知道现在该扮演什么角色、按什么流程工作、输出什么格式的结果。你可以把它理解为给模型一份“岗位说明书”让它在特定场景下按标准作业程序干活。1.2 superpowers的核心设计技能即提示词工程很多人一听到“技能包”以为是复杂的插件系统或者需要写代码的框架。实际上superpowers 的核心资产就是一套经过精心设计的提示词工程。每个技能文件通常包含几个部分技能的名称和适用场景、触发该技能后 AI 应该遵循的任务流程、输入输出的具体约束以及一个或多个真实示例。这种设计非常聪明。它没有去改 Codex CLI 的内部实现而是利用了 Codex CLI 支持外部指令文件的能力把技能以“追加上下文”的方式注入对话。所以它很轻量不需要编译、不需要依赖安装本质上就是文本文件。你完全可以用 Git 管理这些技能文件团队之间互相分享甚至根据自己的项目定制专属技能。1.3 适用场景哪些人最适合用它我实际体验下来有三类用户最适合 superpowers。第一类是个人开发者特别是那些在多个项目之间切换、需要快速让 AI 理解项目背景的人。第二类是小团队几个人共用一套技能库能把团队的编码规范、代码审查清单、发布检查项全部固化下来新人加入时也能少踩坑。第三类是重度依赖 AI 编程助手的效率型用户他们希望 AI 的输出尽量稳定而不是每次凭“感觉”生成代码。如果你的场景只是偶尔用 Codex CLI 问问 API 怎么调用那 superpowers 可能有点大材小用。但只要你开始让 AI 独立完成“改一个功能”“审一次代码”“补一批测试”这类相对复杂的任务技能包的价值就会非常明显。2. 安装前要搞懂的几件事环境准备与版本选择2.1 确认你的Codex CLI环境在安装 superpowers 之前第一步不是急着 clone 仓库而是先确认自己的 Codex CLI 环境是可用的。打开终端依次执行以下命令node -v npm -v codex --versionsuperpowers 本质是文本技能包对 Node 版本没有硬性要求但 Codex CLI 本身需要较新的 Node 环境。如果你能用codex命令正常对话说明基础环境没问题。如果还没有安装 Codex CLI需要先安装并完成登录认证再回来看这篇指南。另外建议确认一下 Codex CLI 的版本是否支持加载外部技能目录。这个功能在不同版本里的叫法不完全一样有的版本通过AGENTS.md文件自动加载有的版本支持在配置文件里指定 additional instructions 目录。安装前用codex --help看一下帮助信息重点找--skill、--instructions、--config这几个参数。提示如果你发现自己的 Codex CLI 版本太老不支持加载外部技能文件建议先升级到最新版本再继续。技能包对版本兼容性有一定要求老版本可能会忽略某些指令。2.2 拉取superpowers到本地superpowers 的发布渠道主要是 GitHub。你可以直接通过git clone把仓库拉到本地这也是目前最主流的做法。为了方便管理我习惯把它放在用户目录下的一个独立文件夹里比如~/.superpowersgit clone superpowers仓库地址 ~/.superpowers如果没有安装 Git也可以从 GitHub 页面下载 ZIP 压缩包解压到同一个位置。不过我还是建议用 Git 克隆因为后续可以方便地git pull更新技能包体验新版本的功能。拉取完成后先不要急着配置进入目录看一下整体结构cd ~/.superpowers ls -la通常你会看到类似skills、prompts、commands、docs这样的子目录以及README.md和LICENSE文件。其中skills目录是最核心的里面每一个 Markdown 文件就是一个技能。2.3 让Codex CLI“认出”superpowers这是整个安装过程中最关键的一步。superpowers 不会自动被 Codex CLI 发现你需要告诉 Codex CLI 去哪里加载这些技能文件。目前常见的做法有两种一种是在 Codex CLI 的全局配置中添加额外指令路径另一种是在项目根目录创建或修改AGENTS.md文件。以修改 Codex 配置文件为例你可以在配置里添加类似下面的内容additional_instructions [~/.superpowers/skills]或者把技能目录写进项目的AGENTS.md中请阅读 ~/.superpowers/skills 下的所有技能文件并在处理相关任务时遵循对应技能中的指令。具体方式取决于你的 Codex CLI 版本。核心思路是让 Codex 在每次对话开始时自动把技能目录里的内容纳入上下文。如果你发现配置后 AI 没有按预期工作可以先用最简单的验证方式在对话中直接问“你加载了哪些技能”看它是不是能列举出 superpowers 目录下的文件。3. 五步完成安装从GitHub到终端实战3.1 第一步检查依赖与Node.js版本我见过很多人在安装时卡住最后发现问题出在 Node.js 版本太旧。虽然 superpowers 本身不依赖 Node但 Codex CLI 在加载技能文件时需要解析目录和 Markdown 内容老版本 Node 可能会导致运行异常。建议先执行node -v如果版本低于 18建议先升级到 LTS 版本。另外检查 npm 和 git 也是必要的npm -v git --version这三条命令都正常输出版本号后再继续下一步。3.2 第二步克隆或下载superpowers仓库选择你要存放 superpowers 的路径。我建议放成全局路径因为技能包往往会跨项目使用。在终端执行git clone superpowers仓库地址 ~/.superpowers如果网络比较慢也可以用镜像或者手动下载 ZIP 再解压。解压后把目录重命名为~/.superpowers方便后续配置。这里有一点需要注意不要随便删除仓库里的.git目录除非你确定不再需要更新。3.3 第三步目录结构与技能文件的关系克隆下来之后最好花几分钟时间浏览一下目录结构。很多用户安装完直接开始用结果发现某个技能不生效回头排查才发现是自己把技能文件放错了位置。以主流版本为例目录结构大致是这样的~/.superpowers/ ├── skills/ │ ├── code-review.md │ ├── task-planning.md │ ├── test-writing.md │ └── ... ├── prompts/ │ └── ... ├── commands/ │ └── ... ├── README.md └── LICENSE技能文件通常带有 YAML 格式的 front matter里面记录了这个技能的名称、描述、触发条件。Codex CLI 在加载时会读取这些元数据所以如果你要自定义技能也请保持相同的结构。我自己的习惯是先打开两个技能文件看看格式再决定是自己写还是修改默认文件。3.4 第四步在Codex CLI配置中挂载技能目录挂载方式根据 Codex CLI 版本的差异略有不同。如果你使用的是支持配置文件的版本可以编辑~/.codex/config.toml文件model gpt-4o additional_instructions [~/.superpowers/skills]如果你的项目有特殊性也可以只在项目根目录的AGENTS.md里按需引入技能文件内容。比如你的项目只关心代码审查和测试可以在AGENTS.md里写# 项目指令 请严格遵循以下技能中的流程 - ~/.superpowers/skills/code-review.md - ~/.superpowers/skills/test-writing.md这种按需引用的方式更灵活避免每个项目都加载全套技能导致上下文浪费。3.5 第五步用一条简单指令验证是否生效配置完成后不要急着开干先做一次快速验证。启动 Codex CLI输入一个很简单的测试指令请使用“任务规划”技能把“为一个待办清单应用增加用户登录功能”拆解成子任务。如果 superpowers 加载成功你会看到 AI 不再直接给你一段笼统的回答而是先输出任务拆解结构比如需求分析、数据库设计、接口定义、前端页面、测试用例等步骤。如果它完全没反应或者还是像普通对话一样直接回答说明技能没有加载成功需要回到第三步和第四步检查路径与配置。4. 核心功能拆解superpowers到底给AI加了哪些“超能力”4.1 任务规划与拆解在实际开发中最大的浪费就是让 AI 在没有全局视野的情况下直接写代码。superpowers 里的任务规划技能就是先让 AI 把大目标拆成若干小任务按依赖关系排序再逐个执行。我举个例子我让它给一个老项目增加“导出 CSV”功能默认情况下它可能直接生成一段 Express 路由代码。但加载规划技能后它会先列出需要改哪个文件、是否要加依赖库、要不要处理字符编码、前端怎么触发下载然后才开始改代码。这种模式尤其适合重构和老项目维护。很多项目代码结构不清晰AI 如果直接动手很容易改坏东西。先用规划技能把所有改动点列出来再由你确认风险就小得多。4.2 代码审查与问题发现代码审查技能是我用得最多的一个。直接把一段 diff 或一个文件路径交给 Codex CLI它会按照技能文件里定义的维度去审查安全性、性能、可读性、潜在 bug、边界条件等。它不会只丢一句“看起来没问题”而是会逐条列出风险点并给出修改建议。我实际测试的感受是带技能和不带技能的差距非常明显。不带技能时AI 会倾向于“顺着你的思路”走你说什么它都觉得不错。带上审查技能后它会主动指出你没有考虑到的情况比如空指针、并发问题、SQL 注入风险。这对团队做代码评审非常有帮助相当于多了一个不会累的初级审查员。4.3 自动化补全与重构superpowers 里另一类常用能力是文件修改和重构。它不会只给你一段代码片段而是先读取相关文件分析现有实现再给出修改计划。尤其在涉及跨文件改动时技能文件里的约束会提醒 AI 保持命名一致、更新对应的测试、检查 import 路径。它甚至能在你允许的情况下直接执行一系列终端命令来完成迁移。这个过程其实就是在依赖技能文件里的“工具使用”提示让 AI 知道什么时候该读目录、什么时候该运行测试、什么时候该用 linter。4.4 传统能力之外的可扩展性最吸引我的地方是它的可扩展性。superpowers 不是封闭的你可以把任何团队规范写成新的技能文件。举个例子假设你们团队要求所有新增接口必须带 OpenAPI 注释那你可以写一个api-doc-checker.md技能告诉 AI 在改接口代码时自动检查并补充注释。一个技能文件的基本结构大致是这样的--- name: api-doc-checker description: 检查并补充 OpenAPI 注释 --- ## 适用场景 当用户要求新增或修改 API 接口时。 ## 执行步骤 1. 读取相关路由文件。 2. 检查接口是否有 OpenAPI 注释。 3. 缺少时自动补充。 4. 运行测试验证不影响现有功能。 ## 示例 用户给 /users 增加一个删除接口 AI请先补充 openapi 注释再实现 handler。这种“写技能文件”的学习成本不高但收益很大。团队里的最佳实践终于可以不只是写在文档里吃灰而是真正注入到 AI 的日常输出里。5. 不同工具链下的安装变体Trae、Cursor等场景5.1 Trae Work CN 安装 superpowers skill 的差异最近很多人在问 Trae Work CN 里能不能用 superpowers。Trae 是字节跳动出品的 AI IDE它的 Agent 能力支持加载自定义 skill但与 Codex CLI 的加载机制不完全一样。在 Trae 里技能文件通常要求是SKILL.md格式并且要放在指定的 skills 目录下同时需要在 agents 配置里声明。如果你想把 superpowers 用在 Trae 里需要做两步转换第一步把skills目录下的 Markdown 文件统一改名为SKILL.md并放到独立的子目录里第二步在 Trae 的 agent 配置中将技能目录路径添加进可用技能列表。因为不同工具的元数据解析规则不同直接复制文件过去未必能被识别。注意Trae 的 skill 目录里每个技能都需要一个独立文件夹文件夹里放SKILL.md其他辅助文件放在同目录下。这和 Codex CLI 的“所有技能文件平铺在一个目录”不同转换时不要搞混。5.2 其他兼容工具的挂载方式除了 TraeCursor、Windsurf、Continue 等工具也支持类似技能机制但配置入口各不相同。Cursor 主要是通过.cursor/rules目录下的规则文件加载你可以把 superpowers 里的技能内容按需复制到规则文件里或者用import方式引用。Windsurf 则要求写入全局rules目录通过Windsurf Rules面板管理。这些工具本质上都在做同一件事在 AI 上下文里注入系统指令。所以只要你理解了 superpowers 的“技能即文本指令”这一核心迁移到任何工具都只是路径和格式的问题。不要被配置文件吓到多试几次就能摸清规律。5.3 多环境切换的配置管理我平时同时使用 Codex CLI 和 Trae不同工具有不同的技能目录。为避免两套配置互相干扰我用了一个简单方法把技能文件统一放在~/workspace/skills-template下然后通过符号链接把同一份文件链接到各工具的技能目录。这样改一次技能文件所有工具都能生效。ln -s ~/workspace/skills-template/code-review.md ~/.superpowers/skills/code-review.md ln -s ~/workspace/skills-template/code-review ~/.trae/skills/code-review这种方法需要你提前规划目录结构但长期来看很省心。如果有团队协作需求还可以把技能模板放到 Git 仓库让同事克隆后一键链接到各自环境。6. 常见问题与排查技巧实录6.1 技能没有加载怎么办最典型的症状是你输入测试指令AI 完全没有技能相关的反应。排查思路很简单按顺序检查三件事。第一技能文件路径是否正确确认ls ~/.superpowers/skills能看到文件第二Codex 配置里的additional_instructions是否写对了绝对路径注意~是否被正确展开第三确认 Codex CLI 的当前会话是否重新加载了配置一般改完配置后需要重启终端或新开会话。如果还是不行可以用调试模式启动 Codex CLI看看加载指令时有没有报错。绝大部分情况下问题都出在路径或者文件名拼写上尤其是 Windows 用户路径分隔符和大小写问题比想象中常见。6.2 提示词太长/上下文不够所有的技能文件最终都会占用上下文窗口。如果你把几十个技能一次性挂载进去会有两个后果一是 AI 的注意力被稀释真正需要用的技能反而没被重视二是上下文窗口可能会被塞满导致对话质量下降。这个问题的解法是“按需加载”在AGENTS.md里只引用当前项目相关的技能或者把技能文件按目录拆分按功能分组。我在实际使用中会把常用技能控制在 5 个以内其他不常用的放到单独的skills-extra目录需要时再手动引用。尤其是使用 gpt-4o 这类模型时上下文管理必须用心否则生成的代码容易出现“前后矛盾”的奇怪问题。6.3 某些技能不生效的排查思路如果你发现同一个会话里任务规划技能生效了但代码审查技能没有反应可能是技能文件里的元数据格式不对导致 Codex 无法识别它的触发条件。很多技能文件在 front matter 里写有description这个描述就是告诉 AI 什么时候该用这个技能的“信号”。如果描述写得太窄AI 可能认定当前任务不匹配如果描述太宽又会被乱用。排查时可以打开对应技能文件检查 front matter 的格式有没有损坏。另外如果技能文件里有复杂的变量替换语法也要确认是否与当前模型兼容。我用过一个技能里面对不同编程语言有不同的提示词模板结果在多语言项目中经常只触发默认分支后来才发现是变量命名冲突。6.4 卸载与清理卸载 superpowers 很简单只需要两步第一步删除 Codex 配置里的additional_instructions引用第二步删除本地技能目录比如~/.superpowers。如果你在项目AGENTS.md里写过引用也要一并移除。要注意的是删除目录前最好确认没有其他地方引用这些文件尤其是符号链接否则清理后其他工具可能报错。为了方便回滚我建议在卸载前先把技能目录打个包备份。毕竟你可能会因为某次更新引入不兼容改动想回到旧版本却发现已经删干净了只能重新配置非常浪费时间。7. 避坑指南与个人实战心得7.1 我踩过的三个坑第一个坑是一开始把全套技能直接扔进 Codex CLI结果 AI 每次回答都变得非常“啰嗦”做什么都要先列一堆步骤改一行代码也要告诉我要“优化设计”。后来我意识到不是所有任务都需要完整流程技能之间也会互相干扰。从那以后我只在项目的AGENTS.md里按需引入两三个技能问题立刻缓解。第二个坑是升级 superpowers 后某个技能的行为突然变了。因为技能文件是文本Git pull 后很可能覆盖了你自己修改过的内容。现在我每次升级前都会先git stash自己的改动或者用单独的分支管理本地修改避免和主仓库冲突。第三个坑是不同工具之间的兼容性问题。我在 Codex CLI 里调试好的技能文件复制到 Trae 后发现完全不生效原因就是 Trae 要求SKILL.md作为入口文件而 Codex CLI 没有这个约定。现在我会提前做好格式转换脚本一步生成多工具需要的技能结构。7.2 让superpowers发挥最大效果的最佳实践根据我自己的经验有四个习惯能让技能包的效果最大化。第一每个技能只做一件事专注才能把流程写清楚。第二技能文件里必须有真实示例AI 对示例的模仿能力远超对抽象规则的理解。第三定期更新技能文件把团队最近踩过的坑变成新的规则。第四不要害怕修改别人的技能文件superpowers 的价值就在于可定制固定不变反而不正常。另外建议在技能文件里加明确“输出格式”的要求。比如代码审查技能要求 AI 按“风险等级 问题描述 修改建议”的格式输出。这样生成的结果可以直接复制到 PR 评论里省去大量整理时间。7.3 后续还可以怎么扩展如果你已经熟练使用 superpowers可以尝试搭一套团队共享的技能库。把技能文件放到一个内部 Git 仓库用 CI 自动检查格式推送到主分支后让所有人更新本地。你甚至可以写一个简单的 CLI 脚本用来创建新的技能文件模板、检查所有技能的元数据是否完整、统计哪些技能被高频使用。我自己还尝试过把技能和自动化测试结合起来在 CI 里调用 Codex CLI用 superpowers 的代码审查技能自动检查 MR 中的 diff把审查结果作为注释发回代码平台。虽然还需要人工复核但已经能挡住很大一部分低级问题。这个方向很有潜力如果你在团队里做开发效率工具值得一试。最后再分享一个小技巧不要只把 superpowers 当作“装完就完事”的工具而是要持续往里沉淀你自己的经验。每次发现自己花了很多时间向 AI 解释同一类事情时就把它写成一个技能文件。时间久了你会发现你跟 AI 配合的越来越默契很多以前需要人肉判断的细节它都能自动按照你的预期处理。这正是 superpowers 这类技能包最有魅力的地方——它不是给你一个固定的智能而是让你把散落在大脑里的“工作方法”真正变成可复制、可管理、可进化的资产。