superpowers技能库接入Codex CLI与Trae实战：让AI按流程执行任务

最近几天我一直在折腾一个新玩意儿，叫 superpowers。说实话，看到这个项目名的时候我第一反应是“又中二了”，但翻完 GitHub 仓库之后才发现，这玩意儿跟超能力没什么关系，它是给 AI 编码代理用的一套“技能库”——尤其是结合了 codex cli、trae 这类工具之后，确实能让 AI 干活的方式更像一个老手，而不是一个只会写代码片段的复读机。最近不少人在搜“superpowers 使用教程”“codex cli 安装 superpowers”“trae work cn 安装 superpowers skill”，说明大家跟我一样，刚上手时还是有不少疑问。我把这两天从踩坑到跑通的全过程整理一下，顺便把底层逻辑也说清楚，方便后面的人少走弯路。

1. superpowers 到底是个什么东西

1.1 名字背后的含义：不是超能力，是技能库

superpowers 是一个开源项目，托管在 GitHub 上。它的核心定义不是一套应用，也不是一个框架，而是一组“技能（skills）”的集合。你可以把它理解成给 AI 编码代理准备的“操作手册”，每一条技能都对应一类特定任务，比如代码审查、调试、测试用例生成、重构、架构分析等。

为什么会有这种东西？因为现在的 AI 编码工具（Codex CLI、Trae、Cline 等）虽然能听懂自然语言，但默认情况下它们并不知道“完成一个任务应该走哪几步”。你让它“修查一下这个 bug”，它可能会直接给出一个猜测性的修改；但如果你告诉它“先复现、再隔离、再定位根因、最后验证”，它的成功率会高很多。superpowers 就是把这些“老手的思路”打包成标准流程，让 AI 能按步骤执行。

这个设计思路很像我们平时写代码时抽公共函数：与其每个 prompt 里重复写那一大堆方法论，不如把这些方法论做成可复用的 skill，需要时让 AI 直接调用。这也是为什么现在的热门搜索里，“superpowers”总是和“codex cli”“trae”放在一起——因为那几个工具恰好支持自定义技能机制。

1.2 与 Codex CLI、Trae 的关系

Codex CLI 是 OpenAI 出的一个终端工具，让你能直接在命令行里跟 GPT 模型对话，让它帮你写代码、跑命令、操作文件。Trae 则是一个 AI IDE（字节跳动推出的），集成了类似的能力，但以图形化界面为主，Windows 和 macOS 都能用。

superpowers 与它们的关系，就像是“插件之于主程序”。Codex CLI 和 Trae 都提供了一种机制，允许你往项目里塞入额外的 skill 定义，告诉 AI “当用户提到某个关键词时，你应当使用对应的技能流程”。superpowers 恰好准备了一批质量比较高的 skill，可以直接被这些工具识别。

我在实际使用中觉得，它最大的价值不是“多了一个命令”，而是“改变了 AI 的工作习惯”。用上和没用上，就像同样一个员工，一个只有双手，一个还有标准作业蓝图。

1.3 适合谁来用

如果你只是偶尔用 AI 写几句函数，那你不需要 superpowers；但如果你像我一样，天天用 Codex CLI 或 Trae 来做日常的代码提交、模块重构、调试疑难 bug，那它绝对值得一试。尤其是下面这几类人：

• 想减少重复性 prompt 书写的人，把经验沉淀成可复用的技能。
• 需要让 AI 自动执行多步骤任务的开发者。
• 团队里想统一 AI 编码规范，让所有人都按同一套流程走。

2. 安装前的准备与核心概念

2.1 环境要求

先捋一下你机器上需要有什么：

• 操作系统：Windows 10/11、macOS 10.15+ 或主流 Linux 发行版。Trae 在 Windows 上的玩家很多，Codex CLI 则三个平台通吃。
• Node.js 16+：Codex CLI 本身依赖 Node.js 来运行，superpowers 里的部分脚本也基于 Node。
• Git：用来从 GitHub 克隆仓库。
• 可用的 Codex CLI 或 Trae：这个必须提前装好，因为 superpowers 只是“内容”，本身不带执行引擎。

提示：我一开始以为 superpowers 是个独立的 CLI，装完发现它不提供可执行文件，正确姿势是把它作为“技能素材”放进 Codex/Trae 的配置目录里。别搞反了。

2.2 从 GitHub 获取 superpowers

在终端中执行克隆命令：

git clone https://github.com/obra/superpowers.git

注意这个仓库名和作者我实测过是可访问的，但如果后续仓库地址有变动，你直接在 GitHub 搜索关键词 “superpowers skills” 也能找到。Clone 完成后，你会看到类似这样的目录结构：

superpowers/ ├── skills/ │ ├── brainstorming/ │ │ ├── SKILL.md │ │ └── ... │ ├── debugging/ │ │ ├── SKILL.md │ │ └── ... │ ├── code-review/ │ ├── writing-plans/ │ └── ... ├── AGENTS.md ├── README.md └── ...

核心目录是skills/，里面每一个子文件夹代表一项技能，每项技能至少包含一个SKILL.md文件。这个文件用 Markdown 编写，里面有技能的触发条件、执行步骤、注意事项等。

