Superpowers实战：用技能包让Codex CLI从“会说话”到“会干活”

这是一个让我挺兴奋的题目。先说下背景，我最近半年基本把主力开发环境从IDE搬到了终端，日常写代码、做重构、提交PR都用Codex CLI这类AI编程工具在跑。工具用久了，我逐渐发现一个问题：AI能听懂人话，但做起事来总差那么点“专业感”——让它改一个方法，它就只改那个方法；让它写个功能，它连测试都不写就给我端上来。直到我发现了Superpowers这个开源项目，才真正解决了“AI会说话但不太会干活”的毛病。

如果你也在用Codex CLI、Claude Code这类编程代理，或者你所在团队正打算把AI接入日常研发流程，那这篇文章值得你看完。我会从安装部署、核心机制、实际效果到踩坑记录，完整分享我这段时间的使用心得，最后再聊一聊如何为团队自定义自己的“技能包”。

1. Superpowers到底在解决什么问题：AI助手“会说话但不会干活”的困境

1.1 为什么Codex、Claude Code这类工具离“资深工程师”还有距离

先聊个现象。很多人第一次用Codex CLI的时候，会觉得它很聪明，让它写个排序算法、写个爬虫，它都能秒回。但真正落到项目里，你会发现它的工作方式更像一个“响应式实习生”：你说什么，它就做什么，做完了就停，不会主动考虑边界条件，不会去翻项目里已有的约定，更不会在提交代码前列出测试清单。

我用Codex CLI做过一次重构，明明提前告诉它“先分析依赖关系，再设计迁移方案”，结果它第一轮就直接动手删改代码，把模块引用全部改崩了。问题出在哪？不是模型能力不够，而是模型缺少一套“行为规范”——就像一个新入职的工程师，如果他没看过团队的工作手册，他做事的方式就是随机的。

1.2 Superpowers的破解思路：把经验变成技能包

Superpowers这个项目，本质上做了一件事：把资深工程师的工作方法论，封装成机器可读、AI可遵循的“技能包”。它不是一条复杂的提示词，也不是一个对话模板，而是一堆结构化的Markdown文件，每个文件对应一个技能，比如做代码审查、写提交信息、处理Git工作流、做技术规划。

说得再直白点，这就像你在给AI一本“工作手册”。每个技能包里包含三样东西：触发条件、执行步骤、检查清单。AI在开始干活之前，会先查阅这些技能包，然后按照里面的流程一步步执行。这样一来，它就不再是“想到哪做到哪”，而是一个有章法的执行者。

我最开始用的版本还比较原始，需要自己在AGENTS.md里写一堆配置，现在项目结构已经成熟很多了，默认的Skills Explorer技能会自动扫描技能目录，把可用的技能清单交给AI自己判断。这就是Superpowers能火起来的核心原因——它把“调教AI”的门槛，从写长长长的系统提示词，降到了会写Markdown文档。

1.3 它和普通prompt、rules文件的本质区别

很多人会问：我自己在项目里写一个RULES.md，效果不是一样的吗？还真不一样。

普通的rules文件是“静态约束”，相当于你告诉AI“不要做什么”“应该做什么”，但它没法告诉AI“具体怎么做”。而Superpowers的技能包是“动态流程”，它把做事的完整路径写出来了——比如“先读SERP文件，再跑测试，最后逐条对照检查”。AI拿到技能包之后，是真正在“按流程执行”，而不是在“受约束地自由发挥”。

另一个区别在于技能包的可组合性。一个Superpowers项目里可以同时装几十个技能，AI会根据当前任务自动调用不同的技能组合。比如你让它“新增一个用户注册接口”，它会同时参考“规划技能”“测试驱动技能”“提交信息技能”，整个过程接近一名工程师的真实工作流。而普通的rules文件，一旦长了，AI根本不会全部读，或者读了也不知道什么时候该用哪条。

2. 环境准备与安装：三条路线该怎么选

2.1 前提条件：Node.js、Codex CLI、Git的检查清单

在开始之前，先把环境梳理一遍。Superpowers主要是为Codex CLI设计的（目前也支持Claude Code），所以前提条件很明确：

• 你的机器上装了Node.js，版本最好在18以上，否则npx可能跑不起来
• 你已经安装并登录了Codex CLI，能正常发起对话请求
• Git已经就绪，因为很多技能包会用到Git命令
• 如果你用的是Claude Code，需要确认版本支持external plugins机制

