superpowers这个词我一听还以为是某款超级英雄游戏直到有次在技术社区刷到它和Codex CLI绑在一起出现才意识到这其实是最近AI编码工具圈里最值得玩的开源项目之一。简单说superpowers是一套给AI编程代理准备的“专业技能包”核心作用是让Codex CLI这类终端AI编码助手在需求分析、任务拆分、周报生成、代码审查这些具体场景里按一套稳定、规范的工作流干活而不是每次都在那里自由发挥、碰运气。这套东西适合谁如果你主力用Codex CLI或者Claude Code这类终端AI编程工具并且已经被“AI热情地答非所问”折磨过好几回那它大概率能解决你的痛点。我前后用了大概三周踩了不少坑今天把安装、配置、核心技能和排错经验一次讲清楚。1. superpowers到底是什么给AI编码助手“补课”的技能包1.1 先搞懂它的定位不是IDE也不是插件我第一次在GitHub上看到superpowers时差点把它当成又一个prompt合集。实际上它的定位很明确一个给AI编码代理用的“职业技能包”或者说一套结构化的技能库。很多人把Codex CLI这类AI编程工具当成“能聊天的终端”但用得多了就会发现一个问题——它很强但很不稳定。同样一句“帮我整理一下项目需求”今天它可能先问三个问题再动手明天它可能二话不说直接生成一份需求文档后天可能干脆给你写了一段代码。这种随机性在写段子时问题不大但放到真实的项目开发里就很致命。superpowers想解决的就是这个“不稳定”问题。它的做法不是去改Codex本身的模型能力而是在模型和任务之间插入一层“流程规范”。每个技能对应一类真实工作场景技能文件里明确写好了触发时机、执行步骤、输出格式。AI加载了这些技能之后遇到对应场景就会按照技能里写好的流程走而不是凭感觉自由发挥。你可以把它理解成给一个很聪明但缺乏社会经验的新人配了一套SOP手册。新人还是那个新人但有了SOP他至少不会把需求文档写成代码也不会在写周报的时候突然给你输出一段SQL。1.2 为什么叫“超能力”从通用助手到领域专家“superpowers”这个名字起得挺妙。它暗示的核心价值是模型本身的通用能力是地基而技能是在地基上盖起的不同功能房间。同样是GPT-4o或者最新的o系列模型一个裸奔的Codex和一个装了superpowers的Codex干起活来的表现差距可以是两倍甚至更多。举个直观例子。裸奔状态下你让AI“把这些需求拆成任务”它通常会返回一个列表看起来像模像样但其实既没有优先级也没有验收标准跟需求本身的对齐也全靠运气。装上superpowers里的break-down-tasks技能后它会先要求你确认需求背景、识别里程碑再逐层拆分任务每个任务都带上依赖关系、验收标准和预估工时。同样是“拆分任务”产出物的质量完全不在一个层级。这个差距背后的原理并不玄乎superpowers实际上把资深工程师的思考过程“脚本化”了。比如我自己做需求拆分时会先看业务目标再划分子系统然后才拆功能点。这套思考顺序被写成技能步骤之后AI每一步都会照做最终输出自然就更有结构。1.3 哪些AI编码工具能用这双“翅膀”跟superpowers配合最顺畅的是OpenAI开源的Codex CLI这也是项目默认支持的环境。Codex CLI本身支持一套skills机制superpowers正是基于这个机制构建的。同时只要支持类似skills机制的AI编码工具理论上都可以尝试接入。比如Claude Code有原生的Skills特性Roo Code、Cline这类VSCode插件也陆续支持了自定义技能Trae提供了对应技能的安装路径。不过每个工具的技能格式细节略有差异直接复制目录进去不一定百分百兼容后面我会专门讲怎么适配。2. 动手安装前的三个核心概念Codex CLI、skills、AGENTS.md2.1 Codex CLI终端里的AI编码代理如果你还没用过Codex CLI先简单认识一下它。它是OpenAI推出的开源命令行工具作用是在终端里给你一个AI编程助手可以直接读取文件、执行命令、跑测试本质上和Claude Code是同类产品。安装方式很简单npm install -g openai/codex装完之后在终端输入codex进入交互模式首次运行会引导你完成登录认证支持用ChatGPT账号登录也可以配置OpenAI API Key。登录成功后你就可以在终端里用自然语言指挥它操作项目代码了。Codex CLI的设计里有一个很重要的目录概念用户级别的配置目录默认是~/.codex/。里面有几个关键东西——config.toml是主配置文件AGENTS.md是给AI看的全局指令文件skills/目录则是放技能的地方。superpowers的安装本质上就是往skills/目录里塞东西。2.2 skills技能机制到底怎么工作读懂skills机制是理解superpowers的关键。一个技能本质上就是一个文件夹里面有一个核心文件叫SKILL.md。这个文件的顶部有YAML格式的元信息包括技能名称、描述、适用场景等。正文部分则详细定义了AI拿到这个技能后应该怎么干活。拿superpowers里的specify技能举例它的SKILL.md大概结构是这样的区块作用name技能唯一标识通常是英文小写连字符description告诉AI“什么时候该用这个技能”的关键描述执行步骤AI被触发后需要按顺序完成的动作清单输出模板AI最终产出的文档或代码应该长什么样这里有个细节description写得好不好直接决定AI会不会在正确时机主动调用这个技能。所以superpowers的技能描述通常写得很细致甚至会列出触发词和使用场景。这也是为什么安装之后你只需要用自然语言描述场景AI就可能自动想起“哦这种情况我应该用specify技能”。2.3 AGENTS.md让技能在合适的时机自动出现AGENTS.md是另一个需要理解的文件。它本质上是给AI编码代理看的“项目说明手册”类似给新同事看的团队文档。里面可以写项目结构、代码规范、常用命令以及技能使用策略。在superpowers的使用中你可以在项目根目录创建一个AGENTS.md里面写明“当用户描述模糊需求时优先调用specify技能进行需求澄清”这样AI在项目里工作时就会把superpowers里的技能当作自己的“职业习惯”来使用。我的建议是全局技能装到~/.codex/skills/项目级技能和AGENTS.md放到具体项目里。这样既保证所有项目都能用上通用技能又能针对不同项目做定制化配置互不干扰。3. 实操安装把superpowers部署到Codex CLI3.1 第一步安装并登录Codex CLI如果你还没装Codex CLI先把环境准备好。需要Node.js 18以上版本确认好了执行node -v npm install -g openai/codex codex --versioncodex --version能打印出版本号说明安装成功。接下来运行codex按提示完成登录。这里有个小坑首次登录可能要等一会儿如果你之前配过API Key也可以直接设置OPENAI_API_KEY环境变量跳过登录步骤。3.2 第二步获取superpowers技能集superpowers是开源项目直接clone到本地即可。仓库地址可以在GitHub上搜索“superpowers”认准项目描述里带“skills for AI coding agents”的那个。我实际使用的命令是git clone https://github.com/jensnti/superpowers.git ~/superpowers如果仓库地址有变动导致404去GitHub搜索“superpowers codex”也很容易找到。clone完成后进去看一下目录结构ls ~/superpowers ls ~/superpowers/skills正常情况下你会看到一个skills/目录里面按技能名分成多个子目录比如specify、break-down-tasks、weekly-report等。这就是整个项目最核心的资产。3.3 第三步部署技能到正确目录部署本质上就是把技能文件放到Codex CLI能扫描到的位置。全局安装这样操作mkdir -p ~/.codex/skills cp -r ~/superpowers/skills/* ~/.codex/skills/复制完之后检查一下ls ~/.codex/skills/你会看到技能目录已经躺在那里了。这里我强烈建议不要直接复制而是用软链接ln -s ~/superpowers/skills ~/.codex/skills为什么因为superpowers迭代很快作者几乎每周都会更新技能内容。用软链接的话你只需要git pull就能完成技能升级不需要重新复制。我第一次就是复制安装的后来项目更新只好又手动同步一遍麻烦。3.4 第四步验证技能是否被加载技能文件放好之后重新打开Codex CLI进入交互界面后输入/看看弹出的命令列表里有没有superpowers里的技能。如果没看到可以再补一个验证动作codex exec 列出你当前可用的所有skills如果AI能列出一串技能名说明加载成功。我在这一步遇到的问题比较典型技能目录确实复制过去了但Codex没扫描到原因是我把目录结构搞成了~/.codex/skills/skills/xxx权限层级多了一层。所以验证时最好直接确认最终的技能文件路径是~/.codex/skills/specify/SKILL.md这种形式而不是~/.codex/skills/superpowers/skills/specify/SKILL.md。4. 核心技能逐个拆解这双“超能力”到底能干啥4.1 specify从一句模糊需求到可执行规格说明specify是superpowers里我最先尝试、也是目前用得最多的技能。它的使用场景一句话就能说清楚当用户描述了一个模糊的想法AI会自动进入“需求分析师”模式通过多轮提问澄清需求最终输出一份结构化的规格说明文档。我实测的场景是这样的。我在Codex里输入我想做一个个人记账工具帮我把需求写清楚没有skills的Codex大概率会直接产出一段“个人记账工具需求”的段落看似全面实则没有重点。而加载了specify技能之后它先问我这个记账工具是给自己用还是给团队用核心是记录支出、收入还是也需要预算管理数据存在本地还是要支持多端同步是否有导出报表的诉求这一系列追问本身就是在帮你把藏在脑子里的“我以为”一层层剥离出来。回答完之后它生成的规格说明文档包含目标用户、功能清单、优先级、数据模型、成功指标等模块。我可以直接拿这个文档去作为开发依据或者继续让它出技术方案。这里分享一个细节specify技能执行时会消耗较多token因为多轮对话和长文档输出都比较吃量。如果API是按量计费建议在需求特别模糊时才用并且可以在问题里补一句“请控制提问轮次在5轮以内”效率会高很多。4.2 break-down-tasks把大任务拆成人能执行的小步break-down-tasks这个技能解决的是“需求有了但下一步不知道干什么”的问题。它和specify是好搭档——specify负责把需求变成规格break-down-tasks负责把规格变成可执行的任务清单。我在一个中型项目里试过这个技能。当时的需求是“给现有后台管理系统增加一个数据看板”它拆出来的任务清单包括梳理看板数据来源确认哪些表需要新增查询接口设计看板布局和图表组件选型开发统计概览模块包含今日订单量、销售额等核心指标开发趋势图模块支持按天/周/月切换粒度配置前端路由和菜单入口联调测试和性能优化关键的区别在于它不只是列任务还会标注每个任务的依赖关系和验收标准。比如“设计布局”这个任务被标记为“依赖数据来源梳理完成”验收标准是“UI稿通过评审且组件库无阻塞项”。这个技能非常适合同事协作的场景它拆分出来的任务可以转成工单分配给不同人每个任务因为有明确的验收标准减少了大量来回沟通成本。4.3 weekly-report三分钟搞定团队周报weekly-report是我一开始最不看好、后来真香的技能。因为在传统认知里写周报这个活儿复杂度不高裸奔的Codex只要给几个git提交记录也能写。但实际效果差别很大——裸奔的AI写出来的周报像流水账而superpowers里的weekly-report技能会引导AI先读取git日志、分析分支合并情况、识别关键改动和未完成事项再分模块生成报告。它还有一个贴心的设计自动区分“给团队看的版本”和“给Leader看的版本”。给团队的版本突出协作信息比如哪些模块改动了、有没有外部依赖需要同步给Leader的版本则更关注进度和风险比如核心功能完成度、延期风险、需要协调的资源。需要注意的是weekly-report依赖git仓库的质量。如果你的提交信息写得很随意比如“fix”“update”“aaa”那它再强也没办法变出一份像样的周报。所以我现在的习惯是每次提交都写清楚改动内容和原因其实这也是对自己项目负责。4.4 其他技能文档、审查、写作superpowers还内置了一些其他技能这里挑几个值得提的code-review代码审查技能能自动读取你暂存的变更并输出审查意见按严重程度分级。比让AI裸跑着“帮我看看代码有问题吗”要系统很多它会关注安全性、性能、可维护性和边界情况。blog-post把一段技术方案或项目经验翻译成技术博客。用这个技能写出来的文章结构比我让AI裸写时要好不少因为它会在生成前先要求你提供目标受众、核心观点和风格参考。documentation生成项目文档。区别于直接让AI写README这个技能会先梳理项目结构和公开API再逐模块生成文档避免“看起来写了实际没写”的空洞文档。这些技能有一个共同特点它们都在“输出之前”多了一个“理解输入”的环节。正是这个环节拉开了和裸奔AI的差距。5. 常见问题与排查技巧实录5.1 技能列表是空的怎么办这是我遇到的最常见问题。技能文件复制过去了但Codex里看不到任何技能。排查思路走三步确认目录层级正确最终必须是~/.codex/skills/技能名/SKILL.md不能多套一层。重启Codex CLI技能是启动时扫描的运行中加载不到。确认Codex版本够新skills机制是较新版本才支持的功能npm update -g openai/codex升级一下。5.2 斜杠命令识别了但AI不按步骤执行有时候输入/specifyAI确实响应了但不按SKILL.md里的步骤走自由发挥。这种一般是上下文污染造成的——当前会话里已经有太多无关内容AI在长上下文里丢失了技能指令的优先级。解决办法开一个新会话再试。如果问题依旧检查一下项目根目录有没有AGENTS.md内容里如果有“覆盖默认行为”的指令可能会干扰技能的优先级。试着注释掉再试。5.3 Token消耗太大、响应变慢superpowers的技能普遍要求多步推理和结构化输出自然比单轮问答耗Token。我实测下来一次specify完整流程大概要消耗20k~40k Token首次还会因为技能文件本身的注入产生额外开销。控制Token可以这样操作在配置里限制技能输出长度比如明确告诉AI“规格说明控制在200行以内”或者把大项目拆成小会话不要在同一个会话里连续跑多个技能。5.4 在Trae等AI IDE里怎么用Trae这类AI IDE目前也支持skills机制安装思路和Codex CLI类似把技能目录放到Trae用户目录的skills文件夹下。具体路径会因为IDE版本不同而有差异我建议在Trae的设置面板里搜“skills”找到它实际读取的目录路径再把superpowers里的技能复制过去。需要提醒的是Trae国内版和国际版对技能的支持进度不完全一致。如果你发现复制过去后不生效先确认IDE版本支持自定义技能再看文档确认目录结构。因为各家的技能格式规范还在持续演进短期内不能保证百分之百兼容但大方向是一致的。6. 实操心得与后续扩展6.1 我踩过的几个坑第一个坑是目录结构。我一开始把整个superpowers仓库直接复制到了~/.codex/skills/下结果Codex扫描不到任何技能原因前面说过了多了一层目录。第二个坑是让技能互相打架。我在全局AGENTS.md里写了“所有需求都要先走specify流程”结果连“帮我查一下某个函数定义”这种问题都要被AI追问半天需求背景严重影响效率。后来我把这种强制性的调用策略放进项目级AGENTS.md里只对需要严谨文档和任务拆分的重点项目生效。第三个坑是技能文件和项目内容脱节。superpowers自带的技能都是英文描述中文环境下的触发准确率会略低。比如你说“帮我写个周报”AI可能不会主动联想到weekly-report。解决办法很简单手动敲斜杠命令或者在自己的AGENTS.md里加一句“用户说周报时使用weekly-report技能”。6.2 自己写一个技能的完整思路用了一段时间之后你大概率会有“要是它还能帮我做那个就好了”的想法。这时候就可以动手写自己的技能了。流程其实不难在~/.codex/skills/下新建一个目录比如my-release-checklist然后在里面创建SKILL.md写好元信息和执行步骤。给你看一个我自己写的简版技能示例--- name: release-checklist description: 在准备发布新版本时输出发布检查清单 --- ## 步骤 1. 读取package.json中的版本号 2. 检查git tag和当前分支状态 3. 运行测试命令并确认全部通过 4. 根据以上信息输出发布检查清单写完丢进技能目录重启Codex就能用了。自建技能的价值在于你可以把团队里沉淀下来的最佳实践直接固化成AI的执行规范让每个用AI的人都能按团队标准干活。6.3 这双“超能力”到底适合谁用了这几周我的结论是superpowers不是给所有人准备的。如果你是那种让AI写段一次性脚本、跑完就删的轻量用户那没必要折腾它。但如果你依赖Codex CLI进行项目管理、多文件开发、文档产出这类“持续性工作”它就是那种用了就回不去的效率工具。尤其适合的是团队里的Tech Lead或需要带人的开发者。你把需求分析、任务拆分、代码审查这些套路装进技能里等于每个用AI的同事都自动具备了一套合格的工作方法。从这个角度看superpowers更像是一种“经验分发系统”把个人的脑内流程变成团队可复用的资产这比多写几个prompt有价值得多。最后分享一个小技巧定期把项目里的AGENTS.md和自建技能提交到代码仓库。我现在的做法是单独建了一个团队私有仓库存放所有定制技能和各项目的AGENTS.md模板新同事入职之后直接clone一套配置AI行为和团队规范马上对齐省掉很多口头沟通成本。这大概是我这段时间从superpowers身上收获的最大价值。
谱)
