最近AI编程圈子里“Superpowers”这个词被反复刷到GitHub上的star涨得很快。我陆续看到有人在Codex CLI、Trae、Workbuddy里装它也有人讨论它的安装脚本和AGENTS.md配置。如果你也在用AI编程助手多少会遇到这种场景让AI改个需求它改完这处、漏了那处或者干脆把原有逻辑带歪了让它自己写测试它象征性写两个用例就交差让它做点稍微复杂的重构它连文件结构都没看全就开始动手。Superpowers解决的就是这一类问题。它不是IDE插件也不是一个独立App而是一套“给AI Agent加Buff”的skill集合。装好之后Codex、Claude Code这类命令行AI助手会额外获得一套更完整的工作流——先想清楚再动手、规划完再编码、拆子任务并行跑、写测试跑测试再收尾。这篇文章我会从我在真实项目中试过的角度把Superpowers是什么、为什么值得装、怎么在Codex CLI里一步步配好、以及装完怎么用出效果一次性讲清楚。适合正在深度使用AI编程助手、觉得AI“不够使唤”的开发者参考。1. 先弄明白Superpowers到底是什么1.1 它不是又一个“提示词模板库”我看到网上很多讨论把Superpowers和普通的prompt工程混为一谈这是最大的误解。普通提示词模板是一段文字你贴给AI它照着执行一次性的换个上下文就失效了。Superpowers的做法完全不同它是一套带目录结构的技能包里面每个子技能都是一个独立的SKILL.md文件通过项目根目录的AGENTS.md告诉AI“在什么时候应该读哪个技能文件、按什么流程执行”。这就好比你以前让新同事“好好写代码”这是提示词Superpowers是直接递给新同事一本《团队编码手册》手册里每个章节都写明“遇到这种情况按三步走每一步做什么”。agent会在开工前先去翻手册再决定怎么干活。它改变的不是AI的回答质量而是它的工作方式。我在本地仓库里看到的典型目录结构大概是这样的superpowers/ ├── skills/ │ ├── brainstorming/ │ │ └── SKILL.md │ ├── planning/ │ │ └── SKILL.md │ ├── subagents/ │ │ ├── SKILL.md │ │ └── subagent-skills/ │ ├── test-driven-development/ │ │ └── SKILL.md │ ├── deep-research/ │ │ └── SKILL.md │ └── ... ├── build-server/ ├── install.sh └── AGENTS.md每个技能目录里都有一份结构化的Markdown说明AI读取之后会按照里面的步骤去调用工具、拆解任务、组织代码。这套东西本质上是一个行为框架不是几句咒语。1.2 它到底能给Agent加哪些能力我从实际使用中体会比较深的有这几个第一是先研究再动手。默认情况下AI拿到需求直接开写代码这非常容易在没搞清项目结构的情况下乱改。Superpowers里的brainstorming和planning技能会强制它先分析需求、列出候选方案、跟用户确认然后才进入编码阶段。这在多文件项目里尤其有用AI不会再“盲改”。第二是子代理并行。Codex本身支持多会话但需要你手动拆分任务。Superpowers的subagents技能会把大任务拆成若干子任务分别派给不同上下文窗口的子代理去做最后再汇总结果。我没法给一个绝对的加速倍数但体感上涉及十几个文件的批量重构完成时间确实缩短了而且每个文件的处理更专注。第三是测试驱动开发TDD。它内置的TDD技能会要求AI先写失败测试、再写实现、最后重构。对不喜欢写测试的人来说这像是多了一层“束缚”但如果你想保证代码可回归性这个流程能让AI产出的代码质量上一个台阶。第四是深度研究。deep-research技能支持AI联网查找资料、汇总技术方案。这个我用来查某个Python库的API变更比较多效果比让AI直接凭记忆瞎编准确得多。1.3 为什么它不太挑宿主工具注意Superpowers不是为某一个工具量身定做的。它借助的是AGENTS.md这个通用机制。Codex CLI读项目根目录的AGENTS.mdClaude Code读CLAUDE.md理论上只要宿主工具支持类似的项目级指令文件就能把Superpowers接进去。这也是为什么你在热搜词里会看到Workbuddy、Trae、Codex CLI都能装它——它是一套“可移植的AI行为定义”不是某个IDE的私有格式。这带来了一个好处你在一台机器上配好之后其他项目只要克隆同一套skills目录、在AGENTS.md里指个路径就能复用全部能力不需要重复安装插件。2. 安装前的准备与工具选型2.1 先确认你的宿主工具能跑通我强烈建议新手先别一上来就折腾Superpowers而是先把你的Codex CLI或同类工具跑通一个最简单的对话。以Codex CLI为例安装和基础配置不算复杂装好之后在项目目录里能正常跟它对话、能读写文件、能执行shell命令再往下走。为什么要把这一步单独拿出来说因为我踩过坑我之前在配置不完整的环境里装Superpowers结果agent加载skills失败报错信息不直观排查了半天才发现是它的运行环境本身有问题跟Superpowers一点关系都没有。基础不牢后边的问题会非常难排查。2.2 两条安装路径怎么选Superpowers仓库提供了两种装法自动安装脚本克隆仓库后运行./install.sh脚本会把skills目录复制到你的项目或全局配置目录并生成好AGENTS.md。适合第一次装、不想手动搞细节的人。手动方式克隆仓库后自己把skills/目录放到你想放的位置然后在项目的AGENTS.md里追加一行指向它。适合想控制目录结构、多项目复用同一套skills的人。我的建议是第一次用脚本装但装完之后打开生成的AGENTS.md看一眼。脚本帮你做的事不多但你需要知道它把文件放哪了、AGENTS.md里写的是什么否则出了问题你完全不知道从哪里查。2.3 装的时候注意三个细节第一个是版本匹配。如果你用的Codex CLI版本比较老或者用的不是原版而是某个二次封装版对AGENTS.md的解析规则可能不一样。我遇到过老版本把path/to/skills这种指令忽略掉的情况导致skills一个都没加载。出现这种情况优先查宿主工具的更新日志或试下新版本。第二个是网络与raw文件访问。Skills里的某些子技能会要求在运行时获取远程资源如果你的开发环境网络受限、拉取超时会报错建议给相关域名配一下可用通道或者把依赖打包到本地。这个跟你的具体环境强相关我没法给统一的配置只能说“先确认环境能不能正常访问外网”。第三个是目录权限。自动安装脚本里有一步会创建目录或写配置文件如果你在Linux/macOS的受保护目录下操作记得给足写权限。我碰到过脚本把AGENTS.md写到了项目根目录但当前用户没有写权限导致半途失败的情况。3. 实操在Codex CLI里快速装好Superpowers3.1 第一步确认Codex CLI版本先打开终端跑一下版本号codex --version我建议至少使用支持AGENTS.md完整语法解析的版本。这个没有特别固定的“最低版本号”因为项目更新快直接升到最新稳定版最省事。如果你用的是某个发行版自带的旧版建议先更新npm install -g openai/codex或者你如果是通过Homebrew等其他渠道装的就用对应渠道的方式升级。这一步别跳过很多奇怪问题都是版本太老导致的。3.2 第二步克隆Superpowers仓库在你的工作目录或者一个固定的工具目录下克隆git clone https://github.com/obra/superpowers.git注意这个仓库里不止有skills还有build-server和install.sh。我不建议你把它整个塞进业务项目里而是放在一个独立目录比如~/tools/superpowers。这样多个项目都能引用不会污染单个项目的结构。如果你想保持最新可以后续定期git pull。这个仓库更新挺勤的因为AI编程工具本身迭代也快隔一两个月可能就有新skill或者对旧skill的修正。3.3 第三步用安装脚本或手动配置我推荐第一次用脚本cd superpowers ./install.sh脚本会做一些事情把skills/目录放到它会检测到的一个目标位置然后在当前项目或者全局配置里生成或追加AGENTS.md让agent能发现这些skills。如果你是在一个已有项目里运行它大概率只会往项目的AGENTS.md里加内容不会动你的代码文件。如果你更想手动控制那就三步走把skills/目录复制到你的项目里比如:dev/skill-store/skills/。在项目根目录创建或编辑AGENTS.md。在文件里加一行引用路径大致形式是## Skills Read the skill files in the skills/ directory before starting work. Always follow the SKILL.md instructions when relevant.具体路径按你的实际目录调整。这一步的本质是让agent在开工前“知道有这些手册存在”。3.4 第四步验证是否生效光装完不算完一定要验证。我建议先用一个简单任务试水别直接拿核心项目去测。我的验证方式是这样的在项目里新建一个测试需求让Codex执行一个任务然后观察它输出的日志。正常情况下agent的思考过程里会出现“读取了superpowers/.../SKILL.md”之类的痕迹或者在执行计划时会明确提到“根据planning流程我先拆解任务”。如果不能直接看到加载痕迹你也可以在对话里直接问它你知道superpowers里的test-driven-development技能是什么吗如果它答得出来、能说出这个技能的使用步骤说明配置是通的。如果它一脸茫然那八九不离十是路径或者AGENTS.md没配置对。4. 把Superpowers用出效果的关键技巧4.1 不同宿主工具的配置差异我试过在Codex CLI和Trae里分别装Superpowers。两者思路一样但细节有差异。Codex CLI读的是AGENTS.mdTrae作为AI IDE它的项目级指令文件有时也叫AGENTS.md或类似名字但解析严格度不太一样。你在Codex里手写的路径引用换到Trae里可能要调格式。Workbuddy那边的情况更特殊一点它本身就是面向“多agent协作”的工具对skill机制的支持度更高安装体验也顺滑。但原理照旧让agent读SKILL.md按文档定义的流程去执行。我的建议是固定一个主工具先把Superpowers的核心skill用熟再考虑迁移到别的工具。别同时在不同工具间横跳因为每个环境调试一次的成本不低容易把精力耗在“工具打磨”而不是“干正事”上。4.2 优先级与冲突处理当项目里已经存在一个自定义的AGENTS.md里面写了不少你自己的规则时Superpowers的安装脚本通常会把它的配置追加进去而不是覆盖。这就可能出现指令优先级问题如果前文说“不写测试”后文又说“必须用TDD技能”AI到底听谁的以我的经验agent对AGENTS.md里的指令通常“就近”或“按出现顺序”处理但这不代表靠顺序就能解决冲突。最稳妥的做法是安装完Superpowers之后自己打开AGENTS.md检查一遍把你自己原有的规则和Superpowers的规则理出层次。比如在文件开头先写“项目全局规范”再写“Superpowers skills使用说明”避免互相打架。4.3 自定义skill把团队规范写进agentSuperpowers真正好用的地方是你可以照着它里的SKILL.md格式给自己的团队写一个专属skill。比如团队规定“前端组件必须包含可访问性标签、错误状态和loading状态”你完全可以建一个frontend-componentskill把这些要求结构化写进去然后让agent在写前端代码前必读。写法也不难核心是给你的skill建目录、写SKILL.md并在AGENTS.md里注册。我在团队里就加过一个“后端接口定义”的skill里面写清楚了我们用的响应体格式、错误码规范、字段命名约定。从此agent生成的接口代码基本不用再改风格效率提升非常明显。5. 常见问题与排查实录5.1 Skill加载不上agent一脸茫然这是我被问得最多的问题。症状是装完之后问AI认不认识某个skill它说不认识或者执行任务时完全没有表现出技能加持的迹象。排查步骤我建议按顺序来先看AGENTS.md里是否真的包含了对skills目录的引用。确认路径写对没有相对路径是从项目根目录算的别写错层级。确认目录名和技能名是否对得上。有些skill的名字和目录名不完全一样AI是通过SKILL.md里的name字段识别的。再新开一个会话试试。Codex这类工具AGENTS.md通常是在会话初始化时读取的你改了配置之后老会话可能不会重新加载。5.2 安装脚本报权限或者路径错误如果你在运行./install.sh时碰到Permission denied先看看脚本有没有执行权限chmod x install.sh如果它还往/usr/local写东西而你的用户没权限可以给命令加sudo但我不建议对仓库目录整体加sudo最好是只对安装动作放权。另外一个容易忽略的问题如果你是在Windows上用Git Bash或WSL脚本里的路径逻辑可能有不兼容此时我建议直接用WSL的Linux环境来装别在Git Bash里硬搞。5.3 装完之后AI行为没变化有几种可能它读了但认为当前任务用不上这些技能。比如让它写一个Hello World它可能不会调用planning或TDD。这不一定是配置失败反而说明skill框架在起作用——它知道什么时候该用什么技能。任务太简单skill没有施展空间。我建议验证时用一个至少涉及“多文件修改需要测试”的任务比如“给这个模块加一个新接口并补上单元测试”。这种任务最能看出Superpowers有没有真的介入工作流。模型本身能力偏弱。部分轻量模型对长指令的遵循能力有限即使读到一堆SKILL.md也可能不会严格按流程执行。这就不是Superpowers能解决的问题了你得换个更强的主模型。5.4 兼容性不是所有“Codex”都一个样市面上叫Codex的东西不少OpenAI的Codex CLI是其中一种还有些项目或工具也以Codex命名但它们对AGENTS.md和skill的支持程度未必一致。另外有些封装版“Codex”用来自动化处理特定任务并不开放通用的agent循环给你跑skill。我见过有人在某个“Codex”里折腾半天装不上Superpowers最后发现他用的那个工具根本不支持AGENTS.md指令理论上就接不了这套体系。所以装之前先确认你的宿主工具用的是通用agent指令机制。5.5 常见问题速查表症状可能原因解决方向agent不加载任何技能AGENTS.md路径错误或格式不支持检查路径写法、确认工具版本安装脚本权限报错脚本无执行权限或目标目录受限chmod x install.sh必要时用sudo部分技能生效、部分不生效对应skill目录缺失或SKILL.md不完整重新克隆仓库确认skills目录完整项目原有规范和Superpowers冲突两套指令打架打开AGENTS.md手动调整优先级老会话里行为没变化会话初始化后才读取配置新开一个会话再测试核心项目不敢试担心AI乱改先在临时分支或小demo项目里验证6. 我的几个实际体会折腾Superpowers这段时间我最大的感受是它没有让AI变聪明但让AI变规矩了。模型还是那个模型智商没有变高但因为工作流程被强制分成了“先研究、再规划、然后编码、最后测试”产出的稳定性确实提升了一截。以前让AI改个大一点的功能它经常一股脑把文件改完也不管会不会破坏别的地方。加了这个技能框之后它至少会先跟我确认范围、再动手这个“多一步确认”有时候确实烦但它帮我挡住了不少次大返工。我也建议你别把它当成银弹。如果你的模型能力本身就一般装上Superpowers也只是让它在执行时更规范没法让它凭空学会它本来就不会的东西。工具是放大器前提是你得有一个不错的底子。最后分享一个我一直在用的操作在安装时我会额外建立一个只读的skills/软链接让多个项目共享同一套Superpowers这样更新skill时只要在一个地方git pull所有项目都能生效不需要逐个重装。具体操作就是在项目里建软链接指向你的全局skill存放目录路径指向请自行调整。这样既不需要重复拷贝文件项目里还留了一个清晰的入口后续排查也方便。如果你已经把这些skill用顺手了下一步可以试试自己仿照它的格式写一两个团队专属技能那才是让这套体系真正价值最大化的玩法。