我当时卡在Node版本上，因为用的是系统自带的Node 16，运行安装命令直接报语法错误。后来用nvm切换到了Node 20，一路顺畅。所以建议你在安装前先跑一句node -v和npm -v确认基础环境，别一上来就装，装到一半报错再回头排查很浪费时间。

2.2 三条安装路径与个人推荐

Superpowers的安装方式有三种，我逐一试过，各有适用场景：

我的建议是：个人开发用全局安装，因为方便，一次配置全部生效；如果你的团队有多个项目且规范不一致，就用项目级安装，把技能包连同AGENTS.md一起提交到仓库里，新人克隆下来就自带规范。我自己现在是全局安装为主，但对不同的项目做了单独的skill筛选。

需要注意的点：全局安装时，Superpowers会往~/.codex/目录写入AGENTS.md，并创建默认的skills目录。如果你的~/.codex下已经有自定义的AGENTS.md，安装脚本会先备份再合并，这点做得比较稳妥，我后面会讲一个和它相关的坑。

2.3 安装后立即检查的文件：AGENTS.md和skills目录的作用

安装完成后，不要急着就开始对话，先花两分钟看下文件结构。在~/.codex/下你应该能看到：

• AGENTS.md：这是Codex CLI的全局行为配置文件，Superpowers会把工作流描述写在这里，AI每次对话都会自动读取它
• skills/目录：这是默认技能包的存放位置，里面是若干个Markdown文件
• skills/skills.json（或类似的清单文件）：这是技能的索引，Skills Explorer技能会依靠它来扫描和选择技能

我的习惯是安装后马上打开AGENTS.md看一眼，确认里面提到了skills/目录路径和触发方式。如果看不到这两块内容，说明安装脚本没有正确写入，需要重新跑一次或者手动补上。

3. 核心机制拆解：技能包、Skills Explorer与AGENTS.md的联动

3.1 一个技能包到底长什么样：以clean-code为例

技能包是整个Superpowers的灵魂。我拿默认的clean-code技能举例，它的Markdown结构非常有代表性：

--- name: clean-code description: 在修改代码前先学习清洁代码规范，确保改动符合可读性与可维护性标准 --- ## 适用场景 当你需要修改、重构或新增代码时，先阅读本技能要求。 ## 执行步骤 1. 阅读项目现有代码的组织结构 2. 对照清洁代码的12条核心原则逐项检查 3. 若发现明显违反原则的写法，在改动时一并优化 4. 提交前使用检查清单逐条自查 ## 检查清单 - [ ] 函数是否只做一件事？ - [ ] 变量命名是否准确表达语义？ - [ ] 是否有重复代码可以抽取？ - [ ] 缩进与项目风格是否一致？

看明白了吗？技能包的核心不是知识本身，而是行为流程。它不会长篇大论讲什么是变量命名，而是告诉AI“你在做这个任务时，应该按什么顺序做、每步做什么、最后检查什么”。模型本身就具备判断代码好坏的能力，Superpowers做的只是把它工作的顺序和标准固定下来。

3.2 Skills Explorer：让AI学会“先查书再动手”

Superpowers内置的Skills Explorer是它最巧妙的设计。它的工作机制大致是：当AI收到一个任务时，会先通过AGENTS.md里配置的指令，去读取skills/目录下的索引文件，看看有哪些技能可用，然后根据任务性质选择要参考的技能包，再开始实际编码。

这个“先查书再动手”的机制，看似多了一步，实际效果却非常好。我做过对照实验：同一个任务，未接入Superpowers的AI直接给出答案；接入之后，AI会先输出一句“这个任务涉及代码重构，我将参考clean-code技能包”，然后才动手。虽然响应速度会慢一丢丢，但代码质量明显上了一个台阶，尤其是代码风格一致性方面。

3.3 AGENTS.md是总调度：为什么hooks顺序对最终结果很敏感

如果说技能包是“书”，那AGENTS.md就是“图书管理员”，它负责告诉AI：在什么阶段应该查阅哪本书。Superpowers在AGENTS.md里配置了一组hooks，每个hook对应一个工作阶段，比如开始任务时运行planning，修改代码前运行clean-code，提交前运行commit-message。

