最近在折腾 AI 编程助手的时候发现一个很有意思的现象大家把太多精力放在选模型、堆参数上却很少想过一个问题——同样拿着 Codex CLI、Trae 这类工具为什么别人能让 AI 老老实实走完“设计-开发-测试-修复”的完整流程而我的 AI 动不动就自作主张改一处崩三处我试了一圈下来发现差距往往不在模型而在“调教方式”。最近这套叫superpowers的技能包确实把这层窗户纸捅破了。它不是给 AI 装什么外挂而是一整套用 Markdown 写成的技能提示词体系能让 AI 编程助手从“你说一句、它写一段”的被动执行模式切换成“先规划、再动手、自测完再交付”的工程化工作流。尤其配合 Codex CLI 这类命令行工具效果比我预想的要明显得多。这篇文章就是我自己的完整折腾记录从 superpowers 到底是什么、为什么能起作用到在 Codex CLI、Trae Work 里具体怎么装、怎么配、怎么改再到我实际跑项目时踩过的坑和排查思路一次性全写清楚。无论你是刚接触 AI 编程助手还是已经用了一段时间但觉得输出不稳定这篇都值得你花十分钟看完。1. 先搞清楚superpowers 到底给 AI 加了什么“超能力”先说结论superpowers 本质是一套分层清晰的提示词技能集合它把 AI 编程助手的思考过程拆成了几个固定阶段每个阶段对应一组极其具体的规则和动作。或者说它像是给 AI 配了一本内部工作手册。1.1 为什么 AI 编程助手总是不按套路出牌用过 Codex CLI 或者同类工具的朋友应该都有体会模型本身的写代码能力已经很强但它在项目管理这件事上非常“自由散漫”。你让它“实现一个用户登录功能”它可能上来就写路由、写数据库、写前端页面中间跳过异常处理不写测试最后交付的东西看着能跑一上线全是洞。这背后的原因不复杂。大模型训练时见过海量代码它能“模仿”出很像样的代码但它没有你项目的上下文不知道你的编码规范、不知道你要求测试覆盖率、不知道你“先出设计再动手”的习惯。如果你不在提示词里把这些规则讲清楚模型就会按照训练数据里的“最大公约数”来干活——而那个公约数通常就是最短路径、最省事的做法。superpowers 解决的就是这个问题。它用流程约束 规则注入 清单校验的方式把“一名合格工程师在真实项目里会怎么工作”这个过程变成 AI 能理解和执行的显式指令。1.2 核心技能包“规划-构建-测试-修复”的闭环整套 superpowers 体系里最核心的是四个环环相扣的技能技能触发场景核心作用workflow每次任务开始先分析需求、拆解步骤、列出明确任务清单再动手build进入编码阶段按小步走、勤验证的原则写代码避免一次性堆大量改动test代码写完自动做测试覆盖评估明确报告新增代码的测试缺失fix测试不通过或报错控制修复节奏规定最多尝试次数避免无限循环改代码这四个技能不是互相独立的它们是按顺序被 workflow 调用的一条流水线。AI 接到你的指令后会先读 workflow 技能规划出 Step 1、Step 2、Step 3……然后每一步执行时再调用 build 技能做完一段就触发 test 技能检查出了问题才进入 fix 流程。这种设计的最大价值在于它把“质量检查”从人的身上转移到了流程本身。以前你需要在对话里反复提醒“记得写测试”“先看看有没有破坏其他功能”现在不用了技能会替你做这些事。1.3 和 AGENTS.md、CLAUDE.md 这类配置的定位差异之前我也折腾过 CLAUDE.md、AGENTS.md 这类项目记忆文件它们的作用是给 AI 输入项目背景、代码结构、常用命令。但坦白说这类文件管的是“静态知识”AI 接没接住、执行到哪一步该用哪条规则它没法自动判断。superpowers 的思路不太一样。它把技能文件放在项目特定目录里依赖 AI 在每次执行任务时主动扫描、加载。真正的关键在于它的提示词写得极其具体不是“请写高质量代码”这种正确的废话而是“先查看现有测试命令如果没有测试先创建一个基础的测试框架再继续”这种可以直接执行的指令。所以你可以这样理解AGENTS.md 是给 AI 的“项目简介”superpowers 是给 AI 的“工作守则”。两者配合使用效果才会最大化。后面我在自定义技能的部分会专门演示这种配合方式。2. 安装 superpowers 的两种主流方式含 Codex CLI 配置细节superpowers 的安装方式有好几种我实际用下来最常见的两种是npm 包安装和传统手动放置。这节我把具体步骤、命令和校验方法都写出来你可以直接照着操作。2.1 方式一npm 全局安装一行命令搞定如果你和我一样用 Codex CLI而且 Node.js 环境比较干净我推荐直接用 npm 安装。在终端里执行npm install -g superpowers/skills安装完成之后需要确认全局 node_modules 的路径。这一点很容易被忽略——很多朋友装完说“找不到技能”其实就是因为 npm 全局安装目录不在系统 PATH 里或者安装路径跟 Codex CLI 的默认配置对不上。可以用下面的命令查看全局根目录npm root -g以我目前的机器为例输出是类似/usr/local/lib/node_modules这样的路径。记下这个路径一会儿配置 AGENTS.md 时要用。2.2 配置 Codex CLI 的 AGENTS.md 来加载技能Codex CLI 的配置模型有点特殊它默认会读取项目根目录下的AGENTS.md文件作为上下文的一部分。superpowers 的技能要生效就得在这里把技能目录引用进去。我用的配置方式是在项目根目录新建一个AGENTS.md内容大致如下# 项目说明 这是一个基于 TypeScript 的 CLI 工具项目使用 pnpm 作为包管理器。 ## 技能加载 每次任务开始时先读取以下技能文件 - /usr/local/lib/node_modules/superpowers/skills/workflow/SKILL.md - /usr/local/lib/node_modules/superpowers/skills/build/SKILL.md - /usr/local/lib/node_modules/superpowers/skills/test/SKILL.md - /usr/local/lib/node_modules/superpowers/skills/fix/SKILL.md这里有两个关键点第一路径一定要写成绝对路径不要用~或者环境变量简写。我在实际操作中发现Codex CLI 对相对路径和 shell 风格路径的处理不算稳定有时候能加载有时候不能排查起来很头大。用绝对路径一次性解决。第二如果你的 npm 全局路径里有空格比如 Windows 下常见的C:\Users\Your Name\AppData\Roaming\npm\node_modules一定要用引号把路径括起来不然解析会出错。2.3 在 Trae Work 中安装 superpowers 的特别说明Trae Work 是字节跳动出的 AI IDE它本身也支持类似 Claude Code 的 skills 机制。superpowers 在 Trae Work 里的安装逻辑跟 Codex CLI 略有不同。先说结论Trae Work 可以读取项目目录下的.agents/skills文件夹。所以如果你在项目根目录创建.agents/skills/workflow/SKILL.md、.agents/skills/build/SKILL.md这种结构Trae 里也能识别并加载。但要注意Trae 的默认上下文管理跟 Codex CLI 不太一样。它不会自动读取AGENTS.md需要你在.trae/rules里配置或者通过对话中的“添加规则”功能。我建议你在 Trae Work 的项目设置里把技能目录和一个说明文件关联起来让 IDE 每次会话都先扫描一遍.agents/skills目录。另外Trae Work 对技能文件名的识别比较严格必须叫SKILL.md用其他名字会出现“技能存在但无法触发”的玄学问题。这一点我在实际工程里踩过后面排查表里会再提到。2.4 传统安装方式手动放置技能文件如果你不想装 npm 包或者项目对依赖管理有强制要求手动放置是最直接的办法。操作也很简单从 superpowers 的官方仓库下载最新 release 的 zip 包或者直接把仓库里的skills目录完整克隆下来。在项目根目录创建.agents/skills文件夹。把下载的技能子文件夹复制进去最终目录结构像这样.agents/ └── skills/ ├── workflow/ │ └── SKILL.md ├── build/ │ └── SKILL.md ├── test/ │ └── SKILL.md └── fix/ └── SKILL.md这种方式的优势是完全可控。你可以随意修改技能文件里的提示词不受 npm 包版本更新影响。缺点是后续官方如果更新了技能逻辑你需要手动同步否则容易版本漂移。我在一些需要严格供应链管理的团队项目里更倾向这种手动放置的方式因为可以把技能文件提交到 git 仓库里团队所有人共享同一套规则code review 时也能直接看到改了什么。2.5 安装后怎么确认技能被正确加载装完别急着干活先做一次“加载验证”。方法很简单在 Codex CLI 或者 Trae Work 里发一句指令例如先读取 workflow 技能然后帮我梳理一下当前项目里有哪些待办任务。如果 AI 的回答里出现了类似“我先按照流程规划然后逐个执行……”这样的结构化输出说明 workflow 技能已经生效。如果它直接开始列代码、给建议八成是没读到技能文件优先检查路径和文件名。更硬核的验证方式是直接在技能文件里临时加一行“如果读到这段话说明技能加载成功请在回复开头回复‘收到’”然后看 AI 回不回。这个方法笨但很有效排查配置问题时能省下大量时间。3. 核心技能拆解workflow、build、test、fix 到底在改 AI 的什么行为安装只是开始。真正有价值的部分在于理解这些技能文件里到底写了什么、为什么这么写。我花了不少时间逐行研读 superpowers 的技能提示词下面这节算是我自己的“阅读理解”。3.1 workflow让 AI 先长出“项目思维”workflow 技能是所有技能里最宏观的一个它要求 AI 在接到任务后不要急着写代码先做三件事分析需求明确目标、约束条件、交付产物。查看项目现有结构、已有测试命令、代码风格。生成有序的任务清单并在执行过程中边做边更新清单状态。听起来很简单但就是这简单的三步能改变 AI 的整个行为模式。没有这套流程时AI 接到“给登录模块加个验证码”这种需求可能直接就把图片验证码组件、后端接口、数据库字段全写了。有了 workflow它会先问你验证码类型、有效期、是否需要滑块校验然后列出一个包含 6-8 个小步骤的清单每完成一步就用task done标记让你随时能看见进度。从实现层面讲workflow 技能的关键是把“清单驱动”写进了规则。它不只是建议 AI“可以考虑列个计划”而是明确要求“每一步完成后跟用户报告进度然后再继续下一步”。这种强制性是它区别于一般提示词的核心。3.2 build把“小步快跑”写进编码规则build 技能是针对编码阶段的行为约束。核心规则我记得非常清楚每次只做一个小任务不要一次性写出一个 500 行的巨大变更。编写的代码要符合项目现有风格和规范。完成每一个小任务后先确认没有引入破坏性变更再继续下一步。如果发现当前方案不如预期及时向用户提出而不是硬着头皮写完。这里最反直觉的一点是它刻意限制 AI 的输出规模。很多人觉得 AI 一次性生成大段代码才是“强大”但实际工程里一次改动越大review 越困难出问题的概率越高出了问题也不好回滚。superpowers 让 AI 学会“增量交付”这种模式在我们做 code review 时体验尤其明显——每个 diff 都很小逻辑清晰出了问题能快速定位到具体提交。3.3 test用“无情的测试覆盖检查”逼出可交付代码test 是我最欣赏的一个技能。它不再简单说“请写测试”而是要求 AI先查看项目现有的测试命令和测试框架。针对当前改动识别出哪些是新功能逻辑、哪些是修改的既有逻辑。给出测试覆盖建议对于没有测试覆盖的新增代码明确标注“未覆盖”。如果项目里没有测试框架建立一个最小的测试环境再继续。这个技能背后对应了一个很实际的痛点AI 生成代码时如果提示词没说“测”它就默认不测。superpowers 的做法是把它从“可选项”变成“强制项”并且在交付完成前先输出一段测试覆盖报告让你看到哪些函数测了、哪些没测。有了这种明确的输出格式开发者对 AI 交付质量的信任度能提升一大截。3.4 fix给 AI 的“反复横跳”按下暂停键用过 AI 编程助手的人一定遇过这个场景某个测试挂了AI 改了一次另一个测试又挂了它再改结果把原来好好的功能也改坏了陷入死循环。fix 技能就是专门来收拾这个局面的。它规定在修复 bug 时AI 最多尝试几次我记得默认是三次如果三次之内仍未解决就停止操作把当前状态、已尝试的方案、失败原因全部汇报等待人工介入。它还要求 AI 在修复前先复现问题确认根因而不是凭感觉乱改。这个设计对项目安全性的保障非常实际。它承认了 AI 不是万能的并且用流程机制守住“不能无限破坏”的底线。在团队协作场景里这等于给 AI 装了一个熔断器避免它把好好的代码库搞得一团糟。3.5 这套技能组合的价值在于“边界清晰”单独看每个技能似乎都是“正常工程师会做的事”。但当它们组合在一起价值就体现出来了AI 的行为从不可预测变成了可预测从一次性交付变成了有节奏的迭代。我自己最直观的感受是在没有 superpowers 之前我每次让 AI 改完代码都要自己再跑一遍测试、看一遍 diff心理负担很重。用了这套技能之后AI 会自己把改动拆成小块配套测试和检查我只需要在它停下来报告时做最终确认。这种“AI 干活、人来验收”的协作方式才真正符合我对 AI 编程助手的预期。4. 不止于内置如何自定义 skill让 AI 真正适配你的团队superpowers 的第二层价值是它提供了一整套可复制的技能格式。也就是说你完全可以不局限于内置的 workflow、build 这些技能而是按照同样的格式写你自己的技能。这部分对团队落地特别有帮助。4.1 skill 的标准结构一个文件夹加一个 SKILL.md每个 superpowers 技能就是一个独立的文件夹文件夹里至少有一个SKILL.md文件。这个文件使用 Markdown 格式头部带一段 YAML frontmatter主要声明技能的元信息--- name: review description: 当需要做代码审查时使用。重点检查安全性、性能、可维护性并逐条输出问题清单。 ---然后是正文正文就是提示词的完整内容。这里有个核心技巧description 一定要写清楚触发场景越具体越好。因为 AI 在收到用户请求时就是靠 description 来决定要不要加载这个技能。如果你写得太宽泛AI 可能永远想不起来用它。4.2 实例给团队写一个“commit 规范”技能以我自己的团队为例我们要求所有 commit message 必须遵循 Conventional Commits 规范并且必须关联 Jira 单号。以前这个规则靠人肉提醒经常有人漏掉。后来我写了一个commit技能--- name: commit description: 当用户要求提交代码、生成 commit message 时使用。严格遵守 Conventional Commits 规范并以 Jira 单号为前缀。 --- # Commit 规范 1. commit message 格式 type(scope): subject 例如feat(auth): add login captcha 2. type 只能使用以下取值 - feat: 新功能 - fix: 修复 bug - docs: 文档变更 - style: 格式调整 - refactor: 重构 - test: 测试相关 3. 如果用户没有提供 Jira 单号主动询问。 4. 禁止直接使用 git commit -m update 这种无意义信息。把这个文件放到.agents/skills/commit/SKILL.md目录下然后在 AGENTS.md 里加一行引用。从此以后团队里任何人用 Codex CLI 提交代码AI 会自动按规范生成 commit message。这种“把团队规范变成 AI 默认行为”的能力是 superpowers 最被低估的价值。4.3 在 AGENTS.md 和 CLAUDE.md 里引用自定义技能的注意事项如果你同时用 Codex CLI 和 Claude Code 这类工具注意它们的记忆文件名不同一个是AGENTS.md一个是CLAUDE.md。最好的做法是让两份文件内容保持一致并且都指向同一个技能目录比如.agents/skills。这样无论 AI 助手走哪个入口加载的技能逻辑都是一样的。实际操作里有个细节两个工具对技能目录层级的要求不完全一致。Codex CLI 能直接扫描整个.agents/skills目录但 Claude Code 更倾向于在CLAUDE.md里明确列出要使用的技能文件路径。所以建议你在AGENTS.md里写“遍历目录自动加载”在CLAUDE.md里写“列出具体路径按序加载”这样能尽量规避兼容性问题。4.4 技能开发的两个原则一次只做一件事规则要能被执行最后分享两个写技能时很重要的原则也是我在反复修改技能文件过程中总结出来的。第一个原则是技能职责单一。一个技能只处理一类场景别试图写一个“万能技能”把什么都管了。比如 commit 技能就别管代码风格code review 技能就别管环境部署。混在一起会让 AI 在决定“该不该加载”时疑惑触发准确率下降。第二个原则是每条规则都能被 “检查”。也就是说不要写“保证代码质量”“注意性能”这种抽象的表述而要写“如果新增逻辑必须附上对应的测试用例”“如果查询数据量可能超过 1000 条必须加上分页”。AI 对抽象要求没有执行力但对可验证的指令有很高的遵循率。一条技能规则好不好就看你能不能照着它设计一个 checklist 来验收。5. 使用 superpowers 一段时间后的心得与常见问题排查最后这部分我把自己实际使用中遇到的典型问题、排查过程和一些个人体会整理出来希望能帮你少走弯路。5.1 问题排查速查表按现象找方案现象可能原因解决办法技能完全不生效AI 行为和没装一样AGENTS.md 里路径写错或者技能文件名不是 SKILL.md检查路径是否为绝对路径确认文件名严格为 SKILL.md重新加载会话只在某些项目生效换个项目就不行技能文件没有复制到新项目目录最好在项目模板里内置 .agents/skills 目录用模板创建新项目AI 能读技能但经常选错技能description 写得太模糊多个技能描述相互覆盖重新写每个技能的 description尽量包含触发关键词和场景条件技能加载后 AI 反而变“啰嗦”输出太长技能提示词里“报告进度”的要求太多削减每个技能里的进度汇报频率保留关键节点即可Windows 下路径解析失败路径里有空格或中文转义没处理好用引号包裹路径或者把技能文件放到项目目录内使用相对路径npm 全局包更新后技能消失全局目录被包管理器重置改用项目级安装或手动放置技能文件并纳入 git 管理5.2 经验技巧把技能文件纳入版本管理统一团队基线我强烈建议把.agents/skills和AGENTS.md一起提交到 git 仓库里。这样做有几个好处一是团队所有成员共享同一套 AI 工作规范不会出现你配了一套、同事配了另一套的混乱二是技能文件的变更可追溯哪天 AI 行为突然变了可以跑git diff查看是谁改了什么三是新成员加入项目后只要拉代码就能无缝获得全部规则不用单独培训。我们团队在实际使用中还做了一层扩展就是把已经验证过的好用技能同步到公司内部的模板仓库里。新项目一律从模板创建天然带上这套技能配置等于所有项目从第一天起就站在同一个质量基线上。5.3 避坑指南不要把 superpowers 当成“免死金牌”需要强调的一点是superpowers 不能替代代码审查更不能替代开发者对代码的最终责任。它只是把 AI 的行为从“自由发挥”拉回到“有流程约束”但 AI 生成的东西依然可能有逻辑漏洞、性能问题、安全隐患。我在团队里推广时反复强调技能加载、测试通过、流程完整不等于产品可上线该做的 review、该做的性能测试、该做的安全扫描一步都不能少。另外也别天真地以为装了固定技能就可以把所有型号的模型套上去。我在实际测试中发现不同模型对技能提示词的遵循率差异很大。逻辑能力强的模型比如 Claude 系列、GPT-5 系列执行得比较到位轻量模型有时候会在流程中“跳步”。所以如果你发现某台设备上效果不佳不要先怀疑技能先检查模型本身的输出能力。5.4 最后再分享一个我最近的扩展玩法前面说的都是让别人写的技能最近我开始尝试把团队的代码评审规范和部署检查清单也做成技能。做法就是把那些原本写在 Notion 文档里的规则一条条改写成可执行的指令放进.agents/skills目录。这样无论是谁用 AI 写代码AI 都会在交付前自动对照这些规则做一轮自我检查。目前实测下来这个方法对团队规范落地的帮助非常明显。以前新人的代码要反复 review 才能符合规范现在 AI 在生成阶段就按规范走review 的负担小了很多。我也慢慢意识到superpowers 这套东西最值钱的地方不在于那几个默认技能而在于它给了你一个“把经验沉淀成技能”的标准格式。你团队里十条鲜活的踩坑经验一旦变成技能文件就能在每次 AI 工作时自动替你提醒自己和队友这份复利比任何提示词技巧都来得实在。