AGENTS.md也很重要，它对 AI 代理做了全局说明，告诉代理“本仓库有哪些技能、怎么用”。后面我们把它复制到自己的项目里，AI 就能顺着索引找到对应技能。

2.3 将 superpowers 作为 skill 接入的原理

Codex CLI 和 Trae 主要通过读取项目下的AGENTS.md文件来感知项目背景和可用技能。你不需要把 superpowers 整个仓库塞进每个项目，只需要做两件事：

1. 把AGENTS.md复制到你当前项目的根目录。
2. 把skills/目录也放到项目根目录（或者通过配置引入外部路径）。

这样当你在项目里启动 Codex CLI 或 Trae 时，AI 会读取AGENTS.md，发现自己能调用哪些技能，然后在用户请求匹配时按SKILL.md中的步骤执行。

原理听起来玄妙，其实就像你在新公司入职时拿到一份员工手册，手册里写了“遇到投诉走流程 A，设备损坏走流程 B”。superpowers 只是把这份手册做得更标准、更细。

3. 在 Codex CLI 中安装与使用 superpowers

3.1 Codex CLI 基础

如果你还没装 Codex CLI，先用 npm 安装：

npm install -g @openai/codex

装完后在项目目录下运行：

codex

它会进入交互式终端，你可以在里面直接说“帮我看看这个项目里有哪些 TODO”，Codex 会结合当前目录下的文件来回答。

Codex CLI 默认支持读取AGENTS.md文件，这正是 superpowers 能被 Codex 识别的基础。

3.2 将 superpowers 技能注入 Codex 的具体步骤

我用的是 macOS 环境，Windows 下步骤也差不多，只是路径分隔符不一样。整个安装过程如下：

第一步：克隆 superpowers 仓库

git clone https://github.com/obra/superpowers.git ~/superpowers

我建议放到家目录，这样多个项目都能复用，不用每个项目都 clone 一遍。

第二步：进入你的项目，复制 AGENTS.md

cd /path/to/your/project cp ~/superpowers/AGENTS.md ./AGENTS.md

第三步：复制或者软链 skills 目录

复制有个问题：以后 superpowers 更新了，你项目里那份还是旧的。所以我更推荐用软链：

ln -s ~/superpowers/skills ./skills

Windows 下对应做法是：

mklink /D skills C:\Users\你的用户名\superpowers\skills

注意 Windows 下mklink需要管理员权限，如果你不想折腾，直接copy也行。

第四步：按需选择技能

superpowers 默认包含不少技能，如果你只想要其中几个，也可以修改项目里的AGENTS.md，删掉或注释掉不需要的部分。我自己比较常用的是debugging、code-review、writing-plans，其他的先留着没动。

3.3 实际使用示例

安装完后，我在项目中运行codex，然后输入：

用 debugging 技能帮我查一下这两天新增的登录接口为什么偶发超时

Codex 读取AGENTS.md后知道存在一个debugging技能，于是会按照skills/debugging/SKILL.md里的步骤来执行：

1. 先让我描述问题现象。
2. 让 AI 检查相关日志和代码路径。
3. 提出可验证的假设。
4. 最小化复现实验。
5. 给出修复方案。

你会发现，AI 不再像以前那样一上来就直接改代码，而是先做信息收集和假设验证。这个变化非常明显，很像是一个实习生被带成了老兵。

另一个例子，代码审查：

用 code-review 技能帮我 review 当前分支的改动

它会按照code-review的流程，先检查变更列表、再按模块逐个审查、最后给出安全性和性能上的评论，而不是笼统地给你一句“代码整体写得不错”。输出质量高了好几个档次。

4. 在 Trae 工作台安装 superpowers skill

4.1 Trae 使用场景与目录结构

Trae 是一个 AI IDE，界面和 VS Code 很像，但它内置了 AI 对话、代码补全、Agent 模式等能力。你可以在 Trae 里创建项目，也可以打开已有项目。它同样支持AGENTS.md机制，因此安装 superpowers 的思路跟 Codex CLI 大同小异。

区别在于：Trae 通常以 GUI 操作为主，不一定要在终端里跑命令。在 Windows 上使用 Trae，路径和权限问题比 macOS 更麻烦一些，但也不是什么大坑。

4.2 Windows 下在 Trae 中配置自定义技能

我在 Windows 11 的机器上实际操作了一遍，流程记录如下。

第一步：确认 Trae 安装位置和项目路径

Trae 打开项目后，左下角会显示当前项目根目录。定位到该目录后，打开终端（Trae 内置终端，快捷键是Ctrl + ``），输入：

git clone https://github.com/obra/superpowers.git .superpowers

我用.superpowers这个隐藏目录，避免它被提交进去。

第二步：复制 AGENTS.md 和 skills

在终端里执行：

copy .superpowers\AGENTS.md AGENTS.md mklink /D skills %cd%\.superpowers\skills

如果mklink失败，就用：

xcopy .superpowers\skills skills /E /I /Y

直接用copy目录是传不进去的，得用xcopy。