这里有个经验：hooks顺序很关键，不同顺序得到的输出差异非常大。比如，如果让AI先跑测试驱动开发技能再跑规划技能，它可能会一头扎进测试代码里，忽略了整体架构；反过来先做规划再写测试，整个节奏就顺畅了。

如果你不确定当前的顺序是否合理，我建议在修改AGENTS.md时，每次只调整一个hook的位置，跑一遍任务看效果，再决定下一步。千万别一次性改三四个顺序，出了问题你根本不知道是哪一步导致的。

4. 实测：用superpowers跑一轮“代码审查+重构”任务

4.1 让AI先做规划再动手的效果对比

我拿一个真实项目做了测试：一个Spring Boot的Java后端服务，代码量大概3万行，里面有几个类的职责已经混乱了，Service层和Utils工具类互相调用，看起来挺头疼。

第一轮测试，我用原生的Codex CLI直接下达指令：“帮我重构UserService这个类，让它更清晰”。AI的处理方式是：直接开始分析UserService里的方法，然后把几个方法拆到别的类里，甚至自己臆想了一些接口。等我一跑测试，好几个引用全断了，只能回滚。

第二轮，我接入Superpowers后，同一个指令。AI在动手之前先输出了自己的行动计划：先阅读相关技能包，再梳理UserService的依赖图，然后列出重构清单，最后逐项执行并运行测试验证。实际跑下来，虽然AI还是不能完美理解业务，但它输出的每一步都有依据，我随时可以中断、调整，整个过程的“失控感”少了很多。

4.2 Java项目专项实测：效果和注意点

因为热词榜上“superpowers java”的搜索量很高，我多说几句Java场景下的实测。Superpowers的技能包语言虽然是英文为主，但对Java项目的适配没什么问题，它关注的是流程，不是语言。

我在一个遗留的Java 8项目中接入了Superpowers，发现它有两个明显的优势，也有一个需要注意的地方。

优势一是代码风格的一致性：让它往一个工具类里新增方法时，AI会自动沿用项目里已有的日志规范、返回类型风格，而不是自作主张生成一些“教科书式”但和项目格格不入的代码。优势二是对测试的重视：因为技能包里强制了“先写测试再写实现”的流程，AI在新增功能时，会自动生成对应的JUnit测试，这几个测试的质量还不低。

需要注意的地方是：技能包可能会建议AI做一些现代化的代码改造，比如推荐函数式写法，但你的项目可能还是Java 7/8的老风格，混写会让代码变得很难看。我的解决办法是在项目的技能包描述里，明确加上一句“保持项目现有语法风格，禁止大规模现代化重构”，AI就会老实很多。

4.3 实测中我发现的行为差异点

最后总结一下实测中的行为差异，这里列出几个非常明显的对比：

这里最让我惊喜的是最后一条。以前我总抱怨AI“不问清楚就做”，接入之后它居然学会了“反向确认需求”。这对于代码生成工具来说，是很关键的一步。

5. 你以为装完就完了？我踩过的四个坑

5.1 坑一：skills目录没有生效，AI完全无视技能包

第一次接入Superpowers时，我遇到的最诡异的问题是：AI对我的所有指令都正常响应，但完全无视技能包的存在。排查了很久，最后发现是因为我的Codex CLI版本比较老，还不支持自动读取多个技能目录，AGENTS.md里引用了skills路径但没有实际注入到上下文。

解决办法有两个：一是升级Codex CLI到最新版；二是在AGENTS.md里显式声明“在每次任务开始前，必须读取skills/目录下的技能清单”。如果你用的是旧版本，我建议优先升级，因为技能清单的自动检索机制在老版本上体验差很多。

5.2 坑二：AGENTS.md被全局配置覆盖，行为“倒退”

这个问题出现在我切换到~/.codex/目录之外的另一个项目时。项目里有自己的AGENTS.md，但内容很简单，它没有继承全局的Superpowers配置，导致AI在那个项目里的表现一下子倒退回了“原始状态”。

原因在于Codex CLI加载AGENTS.md的优先级是：全局配置和项目配置会叠加，但如果项目配置里定义了同名指令，就可能会覆盖全局的。我当时在项目里写了“你是一个简洁的工程师，直接给答案”，这句和Superpowers的流程化协作方式冲突了，导致技能包全部失效。

