直接说结论：如果你在用 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 --version，Trae 在设置里看“关于”页面。如果版本偏老，先升级，不要跳过这一步。
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 第三步：验证技能是否生效
装是装完了，但怎么知道真生效了？直接跑一个测试任务最靠谱。
在项目目录下启动 Codex：
codex然后输入一个明显需要调试技能的请求，比如：
我有一段代码总是抛出 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 是直接甩代码还是先提问，就能快速判断技能有没有按预期加载。这个方法帮我节省了无数排查时间，也让我对这套机制的理解越来越深。
