直接说结论如果你在用 Codex CLI、Trae 这类 AI 编程工具却总觉得 AI 像个“只会答不会做”的顾问指一步才动一步那 superpowers 就是冲着这个痛点来的。它不是某个具体插件而是一套以 Markdown 文档为核心的技能包Skills装上之后相当于给 AI 助手灌了一整套“资深工程师的工作手册”——从代码审查到深度调试从架构重构到文档生成AI 会按预设的高质量流程主动推进而不是挤牙膏式地等你发指令。这篇文章我会从 superpowers 到底是什么、为什么需要它开始分别拆解在 Codex CLI 和 Trae 里安装、配置、验证的完整过程再分享几个我实际用下来最顺手的高频场景和踩过的坑。不管你是刚接触 AI 编程的新手还是已经每天在命令行里跟 Codex 打交道的老手照着做都能少走弯路。1. superpowers 到底是个什么东西1.1 先从一次“翻车”经历说起上个月我接了个需求把一个历史遗留的 Python 服务从单体里拆出来顺带把日志系统重做一遍。这种活儿本身不复杂但琐碎涉及十几个文件的改动、异常链路的梳理、还有老代码里各种隐式依赖。我一开始直接用 Codex CLI 开干结果 AI 的表现让我血压拉满——让它改一个函数它就只改那一个函数完全不考虑调用方让它补日志它机械地在每个入口加一行 print最离谱的是代码里明明有一个明显的循环依赖我提示了三次它每次都说“您说得对”然后继续按原逻辑写。后来我翻社区看到有人说“你给 Codex 装上 superpowers 再试试”说人话就是一套专门为编码助手设计的技能包。装上之后同样是那台机器、同一个模型表现完全变了它会先列一个执行计划拆成几个阶段改代码之前先扫描所有调用关系遇到不确定的地方会主动停下来提问而不是闷头写。那次需求最后只花了一个下午就搞定了放在以前我至少得和 AI 来回拉扯两天。1.2 拆开看技能包、工作流与提示词工程superpowers 的本质并不神秘它就是一整套结构化的技能定义文件每个技能都对应一种具体的编码任务——比如深度调试、代码审查、性能优化、架构梳理、测试生成。每个技能文档里包含三样东西触发条件什么情况下该启用这个技能AI 看到什么样的请求会自动匹配。执行步骤完成这项任务的标准化流程比如调试要先复现、再定位、再修根因而不是上来就改。输出规范每一步该产出什么代码、说明、还是风险清单格式是什么。这套机制底层依赖的是大模型的上下文理解和指令遵循能力。你可以把它理解成给一个聪明但没经验的新人配了一本“老员工操作手册”——模型本身的推理能力没变但有了手册约束做事方式就从一个“想到哪写到哪”的实习生变成了一个“按流程走、有检查点、有交付标准”的熟练工。提示别把 superpowers 想得太玄。它不修改模型权重也不碰你的代码逻辑所有“超能力”都来自预设的提示词流程。这意味着你随时可以改、可以删、可以定制成自己团队的规范。2. 动手前的准备环境与工具链2.1 哪些工具需要装齐在安装 superpowers 之前建议先把基础环境捋一遍。我吃过亏在缺依赖的环境里折腾了一个小时最后发现只是某个命令行工具版本太旧。先说最低配置Node.js 18 以上最好 20因为 Codex CLI 和 Trae 的扩展机制都依赖较新的运行时。Git用来拉取技能包仓库。Codex CLI 最新版或者 Trae 最新版。老版本对 Skills 机制的支持不完整装了也白装。一个能跑通的 AI 后端配置无论是官方服务还是自建网关确保基础对话功能正常。确认版本的方法很简单。Codex CLI 在终端里跑codex --versionTrae 在设置里看“关于”页面。如果版本偏老先升级不要跳过这一步。2.2 为什么推荐先跑通一个最小 demo我见过不少同学上来就奔着“装全套”去结果技能包拉到一半报错或者装完了 AI 完全没有变化然后开始怀疑人生。其实问题多半出在环境本身。我的建议是先创建一个空目录在 Codex CLI 里跑一次最简单的对话比如让它写一个“hello world”的 Python 函数。确认基本链路是通的再考虑安装 superpowers。这样后续排查问题时你能把“AI 本身的问题”和“superpowers 的问题”分开不至于混在一起瞎猜。另一个小建议装之前先把 Codex 的配置文件备份一份。绝大多数情况下不会用到但万一你把配置改坏了至少有个后悔药。备份方式就是把配置文件复制一份带.bak后缀后面我会详细说配置文件在哪。3. Codex CLI 安装 superpowers 的完整流程3.1 第一步确认 Codex CLI 版本与配置目录Codex CLI 的配置目录在~/.codex下主要文件包括config.toml全局配置、AGENTS.md项目指令和skills目录自定义技能。不同版本的组织方式略有差异但大体一致。先确认你的版本支持 Skills 扩展机制。以我的经验至少在 0.4x 版本以上才有完整的技能加载逻辑。你可以跑一下codex --version如果输出的是 0.3x 或更早建议先升级到最新版本再继续。然后看一下配置目录结构ls -la ~/.codex正常情况下你会看到config.toml和AGENTS.md文件。AGENTS.md是 Codex 的项目级指令文件AI 每次启动都会读它后续安装 superpowers 时需要在这里面加引用。3.2 第二步拉取 superpowers 技能包并安装superpowers 的技能包以 Git 仓库的形式分发。社区里常见的做法是 clone 到本地然后把技能文件软链到 Codex 的 skills 目录。我推荐先 clone 到~/.codex/skills/superpowers这个固定位置方便以后统一管理mkdir -p ~/.codex/skills git clone https://github.com/your-repo/superpowers.git ~/.codex/skills/superpowers提示上面仓库地址是示意实际使用时请以你找到的官方仓库为准。建议认准社区里 star 数高、更新活跃的仓库不要随意从陌生地址拉取未知代码。clone 完成之后查看一下里面的内容ls ~/.codex/skills/superpowers一个标准的 superpowers 仓库通常包含若干 Markdown 文件或子目录每个文件对应一个技能。例如debugging.md、code-review.md、refactoring.md等。有些仓库还会带一个SKILLS.md或README.md描述每个技能的用途和触发方式。接下来最关键的一步让 Codex 知道你装了这套技能。方法是在项目的AGENTS.md文件末尾追加一行引用## Superpowers Skills 启用以下技能包根据任务类型自动选择合适的技能 - 在回答涉及代码调试、错误修复的问题时参考 skills/superpowers/debugging.md 中的标准流程。 - 在回答涉及代码审查、质量评估的问题时参考 skills/superpowers/code-review.md 中的标准流程。注意这里写的是相对路径所以你要确保运行codex命令时所在的目录层级能正确找到~/.codex/skills这个位置。如果你项目的AGENTS.md不在~/.codex下建议用绝对路径或者直接把引用路径写成- 调试任务参考 /Users/你的用户名/.codex/skills/superpowers/debugging.md两种方式都可以重点是让 Codex 能读到完整的技能内容。3.3 第三步验证技能是否生效装是装完了但怎么知道真生效了直接跑一个测试任务最靠谱。在项目目录下启动 Codexcodex然后输入一个明显需要调试技能的请求比如我有一段代码总是抛出 KeyError但我不确定是哪里没有初始化请帮我调试。如果技能生效你会观察到与平时明显不同的反应AI 不再直接给一段“看似合理”的修复代码而是先要求看完整的错误堆栈再列出可疑的变量初始化点最后才给修复方案。它可能还会主动问你要日志文件。我第一次测试时还以为它卡住了因为它没有立刻给代码而是连续问了三个关于运行环境的问题。后来才发现这正是技能文档里标准的“调试前信息收集”环节。如果你观察到这种“先问后答”的行为变化就说明 superpowers 已经成功加载了。4. Trae 中安装 superpowers skill 实操记录4.1 Trae 的 Skills 机制和 Codex 有什么不同Trae 是字节跳动推出的 AI IDE它的 Skills 机制和 Codex CLI 有所不同但核心理念一致给 AI 提供一套结构化的技能定义文件让它按预设流程执行任务。区别主要在三点管理方式Trae 在设置面板里有专门的 Skills 管理入口可以图形化地启用/禁用技能不用手改配置文件。作用范围Trae 的 Skills 更偏向于当前工作区的任务比如代码补全、批量重构、测试生成和 IDE 的编辑器联动更强。加载优先级Trae 会优先读取工作区.trae/skills目录下的技能文件其次才读全局配置。上手时不用被这些差异吓到本质上还是同一套思路只是“放技能文件的位置”和“声明方式”不一样。4.2 安装步骤与配置细节在 Trae 里安装 superpowers skill 比 Codex CLI 简单不少不需要手写引用路径直接把技能文件放到指定目录就行。第一步在工作区根目录创建.trae/skills文件夹mkdir -p .trae/skills第二步把 superpowers 仓库里你要用的技能文件复制进去。比如我常用的是调试和代码审查就只复制这两个cp ~/.codex/skills/superpowers/debugging.md .trae/skills/ cp ~/.codex/skills/superpowers/code-review.md .trae/skills/第三步重启 Trae。在设置面板的扩展或技能区域你应该能看到识别出来的技能列表。如果没有自动识别检查一下技能文件的格式是否包含name和description等必要字段。某些版本的 Trae 要求技能文件头部有 YAML frontmatter例如--- name: debugging description: 用于系统化调试代码错误先收集信息、再定位根因、最后修复并验证。 ---第三块内容是技能文档的正文规则。第四步打开一个项目随便选中一段代码呼出 AI 助手输入一个调试类问题观察 AI 的行为变化。我实测下来Trae 在加载 skill 后AI 给出的建议明显更有条理会先列排查清单再逐项排除。4.3 实测在 Trae 里用 superpowers 改写一段遗留代码我找了一个真实的 Java 项目做测试。项目里有一段用户登录逻辑几百行里面有大量 if-else 判断、重复的属性校验和一个隐藏很深的空指针隐患。正常情况AI 看到“帮我优化这段代码”的请求通常会直接给一个“简化版”的实现——很多时候它会猜你的业务意图结果改出来的代码根本不能用。但加载了 superpowers 的 code-review 技能后AI 的第一轮响应变成了列出这段代码存在的 4 类风险每个风险标注严重级别然后询问我期望的重构边界保持接口不变还是可以改调用方。这种“先定边界再动手”的行为正是技能文档里要求的执行步骤。对实际工作来说这种操作方式带来的安全感完全不一样再也不用担心 AI 自作主张把这些逻辑改出问题。5. 核心玩法与实战场景5.1 高频技能盘点调试、重构、审查、文档生成用了一个多月 superpowers我最常用的技能就四类。调试debugging要求先收集错误信息、复现路径、环境差异再定位根因最后给出修复和验证方案。这套流程救了我好几次尤其是处理线上偶发问题时AI 不会忙着给修复代码而是先让我提供时间窗口的日志缩小范围再下结论。重构refactoring强调保持行为不变、小步提交、每步可运行。它的价值不在于 AI 能一次写出完美的代码而在于它会把重构拆成 5-6 个阶段每个阶段结束都会提醒我可以跑测试。这正好对治 AI 容易“一把梭”的毛病。代码审查code-review要求从正确性、性能、安全、可维护性四个维度逐项检查每个问题标注严重级别并附上“为什么这是问题”的解释。我现在提交 MR 之前都会先让 AI 过一遍比自己盲检查效率高不少。文档生成documentation不只是写 Javadoc而是要求分析调用关系、梳理模块边界、标出潜在依赖。它生成的文档质量更像一份“设计说明”而不是注释堆砌。5.2 实战例子用 superpowers 做一次完整的代码审查拿一个真实的片段举例。我有一段 Python 代码负责从数据库拉取用户列表并做权限过滤def get_filtered_users(conn, role): rows conn.execute(SELECT * FROM users) return [row for row in rows if row[role] role]在没启用 review 技能时让 AI 审查这段代码它最多说一句“建议使用参数化查询避免 SQL 注入”。这确实对但信息密度太低。启用 superpowers 的 code-review 技能后同样的输入AI 给了如下清单严重SQL 拼接虽然在此场景没有直接拼接用户输入但role一旦来自外部会带来注入风险建议参数化。中等一次性加载所有用户行到内存当数据量达到数万级别时会拉高内存占用建议在 SQL 层做过滤。中等缺少异常处理数据库连接断开时上层调用方拿不到明确错误提示。轻微列表推导式里调用了两次row[role]可以提取局部变量让意图更清晰。建议增加对role合法值的校验提前返回空列表而不是等到数据库查询后再过滤。这份清单的价值在于它“有轻重缓急”直接能指导我修改代码。我在实际项目里照着改明显比我自己凭感觉检查得更全。5.3 进阶自定义自己的技能包用熟练之后完全可以定制自己的技能。做法很简单在~/.codex/skills目录下新建一个 Markdown 文件例如security-review.md然后写上触发条件和执行步骤。我的一个自定义技能是“数据库变更评审”凡是涉及 SQL 修改的请求AI 会先要求看当前的表结构、数据量级、是否有索引再给出变更脚本。这个过程本质就是把你平时口头叮嘱 AI 的话固化成一份文档。提示自定义技能时“触发条件”要写具体避免 AI 在无关任务上强行套用。比如“仅当用户明确提到 SQL、表结构、索引时启用”比“涉及数据时启用”要精确得多。6. 常见问题与排查技巧实录6.1 装上之后 AI 毫无变化这是遇到最多的情况九成不是 superpowers 本身的问题而是引用路径写错了。Codex CLI 加载AGENTS.md时如果路径写的是相对路径它会相对于当前项目根目录解析而不是相对于~/.codex目录。你可以在AGENTS.md里写一个绝对路径然后重新启动 Codex再问 AI 一句“你有哪些技能可用”看它是否列得出技能名称。另外注意Codex CLI 有缓存机制改完AGENTS.md后如果不重启AI 可能还读的是旧配置。一定先重启再验证。6.2 多个技能互相冲突当你的技能文件越来越多AI 可能会困惑一个请求同时匹配两个技能该听谁的我的经验是在技能文档的“触发条件”里写清楚“优先级”和“排他性”。例如在 debug 技能里写明“当同时匹配重构技能时以本技能为准先完成正确性修复再考虑重构”。另外一个办法是控制技能数量。我有段时间一口气装了十多个技能结果是 AI 每条回复都变得又长又啰嗦因为它试图把所有技能的规则都“照顾”到。后来精简到 5 个核心技能效果反而更好。6.3 上下文窗口被技能文件塞满这是另一个容易踩的坑。有些 superpowers 技能文件写得很长动辄几百行一旦加载多个会占用大量上下文空间留给实际代码分析的 token 就少了AI 会变得“记性差、反应慢”。我采取的解决办法是“按需加载”不要在AGENTS.md里一次性引用全部技能而是只保留两三个最常用的其他技能放到单独的AGENTS.extra.md文件里需要时再通过对话让 AI 去读那个文件。这样既保留扩展能力又不拖累日常会话。6.4 常用排查速查表问题可能原因解决方法技能完全不生效引用路径错误/未重启改为绝对路径重启 Codex/Trae部分技能生效、部分不生效技能文件格式不符合要求检查 YAML frontmatter 是否完整AI 回复变慢加载技能过多占用上下文精简为 2-3 个核心技能技能之间行为冲突触发条件重叠在文档中写明优先级CLI 报错无法启动配置语法错误用备份的 config 文件恢复最后再分享一个我个人的习惯每次调整完 superpowers 配置我都会用一个固定的测试问题来验证效果比如“给我写一段有隐藏 bug 的 Python 函数”。通过看 AI 是直接甩代码还是先提问就能快速判断技能有没有按预期加载。这个方法帮我节省了无数排查时间也让我对这套机制的理解越来越深。