最近倒腾 Codex CLI 的时候被群友安利了一个叫 superpowers 的开源项目。装上之前我一直觉得 AI 编程助手已经够方便了可真正跑完几个小需求后才发现以前我用的只是“带自动补全的搜索引擎”而加上了这层技能包它才慢慢像一个会系统思考、会自己安排步骤的结对程序员。这篇文章我会从 superpowers 是什么、它的技能文件怎么设计、在 Codex CLI 和 Trae CN 里怎么安装到实际跑一个需求的全过程都过一遍给正在折腾 AI 开发工具的朋友做个参考。superpowers 不是一个编程语言也不是一个新的 AI 模型它更像一套“外挂技能库”。你把项目放进本地目录或者导入 IDE 后原本只会“你问我答”的模型会突然多出很多显式工作流拿到需求先拆解然后全局搜索相关代码再输出实施计划最后动手改代码改完还自己跑测试、做代码审查。这一切并不需要重新训练模型而是把优秀工程师的工作习惯写成结构化指令让模型按步骤执行。适合那些觉得直接用 AI 写代码不靠谱、希望让 AI 的工具属性更可控的开发者。如果你已经在用 Codex CLI、Trae 这类支持 Agent/技能体系的开发工具那这篇内容可以直接照着抄作业。1. superpowers 项目定位与整体拆解1.1 它到底解决了什么问题先聊一个很多人都遇到过的情况。直接打开 Codex CLI丢给模型一个需求它会很热情地给出大段代码但代码大概率存在几个问题第一它没有先去翻你项目里已有的模块和约束第二它不会主动写测试更不会在写完代码后回头审查第三一旦需求复杂一点它就容易陷进某个细节里把其他关联代码改坏。superpowers 的核心思路就是把这些“掉链子”的环节变成一个一个可加载的技能模块。每个技能模块本质上是结构化的提示词但比普通 prompt 做得更细。比如“测试驱动开发”这个技能它会要求模型先写失败测试再实现最小代码再运行测试并重构中间任何一步没有通过就停下来向你汇报而不是嘴硬说“代码应该没问题”。这让我想到带新人的时候与其反复叮嘱对方“认真一点”不如给一份带检查项的 SOP让每个人按流程走出错概率自然就低了。1.2 项目仓库与目录结构从 GitHub 拉下来之后整个项目的目录结构非常有代表性。常见的会有skills/、agents/、docs/这几块其中skills/是核心里面按功能拆成很多子目录比如review、tdd、debugging、commit-message等。每个子目录下都有一个SKILL.md文件这个文件就是技能的定义本体。SKILL.md采用业界逐渐流行的 Agent Skills 格式头部是 YAML frontmatter包含技能的name和description用来告诉模型这个技能是干什么的、什么时候该调用它。正文部分则是具体的执行步骤、输入输出模板和自检清单。模型在收到用户请求后会根据描述里的语义匹配主动加载对应的技能文件然后像读操作手册一样按步骤执行。我第一次打开这个文件的时候有点意外没想到居然没有任何“魔法”全是清晰得有点啰嗦的指令。1.3 与 Codex CLI、Trae 的配合方式superpowers 本身不绑定某个固定平台它的加载方式依赖于底层工具对技能目录的支持。Codex CLI 目前可以通过配置指定额外的技能路径所以我会把整个skills/目录复制到 Codex 的配置目录下再在会话里让它确认是否加载成功。Trae CN 这边走得不太一样它更像一个 IDE提供了图形化的技能管理界面你可以在项目侧边栏里导入外部的 skill 目录。两条路尽管入口不同底层都绕不开 SKILL.md 这套格式所以只要项目本身遵循统一规范移植起来成本很低。有人可能会问直接把技能写死在系统提示词里不就好了我在实践中的感受是技能一旦多起来系统提示词会被撑爆而且模型会把所有指令都当成背景信息重要度反而被稀释。superpowers 这种“按需加载”的设计让模型只有在需要处理某类任务时才读取对应技能上下文更干净命中率也稳定得多。2. 技能包的核心设计与工作流解析2.1 把专家习惯显性化技能设计的本质是把那些资深工程师脑子里的默认动作变成模型可以看见的显式规则。比如我让小兵去改一段老代码他可能上来就动手但如果让一个十年经验的同事来做他大概率会先搞清楚老代码的调用链、确认有没有测试覆盖再决定是用重构还是补丁的方式改。这些习惯不是天生的而是在无数次事故里踩坑踩出来的。superpowers 里的技能文件本质上就是把这种“踩坑后沉淀的检查表”交给模型。模型本身有很强的语言理解和模式匹配能力缺的恰恰是边界清晰的流程约束。给它一个“先搜索再回答”的规则它就会真的先调用代码搜索工具而不是凭训练数据里的模糊印象瞎编。给我的感觉是模型还是那个模型但行为模式从一个“自信的实习生”变成了“守规矩的中级工程师”。2.2 典型技能模块拆解在常用的技能模块里我挑几个体会最深的展开。代码审查技能review会要求模型先提取当前改动文件的 diff再列出可能存在的风险点按严重程度排序每一条风险都要给出代码行号和修改建议。它不是只说“这段代码可以优化”而是必须给出“第几行存在潜在空指针风险因为那里没有判空”。这个强制要求非常有价值。测试驱动开发技能tdd则规定了严格的节奏先写一个会失败的测试运行测试确认失败再写最小实现让测试通过最后做重构。模型每走一步都会打印当前状态比如“我还没有实现该方法因为当前步骤只允许写测试”。这样即使模型理解出现偏差我也能在最早阶段发现并纠正。提交信息生成技能commit也不是简单地把 git diff 喂给模型让它总结而是要求模型先根据 diff 判断本次改动类型再对照项目历史提交信息的风格最后生成多个候选信息让用户选择。整个过程非常像一位重视工程规范的同事在整理提交记录。2.3 多阶段提示与自省机制superpowers 里另一个有意思的设计是“自省机制”。很多技能不会让模型一口气把答案吐完而是把任务拆成阶段每完成一个阶段就必须输出阶段性结论并附上它得出这个结论的依据。这种做法的好处是能显著减少幻觉当模型被要求“先说出你接下来要修改哪些文件理由是什么”时它就得先去做真实的项目文件检索而不是靠猜。我自己测试下来的体感是加了自省这一步之后模型在改动前“想清楚”的比例明显提升。它会在回复里出现“我先搜索了 utils 目录下的相关函数发现现有实现没有处理空输入的情况因此计划新增一个辅助方法”这样的内容。尽管这会增加一点交互轮次但换来的是更高的可预测性我认为这笔交易非常划算。3. 在 Codex CLI 与 Trae CN 中安装 superpowers3.1 安装前置条件首先确保你的开发环境已经具备几个基础条件Git 用来拉取项目Node.js 18 以上版本保证 Codex CLI 能正常运行。Codex CLI 本身需要你已经完成登录认证能够正常发起模型请求。如果你用的是 Trae CN则需要在设置里确认当前版本支持 Skill 导入不同版本菜单位置会有些出入但大方向一致。我建议在干净目录下新建一个临时文件夹做测试不要直接在生产项目里一上来就全量导入所有技能。先装好一个技能跑通流程再逐步添加这样排查问题会容易很多。3.2 从 GitHub 获取 superpowers 并配置 Codex CLI整个流程可以分为三步拉取仓库、复制技能文件、验证加载。# 1. 将 superpowers 仓库克隆到本地目录 git clone https://github.com/你的用户名/superpowers.git ~/superpowers # 2. 创建 Codex CLI 的技能目录 mkdir -p ~/.codex/skills # 3. 把技能文件复制到 Codex 的配置目录下 cp -r ~/superpowers/skills/* ~/.codex/skills/复制完成之后打开新的 Codex 会话输入一句测试指令请查看你当前加载了哪些技能并从中选择适用于代码审查的技能。如果模型能正确列出review技能并主动进入审查步骤说明配置已经生效。如果它说没有找到技能优先检查复制后的目录层级是否正确常见错误是把整个skills文件夹复制到了~/.codex/skills/skills/导致多嵌了一层。3.3 在 Trae CN 中安装 skillTrae CN 的安装路径更偏图形化。打开项目后在 IDE 的侧边栏找到技能管理入口通常以一个类似“技能”或“插件”的图标表现点进去选择“导入技能目录”然后指向你本地已经拉取好的superpowers/skills目录。导入完成后部分版本需要重启 IDE 会话或重新打开项目才能扫描到文件。如果你用的 Trae CN 版本还没有界面入口也可以手动创建项目内的.trae/skills/目录把技能文件复制进去然后重启一下编辑器。我在实际操作中发现IDE 对环境目录的监听有时候存在缓存重启一次是最稳妥的解决方式。另外要注意不同版本支持的 skill 格式略有差异如果某些技能没有被识别可以检查SKILL.md开头的 frontmatter 字段是否完整。3.4 验证安装结果验证安装是否成功不能只看技能文件有没有复制到位关键还是看模型能不能真正调用它。我建议跑一个带明确“技能信号”的测试场景比如要求模型“用 TDD 流程给 utils.js 写一个数组去重函数”。如果模型严格按照“先写测试再实现再运行”的顺序走那基本可以断定 tdd 技能已生效。如果模型给出的是普通回答而没有进入固定流程那也许是技能描述没有触发匹配。这时候可以更直接一点在提示词里明确写上“请使用 tdd 技能”强制它加载对应文件。若仍然无效就回到目录配置、文件名大小写、frontmatter 是否合法这几个环节排查。4. 实战用 superpowers 完成从计划到提交的全流程4.1 场景选择为了验证 superpowers 的实际效果我拿自己做的一个小工具仓库来试需求是新增一个函数把 Markdown 标题文本转成合法的 HTML 锚点。这个需求看起来简单但涉及大小写转换、空格处理、特殊字符过滤、重复标题去重等细节很适合用来观察模型是否具备项目上下文意识。我刻意没有给模型任何额外的背景说明只把需求一句话写在会话里想看它会不会自己去翻项目现有的工具函数风格和测试目录结构。这种“不喂饭”的测试方式最能暴露技能包有没有起作用。4.2 调用技能后的反应我输入的内容很简单给 utils.js 新增一个 markdown 标题转锚点的方法使用 tdd 流程。如果是以前直接裸用 Codex CLI它大概率会立刻甩给我一大段代码附带一句“已实现”然后就没下文了。但这次加载了 superpowers 的 tdd 技能后模型先是输出了一段计划先查看utils.js现有编码风格再查看对应测试文件命名规律然后列出三种字符过滤方案最后才说“我现在先为锚点方法编写一个失败测试”。这里让我比较意外的是模型真的先去调用文件搜索工具把项目里已有的边界处理方式列了出来比如对中文标题的保留规则、空字符串如何降级处理等。写完失败测试后它还特意把测试命令放在注释里方便我直接执行。整个交互节奏和以前完全不一样更像是在和我做 code review。4.3 与不用 superpowers 的对比为了对比我后来又在没有加载技能的全新会话里问了同一个需求。效果差别非常明显无技能时模型生成的函数确实能跑但测试覆盖率明显不足比如没有处理标题重复、没有处理锚点以数字开头的情况。更关键的是它不会主动说“这段代码没有测试”我问它有没有测试它还信心满满地说“常见场景已经覆盖”。而用 superpowers 的流程跑下来模型在提交结果前主动列出了一个自检清单已处理的边界场景、未覆盖的输入类型、是否运行过测试命令。即使最终代码仍可能有不完善的地方但这个“主动暴露问题”的习惯会让后续的人工审查高效特别多。对于团队里需要兼顾多个项目的开发者来说这种可验证、可追踪的 AI 工作流价值比单纯的代码生成大得多。5. 安装和使用中的常见问题与排查技巧5.1 技能文件识别不到这是最常遇到的问题。模型完全忽视技能指令就像是普通聊天一样给了回答。通常原因有三个技能目录路径配错、SKILL.md文件名大小写不规范、frontmatter 里的name或description缺失导致模型无法解析。排查时我先确认~/.codex/skills下的目录结构确保每个技能文件夹下直接放着SKILL.md而不是嵌套了一层。再看 frontmatter 是否用---包裹字段是否齐全。最后在当前会话里输入“列出所有可用技能”之类的指令观察模型反馈。整个过程不复杂但容易忽略踩过一遍之后就知道要优先查这三处。5.2 模型上下文太长导致技能指令丢失当项目文件很多、对话轮次较长时技能指令有时候会被“挤”出有效上下文模型后半段直接走样不再遵守 TDD 或审查步骤。我的解决方式是把任务拆小每次让模型只处理一个技能范围内的工作而不是把“实现功能写测试生成提交信息审查代码”全部塞进一个会话里。另外也可以精简技能文件本身把步骤写成清晰条目把大型代码模板放到单独引用文件里需要时才读取。这样既能保住技能稳定也减少 token 浪费。5.3 企业内网或离线环境无法拉取项目如果你所在的公司网络环境访问 GitHub 不稳定或者干脆只能用内网源最直接的办法是让网络管理员提前把 superpowers 仓库同步到内网 Git 服务再通过内网地址拉取。这可能不是最“酷”的方案但肯定是最省事的。拉下来之后也不需要实时更新技能文件本质上是一堆 Markdown本地复制过去就能用对版本强依赖不大。5.4 自定义技能的一些技巧最后分享一个我觉得特别值钱的技巧自己写技能。很多人觉得超级技能是别人做好的自己只要“装”就行其实最贴合你工作流的技能往往得自己写。结构很简单一个SKILL.md文件就够了。--- name: dep-check description: 检查依赖更新后是否破坏了现有 API适用于升级第三方库后的验证场景 --- # 依赖升级影响检查 1. 读取 package.json 中被升级的依赖版本变化。 2. 搜索代码中对这些依赖的引用文件。 3. 根据库的 breaking changes 文档和现有调用方式列出可能不兼容的位置。 4. 输出一份标记了风险等级和修改建议的清单。写完放到技能目录模型就可以使用了。我自己实践下来自定义技能的关键是“场景足够具体”和“步骤足够固定”不要写那种“认真审查代码”这种模糊指令而要写“先搜索文件再列出风险再给建议”这种带动作的句子。6. 使用感受与后续扩展用了 superpowers 一段时间后我体会最深的一点是:AI 编程助手的下限被明显抬高了。以前的模型经常会自信地给你一段残缺代码你必须自己拿去跑、自己发现问题;现在它会主动把测试、审查、提交信息这些环节补齐虽然不是每次都对但至少流程上不再漏项。这种“先把流程跑对”的思路放在团队协作里非常重要因为可复现的流程比灵光一现的输出更容易沉淀成团队资产。对于后续扩展我目前正在尝试把自己的团队规范也转化成几个私有技能比如“后端接口变更需要同步更新 API 文档”“前端组件改动必须跑视觉回归”。这类规范直接写在团队文档里没人看但变成模型加载的技能后每次改动都会被自动提醒效果比我反复盯人好得多。如果你也在用类似的工具我建议先别急着把所有技能都装上挑两三个最贴合自己痛点的技能跑熟慢慢再迭代出属于你自己的 superpowers。