第三步：在 Trae 中重置索引

因为 Trae 会缓存文件上下文，加了新文件后最好重新加载一下窗口。在 Trae 中按Ctrl+Shift+P，输入Reload Window，回车等待重启。这样AGENTS.md才会被 AI 重新读取。

第四步：在 .trae 配置中指定技能（可选）

Trae 支持在项目中放一个.trae/目录，里面可以写一些自定义配置。实际上，如果你只是要让 AI 识别 superpowers 里的技能，上述第二步已经够了。但如果你想把 Agent 模式下的行为也串起来，可以在.trae/agents/project_agent.md中添加一行引用：

请参考 AGENTS.md 和 skills/ 下的 SKILL.md 定义，按要求选择合适的技能完成任务。

这个文件不是必需的，但加上以后 Agent 模式的执行连贯性会好很多。

4.3 验证 superpowers 是否生效

配置完了怎么确认生效？最简单的方法是在 Trae 的对话框里问一句话：

你现在有哪些可用技能？请列出名称和用途。

如果配置正确，AI 会说出类似“我可以使用 Code Review、Debugging、Writing Plans 等技能”的话。如果它回答“没有发现技能目录”，那你需要检查：

• AGENTS.md是否在项目根目录，文件名是否完全一致（大小写也要一样）。
• skills目录是否存在，且里面有子目录。
• 子目录里是否有SKILL.md文件（有的是skill.md或SKILL.md，但 superpowers 统一使用大写）。

我自己第一次验证时用的是 Windows 下的xcopy，目录复制过去后少了一层结构，导致 Trae 一直提示找不到skills。后来我直接改用软链，问题立刻解决了。

5. 常见问题与排查技巧

5.1 技能没有正常加载

• 症状：AI 回答时完全不提技能，或者直接说“我没有在项目里找到 skills 目录”。
• 原因：90% 的情况是AGENTS.md没有放在项目根目录，或者文件名写错了（比如小写agents.md）。Codex CLI 和 Trae 对此大小写敏感。
• 处理：确认根目录下文件是AGENTS.md，不要改成别的，也不要放进子目录。然后重新加载窗口。

5.2 技能加载了，但 AI 不按步骤执行

有时 AI 知道有技能，却还是在自由发挥，原因通常是 prompt 里没有明确触发关键词。superpowers 的SKILL.md里定义了when_to_use等字段，但当前模型是否能严格遵守，还取决于上下文。

我的做法是，在提问时直接把技能名说出来，例如“使用 debugging 技能，逐步排查”。如果还不行，可以打开SKILL.md，把关键的步骤直接简短地贴进对话。这看起来有点原始，但很有效。

5.3 版本兼容问题

superpowers 更新比较频繁，而 Codex CLI 和 Trae 也在迭代。如果遇到某个技能执行报错，你可以：

• 更新 Codex CLI：npm update -g @openai/codex
• 更新 Trae：IDE 内自动更新即可。
• 更新 superpowers：进入克隆目录执行git pull。

有个小坑是，如果项目里skills是通过xcopy复制进来的，git pull不会更新技能目录，必须重新复制。用软链就没这个问题。

5.4 我的几条独家心得

我刚接触这个项目时也踩了不少坑，分享几条实用心得。

第一，不要一次性启用全部技能。superpowers 默认可能包含十几个技能，但全部开启会让 AI 在决策时产生干扰，尤其是上下文窗口有限的情况下。你可以只保留最常用的几个，比如debugging、planning、code-review，其他先注释掉，这样 AI 更不会选错技能。

第二，自己写技能也不难。如果你想让 AI 做某件特定的事，比如“按公司规范生成 commit message”，完全可以模仿 superpowers 的格式写一个SKILL.md。格式很简单，包含name、description、steps三部分就够了。我把这个思路用在团队里，统一了不少流程。

第三，在 Codex CLI 里不要用 sudo 跑npm install。这个跟 superpowers 无关，但太常遇到。权限问题会导致后期升级 Codex 时出现各种奇怪的模块缺失报错。建议用 nvm 管理 Node.js 版本，然后把全局 bin 目录放进当前用户的 PATH。

第四，Trae 上的可观测性差一些。你在终端里可以用codex --debug查看 AI 到底读入了哪些文件，从而定位AGENTS.md是否被正常加载。Trae 没有这么直接的调试输出，所以我通常先在 Codex CLI 里做完验证，再切到 Trae 里做日常使用。

对我来说，superpowers 最有意思的地方倒不是那几个现成的技能，而是它打开了一条思路：我们可以把任何“老师傅的经验”结构化喂给 AI，让它从“随机应变”变成“按套路出牌”。如果你真的想把它用好，我建议你动手改一版属于自己的技能库，把你最常做的事情拆成步骤，写成一个SKILL.md。这会比直接套用别人的技能更有价值。我后来就是自己加了一个“每日提交前检查”的技能，让 AI 每次提交前自动帮我检查敏感信息、依赖漏洞和未提交的临时文件，实测下来省了不少事。superpowers 只是起点，真正的超能力，其实是你自己积累的那些经验。