Superpowers 这个名字第一次听到的人十有八九会以为是某个游戏模组或者动漫梗但只要你在 GitHub 上搜过 Codex、Trae 这类 AI 编程助手的扩展配置就会知道它其实是最近在 AI 编程圈里被反复提及的一套技能配置方案。简单说Superpowers 就是一个专门为 Codex CLI 等 AI 编程工具打造的「技能包」集合它通过注入系统级的指令、工作流模板和角色设定让 AI 助手在处理实际编码任务时不再是“问一句答一句”的状态而是真的像一位资深工程师一样知道什么时候该写测试、什么时候该拆重构、什么时候该停下来和你确认需求。我自己是在做一个跨模块重构的时候接触到它的。当时用原生的 Codex CLI 跑了几轮发现它在单点问答上表现不错但一旦碰到需要跨文件追踪、分阶段实施、还要随时回滚的长任务就很容易“跑偏”要么过度修改要么该做的验证步骤直接跳过。后来照着 Superpowers 的安装说明配置了一遍实测下来最大的感受是它不是在给你加功能而是在给 AI 助手“立规矩”。这篇文章我就从设计思路、目录结构、安装步骤到排坑经验完整拆一遍 Superpowers 这个项目希望能帮你少走点弯路。1. 内容整体设计与思路拆解1.1 Superpowers 到底解决的是什么问题先说一个背景。Codex CLI 这一类工具本质上是在终端里给你配了一个能读写文件、执行命令的 AI agent。它的底层模型确实很强但“能力强”和“干活靠谱”之间还隔着一层很厚的东西——工作流。就好比你招了一个名校毕业的程序员代码水平不差但你如果不在入职第一天给他讲清楚团队的规范、项目的架构、测试的要求、提 PR 的流程他照样能把事情干得乱七八糟。原生的 Codex CLI 就有点这种感觉模型知道怎么写代码但不知道在你的项目里“应该怎么干活”。Superpowers 干的其实就是“入职培训”这件事。它通过一套精心设计的 markdown 指令文件把项目开发中会用到的各种工作流——比如 TDD 节奏、重构步骤、代码审查清单、bug 排查路径——编写成 AI 能读取并遵循的规范。这些规范不是泛泛而谈的“请写出高质量代码”而是带具体步骤、判断条件、输出要求的操作手册。比如告诉 AI在修改代码之前必须先写一个失败的测试然后运行它确认失败再写实现代码让它通过最后做重构。每一步都有明确的验证节点AI 就不会跳过测试直接开写。这套设计思路其实很聪明。它没有去改模型本身也没有引入什么重型插件框架而是利用了 Codex CLI 对 AGENTS.md、SKILL.md 这类指令文件的原生支持用纯文本的方式把“经验”灌进 AI 的上下文里。这带来的直接好处是你不需要等待官方更新功能也不用担心工具版本升级后插件失效只要 markdown 语法没大变这套配置就能一直用。而且你完全可以自己改里面的内容把团队规范、个人偏好加进去自由度非常高。1.2 为什么选择 skills 这种组织方式我第一次打开 Superpowers 的仓库时第一反应是“东西真多”。目录里不是一个两个文件而是按功能拆成了十几个甚至几十个 skill每个都对应一类具体的开发任务。这种组织方式绝不是为了好看而是有实际用处的。要知道AI 的上下文窗口是有限的。如果你把所有开发规范都塞进一个巨大的指令文件里模型还没开始干活光读规范就可能占掉大几千 token而且容易“稀释”关键指令的权重。skills 这种按需加载的模式相当于把一本书拆成了十几个章节AI 在干重构这件事的时候只需要读“重构”那一章而不是把整本书从头到尾背下来。这样既省了 token又保证了指令的针对性。另外我自己的体会是skills 的文件命名和描述写得越清晰AI 的“调用意图识别”就越准。Superpowers 里每个 skill 文件开头都有明确的用途说明、适用场景和触发条件Codex 类的工具在决定要不要读取某个 skill 时就是靠这些前置信息来判断的。这其实给了使用者一个很好的启发如果你自己写 skilldescription 部分一定要花心思别随便瞎写直接影响命中率。2. 核心细节解析与实操要点2.1 配置目录与文件结构要理解 Superpowers 的运作机制首先得知道 Codex CLI 的配置目录是怎么组织的。以我用的版本为例Codex CLI 会在用户目录下创建一个.codex的隐藏文件夹里面存放各种配置项和指令文件。Superpowers 的安装过程本质上就是把仓库里的 skills 目录克隆或复制到 Codex 能扫描到的位置然后通过配置文件把它们启用来。具体结构上我建议你安装完以后花点时间用tree命令看一眼整个目录的分布。一般会有一个skills根目录下面按功能分子目录比如重构、测试、调试、代码审查等等。每个子目录里都有一个主文件通常是SKILL.md可能还附带几个辅助说明文件。这些 markdown 文件里写的不是给人看的标准文档而是给模型看的操作指令。这里有一个很容易踩的坑很多人以为把文件放到目录里就完事了结果发现 AI 完全不按 skill 指令走。我排查过几次这个问题最后基本都指向同一个原因——文件路径没对。Codex CLI 对 skill 文件的扫描是严格限定在配置目录或项目.codex目录下的你放到别的乱七八糟的位置它根本不会加载。所以安装前最好先搞清楚自己的 Codex CLI 版本到底读哪个目录别想当然。2.2 关键配置项解读Superpowers 用起来能不能达到预期效果很大程度上取决于几个关键配置项是否设置对了。我不是让你把整个配置文件从头到尾背下来但有几个点确实值得注意。第一个是SKILL.md文件里的name和description字段。这两个字段决定了 AI 在什么情况下会想起用这个 skill。如果 description 写得太窄AI 可能该触发时不触发写得太宽又容易在不合适的场景下乱用。Superpowers 默认的写法我看了下基本都比较精准保持原样就行。但如果你自己加 skill这一块一定要好好打磨。第二个是每个 skill 内的指令格式。Superpowers 的指令普遍写得非常“碎”不是那种长篇大论的段落而是小标题、有序步骤、检查清单的组合。一开始我不太习惯觉得这也太琐碎了。但实测下来发现这种格式恰恰是 AI 最容易遵循的。模型在处理结构化指令时完成率远高于处理一大段散文。所以你在自定义 skill 的时候尽量模仿这种风格步骤拆得越细越好。第三个是版本匹配问题。Superpowers 项目本身更新频率不算慢而 Codex CLI 也在不断迭代。我有一次升级了 Codex CLI 之后发现某些 skills 的加载行为变了后来查看仓库的 release notes才发现是格式要求有调整。所以如果你用的是比较新的 CLI 版本最好也同步更新一下 Superpowers 仓库别一个版本用到天荒地老。2.3 需要注意的操作禁忌与保障细节说实话Superpowers 这类工具最大的“风险”不是安装出错而是用了之后你误以为 AI 真的靠谱了。配置完这套 skillAI 在长任务上的表现确实会好不少但它仍然可能犯错尤其是涉及到项目特有的业务逻辑时。所以我自己的原则是让 AI 干活但绝不让它替你思考。操作上有一个具体的建议在交给 AI 跑一个多步骤任务之前先手动备份当前分支或者创建一个单独的 worktree。因为 Superpowers 里的很多 skill 会指导 AI 做多轮修改虽然它也会做验证但在大型项目中难免出现意外覆盖。我吃过一次亏让 AI 接手一个跨模块重构结果它把一个共用工具函数签名改了导致另一处代码直接报错。幸好提前建了分支一条git checkout就回来了。所以别嫌麻烦备份永远是第一位的。还有一个细节是关于上下文长度的。Superpowers 的 skill 文件叠加起来内容量不小如果在一次会话里让 AI 同时处理多个复杂任务很容易在后期出现“上下文溢出”表现就是 AI 开始忽略之前给过的指令回答质量断崖式下降。遇到这种情况不要硬撑及时清理会话历史或拆分成多个小任务反而效率更高。3. 实操过程与核心环节实现3.1 安装 Superpowers 的完整流程下面直接进入正题说说我是怎么把 Superpowers 装到 Codex CLI 里的。整个过程不算复杂前前后后也就几分钟的事但里面有几个坑我会标注出来。第一步先把仓库克隆到本地。你可以选择任何一个你觉得顺手的目录我自己的习惯是放在一个专门放工具配置的文件夹里比如~/workspace/tools这类位置。命令很简单git clone https://github.com/your-repo/superpowers.git注意一下我这边是假设你已经能正常访问 GitHub 的前提下写的。如果拉取速度很慢可以试试用一些国内的镜像加速方案不过这个看你自己的网络情况我就不展开说了。第二步进入克隆下来的目录看看整个项目的结构。这一步很关键不要跳过。因为你需要确认自己下载的版本里 skills 文件放在哪个子目录。不同版本的 Superpowers 可能组织方式略有差异有的是直接在根目录下有的是在skills文件夹下。我用的版本是标准的skills目录结构所以后续命令都基于这个。cd superpowers ls -la第三步将 skills 目录复制或链接到 Codex CLI 的配置目录。这里我强烈建议使用符号链接而不是直接复制。原因是你以后更新 Superpowers 仓库时只需要git pull所有配置就自动同步了不用再手动复制一遍。如果你直接复制每次更新都要重复操作容易遗漏。ln -s $(pwd)/skills ~/.codex/skills第四步验证配置是否生效。我自己的习惯是随便找一个项目目录然后在 Codex CLI 里问 AI 一句“你能用哪些 skills”看它能不能正确列出。当然更直接的方法是让它执行一个依赖某个 skill 的小任务比如让它模拟一个 TDD 流程。实测下来如果配置正确AI 的回复中通常会引用对应的 skill 名称。3.2 与 Trae 集成的操作记录除了 Codex CLI我看到很多人在问 Trae 里怎么用 Superpowers。Trae 是一款 AI IDE国内用户不少它的插件机制和 Codex CLI 略有不同但思路类似。我自己的使用经验是Trae 支持自定义 skills 目录你只需要在项目的配置里指定 Superpowers 的位置就行。具体来说在 Trae 的配置面板中找到 skills 或 agents 相关的设置项然后添加一个新技能目录指向你克隆下来的superpowers/skills目录即可。添加完之后建议重启一下 Trae 或者刷新会话让配置重新加载。有一个小细节Trae 对技能描述的处理跟 Codex 不完全一样你可以先不做修改直接用。但在使用中如果你发现某些技能一直没被触发可以去检查一下技能的 description 片段看看是不是跟 Trae 的匹配规则不兼容。我遇到过一次类似情况原因是某个技能描述里用了太多的“代码块”标记Trae 解析的时候把它截断了导致后面部分没被读到。删掉代码块重新描述一遍就好了。3.3 自定义 skill 的实际案例演示Superpowers 的价值除了开箱即用还在于你可以往里面加自己的东西。我自己就写过几个自定义 skill效果都还不错。这里我拿其中一个“数据库迁移审查”的 skill 作为例子给你看看它的基本结构。先创建一个新目录比如~/.codex/skills/db-migration-review/然后在里面新建一个SKILL.md文件。文件开头写上基本的元信息和描述让 AI 知道这个技能是干什么的--- name: db-migration-review description: Review database migration files for correctness, consistency, and rollback safety. --- # Database Migration Review 当收到数据库迁移文件审查任务时按以下步骤执行 1. 检查迁移文件的版本号和时间戳是否合理递增。 2. 核对 up() 与 down() 方法的操作是否对称。 3. 查找迁移中出现的数据转换逻辑确认是否有数据丢失风险。 4. 检查是否对大数据量的表执行了危险的 DDL 操作如有则标记出来。 5. 输出审查报告按「致命问题」「建议修改」「可忽略」三档分类。写完保存之后你还需要在 Codex 的配置里注册一下这个新的技能目录或者直接把整个自定义目录放在已有的 skills 根目录下让 AI 自动扫描进去。实测下来这种自定义技能用起来非常顺手特别是对团队内部有特殊规范约束的场景效果远比在对话里反复叮嘱要稳定。4. 常见问题与排查技巧实录4.1 安装后完全不生效怎么办这是最常见的问题也是我收到留言里被问得最多的一类“我明明按照教程装好了为什么 AI 还是不按套路出牌”遇到这种情况先不要慌按照下面的顺序排查。第一确认技能目录是否被正确扫描。不同版本的 Codex CLI 对技能目录的默认路径可能不同有的版本用的是~/.codex/skills有的版本可能要看项目根目录下的.codex/skills。你可以直接用文件管理器看一下目录是否存在、文件是否完整。如果目录不存在多半是启动时没自动创建手动建一个再放文件进去就行。第二确认配置文件里的开关是否打开。有些版本会默认关闭自定义技能加载需要你手动在配置里设置为开启。具体字段名因版本而异你可以在配置文件里搜索skill关键字看看有没有enabled: false之类的字样。第三也是最容易被忽略的会话上下文中是否真的包含了 skill 的内容。即使文件位置正确、开关打开如果当前会话是在安装之前就启动的AI 可能还没有重新加载这些指令。这种情况下退出当前会话重新打开一个新的对话问题基本都能解决。4.2 技能按需加载不灵、AI 答非所问另一个高频问题是某些技能没有被正确触发导致 AI 回答问题时完全没体现出“大师级”的思考路径。我遇到过最典型的场景是明明配置了代码审查类的 skill但让它审查代码时它给出的回答依然很笼统没有按 skill 中要求的格式输出。这种情况我总结下来大概率是技能描述与当前任务的匹配度问题。Codex 这类工具在决定是否加载某个技能时依赖的是技能描述与用户请求之间的语义匹配度。如果你的描述写得过于具体比如“这个技能适用于审查 Python 项目中包含异步逻辑的数据库迁移文件”那 AI 很可能无法把它泛化到普通场景。解决办法有两个一是适当放宽技能描述让它能覆盖更多相关场景二是在任务的提示词里主动点名技能名称比如加上“请使用 db-migration-review 技能来完成审查”这样的话引导 AI 去加载。第一种方法治本第二种方法适合偶尔应急。4.3 Superpowers 的独家避坑技巧最后分享几个我实际用下来非常受用的细节这些在官方文档里基本看不到纯属自己踩坑踩出来的经验。一个是你可以在自己的项目根目录放一个项目级的AGENTS.md文件里面描述这个项目特有的架构、技术栈、编码规范以及“哪些代码不要动”。Superpowers 里的一些通用技能会与这个文件协同工作AI 在执行任务时能同时参考项目级规范和通用工作流效果非常惊艳。我目前的配置是项目级文件管“这个项目怎么做事”Superpowers 管“这类任务怎么做好”各司其职。另一个是用好git diff的复盘习惯。每让 AI 完成一轮修改我都会用git diff仔细看一遍改动不是为了事后找茬而是为了积累“AI 什么时候会自作主张”的直觉。用久了你会发现某些技能在特定条件下特别容易触发 AI 对代码的额外“优化”而这种优化不一定是你想要的。这时候就需要在 skill 文件里加上一句“不要修改未明确指出的代码”效果立竿见影。5. 项目影响与后续扩展思路Superpowers 这个项目让我觉得有意思的地方不仅仅在于它提升了 AI 编程工具的表现更在于它代表了一种趋势AI 应用正在从“拼模型”转向“拼工程”。在模型能力已经很强的前提下如何通过提示词工程、工作流拆解、上下文管理来榨干模型的价值成了新的竞争焦点。从实际影响来看Superpowers 把原本只在提示词高手之间口耳相传的经验变成了一个可分发、可复制的开源项目。这意味着普通开发者不需要从零开始摸索怎么引导 AI 干活直接装一套配置就能获得接近资深玩家的体验。这种“经验开源”的效应会显著拉低 AI 编程的上手门槛。我个人后续的计划是fork一份Superpowers然后在里面加入更多团队开发场景的技能比如代码走查会议的准备、跨模块接口设计的评审清单等。如果你也在深度使用这类工具我建议你也动手改一改哪怕只是微调一个技能的描述配合自己团队的习惯也比纯用默认配置顺手得多。这本来就是这类项目的最大价值——它给了你一套很好的起点但最终的玩法完全取决于你怎么去改它。 Superpowers全解析：给Codex CLI配置AI编程工作流技能包
Superpowers 这个名字第一次听到的人十有八九会以为是某个游戏模组或者动漫梗但只要你在 GitHub 上搜过 Codex、Trae 这类 AI 编程助手的扩展配置就会知道它其实是最近在 AI 编程圈里被反复提及的一套技能配置方案。简单说Superpowers 就是一个专门为 Codex CLI 等 AI 编程工具打造的「技能包」集合它通过注入系统级的指令、工作流模板和角色设定让 AI 助手在处理实际编码任务时不再是“问一句答一句”的状态而是真的像一位资深工程师一样知道什么时候该写测试、什么时候该拆重构、什么时候该停下来和你确认需求。我自己是在做一个跨模块重构的时候接触到它的。当时用原生的 Codex CLI 跑了几轮发现它在单点问答上表现不错但一旦碰到需要跨文件追踪、分阶段实施、还要随时回滚的长任务就很容易“跑偏”要么过度修改要么该做的验证步骤直接跳过。后来照着 Superpowers 的安装说明配置了一遍实测下来最大的感受是它不是在给你加功能而是在给 AI 助手“立规矩”。这篇文章我就从设计思路、目录结构、安装步骤到排坑经验完整拆一遍 Superpowers 这个项目希望能帮你少走点弯路。1. 内容整体设计与思路拆解1.1 Superpowers 到底解决的是什么问题先说一个背景。Codex CLI 这一类工具本质上是在终端里给你配了一个能读写文件、执行命令的 AI agent。它的底层模型确实很强但“能力强”和“干活靠谱”之间还隔着一层很厚的东西——工作流。就好比你招了一个名校毕业的程序员代码水平不差但你如果不在入职第一天给他讲清楚团队的规范、项目的架构、测试的要求、提 PR 的流程他照样能把事情干得乱七八糟。原生的 Codex CLI 就有点这种感觉模型知道怎么写代码但不知道在你的项目里“应该怎么干活”。Superpowers 干的其实就是“入职培训”这件事。它通过一套精心设计的 markdown 指令文件把项目开发中会用到的各种工作流——比如 TDD 节奏、重构步骤、代码审查清单、bug 排查路径——编写成 AI 能读取并遵循的规范。这些规范不是泛泛而谈的“请写出高质量代码”而是带具体步骤、判断条件、输出要求的操作手册。比如告诉 AI在修改代码之前必须先写一个失败的测试然后运行它确认失败再写实现代码让它通过最后做重构。每一步都有明确的验证节点AI 就不会跳过测试直接开写。这套设计思路其实很聪明。它没有去改模型本身也没有引入什么重型插件框架而是利用了 Codex CLI 对 AGENTS.md、SKILL.md 这类指令文件的原生支持用纯文本的方式把“经验”灌进 AI 的上下文里。这带来的直接好处是你不需要等待官方更新功能也不用担心工具版本升级后插件失效只要 markdown 语法没大变这套配置就能一直用。而且你完全可以自己改里面的内容把团队规范、个人偏好加进去自由度非常高。1.2 为什么选择 skills 这种组织方式我第一次打开 Superpowers 的仓库时第一反应是“东西真多”。目录里不是一个两个文件而是按功能拆成了十几个甚至几十个 skill每个都对应一类具体的开发任务。这种组织方式绝不是为了好看而是有实际用处的。要知道AI 的上下文窗口是有限的。如果你把所有开发规范都塞进一个巨大的指令文件里模型还没开始干活光读规范就可能占掉大几千 token而且容易“稀释”关键指令的权重。skills 这种按需加载的模式相当于把一本书拆成了十几个章节AI 在干重构这件事的时候只需要读“重构”那一章而不是把整本书从头到尾背下来。这样既省了 token又保证了指令的针对性。另外我自己的体会是skills 的文件命名和描述写得越清晰AI 的“调用意图识别”就越准。Superpowers 里每个 skill 文件开头都有明确的用途说明、适用场景和触发条件Codex 类的工具在决定要不要读取某个 skill 时就是靠这些前置信息来判断的。这其实给了使用者一个很好的启发如果你自己写 skilldescription 部分一定要花心思别随便瞎写直接影响命中率。2. 核心细节解析与实操要点2.1 配置目录与文件结构要理解 Superpowers 的运作机制首先得知道 Codex CLI 的配置目录是怎么组织的。以我用的版本为例Codex CLI 会在用户目录下创建一个.codex的隐藏文件夹里面存放各种配置项和指令文件。Superpowers 的安装过程本质上就是把仓库里的 skills 目录克隆或复制到 Codex 能扫描到的位置然后通过配置文件把它们启用来。具体结构上我建议你安装完以后花点时间用tree命令看一眼整个目录的分布。一般会有一个skills根目录下面按功能分子目录比如重构、测试、调试、代码审查等等。每个子目录里都有一个主文件通常是SKILL.md可能还附带几个辅助说明文件。这些 markdown 文件里写的不是给人看的标准文档而是给模型看的操作指令。这里有一个很容易踩的坑很多人以为把文件放到目录里就完事了结果发现 AI 完全不按 skill 指令走。我排查过几次这个问题最后基本都指向同一个原因——文件路径没对。Codex CLI 对 skill 文件的扫描是严格限定在配置目录或项目.codex目录下的你放到别的乱七八糟的位置它根本不会加载。所以安装前最好先搞清楚自己的 Codex CLI 版本到底读哪个目录别想当然。2.2 关键配置项解读Superpowers 用起来能不能达到预期效果很大程度上取决于几个关键配置项是否设置对了。我不是让你把整个配置文件从头到尾背下来但有几个点确实值得注意。第一个是SKILL.md文件里的name和description字段。这两个字段决定了 AI 在什么情况下会想起用这个 skill。如果 description 写得太窄AI 可能该触发时不触发写得太宽又容易在不合适的场景下乱用。Superpowers 默认的写法我看了下基本都比较精准保持原样就行。但如果你自己加 skill这一块一定要好好打磨。第二个是每个 skill 内的指令格式。Superpowers 的指令普遍写得非常“碎”不是那种长篇大论的段落而是小标题、有序步骤、检查清单的组合。一开始我不太习惯觉得这也太琐碎了。但实测下来发现这种格式恰恰是 AI 最容易遵循的。模型在处理结构化指令时完成率远高于处理一大段散文。所以你在自定义 skill 的时候尽量模仿这种风格步骤拆得越细越好。第三个是版本匹配问题。Superpowers 项目本身更新频率不算慢而 Codex CLI 也在不断迭代。我有一次升级了 Codex CLI 之后发现某些 skills 的加载行为变了后来查看仓库的 release notes才发现是格式要求有调整。所以如果你用的是比较新的 CLI 版本最好也同步更新一下 Superpowers 仓库别一个版本用到天荒地老。2.3 需要注意的操作禁忌与保障细节说实话Superpowers 这类工具最大的“风险”不是安装出错而是用了之后你误以为 AI 真的靠谱了。配置完这套 skillAI 在长任务上的表现确实会好不少但它仍然可能犯错尤其是涉及到项目特有的业务逻辑时。所以我自己的原则是让 AI 干活但绝不让它替你思考。操作上有一个具体的建议在交给 AI 跑一个多步骤任务之前先手动备份当前分支或者创建一个单独的 worktree。因为 Superpowers 里的很多 skill 会指导 AI 做多轮修改虽然它也会做验证但在大型项目中难免出现意外覆盖。我吃过一次亏让 AI 接手一个跨模块重构结果它把一个共用工具函数签名改了导致另一处代码直接报错。幸好提前建了分支一条git checkout就回来了。所以别嫌麻烦备份永远是第一位的。还有一个细节是关于上下文长度的。Superpowers 的 skill 文件叠加起来内容量不小如果在一次会话里让 AI 同时处理多个复杂任务很容易在后期出现“上下文溢出”表现就是 AI 开始忽略之前给过的指令回答质量断崖式下降。遇到这种情况不要硬撑及时清理会话历史或拆分成多个小任务反而效率更高。3. 实操过程与核心环节实现3.1 安装 Superpowers 的完整流程下面直接进入正题说说我是怎么把 Superpowers 装到 Codex CLI 里的。整个过程不算复杂前前后后也就几分钟的事但里面有几个坑我会标注出来。第一步先把仓库克隆到本地。你可以选择任何一个你觉得顺手的目录我自己的习惯是放在一个专门放工具配置的文件夹里比如~/workspace/tools这类位置。命令很简单git clone https://github.com/your-repo/superpowers.git注意一下我这边是假设你已经能正常访问 GitHub 的前提下写的。如果拉取速度很慢可以试试用一些国内的镜像加速方案不过这个看你自己的网络情况我就不展开说了。第二步进入克隆下来的目录看看整个项目的结构。这一步很关键不要跳过。因为你需要确认自己下载的版本里 skills 文件放在哪个子目录。不同版本的 Superpowers 可能组织方式略有差异有的是直接在根目录下有的是在skills文件夹下。我用的版本是标准的skills目录结构所以后续命令都基于这个。cd superpowers ls -la第三步将 skills 目录复制或链接到 Codex CLI 的配置目录。这里我强烈建议使用符号链接而不是直接复制。原因是你以后更新 Superpowers 仓库时只需要git pull所有配置就自动同步了不用再手动复制一遍。如果你直接复制每次更新都要重复操作容易遗漏。ln -s $(pwd)/skills ~/.codex/skills第四步验证配置是否生效。我自己的习惯是随便找一个项目目录然后在 Codex CLI 里问 AI 一句“你能用哪些 skills”看它能不能正确列出。当然更直接的方法是让它执行一个依赖某个 skill 的小任务比如让它模拟一个 TDD 流程。实测下来如果配置正确AI 的回复中通常会引用对应的 skill 名称。3.2 与 Trae 集成的操作记录除了 Codex CLI我看到很多人在问 Trae 里怎么用 Superpowers。Trae 是一款 AI IDE国内用户不少它的插件机制和 Codex CLI 略有不同但思路类似。我自己的使用经验是Trae 支持自定义 skills 目录你只需要在项目的配置里指定 Superpowers 的位置就行。具体来说在 Trae 的配置面板中找到 skills 或 agents 相关的设置项然后添加一个新技能目录指向你克隆下来的superpowers/skills目录即可。添加完之后建议重启一下 Trae 或者刷新会话让配置重新加载。有一个小细节Trae 对技能描述的处理跟 Codex 不完全一样你可以先不做修改直接用。但在使用中如果你发现某些技能一直没被触发可以去检查一下技能的 description 片段看看是不是跟 Trae 的匹配规则不兼容。我遇到过一次类似情况原因是某个技能描述里用了太多的“代码块”标记Trae 解析的时候把它截断了导致后面部分没被读到。删掉代码块重新描述一遍就好了。3.3 自定义 skill 的实际案例演示Superpowers 的价值除了开箱即用还在于你可以往里面加自己的东西。我自己就写过几个自定义 skill效果都还不错。这里我拿其中一个“数据库迁移审查”的 skill 作为例子给你看看它的基本结构。先创建一个新目录比如~/.codex/skills/db-migration-review/然后在里面新建一个SKILL.md文件。文件开头写上基本的元信息和描述让 AI 知道这个技能是干什么的--- name: db-migration-review description: Review database migration files for correctness, consistency, and rollback safety. --- # Database Migration Review 当收到数据库迁移文件审查任务时按以下步骤执行 1. 检查迁移文件的版本号和时间戳是否合理递增。 2. 核对 up() 与 down() 方法的操作是否对称。 3. 查找迁移中出现的数据转换逻辑确认是否有数据丢失风险。 4. 检查是否对大数据量的表执行了危险的 DDL 操作如有则标记出来。 5. 输出审查报告按「致命问题」「建议修改」「可忽略」三档分类。写完保存之后你还需要在 Codex 的配置里注册一下这个新的技能目录或者直接把整个自定义目录放在已有的 skills 根目录下让 AI 自动扫描进去。实测下来这种自定义技能用起来非常顺手特别是对团队内部有特殊规范约束的场景效果远比在对话里反复叮嘱要稳定。4. 常见问题与排查技巧实录4.1 安装后完全不生效怎么办这是最常见的问题也是我收到留言里被问得最多的一类“我明明按照教程装好了为什么 AI 还是不按套路出牌”遇到这种情况先不要慌按照下面的顺序排查。第一确认技能目录是否被正确扫描。不同版本的 Codex CLI 对技能目录的默认路径可能不同有的版本用的是~/.codex/skills有的版本可能要看项目根目录下的.codex/skills。你可以直接用文件管理器看一下目录是否存在、文件是否完整。如果目录不存在多半是启动时没自动创建手动建一个再放文件进去就行。第二确认配置文件里的开关是否打开。有些版本会默认关闭自定义技能加载需要你手动在配置里设置为开启。具体字段名因版本而异你可以在配置文件里搜索skill关键字看看有没有enabled: false之类的字样。第三也是最容易被忽略的会话上下文中是否真的包含了 skill 的内容。即使文件位置正确、开关打开如果当前会话是在安装之前就启动的AI 可能还没有重新加载这些指令。这种情况下退出当前会话重新打开一个新的对话问题基本都能解决。4.2 技能按需加载不灵、AI 答非所问另一个高频问题是某些技能没有被正确触发导致 AI 回答问题时完全没体现出“大师级”的思考路径。我遇到过最典型的场景是明明配置了代码审查类的 skill但让它审查代码时它给出的回答依然很笼统没有按 skill 中要求的格式输出。这种情况我总结下来大概率是技能描述与当前任务的匹配度问题。Codex 这类工具在决定是否加载某个技能时依赖的是技能描述与用户请求之间的语义匹配度。如果你的描述写得过于具体比如“这个技能适用于审查 Python 项目中包含异步逻辑的数据库迁移文件”那 AI 很可能无法把它泛化到普通场景。解决办法有两个一是适当放宽技能描述让它能覆盖更多相关场景二是在任务的提示词里主动点名技能名称比如加上“请使用 db-migration-review 技能来完成审查”这样的话引导 AI 去加载。第一种方法治本第二种方法适合偶尔应急。4.3 Superpowers 的独家避坑技巧最后分享几个我实际用下来非常受用的细节这些在官方文档里基本看不到纯属自己踩坑踩出来的经验。一个是你可以在自己的项目根目录放一个项目级的AGENTS.md文件里面描述这个项目特有的架构、技术栈、编码规范以及“哪些代码不要动”。Superpowers 里的一些通用技能会与这个文件协同工作AI 在执行任务时能同时参考项目级规范和通用工作流效果非常惊艳。我目前的配置是项目级文件管“这个项目怎么做事”Superpowers 管“这类任务怎么做好”各司其职。另一个是用好git diff的复盘习惯。每让 AI 完成一轮修改我都会用git diff仔细看一遍改动不是为了事后找茬而是为了积累“AI 什么时候会自作主张”的直觉。用久了你会发现某些技能在特定条件下特别容易触发 AI 对代码的额外“优化”而这种优化不一定是你想要的。这时候就需要在 skill 文件里加上一句“不要修改未明确指出的代码”效果立竿见影。5. 项目影响与后续扩展思路Superpowers 这个项目让我觉得有意思的地方不仅仅在于它提升了 AI 编程工具的表现更在于它代表了一种趋势AI 应用正在从“拼模型”转向“拼工程”。在模型能力已经很强的前提下如何通过提示词工程、工作流拆解、上下文管理来榨干模型的价值成了新的竞争焦点。从实际影响来看Superpowers 把原本只在提示词高手之间口耳相传的经验变成了一个可分发、可复制的开源项目。这意味着普通开发者不需要从零开始摸索怎么引导 AI 干活直接装一套配置就能获得接近资深玩家的体验。这种“经验开源”的效应会显著拉低 AI 编程的上手门槛。我个人后续的计划是fork一份Superpowers然后在里面加入更多团队开发场景的技能比如代码走查会议的准备、跨模块接口设计的评审清单等。如果你也在深度使用这类工具我建议你也动手改一改哪怕只是微调一个技能的描述配合自己团队的习惯也比纯用默认配置顺手得多。这本来就是这类项目的最大价值——它给了你一套很好的起点但最终的玩法完全取决于你怎么去改它。