最近给我常用的 Codex CLI 折腾了一套叫 superpowers 的技能包，装上之后最直观的感受是：这个命令行助手终于不只是“会接话的代码补全”，而是开始像一位有经验的工程师一样，在下笔之前先跟你确认需求，动代码之前先拆任务，改完代码还会主动要求做一轮全面审查。之前很多要翻来覆去用 prompt 去“教”它的流程，现在变成了默认动作。如果你也在用 codex cli 这类 AI 编程工具，或者正在研究怎么让 AI 更好地融入真实项目，这篇文章能帮你省下不少自己摸索的时间。我会把 superpowers 是什么、核心技能怎么拆解、完整安装配置流程，以及我实际使用中踩过的坑，一次性讲清楚。
1. superpowers 到底是什么：不是魔法，是一套可复用的技能框架
先给没接触过的朋友定个位。superpowers 是 GitHub 上一个开源项目，本质是一套“Agent Skills”集合，专门给 Codex CLI 这类支持技能机制的 AI 编程工具准备的。它里面封装了多种工程实践能力，比如代码审查、清理烂代码、写测试、研究代码库、逐步调试、任务拆解等。把这些能力以“技能”的形式安装到本地之后，AI 助手会在合适的时机自动调用，展示出比默认行为更有章法的工程素养。
1.1 从 Codex CLI 的 skills 机制说起
Codex CLI 是 OpenAI 推出的命令行编程助手，核心使用方式和很多 AI 编程工具一样：你在终端里描述任务，它读代码、改代码、执行命令、给出结果。但默认状态下，它的行为比较“裸”——你问什么它答什么，你让改什么它才改什么，没有太多主动的工程化意识。
后来这类工具普遍开始支持“技能（skills）”机制。所谓技能，其实就是一个目录加一份 Markdown 文件，目录里可以放参考资料和子文件，Markdown 文件里用 frontmatter 写明技能的名称、描述，正文部分详细规定 AI 在调用这个技能时应该遵循什么步骤、什么输出格式、什么注意事项。Codex CLI 会扫描本地的 skills 目录，在任务上下文中注册这些技能。等到真实任务来了，模型根据技能描述判断“这个任务该用哪个技能”，然后按照技能文档里定义的流程去执行。
说人话就是：技能相当于给 AI 写好的“操作手册”和“岗位说明书”。没手册的时候，AI 凭感觉做事；有手册了，它按流程做事。superpowers 的价值就在于，它把资深工程师多年积累的工作方法，整理成了一套统一、可落地的技能文档，而不是零散的几条 prompt。
1.2 superpowers 技能包解决了什么问题
我自己用下来，最大的痛点在于：AI 编程助手很强，但“不靠谱”。它可以三分钟写一个功能模块，也可以三分钟把模块改成灾难现场。问题是它自己意识不到。你让它写测试它会写，但写完你可能发现测试根本没覆盖核心分支；你让它重构代码它会重构，但重构完接口变了，调用方全炸了。你当然可以在 prompt 里事无巨细地约束，但每次都要重复交代，累，而且容易漏。
superpowers 解决的正是“流程缺位”的问题。它把任务拆解成固定套路，AI 一上来先读技能说明，然后按步骤执行：先分析现状，再列计划，再动手，最后自检。这套流程更像一个靠谱同事的工作习惯，而不是一个“有问必答的工具”。装上之后你会发现，AI 在动手前会先跟你确认边界，遇到不明确的点会主动提问，写完代码会自己尝试审查一遍。这些行为不是模型变聪明了，而是被技能文档“教”出来了。
另外还有一个很实际的价值：它把技能做成了模块化。你不用把几十条 prompt 塞在配置文件里，有些技能用不上可以直接删，有些场景觉得不够可以自己补。整个技能库是开放结构，适合团队内部沉淀复用。这一点我后面会展开讲。
2. 核心技能拆解：这份“超能力清单”里都有什么
打开 superpowers 的技能目录，你会看到十几个子目录，每个子目录都对应一个独立的技能。不同版本会有增删，我挑几个我实际用过、并且觉得最有代表性的展开说。
2.1 元技能：让 AI 在动手前先想清楚
superpowers 的根目录里有一个 SKILL.md，这是一个比较特殊的“元技能”。它的作用不是说“你能写测试”，而是规定 AI 在接到任务时，先遍历一遍整个技能库，理解有哪些能力可以调用，再判断当前任务应该启用哪些技能。你可以把它理解成“总控调度”：先看家底，再定方案。
这个设计很聪明。因为模型本身并不知道自己的“技能清单”到底是什么，它只能感知到 prompt 上下文里被塞进去的描述信息。如果每个技能是零散的，它可能漏掉最合适的那个。元技能的存在，相当于强制 AI 在每次任务开始前做一次“技能匹配”，提高正确技能被调用的概率。我实际用下来，这个机制对“AI 主动使用技能”的影响非常明显。
2.2 常用技能逐个看：clean-code、code-review、testing 等
我把比较核心的几个技能整理成了表格，方便对照。
| 技能名称 | 核心作用 | 典型使用场景 |
|---|---|---|
| clean-code | 清理代码坏味道：命名不清、重复代码、过长函数等 | 写新功能之前先看旧代码，或重构一个文件 |
| comprehensive-code-review | 按架构、性能、可读性、边界条件等维度做全面代码审查 | 写完一个功能模块后做自查，或审查队友代码 |
| comprehensive-testing | 设计并补充单元测试、集成测试，关注边界和异常分支 | 新模块没有测试覆盖，或修复 bug 后补回归测试 |
| researching-codebase | 系统性地搜索、阅读、理解项目代码结构 | 接手旧项目，或者让 AI 找出某个功能实现位置 |
| debugging | 按“复现问题 - 定位根因 - 修复 - 验证”的流程排查 bug | 日志报错，但不确定根因在哪里 |
| explaining-projects | 用通俗语言解释项目整体结构和工作原理 | 新人入职、外部协作者快速了解项目 |
这里我说一下我对 clean-code 这个技能的理解。很多开发者觉得代码写得乱没关系，反正机器能跑。但 AI 改代码时，如果库里全是命名混乱、逻辑纠缠、一坨上千行的函数，它的判断能力会大打折扣。clean-code 技能的作用不是做一次性的格式化，而是让 AI 在动手改某段代码之前，先把附近的结构问题识别出来，避免“在烂地基上盖楼”。
comprehensive-code-review 也很有用。默认情况下，你让 AI “review 一下代码”，它往往只给几条泛泛的评论，比如“建议增加错误处理”“建议提取公共函数”之类。而有了 review 技能之后，它会按固定维度列表逐项检查：架构上有没有问题，性能和并发有没有隐患，边界条件和异常路径有没有覆盖，命名和可读性是否达标，测试是否足够，安全上有无明显漏洞。这样产出的审查意见，才真正是可以直接拿去改代码的东西。
2.3 技能之间怎么配合
还有一个值得说的点：这些技能不是独立的招式，而是一套组合拳。比如，你接到一个“修复搜索接口超时”的任务。按照 superpowers 的套路，AI 可能会先调用 researching-codebase 找到搜索接口的实现位置和调用链，再调用 debugging 技能定位超时的核心原因，修复之后触发 comprehensive-testing 要求补充一个回归测试，最后还会用 comprehensive-code-review 做一遍整体检查。整个过程一气呵成，中间状态是连贯的。
这种配合带来的体验提升是巨大的。以前我要分多次对话才能让 AI 走完整条流程，现在一次任务，它自己就知道什么时候该切换技能。其实就是把“工程师的施工方法”前置成了 AI 的运行规则。
3. 安装与配置实操：给 codex cli 装上 superpowers
下面进入实操环节。如果你的环境是 Codex CLI，安装时间基本在十分钟以内。如果你用的是 Trae 这类支持技能体系的 AI IDE，思路也差不多，就是把技能目录放到 IDE 能扫描到的地方。
3.1 环境准备
安装之前确认三件事。
第一，Codex CLI 已经装好并且能正常使用。如果你还没装，可以先通过 npm 或 Homebrew 安装，完成登录和授权。这一步的前提是 Node.js 环境正常，建议 Node.js 18 以上。
第二，本机有 Git，并且能从 GitHub 拉取仓库。代码就放在 GitHub 上，这是最基本的依赖。
第三，知道 Codex CLI 的技能目录位置。对 mac 和 Linux 用户来说，默认是~/.codex/skills；Windows 用户的路径一般在用户目录下的.codex\skills。如果你改过配置，可以在 Codex 的配置文件里搜 “skill” 关键词确认目录位置。
我在项目里看到的最常见装机错误，就是把技能仓库 clone 到了错误路径，导致 Codex 扫不到。所以别急着执行命令，先确认目录。
3.2 方式一：用安装脚本一键完成
superpowers 官方推荐的方式是用安装脚本，我印象里大致是这个命令：
curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash这个脚本会帮你把仓库克隆到 Codex CLI 的技能目录，同时做一些基础环境检查。如果你是第一次安装，建议先看一眼脚本内容再执行，看看它到底要往你机器里写什么：
curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | less脚本本身通常不复杂，就是创建目录、git clone、失败时给提示。如果网络不通或者 raw.githubusercontent.com 访问失败，脚本会中断，这时候可以退回手动安装。
3.3 方式二：手动克隆到技能目录
我更推荐新手用手动克隆，因为路径掌握在自己手里，出了问题也好排查。假设技能目录是~/.codex/skills，就先创建目录再克隆：
mkdir -p ~/.codex/skills git clone https://github.com/obra/superpowers.git ~/.codex/skills这里有一种情况值得说明：有些版本会建议把仓库克隆到~/.codex/skills/superpowers这种带一层子目录的位置，而不是直接作为 skills 目录本身。经验告诉我，Codex 扫描技能时，会把 skills 目录下的每个子目录当做一个独立技能来识别，每个子目录里必须有一个SKILL.md。所以装完之后，建议检查一下目录结构是不是长这样：
~/.codex/skills/ ├── SKILL.md ├── skills/ │ ├── clean-code/ │ │ ├── SKILL.md │ │ └── ... │ ├── comprehensive-code-review/ │ │ ├── SKILL.md │ │ └── ... │ └── ...注意，你看到~/.codex/skills/SKILL.md是元技能入口，skills/子目录里才是各个具体技能。如果 clone 之后发现多了一层嵌套，比如~/.codex/skills/superpowers/skills/...，Codex 可能只会把最外层当做一个技能，导致内部技能全部失效。解决办法也很简单：把仓库里的内容整体移到~/.codex/skills根目录下，或者把 clone 路径改成目标位置的上一级，再移动目录。
3.4 在 Trae 等 AI IDE 里接入技能
热词里有人提到“trae work cn 安装 superpowers skill”，这里单独说一下。Trae 是字节跳动推出的 AI IDE，国内版叫 Trae CN。它和 Codex CLI 不是同一个产品，但同样在往 Agent Skills 的方向兼容。如果你用的是 Trae，想装 superpowers，核心思路是找到 Trae 的技能目录，再把 superpowers 的内容放进去。
不同版本的 Trae 设置入口会有差异。我试过的办法是：在 Trae 的设置面板里搜索 “skill” 或 “技能”，看看它把用户级技能目录放在哪里。有些版本会默认读取用户目录下的某个工作区目录，比如~/.trae/skills；有些版本则需要你在项目配置文件里显式指定。这个路径很容易因为版本更新而变化，别硬记，最好的方式是先在 IDE 里查设置。
找到目标目录后，其他操作和 Codex CLI 一样：
git clone https://github.com/obra/superpowers.git <你的Trae技能目录>装完重启 IDE，让技能索引重新加载。如果在配置面板里能看到已加载的技能列表，就说明成功了。
3.5 验证安装是否成功
安装完成不表示万事大吉，我建议做一次快速验证。直接在 Codex CLI 里提问：
你有哪些可用的技能？请尽量把技能名称和高频用途列出来。如果它能把 clean-code、comprehensive-code-review、comprehensive-testing 这些技能名说出来，说明技能注册成功了。如果它说“我没有技能”，多半是目录路径没对上，或者 SKILL.md 的结构有问题。
另一种验证方式是看调试日志。Codex CLI 在 verbose 模式下会输出它加载了哪些上下文文件，如果日志里能看到技能文档被加载，那基本就稳了。不同版本命令参数不同，可以在帮助信息里查 verbose 或 debug 参数。
提示：验证技能是否被“加载”是一回事，验证技能是否被“调用”是另一回事。前者只代表 AI 知道技能存在，后者需要实际任务触发。我通常用一个简单测试任务，比如让它写一个带边界检查的函数，看它是否主动触发 comprehensive-testing 流程。
4. 实战使用经验与配置调优
装好只是第一步，真正让 superpowers 发挥价值，关键在于你怎么用、怎么配合团队。我总结了一些实战经验，也算不上标准答案，但至少能帮你少走弯路。
4.1 推荐的工作流：需求进来先定套路
我现在的使用习惯是：拿到一个新需求，不会直接甩给 AI 让它“实现一下”。我会先简单说一下业务背景和目标，让它用 planning 或者 scoping 类技能拆解任务。拆解完之后，我再跟它对齐计划，确认没问题，才让它进入编码阶段。编码结束之后，我会主动触发 comprehensive-code-review，必要的时候让它补 comprehensive-testing。
这个过程看起来多花了轮次，实际上总耗时反而更短。因为 AI 不再“闷头写一个和你预期不一致的东西”，而是先把边界问题暴露出来。有一次我让 AI 做一个数据导入功能，它先问我“导入文件的格式是固定的吗？重复数据要不要去重？失败时是整批回滚还是逐条跳过？”这三个问题问完，我就知道后面的实现方向基本不会跑偏。
这类提问不是免费的，它可能多消耗一些 token，但比起“写错重来”的成本，这点消耗非常划算。我的经验是：注重结果的工程任务，宁可前期多聊两句，也不要后期返工。
4.2 自定义技能：把团队规范也做成 skill
superpowers 本身是个不错的模板，但它毕竟是一个通用项目。你团队的代码规范、提交格式、接口设计约定，它不可能都覆盖。好在技能机制天生支持自定义。你完全可以照抄它的技能目录结构，写一个属于自己团队的 skill。
我做过的一个例子是把“后端接口开发规范”做成了技能。里面包含了：接口路径命名规则、请求参数校验要求、错误码设计约定、返回结构模板、必须补充的测试用例类型。然后在 SKILL.md 的描述里写清楚“在处理控制器、服务层、接口相关任务时优先使用”。这样团队里不管谁用 AI 写接口，写出来的风格都高度统一。
自定义技能的注意事项主要有三个。
第一，目录结构要对。每个技能目录下必须有 SKILL.md，这是硬性要求。第二，frontmatter 的 description 要写清楚使用场景。模型决定要不要用某个技能，很大程度上就是看这段描述。写得太泛，它就不容易被触发；写得太窄，又可能错过使用机会。第三，参考资料可以放在技能目录的子文件里，正文里用相对路径引用。这样避免把大段文档直接塞进技能主文件，毕竟每多一段引用文本，都会增加一次任务上下文消耗。
4.3 当技能不够用时的兜底方案
superpowers 不是万能的。我在实际使用中就遇到过几次“它选错了技能”的情况。最典型的一次是：我让它研究一个模块的实现，它却触发了 comprehensive-code-review 流程，直接开始挑代码毛病，而不是回答我的“这个模块怎么工作”的问题。原因可能是技能描述里有“深入了解项目代码”之类的字眼，模型把它和“审查代码”混在了一起。
碰到这种情况，最简单的兜底方案是显式指定技能。在 prompt 里直接写“不要使用 code review 技能，尽量定位模块的调用链并解释实现流程”。这相当于手动切断了模型的自动技能匹配逻辑。要记住，技能只是工具，优先级永远低于用户的显式指令。
另外，技能之间偶尔也会“打架”。比如 clean-code 技能要求它重构代码，而 comprehensive-testing 技能要求它先补充测试覆盖。如果 AI 在一次任务里同时触发了这两个技能，可能会出现“先重构，后补测试，导致测试覆盖的是旧逻辑”的尴尬。这类问题没有完美的自动解法，只能靠人盯流程。我的建议是：并不是所有任务都需要所有技能，该关闭的关闭，该临时禁用的就禁用。
5. 踩坑记录与常见问题排查
这部分是纯经验分享了。我把装 superpowers 之后遇到的高频问题整理成速查表，不一定每条都发生在你身上，但可以在出问题时先对照看一下。
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| AI 根本不知道 superpowers 技能存在 | 技能目录路径不对，或 clone 层级错误 | 检查~/.codex/skills和 SKILL.md 位置 |
| 安装脚本执行失败 | 网络无法访问 raw.githubusercontent.com | 改成手动 git clone |
| 技能偶尔没有生效 | 技能描述不精确，模型没有触发自动匹配 | 在 prompt 中显式指定使用某个技能 |
| token 消耗明显上涨 | 技能文档被完整塞进上下文，特别是 reference 文件很多 | 精简技能主文件，参考资料按需读取 |
| 自定义技能始终不触发 | description 写得像功能描述，不像“什么时候该用” | 重写描述，强调适用场景和触发条件 |
5.1 技能没有被自动加载
这是安装类问题的第一名。大多数时候不是 superpowers 坏了，而是目录层级不对。Codex 对技能目录的扫描方式比较“死板”：它只认 skills 目录下的直接子目录，然后要求子目录里存在 SKILL.md。如果你 clone 的时候没有拆掉多余的层级，比如变成了skills/superpowers/skills/clean-code/SKILL.md，那它很有可能只识别到superpowers这个技能，或者干脆一个都识别不到。
遇到这种情况，最快的排查方式是在终端手动查看目录树。用tree命令或者find命令确认每个技能的 SKILL.md 都在“skills 目录的下一级”里。如果层级不对，直接把 superpowers 仓库里的内容移动到技能目录的根下即可。
5.2 安装脚本执行失败
虽然一键脚本很方便，但它的前提是你本机能正常访问 GitHub 和 raw.githubusercontent.com。如果环境访问不通，脚本就会卡住。这时候别硬试，改用 git clone 方式安装。如果 git clone 也慢，可以通过设置 git 代理或使用镜像仓库解决，但这部分属于网络问题，不是 superpowers 本身的问题，我就不展开了。
还有一类少见的情况是环境变量问题。比如 HOME 路径没有正确设置，导致脚本把技能目录写到奇怪的地方。这种情况建议先执行echo $HOME确认家目录路径，再确认 Codex 的配置文件指向的技能目录确实在你预期的位置上。
5.3 Token 消耗变大了
装上 superpowers 之后，token 消耗确实会比原来高。原因是技能文档本身就是一段上下文：每个技能都会把 SKILL.md 的内容带进来，元技能可能还会引用整份技能清单。如果你的任务同时触发多个技能，上下文消耗会明显增加。
这不算 bug，但可以优化。最简单粗暴的办法是删掉你不常用的技能目录，只保留核心的几种。我的做法是保留 clean-code、comprehensive-code-review、comprehensive-testing、debugging 这几个，其他的按需补回去。另一个技巧是给技能文档“瘦身”：把大段参考代码移到 reference 目录中，在 SKILL.md 里只用一两句话说清楚“详细示例见 reference/xxx.md”，让模型在需要时才去读取，而不是把内容全部预加载。
5.4 与团队协作时的注意事项
如果你们团队多人共享同一个技能包，我建议把技能目录纳入代码仓库管理。这样每个人 clone 项目后，能通过一个同步脚本快速安装统一版本的技能，避免因为各自改了技能文件导致行为不一致。你可以建一个scripts/install-skills.sh，里面写好 clone 和目录同步逻辑，大家一起用。技能描述也要有人维护，业务逻辑变了，技能里的规范文档也得跟着更新。
最后提醒一句：superpowers 再怎么强大，也只是给 AI 立规矩的工具。真正关心项目质量的人，还是得盯最后一关。AI 写的代码，我会当成“实习生写的代码”来看：先让它按流程走，但最终的架构决策、安全设计、关键逻辑，我会自己再过一遍。把技能当帮手，别把它当信仰，这才是它发挥价值的正确姿势。