后来我把项目的AGENTS.md改成只描述业务背景，不做行为设限，全局Superpowers配置就能正常生效了。如果你有多个项目，建议统一规范项目级AGENTS.md的写法，尽量避免和全局配置冲突。

5.3 坑三：自定义技能包格式不匹配，Explorer扫描不到

Superpowers默认带了一批技能包，但你完全可以自己加。我第一次尝试自定义技能包时，直接在skills目录下新建了一个.md文件，写得很随意，没有frontmatter。结果Skills Explorer始终不认它，运行时根本不提这个技能。

研究了一下才发现，技能包的文件名、frontmatter字段都是有固定格式的。至少要包含name和description两个字段，而且文件名最好和技能名一致。我加上frontmatter之后，技能立刻就能被扫描到了。所以如果你自己写技能包，务必先复制默认技能包的文件，在它的基础上改，不要另起炉灶。

5.4 坑四：多项目并行时技能包互相污染

如果你像我一样同时维护好几个项目，你可能会遇到这个问题：项目A的技能包里要求“每次改动前必须写测试”，项目B的技能包里要求“快速原型，不强制测试”。当你在两个项目目录之间切换时，Codex CLI有时会把项目A的上下文带到了项目B。

这是因为Superpowers虽然是按项目存储技能包的，但它有一个全局的上下文缓存机制。你需要在切换项目时，主动清空对话会话，或者开启隔离模式。我在实操中的做法是：不同项目用不同的终端会话运行Codex CLI，从源头避免上下文串味。

6. 进阶玩法：为自己写一个技能包

6.1 技能包的最小结构：frontmatter、说明、步骤、检查清单

当你熟悉了Superpowers的基本用法后，最大的价值其实是自定义技能包——把你自己团队的工作流程固化下来，让AI帮你自动执行。我先给出一个最小可用的技能包模板：

--- name: my-custom-skill description: 适用于XX场景，详细描述什么情况下使用该技能 --- ## 适用场景 在遇到XXX任务时，必须参考本技能包。 ## 执行步骤 1. 第一步：收集任务相关的上下文信息 2. 第二步：按照既定的顺序处理各项子任务 3. 第三步：验证结果是否满足要求 ## 检查清单 - [ ] 所有必须的文件是否已更新？ - [ ] 是否有遗漏的异常情况？ - [ ] 是否已经运行验证命令？

写技能包的核心原则就是“别人（AI）读了就知道怎么做”，所以描述要具体，步骤要可执行，检查清单要覆盖容易出错的地方。不要写大道理，直接写步骤。

6.2 什么技能值得写成技能包：我的筛选标准

用了两星期之后我总结出一个规律：凡是你在代码审查时反复说的“废话”，都值得变成技能包。比如你经常让同事“记得写注释”“记得补测试”“记得处理空值”，这些就是技能包最好的素材。

反过来，那些过于业务化的逻辑判断、需要实时数据支持的任务，不适合写成技能包。技能包的定位是“稳定的方法论”，而不是“不确定的临时指令”。

我给自己团队写了一个“接口变更评审”技能包，把每次改接口时需要确认的事项全部列出来：是否需要新增版本号、是否影响兼容性、是否更新了文档。AI在每次修改接口相关代码时都会自动检查这些项，团队踩坑率肉眼可见地下降了。

6.3 把团队规范变成技能包：一次内部实践

最后分享一个内部实践案例。我所在的小组有一套严格的Git提交规范，包括分支命名、提交信息格式、合并策略等。以前我们靠人肉提醒，新人经常犯漏。后来我把这套规范写成技能包，在Superpowers的AGENTS.md里配置成“每次提交前自动触发”，AI会先读取技能包，再按照规范生成提交建议。效果非常直观：新人的PR描述和提交信息终于不再需要我们逐条指出问题了。

如果你所在的公司或团队也有一堆“约定俗成但没人写下来”的规范，我强烈建议你把它们沉淀成技能包，这可能是Superpowers在实际工作中能带给你的最大收益之一。

我自己这段时间用下来的体会是，Superpowers不是一个花哨的工具，它更像是给AI编程代理装上的一套“职业培训体系”。AI原本的基本功已经够强了，缺的就是把能力用对、用好、用规范的引导。这个项目补上了那块拼图。如果你已经在用Codex CLI，装上Superpowers大概率也会让你在某个瞬间觉得“这才像话”。