最近 AI 编程圈里Superpowers 这个词出现的频率突然高了起来。如果你在折腾 Codex CLI或者用 Trae Work 中文版写代码大概率刷到过“codex cli 安装 superpowers”“trae work cn 安装 superpowers skill”这类热词。不少朋友以为 Superpowers 是某个新模型或者独立 IDE其实不对。它更像一组打包好的“技能包Skill Pack”里面装着系统性的提示词、任务模板和工作流规则给 AI 编码代理装上后能让它从“你说一句、它写一段”的助手变成“自己拆任务、自己验证、自己修 bug”的初级工程师。我花了一周时间在 Codex CLI 和 Trae 里反复装、反复跑实际做完一个多文件重构和一轮单测修复最直观的感受是这套东西最值钱的不是让 AI 写出更多代码而是逼着它建立起“先规划、再执行、后验证”的可靠工作习惯。这篇文章就围绕 Superpowers 的安装和使用把我踩过的坑和验证过的步骤完整写出来。1. Superpowers 到底是什么一段给 AI 编程助手的“内功心法”1.1 原生编码代理的三个结构性短板用过 Codex CLI 原版工作流的朋友大概都遇到过类似场景你让它“给用户注册接口加个邮箱验证”它啪一下把代码改完直接告诉你“搞定”。但你稍微追问一句“影响面有没有确认原有测试跑过没有”它就开始支支吾吾甚至改一个变量名把另外三个文件带崩。这不是模型能力不够而是原生的编码代理缺少三层约束。第一层是上下文管理AI 只能看到有限上下文经常改着改着就把最初的约束忘了。第二层是目标拆解它默认你会把任务讲得足够细可实际项目里一个需求往往牵扯多个文件、多个模块没人替它把步骤拆好。第三层是验证闭环很多原生代理“写代码”和“验证代码”是割裂的它不会主动去跑测试也不会在测试挂了之后做最小化修复。这三个短板叠加起来就是大家常说的“AI 生成代码一时爽合并之后火葬场”。Superpowers 这类技能包解决的就是这件事。它不改变底层模型而是通过一组结构化的指令文件在每次任务开始之前先给 AI 注入一套完整的工作协议。简单说别人是让 AI 直接答题Superpowers 是要求 AI 先把解题步骤写出来、每步做完验算、最后再交卷。这也是为什么很多人装完之后觉得“AI 变聪明了”——本质不是模型升级而是行为流程被规范了。1.2 Superpowers 的核心模块拆解、执行、验证、收尾我实际把技能包解压开看了一眼目录结构比想象中清晰。通常最外层是一个主入口文件一般叫SKILL.md里面定义了整体工作流下面再挂几个子技能目录比如plan/、test/、debug/、review/。每个子技能都是独立的 Markdown 指令文件专门负责某一类动作。以我手头这个版本为例主流程分四步。第一步是规划Plan它要求 AI 在写任何代码之前先输出一份任务清单每条任务必须标注影响到的文件和执行完要跑哪个测试。第二步是执行Execute要求 AI 严格按照清单逐项实现不许跳步。第三步是验证Verify每个子任务完成后必须运行相应测试不允许用“我觉得没问题”代替测试结果。第四步是收尾Wrap-up要求 AI 更新相关文档、检查是否有临时调试代码、提交时写清楚变更范围。这套流程听起来并不复杂但关键在于它是“强制”的。技能文件里通常会有类似“除非用户明确要求否则禁止跳过验证步骤如果测试失败禁止直接重写整个模块必须先定位最小问题集”这样的约束。模型在执行时会把这条规则当成最高优先级于是很多原本被忽略的验证动作就变成了标准动作。1.3 一个最简单的 SKILL.md 长什么样为了让大家对“技能包”有直观印象我摘一段核心协议片段这基本是所有 Superpowers 变体都会包含的内容# Superpowers Core Protocol ## 1. Plan First Before writing any code, output a task checklist in this exact format: - [ ] Task: 具体任务描述 - Files affected: 涉及文件用绝对或相对路径 - Tests to run after completion: 测试命令或文件 ## 2. Execute In Order - Complete tasks one by one; do not skip. - Do not batch changes across multiple modules unless the checklist explicitly includes them. ## 3. Verify Each Step - After each task, run the listed tests. - If the test fails, do NOT rewrite the whole file. Follow this loop: 1. Read the failure message. 2. Trace it to the smallest possible root cause. 3. Fix only the necessary lines. 4. Re-run the failing test. - If tests pass, move to the next task. ## 4. Wrap Up - Update README or inline comments if interface changed. - Scan for debug statements, TODO placeholders, and dead code. - Summarize the change in the final response.你别小看这几段话。把它塞进 AI 的上下文之后效果立竿见影。我自己试过同一台机器、同一个 Codex CLI没装技能前让它重构一个 utils 模块它直接丢给我一份改完的代码装完技能后它先列出 7 个子任务然后一项项执行每完成一项就自动跑单测中间挂了两次每次都是通过定位失败日志里的具体报错去修而不是无脑回滚。就冲这个变化我认为 Superpowers 的价值被很多人低估了。2. 安装前的准备Codex CLI 与 Trae 环境差异2.1 Codex CLI安装、登录、目录结构想在 Codex CLI 里安装 Superpowers先把基础环境弄干净。Codex CLI 是 OpenAI 官方的命令行编码代理最常用的安装方式就是通过 npm 全局安装。如果你还没装直接执行npm install -g openai/codex装完验证版本codex --version我建议至少用支持 skills 机制的较新版本老版本对自定义指令的支持很弱装了也白装。登录认证方面Codex CLI 通常需要配置 API Key 或者走官方登录流程具体命令如下codex login或者设置环境变量OPENAI_API_KEY。这一步跑通之后你要清楚 Codex CLI 的配置目录在哪里。默认情况下用户在~/.codex/下会有一个配置目录里面可以放全局指令文件、技能目录、以及历史记录。项目级配置则放在当前工作目录下的AGENTS.md里。这里有个容易踩坑的地方很多人把技能文件直接丢进项目根目录但在 Codex CLI 的项目目录里AI 并不是自动扫描所有 Markdown 文件。它通常只会读取AGENTS.md以及明确通过指令引用的文件。所以后续安装 Superpowers 时一定要在AGENTS.md里写明“去哪个路径读取技能”否则文件放得再整齐也没用。2.2 Trae Work 中文版找到工作区和技能目录Trae 是字节跳动推出的 AI IDE国内用户大多数用的是 Trae Work 中文版。它内置了比较完整的“技能Skill”机制和 Codex CLI 那种偏命令行的加载方式不太一样。Trae 的项目级技能目录是.trae/skills/你可以把它理解为 IDE 自己定义的一个扩展目录只要把符合规范的文件放进去AI 在对话中就能自动感知到。我在 Trae Work 中文版里试了半天总结下来有几点关键。第一技能目录必须放在当前项目的根目录下命名结构是.trae/skills/技能名/SKILL.md。第二Trae 对 SKILL.md 的 frontmatter 有要求需要在文件开头写上技能名称和描述这样 AI 才会在合适的场景下主动调用。第三如果你用的是“Work 工作区”模式最好把技能目录放在工作区根目录而不是某个子模块目录里否则 AI 可能扫描不到。需要注意Trae 中文版和英文版的配置目录并不完全一样但.trae/skills这个约定是通用的。所以你在网上看到英文教程里的路径在中文版项目里同样适用不需要额外改。2.3 两者的共同逻辑技能包本质是“指令文件”很多人同时用 Codex CLI 和 Trae以为要分别准备两套不同格式的 Superpowers。其实没必要。技能包的本质是一组 Markdown 指令文件只要目录结构和 frontmatter 符合目标工具的约定同一个SKILL.md可以在这两个工具间复用。区别主要在加载方式。Codex CLI 更多依赖AGENTS.md去“建议”模型读取某个文件而 Trae 则直接在 IDE 层主动解析.trae/skills目录把技能描述注入到模型上下文中。理解了这层逻辑你在安装时就不会被表面的差异带偏放在 Trae 里的技能文件重点要写好 frontmatter放在 Codex CLI 里的技能文件重点要写好AGENTS.md的引用。后面两章我分别给出完整步骤。3. 实操在 Codex CLI 中安装 Superpowers 的完整步骤3.1 方式一用 git clone 导入现成技能包目前社区里有很多 Superpowers 的分支版本有的是完整技能集合有的是精简版。最省事的方式是直接把技能仓库克隆到本地然后复制到 Codex CLI 的技能目录。以我自己为例我习惯把技能统一放在~/.codex/skills/下这样所有项目都能复用。git clone 你关注的技能仓库地址 superpowers-temp mkdir -p ~/.codex/skills cp -r superpowers-temp/skills/* ~/.codex/skills/这里有个小细节技能仓库里的skills/目录可能包含多个子技能文件夹比如plan、test、debug。你要保证复制到~/.codex/skills/后每个子技能文件夹下面都有独立的SKILL.md。复制完可以检查一下ls -R ~/.codex/skills如果看到类似~/.codex/skills/debug/SKILL.md这样的结构说明文件放对了。但如果你只复制了仓库根目录下的SKILL.md而漏掉子技能目录后面 AI 调用子技能时会找不到文件出现“技能未定义”的报错。3.2 方式二从零手写 Superpowers 核心技能如果你不想折腾 git clone完全可以通过手动创建目录和文件把第一节那个核心协议写进去。这个方法最大的好处是你可以按自己的团队规范定制内容不受社区版本限制。mkdir -p ~/.codex/skills/superpowers cat ~/.codex/skills/superpowers/SKILL.md EOF --- name: superpowers description: 强制 AI 在编码任务中执行“规划-执行-验证-收尾”的完整工作流。 --- # Superpowers Core Protocol 这里写前面摘录的四步协议内容 EOF写完这个主文件之后我建议再补一个简单的调试子技能mkdir -p ~/.codex/skills/debug cat ~/.codex/skills/debug/SKILL.md EOF --- name: debug description: 当测试失败时按最小化修复原则定位问题。 --- # Debug Protocol 1. Read the full failure output. 2. Find the failing function and its input. 3. Trace data flow backward from the failure. 4. Modify only the minimum lines required. 5. Re-run the exact failed test before proceeding. EOF手动创建的好处是你能清楚地知道每一行指令在干什么出了问题也容易排查。坏处是技能少了覆盖场景有限。对新手我更推荐先用方式一装社区完整版跑通之后再慢慢改出自己的版本。3.3 在 AGENTS.md 中声明技能并验证文件放好之后最关键的一步是让 Codex CLI 知道这些技能的存在。你需要在当前项目根目录下创建或修改AGENTS.md在里面明确写出加载指令# Agent Instructions ## Skills - 处理代码任务前必须读取 ~/.codex/skills/superpowers/SKILL.md 并严格遵循其中的流程。 - 当测试失败时必须读取 ~/.codex/skills/debug/SKILL.md 并按照调试协议执行。 ## Constraints - 禁止在未完成任务清单中所有步骤的情况下向用户报告“完成”。 - 涉及多文件修改时必须先输出影响文件列表。这里需要提醒的是AGENTS.md和AGENTS.md在不同项目里可能被覆盖尤其是多个工具同时管理它时。我的习惯是把全局技能声明放在~/.codex/config.toml或 Codex CLI 的全局指令里把项目相关的约束放在项目AGENTS.md里避免每次克隆新项目都要重新配置。配置完成后启动 Codex CLI输入你有哪几个技能分别是在什么场景下使用如果 AI 能准确说出 superpowers 和 debug 技能的名字并简单描述用途说明加载成功。如果它只回答“我没有技能”或者“我不确定”大概率是AGENTS.md路径写错或者技能文件里的 frontmatter 缺失。4. 实操在 Trae 中安装 Superpowers Skill 的两种方式4.1 通过项目内.trae/skills目录安装在 Trae Work 中文版里安装我推荐直接用项目内.trae/skills目录步骤非常直白。先在项目根目录创建技能目录mkdir -p .trae/skills/superpowers然后把前面写好的SKILL.md放进这个文件夹。如果你的 Superpowers 里还有其他子技能比如debug就再建一个mkdir -p .trae/skills/debug放好之后Trae 会自动扫描项目中的.trae/skills目录。注意这里的 skill 描述非常重要。Trae 会把SKILL.md中 frontmatter 里的name和description传给模型帮助它判断“什么时候该调用这个技能”。所以描述要写得具体一点别写“这是一个编码辅助技能”这种废话而应该写“当用户要求实现新功能或重构代码时先调用此技能进行任务规划和验证”。我实际测试过把技能文件放到.trae/skills后不重启 IDE 也能在较短时间内被识别到。但如果你的 Trae 版本比较老可能需要重启一下工作区或者重新打开项目让索引刷新。4.2 通过 Trae CLI / 命令面板导入除了手动建目录Trae 还支持通过命令面板导入。在 Trae 里按下CmdShiftP或CtrlShiftP输入“skills”关键词一般能看到“Import Skill”或“安装技能”之类的选项。选择该项后会弹出一个文件选择窗口直接指向你下载好的 Superpowers 文件夹即可。这个方法适合从网上下载了技能包压缩包的朋友。解压之后压缩包里通常有一个包含多个子技能目录的根文件夹你选择那个根文件夹导入Trae 会把它自动复制到当前项目的.trae/skills目录下。省去了手动敲mkdir和cp的麻烦。如果你习惯用命令行也可以打开 Trae 的终端执行类似trae skills install ./superpowers的命令。不过这个命令在不同版本里差异较大我试过的两个中文版版本一个支持一个不支持。所以最稳妥的判断方法是先看 IDE 底部的状态栏有没有提示“检测到技能”如果没有就用命令面板导入。4.3 验证 Trae 是否加载成功安装完成后打开 Trae 的 AI 对话面板直接问当前项目里有哪些可用技能简单描述每个技能的用途。如果 Trae 正确返回了 superpowers 和 debug 技能说明安装成功。如果它回答“没有发现技能”先确认目录是否在项目根目录以及SKILL.md是否以---开头包含 frontmatter。另外Trae 有一个好处是AI 在回答时会显示“正在使用技能 xxx”的标识。你实际让它实现一个小功能比如“帮我写一个读取 CSV 并去重的函数”如果它开始输出任务清单说明 superpowers 的技能协议已经被激活。这一步验证效果比直接问更真实。5. 使用进阶Superpowers 实际项目中的工作流5.1 实战案例用 Superpowers 规划“用户注册接口”光装完不算完真正有价值的是把它用到实际任务里。我拿一个最常见的“用户注册接口”作为例子看看装上 Superpowers 之后的 Codex CLI 是怎么工作的。我把需求发给它“实现一个用户注册接口需要校验邮箱格式、密码长度、用户名唯一注册成功返回 token。”在没有技能时它很可能直接生成一个register.ts文件附带几行校验逻辑然后结束。但有了 Superpowers 之后它第一步输出的是任务清单 - [ ] Task: 创建用户数据模型和数据库表结构 Files affected: src/models/user.ts, migrations/xxx.sql Tests to run after completion: npm run test:model - [ ] Task: 实现邮箱格式和密码长度校验 Files affected: src/validators/auth.ts Tests to run after completion: npm run test:validators - [ ] Task: 实现用户名唯一检查 Files affected: src/services/user.ts Tests to run after completion: npm run test:service - [ ] Task: 生成 token 并构造响应 Files affected: src/controllers/auth.ts Tests to run after completion: npm run test:controllers然后它真的会按照这个顺序逐个文件执行。执行完第一个任务它自动跑模型测试第二个任务完成再跑校验器测试。中间有一次因为数据库表字段写错导致测试失败它没有重置整个迁移文件而是读取失败日志定位到“外键约束缺失”只给迁移文件加了一行索引再重新跑测试通过后才继续下一个任务。整个过程保持了很好的节奏。5.2 实战案例让 AI 自己完成“重构回归测试”另一个典型场景是重构。我试了一个有 8 个文件的 Python 工具库需求是把所有requests.get调用统一封装成HttpClient。如果用原版代理它会全局搜索替换看起来很高效但经常漏掉异常处理不一致的问题。Superpowers 模式下的处理方式完全不同。它先扫描所有引用requests的模块列出 8 个文件各自的调用方式有的用了timeout参数有的没设置异常捕获有的直接返回response.json()。然后它把任务清单分成三类第一类是提取公共HttpClient类第二类是分别适配 8 个模块的调用点第三类是跑全量测试并对比返回结果。执行到第三个模块时遇到一个很隐蔽的坑那个模块里的函数依赖requests.get返回的原始 response 对象改成HttpClient之后返回值类型变了导致后续.status_code属性取不到。如果按传统方式AI 可能会在调用点硬塞一个response变量。但 debug 技能起作用了它读跑了失败测试的 traceback定位到是返回值类型不匹配然后手动修改HttpClient增加一个raw_response属性同时保持封装一致性。这个细节让我觉得技能包真正值回票价。5.3 经验如何让技能包适配你的团队规范社区默认的 Superpowers 流程可以满足通用需求但每个团队的代码库都有自己的约束。我建议在装完基础包之后往SKILL.md里追加团队专属规则。比如你们要求所有接口必须写 OpenAPI 文档那就在 Wrap-up 阶段加一条“接口变更后必须同步更新docs/openapi.yaml。”比如你们要求测试命名必须用test_前缀那就在 Verify 阶段写明“测试命令只识别匹配test_*.py的用例”。这个方法比写一堆口头提示词要稳得多因为技能文件是每次都会注入上下文的相当于把团队规范写进了 AI 的“入职手册”。我后来把公司里常用的 commit 规范、环境变量命名规范都写了进去AI 生成的代码风格明显更贴近老员工手笔。6. 常见问题与排查技巧实录6.1 问题速查表下面是我在 Codex CLI 和 Trae 里安装 Superpowers 过程中遇到过的典型问题整理成表方便排查。现象可能原因解决方案技能文件放了但 AI 不读没有在AGENTS.md里引用技能路径在AGENTS.md中显式写出SKILL.md的绝对路径Trae 对话里说“没有技能”SKILL.md缺少 frontmatter 或描述太长确保文件以---开头description控制在 50 字左右AI 只在部分任务中使用 Superpowers技能描述写的场景不够具体模型没匹配到修改description明确触发条件比如“当任务涉及多文件修改时”安装后 Codex CLI 报“找不到文件”复制文件时缺少子技能目录用ls -R ~/.codex/skills检查目录结构测试失败后 AI 无限重写代码技能文件里的 debug 协议没有被加载单独声明debug/SKILL.md强调“禁止重写整文件”Trae 中文版导入技能后不生效导入到了项目根目录但 IDE 没有刷新索引重启 Trae 工作区或手动重开项目同一份 SKILL.md 在 Codex 和 Trae 里效果不同两个工具对 frontmatter 和加载机制的解析不同分别配置Codex 偏重路径引用Trae 偏重目录扫描6.2 独家避坑技巧最后分享几个不太容易在网上看到的小经验。第一技能文件里尽量不要出现“必须”“永远”这类绝对化词汇叠太多。模型是概率输出的有的版本会过度遵循指令导致 AI 在简单问答场景也强行拆解任务显得很笨拙。解决办法是在SKILL.md里加一句“如果用户请求的是简单事实问答或与代码无关则不启动编码协议”。这样既能保留技能优势又不会把简单对话复杂化。第二Codex CLI 里AGENTS.md的优先级很容易被项目本身的 README 影响。我发现如果 README 里写了“run npm install npm test”AI 在验证阶段会倾向于直接执行整个测试套件而不是按子任务跑单文件测试。这会导致执行时间飙升。我后来在AGENTS.md里明确写了“验证依赖必须写在任务清单中禁止自行扩大测试范围”症状立刻缓解。第三如果你在 Trae 里同时装了很多技能AI 可能因为描述冲突而不知道调用哪个。建议每个SKILL.md的description第一句话就点出触发场景就像“当用户要求创建新接口时使用”这样不要泛泛而谈“编码技能”。实测泛化描述会让 AI 选择困难反而降低效率。第四版本升级问题。Codex CLI 和 Trae 都会频繁更新技能加载机制偶尔会变。我遇到过 Trae 升级后需要到设置里重新分类技能目录的情况。所以装完技能后不要急着删安装包先保留原始压缩包一周等确认所有功能稳定后再清理可以省去重新下载的麻烦。我自己装了 Superpowers 之后最大的变化不是 AI 写的代码突然变牛了而是它做事的方式确实更像一个知道轻重缓急的同事先确认范围再动手做完还自动给我一份变更说明。这种工作流带来的安心感比单纯生成代码的爽感要重要得多。如果你手头正好有 Codex CLI 或者 Trae建议先拿一个小功能跑一遍感受一下“被规范过的 AI”是什么手感。等你熟悉了流程再慢慢往里加自己的规则把它调成属于你的开发搭子。