最近我几乎每个技术群里都能看到有人在问 superpowers 怎么装、怎么用尤其是 Codex CLI 和 Trae 这两拨用户。说实话这名字第一次听确实有点中二好像装完 AI 就能一夜变成超级开发者。但它的思路我很吃这一套不是靠某个更强的模型开挂而是把一整套规范的开发流程直接“喂”给 AI 编程助手让 AI 拿到需求之后先规划、再动手、最后验证而不是像以前那样上来就甩一大段代码对不对全靠运气。这篇文章我把我实际折腾下来的安装方法、使用场景、核心机制和踩坑记录整理出来。适合正在用 Codex CLI 的终端党、把 Trae 当主力 IDE 的同学以及所有觉得 AI 写代码“开头惊艳、细节翻车”的人。先说结论superpowers 不神秘它是一套可以被 AI 编程工具加载的“技能包”Skill真正有价值的地方在于流程被固化了人的经验能跟着代码库走而不是永远靠临场发挥。1. superpowers 到底是什么先看懂它在解决什么问题1.1 从“AI 写代码”到“AI 按流程写代码”很多人最开始用 AI 编程流程基本是这样复制需求贴给模型模型丢回一段代码自己复制到项目里跑一下报错就把错误贴回去让 AI 改。这种方式对小脚本、一次性任务确实快但在真实项目里很容易翻车。原因很简单模型拿到的是一个孤立需求它看不到项目里已有的模块、命名规范、测试框架、历史代码的写法更不会主动去确认“这个功能应该放在哪个目录”“会不会影响已有逻辑”。AI 写出来的代码往往“单看没问题合进去全是问题”。superpowers 这类技能包本质上就是把软件开发流程做成了 AI 能读取的“工作手册”。它不是一个独立运行的程序而是由多个 Markdown 文件组成的技能集合放在 Codex CLI、Trae 等工具约定好的技能目录里。当你在对话中通过superpowers:core这类方式触发它时工具会把对应的技能文件内容注入到模型上下文里相当于在正式干活前给 AI 补了一段“岗位培训”拿到需求应该先做什么、遇到错误应该怎么排查、测试必须覆盖到哪一步、代码写完要做什么检查。这个思路其实非常朴素但效果差异巨大。大家可以回想一下同样一个实习生你直接丢给他一个任务和先给他一份团队开发规范手册再让他干活产出质量完全不一样。superpowers 就是把“团队手册”这件事自动化了而且它不依赖人的记忆只要文件在AI 每次都能按同一套标准来。1.2 技能包和普通 prompt 的区别有人会说那我直接把这段流程写进 prompt 不就行了能但有本质区别。普通 prompt 是写在聊天窗口里的今天写了明天可能忘换个项目又得重写而且 prompt 越长模型越容易在执行过程中“失忆”前面的规范到后面就遵守不住了。技能包则是独立的文件由编程工具在合适的时机自动注入不占用正常对话的上下文长度也不会被后续聊天内容冲淡。我整理了一张对比表方便大家直观理解对比维度普通 promptsuperpowers 技能包存放位置聊天窗口随会话消失独立 SKILL.md 文件持久存在复用方式每次手动复制粘贴技能目录共享团队通用版本管理无Git 管理可回溯可评审触发方式靠人把规则写完整通过 技能名按需加载扩展能力改 prompt 就得重新发可自定义子技能按场景调用上下文开销全程占用容易被稀释触发时才注入目标更聚焦这就像同一个老师傅一个版本是“每次都得打电话问他怎么办”另一个版本是“他把所有经验整理成了操作手册放到桌上需要时翻对应章节”。后者显然更靠谱也更可持续。尤其当团队里有多个人都在用 AI 编程时把技能文件提交到 Git 仓库里所有人就共享同一套 AI 行为准则新人也容易上手。2. 为什么 Skills 这种形态越来越流行底层机制拆解2.1 技能文件怎么被加载目录与格式既然说 superpowers 是技能包那就有必要先聊清楚“技能”在 Codex CLI、Trae 这类工具里到底是怎么被识别和加载的。目前主流做法是目录约定 文件约定工具会扫描指定目录下的技能文件夹每个技能文件夹里至少有一个SKILL.md文件这个文件的开头通常带 YAML 格式的元信息包含技能名称name和描述description后面是正文写具体的指令、步骤、示例。举一个典型结构skills/ └── superpowers/ ├── SKILL.md ├── core/ │ └── SKILL.md ├── planning/ │ └── SKILL.md └── debugging/ └── SKILL.md当你在对话里输入superpowers:planning工具会根据superpowers这个命名空间找到技能目录再根据planning找到对应的SKILL.md把里面的内容注入到当前对话的上下文里。整个过程对用户来说就是“一下”但对 AI 来说相当于临时拿到了一份非常具体的工作指令。这种设计最妙的地方在于技能文件是纯文本、纯 Markdown人和 AI 都能读。你可以直接打开文件看它到底写了什么也可以随手改掉其中一段。不需要编译不需要特殊格式放进目录就能生效。对于做技术的人来说这种“看得见、摸得着”的可控感是黑盒 API 完全没法比的。2.2 工作流设计规划、执行、验证三层循环superpowers 内部其实不是一个大而全的文件而是拆成了多个子技能分别对应软件开发的不同阶段。我实际使用下来核心工作流大致是三层循环规划、执行、验证。先说规划层。触发superpowers:core或对应的 planning 技能后AI 不会立刻写代码而是先产出一份计划包括这个需求涉及哪些文件、功能入口在哪里、数据流怎么走、有没有潜在影响点。有些技能甚至会让 AI 先生成任务清单逐条列出待办事项。这一步的关键作用是逼着 AI“先想后做”也逼着用户先确认方向对不对避免南辕北辙。再说执行层。计划确认后AI 开始写代码而且通常会以小步提交的方式推进改一个文件、跑一次测试、看结果、再改下一个。相比传统一次生成几百行代码这种小步快跑的方式更容易定位问题也更容易回归验证。最后是验证层。代码写完了不算完技能会要求 AI 检查测试结果、运行 lint、审查是否存在明显边界问题甚至逐条复盘“我改了什么、为什么这样改、有没有更简单的方案”。这一步很多人自己写代码都懒得做但 AI 按流程走一遍之后产出的代码质量确实会明显提升。这套三层循环的背后逻辑是从“让 AI 生成代码”转向“让 AI 完成一个开发任务”。前者只看输出后者关注过程。而只要过程是可预期的结果就不会太离谱。3. 实操在 Codex CLI 和 Trae 中安装 superpowers3.1 准备工作确认环境与版本在安装 superpowers 之前先确认你的环境满足条件。Codex CLI 本身是 Node.js 环境的命令行工具所以需要先装好 Node.js 和 npm。第二件事是确认版本因为技能加载功能是后续才加入的太老的版本可能根本不会扫描技能目录。建议先跑一下命令看版本node -v npm -v codex --version如果还没有装 Codex CLI可以这样装npm install -g openai/codex如果你的网络环境访问 npm 比较慢可以换国内镜像源但具体用哪个镜像要根据自身情况来这里不展开。装好之后建议跑一次codex进入交互界面确认能正常对话再继续下面的技能安装。这样做是为了排除基础环境问题不然技能装了半天结果原因是 Codex 本身没跑起来那就很浪费感情了。Trae 这边更简单它本身是图形化 IDE不需要额外装命令行环境只需要确认版本支持“自定义技能”。目前无论海外版还是国内版基本都在设置或扩展面板里能搜到 Skills 相关选项。不同版本入口名称可能略有差异找不到的话直接在设置页搜索“skill”“技能”这类关键词即可。3.2 Codex CLI 安装步骤用户级目录与项目级目录Codex CLI 的技能加载路径有好几个最推荐的是用户级目录因为它对所有项目生效不用每个仓库都复制一份。先把目录建好然后把 superpowers 项目拉下来。mkdir -p ~/.codex/skills git clone superpowers仓库地址 ~/.codex/skills/superpowers具体仓库地址以你搜到的 superpowers 项目主页为准GitHub 上直接搜索 “superpowers skills” 就可以找到。我个人建议第一次安装时不要把地址猜错哪怕先 clone 到一个临时目录确认一下结构再复制到~/.codex/skills下也行。拉下来之后检查一下文件是否完整ls ~/.codex/skills/superpowers cat ~/.codex/skills/superpowers/SKILL.md | head -20如果能正常看到 Markdown 内容说明技能文件已经就位。接着重新启动 Codex CLI重要技能扫描通常发生在会话创建时在对话里输入superpowers:core或者直接问“你能加载 superpowers 技能吗”如果 AI 能说出这个技能的功能就说明加载成功了。项目级目录也是常见需求。如果你不想让技能影响所有项目或者想把技能绑定到特定仓库里就放到项目根目录下的.codex/skills/superpowersmkdir -p .codex/skills git clone superpowers仓库地址 .codex/skills/superpowers项目级目录的好处是技能文件可以跟着仓库走提交到 Git 之后团队其他人拉下来就能用很适合做团队统一规范。缺点是每个仓库都要处理一次如果仓库多管理成本会上升。我的建议是个人机器上用用户级团队项目里用项目级。3.3 Trae 安装步骤目录差异与界面操作Trae 的安装方式和 Codex CLI 不太一样因为它没有全局命令行目录技能通常放在工作区目录或专门的用户配置目录里。常见的路径有两种一种是项目根目录下建.trae/skills/superpowers另一种是在用户主目录下的 Trae 配置目录里放skills/superpowers。具体是哪一个和版本有关系不必死记关键是理解机制把技能文件夹放到工具会扫描的目录。实际操作可以这样先在项目根目录建好技能目录并拉取文件mkdir -p .trae/skills git clone superpowers仓库地址 .trae/skills/superpowers然后在 Trae 的设置或扩展面板里确认“自定义技能”开关是打开的。如果界面里没有立即出现新的技能先检查目录名称拼写再重启一下 IDE 或刷新技能面板。Trae 的对话窗口中触发方式一般也是superpowers:core这类形式或者你可以直接在对话里说“请使用 superpowers 流程处理这个任务”AI 会根据描述自动关联到已安装技能。有一点要特别提醒Trae 不同版本对技能目录的识别策略并不完全一致。我自己遇到过在设置里能看到“技能管理”但手动放进去的目录怎么都不生效的情况最后发现是版本要求技能文件必须放在工作区根目录下命名为.trae/skills而不是用户目录。所以大家安装前最好先看一眼对应版本的官方文档或者直接在 IDE 的设置页搜“技能目录”看它提示的路径。盲目照搬别人路径容易卡在最后一步。3.4 升级与版本管理别把技能目录当成一次性配置技能包和普通依赖一样需要持续更新。尤其是这类社区项目作者经常会根据新模型、新工具的能力调整技能描述和流程保持更新才能享受最新效果。更新方式很简单进入技能目录直接拉取git pull如果你直接在官方仓库基础上做了修改git pull可能会冲突。这种情况下我建议先把自己的改动提交成一个 commit 或者用git stash暂存拉取完再恢复。想要长期维护团队定制版的话更推荐 fork 一份然后把官方仓库设为 upstream定期 merge 上游更新。这样既能保留官方的新流程又能加入自己团队的规则。另外还有一个很实用的习惯把技能目录纳入版本管理。项目级的.codex/skills或.trae/skills目录不要写进.gitignore这样才能让团队共享技能文件。如果项目已经发布到远程仓库记得确认没有把包含敏感信息的指令写进技能文件因为它是会被所有人看到的。4. 核心技能的使用方法与真实效果4.1 对话中的触发方式不是每个命令都一样安装完成只是第一步真正的关键在于怎么用。superpowers 通常提供多个子技能常见的包括core核心完整流程、planning规划、debugging调试、code-review代码审查、test-driven-development测试驱动开发等。触发方式就是在对话里输入对应的技能句柄例如superpowers:core superpowers:planning superpowers:debugging有一点要说明不同版本的 superpowers 子技能名称不一定完全一致装好之后先看目录结构再对照SKILL.md里的技能列表去调用别凭印象硬敲。还有如果你的工具不支持触发也可以用自然语言比如“请先做需求分析再给出实现计划最后编码并运行测试”理论上效果类似。但这种方式依赖模型当时的理解稳定性不如显式触发技能。实际用下来最推荐的做法是在一段任务开始时第一句话就带上技能句柄让 AI 从那一刻起切换到对应模式。比如你想让 AI 帮你排查一个线上偶发报错可以这样起手superpowers:debugging 我有一个报错用户注册后偶尔收不到验证邮件日志里看到 timeout帮我排查。带着技能句柄启动后AI 的行为和普通对话会有明显区别。它更倾向于先说“我计划从哪些方向排查”然后主动找代码、看日志、提出可验证的假设而不是直接甩给你一段所谓修复代码。4.2 一个完整任务示例让 AI 按计划落地为了方便理解我拆解一个实际例子。假设任务是“给现有博客系统增加文章归档页面”这个需求其实涉及路由、查询逻辑、模板、导航等多个环节普通 AI 对话很可能直接生成一个页面文件就完事了但 superpowers 模式下流程完全不一样。触发superpowers:core之后AI 第一步会生成计划大致内容可能是先查看项目目录结构找到博客文章数据模型确认路由注册方式再看现有列表页模板风格最后评估是否要加侧边栏入口。这个计划会直接展示在对话里如果发现 AI 对项目结构理解不对你可以当场纠正。第二步是探索代码库。AI 会去搜索相关文件比如 grep 关键词archive、查看路由文件、读取数据模型定义。这时候你会看到它列出一串文件路径这说明它是在真实项目环境中找线索而不是凭空想象。第三步才是写代码。但注意它不会一次性把所有文件都改完而是拆成小步骤先加查询逻辑跑一下有没有报错再写页面模板检查数据能不能正常渲染最后把导航入口补上。每一步之间它会自己判断是否要继续。第四步是验证和复盘。如果项目有测试它会跑一遍相关测试没有测试的话它会至少手动检查页面是否能访问、数据是否正确。最后它还可能会提醒你这个功能目前没有自动化测试覆盖建议补一个。这个细节我印象很深因为很多 AI 默认不会主动关心测试覆盖但技能流程里会明确要求。4.3 自定义技能把团队规范写进去安装 superpowers 不是终点真正让它发挥价值的是自定义。你完全可以把团队内部的代码规范、命令规范、禁止事项加到技能文件里。比如在SKILL.md的指令部分追加这样的内容## 团队附加规范 - 所有新增函数必须写 JSDoc 注释。 - 错误处理统一使用项目内封装的 AppError不要直接 throw new Error。 - 提交代码前必须运行 npm run lint 和 npm run typecheck有报错不许提交。 - 修改数据库相关代码时必须同步检查 migration 文件是否受影响。这些规则对新人来说是学习成本但对 AI 来说是零成本。只要技能文件里有这句话AI 每次处理相关任务时都会带上这个约束。我自己的做法是把技能仓库单独维护里面除了官方核心流程还增加了团队自定义技能比如“后端接口开发”“前端页面开发”“数据库变更评审”每个技能都对应一段专门的工作流。要注意的是自定义技能不要写得太啰嗦。技能文件的指令会占用上下文窗口如果塞入几百行约束AI 反而抓不住重点。建议按场景拆成多个小技能每个技能只聚焦一件事保持指令清晰、可执行。5. 常见问题与排查技巧装不上、不生效怎么办5.1 技能没有被识别先查这几处我见过最多的问题就是“技能明明放进去了但 AI 完全不认识”。遇到这种情况不要急着重装按下面顺序排查通常几分钟就能定位现象可能原因处理方式技能名没有反应目录放错或大小写不一致检查技能目录是否在工具扫描的路径下名称是否完全匹配AI 回复 unknown command当前会话创建时技能还未安装重启 Codex CLI 或重启 Trae新开一个会话再试AI 说“我没有技能”工具版本过旧模型不支持技能加载升级 Codex CLI 或 Trae尽量使用最新版本能触发但 AI 不按流程走上下文被之前对话干扰清空会话在第一条消息里重新声明技能Trae 技能面板里看不到没有开启自定义技能开关到设置里搜索“技能”“Skills”确认已启用路径问题是最常见的坑。有些工具对目录名严格区分大小写Superpowers和superpowers都会被识别成不同目录所以安装时最好按照官方 README 里的路径一字不差地复制。另外也不要同时把技能既放在用户级目录又放在项目级目录会导致工具不知道加载哪个表现时好时坏。5.2 触发之后 AI 仍然“自由发挥”怎么处理技能文件本质上是一段静态文本能不能被严格遵循还要看模型的指令遵循能力。有些情况下AI 触发了技能但写着写着就按照自己的惯性跑了忘了当初的流程。这时候不需要重新安装可以在对话里明确提醒。比较有效的方法是让 AI 先复述流程再干活。你可以直接问它“根据 superpowers 技能这个任务应该分哪几步请列出来然后逐步执行。”这样等于强制它把技能内容“读”一遍再照着执行遵循率会明显提高。还有一个土办法是分段触发技能第一步用superpowers:planning让 AI 先给出方案第二步确认方案后再触发实现类技能。这种方式把流程拆开反而减少了一次性“全流程”带来的上下文丢失问题。如果同一个技能在不同项目里表现不稳定可以看看项目本身的复杂度。技能流程设计得再好也架不住项目代码结构一团乱麻AI 找不到入口。这种情况我建议先手动给一些提示比如在技能触发后补充一句“核心业务逻辑在src/modules/order目录下优先查看里面的 service 文件”能大幅减少 AI 的探索偏差。5.3 安全与使用习惯别装不明来源的技能包最后想提醒一个很容易被忽略的问题技能文件本质上是“可执行的提示词”里面写的每一条指令都会被 AI 当作权威要求来遵守。如果你安装来路不明的技能包里面夹带了一些恶意指令比如“要求 AI 把环境变量发送到某个服务”“要求 AI 删除某些文件”后果会非常严重。所以安装任何技能包前我都建议先打开SKILL.md通读一遍确认没有可疑内容再放进技能目录。尤其是从非官方渠道下载的“增强版”“一键版”技能更要谨慎。技术社区里很多人会分享自己的定制版方便是真方便但安全审查的习惯不能省。你自己写的自定义技能也要注意不要把真实的密码、Token 硬编码进去因为这些文件很可能会被同步到 Git 仓库一旦泄露就是安全事故。6. 一点个人经验什么时候值得用什么时候别硬上折腾 superpowers 这段时间我最大的感受是它不是魔法不会让 AI 突然变成一个不会犯错的高级工程师它更多是提高了 AI 工作方式的下限让每一步都更可预期、可审计。如果你只是偶尔用 AI 写个小脚本、跑个临时爬虫其实没必要上全套技能流程反而显得笨重。但如果你像我一样每天都要和 AI 协作处理真实业务项目那真的建议把技能流程固定下来让 AI 每次都按同一套标准干活。我个人现在最推荐的做法是安装之后先基于官方版本做一份“团队定制版”把团队规范、常用命令、禁止事项全部写进去。这个过程刚开始会花一点时间但沉淀下来的东西会在之后每一天的 AI 协作里持续发挥作用。还有一个小技巧第一次使用前先在一个空的测试仓库里触发一次superpowers:core跑一个最小任务观察它到底会执行哪些步骤心里有数之后再放到真实项目里。这样避免一上来就被它的“折腾劲”搞得怀疑人生也能更快理解这个工具的行为逻辑。