superpowers技能包：让Codex CLI编码智能体告别乱冲，按流程开发

我最早对 superpowers 这个项目产生兴趣完全是出于一个很现实的痛点让 Codex CLI 干活活儿是干了但过程像开盲盒。运气好的时候它改一行代码顺手补个测试运气差的时候它能为了加个按钮给你重写整个模块而且从头到尾不跟你商量一句。模型能力本身没有问题问题在于它缺少一套做事的方法论——什么时候该问清楚需求什么时候该先写计划什么时候该停下来跑测试。superpowers 这个开源项目解决的就是这个问题它给 Claude Code、Codex CLI、Trae 这类编码智能体装上了一套工程技能包让 AI 干活的方式从凭直觉乱冲变成按流程推进。这篇文章我不打算写成像 README 翻译那种东西而是从实际使用的角度把这套东西拆开讲清楚它的工作原理是什么、在 Codex CLI 里怎么装、内置技能有哪些、日常开发里怎么真正用起来、怎么给自己写定制技能以及我踩过的几个坑。如果你最近正在研究怎么让终端里的智能体更可控这篇应该能帮你省不少时间。1. 编码智能体为什么需要技能包这种东西1.1 模型的通病不是笨而是没有章法先聊一个很普遍的现象。你用 Codex CLI 或者任何 AI 编程工具时给它一个任务它确实能完成但经常表现出三个毛病需求理解得不够深拿到一句话就开始写代码写到一半发现方向错了推倒重来。不写测试或者写完代码之后象征性补一个测试根本不关心覆盖率和边界情况。遇到 bug 靠猜改一个变量试试不行再改另一个运气好碰对了运气差越改越乱。这其实不是模型能力问题而是缺少流程约束。一个资深工程师拿到需求第一反应是先确认边界条件、再拆解任务、然后写测试、最后实现。AI 没有这个习惯除非有人用明确的方式告诉它你应该按这个流程来。superpowers 做的事情就是把资深工程师的这套工作方式沉淀成一份份可以被 AI 按需加载的技能。1.2 superpowers 的核心理念把工程方法论搬进 Agent这个项目的作者是 Jesse VincentGitHub 上仓库名就叫 obra/superpowers。它的定位很明确不是给 AI 灌更多知识而是给 AI 一套行为规范。就像给新入职的工程师发一本团队工作手册里面写了需求澄清怎么开代码评审怎么过bug 怎么定位而不是把整个代码库塞进它脑子里。这套东西之所以叫 superpowers我觉得有两层含义。表层含义是这些技能确实让 AI 变强了深层含义是它把人类工程师最值钱的那部分——不是写代码的能力而是怎么组织工作、怎么保证质量的能力——复制给了 AI。这也是我认为它比单纯的提示词工程更有价值的地方它是一套可复用、可扩展、可沉淀的机制。所以就引出了下一个问题这套机制到底是怎么运转的。2. Skill 机制拆解渐进式披露是怎么工作的2.1 一个技能就是一个目录加一份 SKILL.mdsuperpowers 里的每个技能本质上就是一个文件夹里面最重要的是一份名为SKILL.md的 Markdown 文件。这个文件遵循目前各家 Agent 通用的技能规范头部用 YAML frontmatter 写元信息正文写具体的操作指导。一个典型的技能目录长这样~/.codex/skills/ ├── superpowers/ │ ├── SKILL.md │ └── ... ├── brainstorming/ │ ├── SKILL.md │ └── ... ├── writing-plans/ │ ├── SKILL.md │ └── ... └── tdd/ ├── SKILL.md └── ...SKILL.md里 frontmatter 的核心字段是两个name和description。description特别关键它决定了 Agent 在什么情况下会主动想起加载这个技能。举个例子systematic-debugging这个技能的 description 大概会写当程序出现异常、测试失败、需要定位 bug 根因时使用这样 Agent 在遇到报错时就会自动去翻这个文件里的排查步骤。正文部分就是具体的操作指令了。拿writing-plans来说它会告诉 Agent先理解需求拆解成可执行的步骤明确每个步骤的产出物和验证方式最后把计划写进一个文件里并且每完成一步就更新进度。本质上就是一份给 AI 看的项目管理流程。2.2 按需加载不是把说明书糊在脸上这套机制里最聪明的设计是渐进式披露。什么意思如果你把一份五千字的工作手册全文塞进 Agent 的上下文它反而会迷失重点——上下文一长注意力就被稀释了。superpowers 的做法是把技能拆得很细每个技能只负责一件事。Agent 启动时看到的只是一个简短的技能索引知道有哪些技能可以用各自是干什么的。当实际对话中遇到了匹配的场景它才会去读取对应技能里的详细步骤。这就像你家里有一个工具箱你不会把电钻说明书贴在脑门上而是要用的时候才打开抽屉拿出来看。这种设计带来的直接好处是上下文可控。Agent 的工作记忆是有限的技能按需加载就能把宝贵的上下文空间留给真正重要的东西——你的项目代码和当前任务。2.3 Codex CLI / Claude Code / Trae 的技能目录目前主流支持技能机制的 Agent各自的技能存放目录并不完全一样。我实际接触下来是这样的Agent技能目录说明Claude Code~/.claude/skills/也可以用/plugin marketplace方式安装Codex CLI~/.codex/skills/近期版本内置支持 skills 规范Trae跟随 IDE 的用户配置目录Agent 设置里可以配置技能目录好消息是 superpowers 的安装脚本会自动检测你机器上装了哪个 Agent然后把技能放到对应的位置去不需要你手动去记这些路径。这个我下面会具体讲。3. 在 Codex CLI 里装好 superpowers脚本与手动两种方式3.1 安装前要满足的环境条件先别急着跑命令确认三件事你已经装好了 Codex CLI并且完成登录认证能在终端里正常跑codex命令。Node.js 版本不要太老建议 18 以上。Codex CLI 本身依赖 Node 运行时版本太老可能连 Agent 自己都起不来。你的项目目录里有代码最好是 Git 仓库。因为 superpowers 里好几个技能比如 git worktree 相关的那套都依赖 Git。这些条件不满足的话后面装完也用不起来容易误以为是 superpowers 的问题。3.2 一键安装脚本做了什么superpowers 仓库里提供了一个安装脚本用法很简单curl -sSL https://raw.githubusercontent.com/obra/superpowers/main/install_superpowers.sh | bash我强烈建议你在跑之前先看一眼脚本内容别养成直接管道执行的习惯。你可以先把脚本下载下来curl -sSL https://raw.githubusercontent.com/obra/superpowers/main/install_superpowers.sh -o install_superpowers.sh less install_superpowers.sh脚本做的事情大致是检查你系统里装了哪些支持的 Agent然后从 GitHub 拉取 superpowers 仓库再把skills/目录下的所有技能复制到对应 Agent 的技能目录里。整个过程是幂等的也就是说重复执行不会出问题只会把新增的技能补进去。装完之后检查一下ls ~/.codex/skills/正常的话你会看到一溜技能目录superpowers、brainstorming、writing-plans、executing-plans、tdd、systematic-debugging、code-review、using-git-worktrees等等。看到这些目录安装就算成功了。如果你用的是 Trae脚本同样会检测出来把技能放到 Trae 的对应目录。这个对国内用 Trae 的朋友比较友好不需要自己折腾路径。3.3 手动安装和验证有些环境里脚本跑不通比如网络受限、或者你不想用管道执行远程脚本手动装也就三条命令的事git clone https://github.com/obra/superpowers.git mkdir -p ~/.codex/skills cp -r superpowers/skills/* ~/.codex/skills/装完之后别忘了验证技能真的被 Agent 感知到了。你可以在 Codex CLI 里直接问一句你有哪些技能分别在什么场景下会使用如果 Agent 能准确列出writing-plans、tdd、systematic-debugging等技能以及各自的使用场景说明已经生效。如果它一脸茫然多半是技能目录放错了位置或者 Codex CLI 版本太老不支持技能机制先升级再说。代码项目里还可以配合AGENTS.md文件使用。Codex 会读取项目根目录下的AGENTS.md作为项目级的行为准则你可以在里面写一句涉及多步骤需求时请先加载 writing-plans 技能这样相当于把技能激活规则也固化到项目里了。4. 内置技能包全景哪些技能最值得在项目里用起来4.1 先看一张全景清单我根据自己的使用频率把目前内置的技能整理成了下面这张表技能名适用场景我的使用频率superpowers元技能定义 Agent 的总工作原则始终生效brainstorming需求模糊、方案未定时做头脑风暴高writing-plans明确要做什么之后拆解执行计划高executing-plans按照既定计划一步步执行并跟踪进度高tdd需要用测试驱动开发的场景高systematic-debugging排查 bug、定位失败的根因极高code-review审查代码变更、找潜在问题中using-git-worktrees需要并行开多个分支时低这几个技能不是孤立的它们之间是有配合关系的。brainstorming负责把模糊需求理清楚writing-plans负责把清楚的需求拆成步骤executing-plans负责落地tdd和systematic-debugging贯穿在落地过程中保证质量。4.2 writing-plans让 Agent 先想后做我最早被这个项目打动就是因为writing-plans。装了 superpowers 之后你给 Codex 派一个稍微复杂点的需求它不再直接开写而是先问你几个关键问题然后生成一份计划文件里面分好了步骤每一步标了目标、改动范围、验证方式。执行过程中每完成一步就回来更新计划进度。这个体验上的差异是非常明显的。以前它闷头写半小时交给你一堆没法 review 的代码现在它先把路线图摊开给你看你觉得哪里不对可以立刻让它调整。这本质上是把不可控的 AI 黑盒变成了可协商的协作过程。4.3 tdd 和 systematic-debugging质量与排查的双保险tdd技能要求 Agent 严格走红-绿-重构循环先写一个失败测试再写最小实现让测试通过最后做重构。我实测下来这个技能对 Agent 的约束力很强能明显减少代码跑通但没测试兜底的情况。systematic-debugging则是另一个我离不了的功能。它要求 Agent 不要靠猜来修 bug而是先复现问题、圈定范围、二分定位、找到根因、修复、再验证。装了这个技能之后Codex 遇到报错时会先问你要复现步骤然后自己加日志去定位而不是上来就改代码。这个变化对生产项目的安全性太重要了。4.4 brainstorming 和 code-review不在代码编写期但同样关键brainstorming适合在需求还很模糊的时候用。比如你说我想给项目加个搜索功能它不会直接开写而是会跟你讨论搜索的实现方式数据库 LIKE 还是 Elasticsearch、排序策略、分页方式等等把方案敲定之后再往下走。这其实替代了传统团队里技术方案评审的那一步。code-review技能会以一个挑剔的 reviewer 视角去审视你的代码变更找边界条件、并发问题、安全隐患。我习惯在准备提交 PR 之前让 Codex 先自己 review 一遍提前把低级问题过滤掉再交给同事看双方都轻松不少。5. 一次完整走查从一句模糊需求到一行行可合入代码5.1 一个实际例子给项目加用户登录我用一个实际场景把这套东西串起来。假设你的项目是一个 Web 服务你想让 Codex 加一个用户登录功能。没有 superpowers 的时候你得到的可能是一大坨代码包括模型、路由、中间件、前端页面全塞在一个回答里。装了 superpowers 之后我的实际体验大致是这样的流程第一步Agent 加载brainstorming技能向你确认几个问题登录用邮箱还是手机号密码方案还是 OAuthSession 还是 JWT需不需要注册接口如果你只回了邮箱密码登录JWT它会继续追问 token 有效期、刷新机制这些细节。这一步看着啰嗦但能避免 80% 的方向性返工。第二步需求清楚之后Agent 加载writing-plans生成一份类似这样的计划文件# 用户登录功能实施计划 1. 创建 users 表迁移字段id, email, password_hash, created_at 2. 实现用户注册接口 POST /api/register 3. 实现登录接口 POST /api/login签发 JWT 4. 实现认证中间件校验 Authorization header 5. 编写上述接口的集成测试 6. 更新 API 文档每一条都有明确的验收标准。你确认之后它才开始动手。第三步执行阶段加载executing-plans和tdd。它会先写测试再写实现每个步骤完成之后回来更新计划把已完成项勾掉。这一步你能实时看到进度不用干等。第四步全部完成之后它会主动跑一遍测试套件然后加载code-review技能自查一遍自己的代码最后才把结果汇总给你。5.2 这个过程背后的机制是什么你可能会问它怎么知道该在哪个阶段用哪个技能答案就是前面说的description匹配机制。Agent 每接收一条新信息都会在心里过一遍当前的情况匹配哪个技能的使用条件匹配上了就去加载对应的SKILL.md按里面的指示行动。所以 superpowers 真正的工作方式是技能调度。这是它和其他提示词方案最大的区别。不是一次性给你一堆规则而是像操作系统调度进程一样根据任务状态决定接下来跑哪个程序。5.3 这套流程的适用边界我不是说这套流程适合所有场景。像帮我改个变量名把这个报错修一下这种小任务直接做就好不需要走完整套流程。superpowers 的设计也有这个意识——技能是按需加载的小任务一般不会触发那些重型技能Agent 会根据任务复杂度自己判断。但它特别适合两类场景一是多步骤功能开发二是需要长期维护的正式项目。如果你的项目只是临时脚本、写完就跑那这套流程反而显得笨重。6. 自己动手写技能数据库迁移技能从 0 到 16.1 什么时候值得自建技能内置的技能是全行业的通用方法论但每个团队都有自己的土规矩。比如你们团队约定所有数据库变更必须同时提交回滚迁移、所有对外接口必须带请求日志、所有 Redis key 必须带项目前缀……这些约定如果只存在于文档里Agent 是不知道的。把这些团队规范写进一个自定义技能是让 Agent 真正融入团队的最佳方式。它相当于把团队代码规范从一个被动文档变成了 Agent 的主动行为约束。6.2 手写一个 database-migrations 技能我拿一个实际例子演示。假设你们团队对数据库迁移有严格规范那就可以建一个database-migrations技能mkdir -p ~/.codex/skills/database-migrations然后在里面创建SKILL.md--- name: database-migrations description: Use when creating or reviewing database schema changes, writing migration files, or evaluating the safety of a migration plan --- # Database Migrations ## 核心原则 - 所有迁移必须同时包含 up 和 down 两个方向保证可回滚。 - 禁止修改已经应用到生产环境的迁移文件。 - 大表变更必须评估锁表风险优先使用分批迁移。 ## 操作步骤 1. 首先检查 migrations 目录下是否已有同名或相似迁移。 2. 编写迁移文件遵守团队命名规范YYYYMMDDHHMMSS_description.sql。 3. 同时编写 down 迁移。 4. 在本地环境执行迁移确认 through 后运行 migrate:rollback 验证回滚。 5. 完成后在 PR 描述中列出迁移的风险评估。写完之后在 Codex CLI 里测试请使用 database-migrations 技能帮我把 users 表的 email 字段加上唯一索引先给出迁移方案。如果 Agent 会主动要求你提供 down 迁移、提醒你锁表风险说明技能已经被正确加载并理解了。6.3 验证技能生效的两个技巧写完技能最怕的是什么是 Agent 根本没读到。我分享两个验证技巧。第一直接问有没有这个技能。在会话里问列出你能用的所有技能看它是否包含database-migrations。第二看行为而不是看回答。有时候 Agent 嘴上说我知道这个技能实际干活的时候并不按里面的规范执行。这时候我会故意给它一个违反规范的任务比如让它直接改一个已应用的迁移文件如果它拒绝或者纠正你说明技能真正内化了如果它照做不误那就像我给老板汇报——听到了但没听进去得检查技能的触发描述是不是写得太模糊。7. 使用一个多月后的坑与心得7.1 最常见的三个翻车场景先说坑给大家排雷。第一个坑是技能目录放错。有一次我手动装技能cp的时候把skills目录整个复制成了~/.codex/skills的子目录结果变成了~/.codex/skills/skills/xxxAgent 一个技能都识别不到。检查方法很简单看ls ~/.codex/skills/里面是技能目录还是嵌套的skills文件夹。第二个坑是描述写得太抽象。我自己写技能的时候description写过Use when dealing with database stuff结果该触发的时候完全没触发。后来改成Use when writing or modifying migration files, adding indexes, changing columns触发的准确率一下就上来了。description就是技能的触发条件它越具体Agent 的调度就越准。第三个坑是过度约束导致效率下降。我一开始给 Agent 装了满满一整套技能期望它能变成完美工程师。结果它每干一件小事都要加载一堆流程改一行注释都要停下来按计划执行反而低效。后来我理解了技能机制的核心是让 Agent 自己判断复杂度所以我把团队规范里真正重要的几条写进去其余砍掉反而效果更好。7.2 与团队已有流程的配合还有一个比较深的体会superpowers 不是来替代你现有开发流程的它是让你的 Agent 先学会遵守流程。我们团队之前有完整的 PR 评审规范但 Agent 提的 PR 经常不按要求写描述、不附测试结果。后来我把 PR 规范写成一个pull-request技能AI 每次提 PR 都会自动按模板写描述、附测试输出。研发同学再也不用追着它补文档了。相比之下如果只是口头提醒你以后提 PR 规范点效果约等于零。技能机制的优势就在这里它是一种结构化的、可被 Agent 主动读取和遵守的规范载体比任何对话里的临时要求都可靠。7.3 我的建议如果你现在正在用 Codex CLI 或者其他支持技能的终端 Agent我建议你先从最小闭环开始装上 superpowers用默认技能跑一个星期的真实任务重点观察writing-plans和systematic-debugging对你工作流的改变。等熟悉了技能的运行逻辑之后再试着把团队里最痛的规范沉淀成自己的技能。最后再分享一个小技巧技能的版本管理也值得做。我一般把团队自定义的SKILL.md放进一个单独的 Git 仓库跟代码仓库分开管理。这样技能更新有历史记录同事之间也能共享新成员入职之后拉下来放到自己目录里就能用。这大概是这套机制里投入产出比最高的一件事了。