最近两天“Superpowers”在开发圈刷屏的速度有点快。头一天我还在 GitHub 上刷到这个项目第二天就有好几个群里在问 codex cli 怎么装 superpowers、Superpowers 如何使用、甚至有人已经在折腾 trae 里能不能装 superpowers skill。这名字起得很直白——它想给 Codex 这类命令行 AI 代理装上一整套“超能力”让 AI 从一个只会听一句动一句的聊天机器人变成能自己拆需求、写计划、做测试、重构代码、审查提交的工程助手。我花了两天时间把仓库拉下来在 Codex CLI 里完整跑通又把 skills 拆到 AI IDE 里试了试整体感受是它比单纯写一段 prompt 要踏实得多。这篇文章不吹不黑把 Superpowers 是什么、怎么装、底层怎么工作、真实使用中有哪些坑一次性说清楚给想上车的人当块垫脚石。1. Superpowers 解决的核心问题以及为什么值得装1.1 从“写一句提示词”到“给 AI 装 SOP”以前我们让 AI 写代码本质上是“临时工模式”。每次都要在对话里交代上下文、目标、约束、输出格式AI 在没有任何流程约束的情况下即兴发挥。结果大家应该都有体会同一个需求第一遍可能写得又快又好第二遍换个说法它就跑偏了让它改一个函数它经常顺带把别的模块也动了。问题不在模型不够聪明而在于你每次都在要求模型“自己摸索一套工作方法”。Superpowers 的思路很朴素把成熟工程师做事的流程固化成一份份可复用的“技能说明书”AI 一旦判断当前任务命中技能描述就会自动按说明书里的步骤一步步执行。这相当于给新员工发了一本详细的 SOP 手册而不是每天等他来问“老板这一步我该干嘛”。整个机制基于 Anthropic 提出的 Agent Skills 标准用一种叫 SKILL.md 的文件来描述技能现在 Codex CLI 在新版本里也兼容了这个标准Superpowers 就是在这个标准之上做了一套覆盖面很广的开源技能库。我用一个比喻帮你理解以前的 prompt 像你在餐厅口头点菜厨师怎么炒全看心情Superpowers 更像中央厨房的标准菜谱什么时候下油、几成热、加多少盐全是固定动作。如果你只是让 AI“写个排序算法”这个差异不明显一旦任务是“给一个老项目加个功能并且保证不破坏已有测试”固定流程的价值就会被无限放大。1.2 这套“技能体系”能干什么适合谁Superpowers 仓库里塞了大量工程场景相关的技能核心能力覆盖几个方向需求澄清与方案设计、把宏大任务拆成可执行的小步骤、测试驱动开发、调试排查、安全重构、代码审查、Git 工作流管理。它甚至内置了“planner”“builder”“reviewer”之类的 agent 角色配置相当于让 AI 在不同阶段切换不同的“人设”计划阶段像一个谨慎的架构师写代码阶段像一个高效但不莽撞的工程师审查阶段又变成一个挑刺的代码评审人。什么人适合装如果你平时就在用 Codex CLI 做实际项目尤其是那种“让它负责一个完整小需求”而不是“让它补一段函数”的场景你大概率会遇到输出不稳定、越改越乱的问题Superpowers 值得一试。如果你喜欢让 AI 先写测试再写实现它会让你非常舒服因为 TDD 流程被内化成了标准动作。反过来如果你的使用场景只是问答、翻译、写文案或者你完全不想让 AI 自动执行 shell 命令这套东西其实对你没啥用装不装都行——它天生是给“愿意授权 AI 动手干活”的人准备的。需要提醒的是授权 AI 自动执行命令是把双刃剑。技能体系做得越完善AI 自主性越强你就越要留意它会动哪些文件、跑哪些命令。我后面会专门讲这部分怎么把控风险这里先记住一个原则任何自动化工具控制权必须留在你手里。2. 环境准备在 Codex CLI 中完整安装 Superpowers2.1 第一步装好 Codex CLI 并确认版本安装 Superpowers 之前你得先有一个能跑起来的 Codex CLI。安装方式我推荐用 npm 全局安装一条命令搞定npm install -g openai/codex如果你机器上已经装过旧版本先升级到最新版再往下走因为 SKILL.md 和 AGENTS.md 的加载机制是近期版本才完整支持的版本太老会导致装完 Superpowers 却发现 CLI 根本读不到技能。装完以后执行codex --version看到版本号正常输出了再执行一次codex进入交互界面。首次使用需要完成登录认证或者配置 API Key这一步按官方提示操作即可。这里有个实际小建议不要在装完 CLI 的第一时间就去装 Superpowers先随便让它跑一个小任务确认认证、联网、基本对话都正常再进入下一步。先把地基打牢后面排查问题会省很多事。我见过不少人卡在“装完 Codex 之后输入codex没有反应”这类问题上九成是 npm 的全局 bin 目录没进 PATH。如果你也遇到这种情况执行npm prefix -g查看全局目录再把对应的 bin 目录加到 shell 配置文件里基本上就能解决。2.2 第二步拉取 Superpowers 仓库并安装 skills环境就绪后找一个合适的目录把 Superpowers 仓库拉下来git clone https://github.com/obra/superpowers cd superpowers拉下来之后先别急着装我建议你先看一眼目录结构。你会发现里面主要分两块一个放的是 skills也就是那些 SKILL.md 技能文件另一个放的是 agents里面是像 opcode 这样的角色配置。搞清楚结构之后你就可以选择自动化安装或者手动安装。自动化安装很简单直接跑仓库根目录的安装脚本./install.sh这个脚本做的事情说白了两件把 skills 目录下的技能文件复制到 Codex CLI 默认的技能读取目录~/.codex/skills然后把 agent 相关的配置写进~/.codex/AGENTS.md。如果你习惯手动控制也可以复制这两条核心命令自己来做mkdir -p ~/.codex/skills cp -r skills/* ~/.codex/skills/ cp agents/opcode/AGENTS.md ~/.codex/AGENTS.md我个人的习惯是先看脚本做了什么再执行因为开源脚本有时候会顺手改掉一些 shell 配置。这个项目还算克制主要就是复制文件和处理配置目录。但不管怎样手动装一次能让你清楚每个文件去了哪里后面排查问题会更有感觉。2.3 第三步验证安装是否生效装完之后千万别急着开始写代码先验证一下技能到底有没有被加载。重新启动codex进入交互对话后直接问它一句请列出你当前加载了哪些可用的 skills你了解 Superpowers 吗如果安装成功它通常会在回答中提到自己掌握了一批技能比如 brainstorming、writing-plans、test-driven-development 等。这里有个很常见的现象如果你是在安装之前就打开了 Codex 会话新装的技能不会自动热加载退出重进一次就好。如果想要更确定的验证方式可以在某个测试项目目录下执行codex exec 用一句话总结一下 superpowers 项目里 skills 目录的用途如果它能准确回答说明技能文件已经被读取到了。另外你在实际项目里使用 Superpowers 时建议在项目根目录放一个自己的AGENTS.mdCodex 在进入项目目录时会读取这个文件并把里面的规则注入到对话上下文中。这相当于给每个项目单独交代“本项目有哪些约定”配合全局安装的 skills效果会更好。3. 核心机制拆解SKILL.md、agent 与 TDD 工作流是怎么运作的3.1 SKILL.md 里到底写了什么SKILL.md 是整套机制的核心文件格式上很接近我们平时写 Markdown 文档但头部有一段 YAML 格式的元信息用来描述这个技能的名称、用途、触发条件等。我找一个典型的例子给你拆开看--- name: test-driven-development description: 当一个任务涉及实现新的功能或修改现有功能时使用通过先写失败测试再写实现代码的方式保证行为可验证。 when_to_use: 用户要求编写新功能、修复 bug、或者需要对现有行为增加测试保障 version: 1.0.0 model: recommended ---正文部分就是具体的执行流程通常包含步骤列表、检查清单、以及一些硬性约定。比如 TDD 技能会明确要求先写一个会失败的测试运行测试确认是红灯写最简实现让测试变绿最后做重构。每一步还会附带“为什么这么做”的解释让模型理解规则背后的意图而不是机械照做。这个设计的妙处在于模型不是靠“记忆”来遵守流程而是每一次都从文件里重新读取规则。所以只要你修改了 SKILL.md下一次执行就立刻生效不需要重新训练模型。你可以把“技能”理解成给模型外挂的一份知识库prompt 是一次性传递会随着对话上下文被冲淡SKILL.md 则像一本随时可以翻的工具书AI 在需要的时候去查。需要注意的是description和when_to_use这两个字段直接影响匹配效果它们决定了 AI 什么时候会加载这个技能。写得太宽泛会导致无关任务频繁误触发写得太窄又会导致该用的时候找不到。我在自建技能文件时会尽量把description压缩在几句话以内覆盖最常见的触发场景但不过度承诺能力范围。3.2 “agent”在 Superpowers 里的角色skills 负责定义“做什么”agent 负责定义“以什么角色去做”。Superpowers 仓库里的 agents 目录放了一些配置比如 opcode 这个 agent它本质上也是一份 AGENTS.md 风格的规则文件但内容和全局规则不同——它更聚焦于工程执行的纪律性。当 Codex 以某个 agent 模式运行时它会把这个 agent 的规则注入上下文让模型在回答时保持特定的行为风格。你可以把 agent 理解成给同一个 AI 换“人设”全局技能是通用的方法论agent 则是执行方法论时的“行为准则”。比如默认的 Codex 可能更倾向于直接给代码而 opcode 则被要求“不要急着写代码先计划、再测试、后实现”。这种角色分离的价值在于你可以针对不同项目选择不同 agent而不必每次都在对话里用一大段话去约束它。实际使用中我在跑一个小需求时经常会在对话开头加上一句“请以 opcode 的工作方式处理这个任务”。这句话就像触发开关AI 会去读取对应的 agent 配置然后整个执行节奏立刻变得不一样——它会更主动地拆解步骤更倾向于先展示计划而不是直接甩代码。3.3 内置了哪些常用技能Superpowers 仓库内置的技能数量不少覆盖了从需求到上线的完整链路。我把实际使用频率比较高的几个整理成了表格方便你对照自己的场景查看技能名称触发场景核心作用brainstorming需求模糊、方案不明确时引导多角度思考澄清约束条件writing-plans任务复杂、需要多步骤实现时把大任务拆成可执行的小步骤writing-tests需要测试保障时生成测试用例并说明断言意图test-driven-development功能开发或 bug 修复时严格按红灯-绿灯-重构循环执行debugging程序运行异常时引导系统性定位根因而非盲改refactoring需要改善代码结构时在不改变行为的前提下优化设计code-review准备提交或合并代码前从正确性、可读性、安全性等维度审查git-workflow涉及分支、提交、合并时规范 Git 操作降低协作冲突这几个技能并不是彼此孤立的。实际执行一个任务时AI 会像人一样按需调用多个技能先 brainstorming 澄清需求再 writing-plans 拆解步骤进入开发后启用 test-driven-development中途可能穿插 debugging 和 refactoring最后用 code-review 收尾。这种组合调用能力才是 Superpowers 比单条 prompt 强大得多的根本原因——它不是给你一个技能而是给你一套完整的工程方法论。4. 实操用 Superpowers 跑通一个真实开发任务4.1 任务场景与启动方式理论讲再多不如亲手跑一遍。我拿一个非常典型的场景来演示需要给一个 Python 小工具增加一个带 TTL 的缓存装饰器要求缓存同一个参数的返回值超过指定秒数后自动失效。这个任务难度适中又有明确的测试点——缓存命中、过期刷新、不同参数互不干扰。如果在没有 Superpowers 的情况下让 Codex 直接写它大概率会直接给你一段装饰器代码。但如果我们用 Superpowers 的流程来跑整个节奏会很不一样。启动方式很简单直接在项目目录下运行codex然后在对话里给出需求。注意你不需要自己指定要调用哪个技能AI 会根据技能文件里的description自动匹配。我实际的输入差不多是这样请按照你的标准工作流帮我实现一个带 TTL 的缓存装饰器要求支持设置过期时间并且要保证不同参数的调用不会被错误复用。建议先测试后实现。后面加的那句“建议先测试后实现”其实只是为了让 AI 更明确地走 TDD 路径。它的技能系统本身就能判断出来但明确说出来可以降低匹配过程的不确定性。4.2 从需求到落地方案的执行过程第一个阶段AI 没有直接写代码而是先做需求澄清。它会读取 brainstorming 或 writing-plans 技能输出类似这样的一段计划1. 定义装饰器接口cache_ttl(seconds) 2. 确定缓存 key 的设计基于函数名 参数值 3. 实现线程安全的缓存读写可选取决于目标场景 4. 先编写测试用例 - 同参数重复调用应命中缓存 - 超过 TTL 后应重新执行函数 - 不同参数应互不影响 5. 运行测试确认失败 6. 实现装饰器逻辑 7. 运行测试确认通过 8. 检查边界情况如 seconds0 时的行为看到这份计划你应该能感受到它和我直接让 AI“写个装饰器”时的差别它先把验收标准定义出来了后面每一步都有据可依。在这个阶段AI 还会在计划里注明需要你确认的关键决策点比如“缓存是否需要线程安全”“装饰器是用于同步函数还是也支持异步函数”。这种“先对齐再开工”的习惯恰恰是工程中最昂贵也最容易被省略的一环。确认方案后AI 会进入测试编写阶段。这一步的输出通常是这样的import time from cache_ttl import cache_ttl def test_same_argument_hits_cache(): calls {count: 0} cache_ttl(seconds10) def add(a, b): calls[count] 1 return a b assert add(1, 2) 3 assert add(1, 2) 3 assert calls[count] 1它会明确告诉你现在运行测试应该是红灯因为cache_ttl模块还不存在。你可能会问为什么不让 AI 直接写实现然后一起跑这正是 TDD 的核心——先让测试失败才能确认测试本身有验证能力。如果测试一开始就通过你根本无法判断是代码写对了还是测试写得太弱、什么都没测到。4.3 TDD 循环里我在现场看到了什么确认测试是红灯之后AI 才会开始写实现。这个阶段它读的应该是 test-driven-development 技能具体的执行节奏是写最简实现让当前测试变绿然后停一下看有没有明显可以重构的点。以下是我在终端里实际看到的一段执行输出简化版$ pytest -q _____________________________ test_same_argument_hits_cache ___ test_cache_ttl.py:18: in test_same_argument_hits_cache assert add(1, 2) 3 E TypeError: NoneType object is not callable 1 failed, 0 passed # 红灯符合预期然后 AI 开始补实现代码再跑一遍测试$ pytest -q 3 passed in 0.32s # 绿灯整个过程中它不会一股脑把所有功能写完而是每完成一个验证点就跑一次测试。这种“小步快跑”的节奏在需要保证代码行为可控的场景里非常可靠。跑绿之后的 output 可能会附带一段重构建议比如“这段缓存 key 的序列化逻辑可以抽成一个辅助函数”。如果它判断当前代码足够清晰也会明确说“当前实现无需重构”。这些信号本身的价值很大它让你知道 AI 每一步在做什么而不是突然给你一堆代码然后让你自己 review。我在现场最大的感受是它不急着写功能代码了而是像一个心里有谱的工程师先铺路再走车。这种节奏对于测试驱动开发的老手来说很熟悉但 AI 能主动按这个节奏跑确实是 Superpowers 给我最大的惊喜。5. 常见问题与避坑实录5.1 装完了但 Codex 完全不认识 skills这是装上之后最常见的挫败场景明明安装脚本跑完了问它有哪些技能它一脸茫然。我先说排查顺序。第一步检查~/.codex/skills目录到底有没有文件很多情况下是安装脚本执行时机不对或者用户主目录不一致导致复制到了错误的路径。第二步确认你的 Codex CLI 版本足够新SKILL.md 功能是老版本不具备的升级后重试。第三步看~/.codex/AGENTS.md是否存在Superpowers 的 agent 配置依赖这个文件注入行为规则。我还遇到过一个很隐蔽的问题skills 目录下如果有子目录带了中文名或者特殊符号某些版本的 CLI 解析会直接跳过整个目录。我当时的解决办法是把所有技能目录名改成纯英文小写加连字符问题立刻消失。另外如果你在安装之后让 Codex 一直在同一个会话里它不会自动发现新技能退出重新进一次是最简单的办法。5.2 SKILL.md 写错了没人会主动告诉你SKILL.md 的格式看起来简单但容错率没有想象中高。最容易踩的坑有三个YAML frontmatter 后面没有留空行就直接写正文这会导致解析失败或整个文件被忽略description写得过长超过了模型读取时的有效范围导致匹配结果飘忽不定when_to_use写得太抽象AI 在判断“当前任务是否该触发”时产生了误判。我的建议是如果你要自己扩展技能第一次先别急着写复杂的从一个只有十几行的技能文件开始跑通之后再逐步丰富。一个简单有效的自检方式是修改完 SKILL.md 之后在 Codex 对话里用一句和你技能描述高度相关的需求去触发它看它有没有按流程执行。如果没触发大概率是description写得不够精准或被其他技能的描述覆盖了。5.3 agent 跑着跑着陷入循环上下文越吃越多用 Superpowers 跑复杂任务时模型可能出现“陷入流程”的问题计划写了一堆测试写了一堆就是迟迟不进入实现阶段或者在重构时反复修改代码但测试一直没有真正通过。这个不一定是 bug更像是模型在长步骤执行中的“注意力漂移”。一旦出现这种苗头我的止血方法是立刻按 CtrlC 终止当前步骤把已经完成的部分保存下来然后补一句新的指令比如“停不要再重写计划了从第 3 步继续”。更根本的解决方案是任务一开始就拆得更小。Superpowers 的 writing-plans 技能其实默认就会拆分任务但如果你给的需求本身跨度过大比如“帮我重构这个项目并加三个新功能”再好的 skill 也容易把上下文窗口塞满。我的经验是一个会话只处理一个核心需求其他需求开新会话做。这样既能避免上下文爆炸也方便你在每个阶段审查 AI 的输出不会因为信息过载而漏看风险点。5.4 在 Trae 这类 AI IDE 里使用 Superpowers 的经验不少人在问 trae 里能不能装 superpowers skill。我实际试过一种通用方案核心思路其实很简单Superpowers 的 skills 本质上是文本文件只要你的 IDE 支持读取类似 AGENTS.md 的规则文件并且能在项目上下文中加载外部规则你就能把它接进去。具体操作上我会在项目根目录创建一个.codex/skills目录把当前项目需要的几个技能文件复制进去然后在项目根目录的 AGENTS.md 里明确声明这些技能的存在。之所以强调“只复制需要的那几个”是因为 IDE 的上下文管理方式和命令行 CLI 不完全一样技能文件太多会占用大量上下文窗口反而降低回答质量。另外IDE 里的模型选择、自动执行命令的权限策略和 Codex CLI 是两套体系首次在 IDE 中使用时一定要看清它弹出的是不是需要执行 shell 命令的授权。我个人的建议是先在 Codex CLI 里把某一套 skill 流程跑通再拿到 IDE 里去用这样你至少清楚正常流程应该长什么样出了问题也好判断是 skill 的问题还是 IDE 环境的问题。最后再分享一个小技巧。我给自己维护了一个“技能清单”文档记录每个技能文件的上次修改日期和触发测试结论没事就打开看一眼保证自己改过的技能都能正常触发。说实话Superpowers 让我对 AI 编程的预期从“它会写代码”变成了“它会按流程把事做完”。如果你已经装了 Codex CLI花半小时把这套技能体系跑通大概率能让你的命令行 AI 助手换一种工作气质。