说实话我第一次看到superpowers这个项目标题时第一反应是又一堆花里胡哨的AI包装。但真正用了一段时间之后我得承认这个项目确实是目前给 AI 编程助手开挂最直接、最系统的一套东西。它不是简单的提示词集合而是一套完整的工程方法论把怎么让 AI 更靠谱地干活这件事从玄学变成了流程。如果你在用 Codex CLI、Claude Code或者任何支持 Skill 机制的 AI 编程工具那么这篇文章值得你花十分钟看完。我会从源码结构讲到实际安装再到每个核心 Skill 的使用场景和坑点全部基于我自己的真实操作记录不是官方文档的复读机。1. superpowers 到底是什么1.1 一个给 AI 编程助手装工作脑的 Skill 合集superpowers 是 GitHub 上一个开源项目核心作者是 Jesse Vincent也是 Hackers Diet 的作者。它的定位非常明确给 Claude Code、Codex CLI 这类 AI 编程工具注入一组结构化的工作流技能让模型不再你问一句它答一句而是能像资深工程师一样按套路开工。所谓 Skill我后面会详细拆解你可以先理解成一个带说明书的外部模块。每个 Skill 都有自己的 SKILL.md 文件里面写清楚这个技能在什么场景用、按什么步骤执行、有哪些注意事项。superpowers 把这个机制玩到了极致——它内置了几十个相互关联的 Skill覆盖从需求头脑风暴、项目规划、任务拆解到测试驱动开发、系统调试、代码审查的全流程。我跟很多朋友聊这个项目时发现不少人一开始都把它当咒语包用觉得装上就能让 AI 变聪明。这其实是误解。它的价值不在于某个单独的提示词而在于让 AI 在工作流程的关键节点主动停下来思考。比如写代码之前先做规划调试的时候不再瞎试而是先建立假设再验证。这个思路本身就是工程上一直在强调的纪律感。1.2 从工具到工作流它解决的根本问题很多人觉得 AI 编程不稳写小 demo 很强一上真实项目就拉胯。我用了这么久核心痛点就三个第一缺乏上下文管理。AI 的上下文窗口再大也是有限的普通用法下它会把大量 token 花在无关紧要的对话历史上等真正要处理关键逻辑时注意力已经散了。superpowers 的每个 Skill 通过渐进式披露progressive disclosure机制只在需要时才加载对应的详细说明从机制上避免了上下文被垃圾信息占满。第二没有推理链。直接问 AI帮我实现一个订单系统它可能会闷头生成一坨代码没有需求澄清、没有技术选型、没有边界考虑。superpowers 的 planning 和 brainstorming 流程强制 AI 在动笔之前完成思考把隐性决策显性化。第三反馈回路缺失。人写代码有编译器报错、有测试跑挂AI 生成代码后往往是一次性交付自己写的东西到底对不对它没有验证意识。superpowers 通过 TDD、系统调试、代码审查等 Skill硬生生给 AI 装上了写完必须验证的肌肉记忆。所以如果你是AI 焦虑型开发者看它怎么一步步把混沌需求变成可执行任务可能会比看一百篇如何让 AI 写代码更准的攻略都有用。它改变的不仅是输出质量更是整个交互模式。2. 核心机制拆解SKILL.md 与渐进式披露2.1 一个 Skill 就是一个随时翻看的说明书要理解 superpowers必须先理解 Skill 的文件结构。每个 Skill 本质是一个目录里面最关键的文件叫 SKILL.md头部有一段 YAML frontmatter定义了技能名称、描述、适用场景后面是正文写具体的执行步骤。我最开始看这个结构时觉得也没什么特别的就是一个增强版提示词。后来才意识到真正的核心在于描述description怎么写。模型会通过描述来判断当前这个场景该不该调用这个技能如果描述太泛模型就容易瞎触发如果太具体又覆盖不了多样化的请求。superpowers 在这一点上处理得很聪明。它每个 Skill 的描述都走场景触发条件的路线比如调试技能会写当系统行为不符合预期、你没有完整解释时请考虑使用本技能规划技能会写在收到需要一步步完成的复杂指令时本技能可以帮助你规划全过程。这也解释了为什么我在 Codex CLI 里经常看到它主动调出某个 Skill 帮我理思路——描述写得好触发就自然。2.2 思维框架注入OODA 循环、第一性原理与系统思考superpowers 真正有含金量的地方是把几种著名的思维模型变成了可操作的 Agent 行为。我在实际使用中最有感知的有三套OODA 循环Observe-Orient-Decide-Act。这是从空战战术里来的决策框架核心是观察-调整-决策-行动的高速迭代。superpowers 把它用在编写代码和调试上先观察现状看代码、看报错、跑命令再调整方向基于观察判断问题类型决定策略选修复方案或回滚最后行动并立即观察反馈。这比让 AI直接修靠谱得多因为大部分调试失败都是因为跳过了前两步直接进入行动。第一性原理思维。这个 Skill 会要求 AI 把问题拆到最底层的不可约事实再从这个基础上重新构建解决方案。比如用户说我要做个博客系统第一性原理的拆法是用户要解决的是发布内容并被他人阅读这个基本需求而不是一上来就选 Next.js 加数据库。我试过几次它确实能让 AI 从惯性方案里跳出来给出更贴合场景的设计。系统思考。这个更偏宏观要求 AI 不只看单个组件而是分析整个系统中的交互关系、反馈回路、瓶颈所在。在有存量代码的项目里这个 Skill 的价值特别明显它能避免 AI 对着一个点猛修结果把其他地方搞崩。2.3 为什么它比普通提示词更有效我自己的理解是普通提示词是一次性指令而 Skill 是可复用工具。Prompt 写得再精细也就针对某一个场景换个项目就废了。Skill 则是把经验沉淀成文件每次调用都是加载一套完整的、经过验证的工作流程。另外它有分层加载特性。superpowers 不是把所有 Skill 内容一次性塞进上下文而是先由主入口文件告诉模型有哪些技能可用模型判断需要某个技能时再通过工具调用去读取对应的 SKILL.md。这种按需加载机制非常关键相当于让 AI 在动手前先查手册而不是脑子里塞满所有手册。打个比方普通提示词像你给实习生口头交代任务说多了他记不住说少了他又会犯蠢superpowers 的 Skill 像给实习生一本 SOP 手册他接任务时翻对应章节按流程做错了还能回到手册查。这在长任务里效果尤其明显因为越到后面模型越容易忘记前面的约定。3. 安装与配置实操Codex CLI 与 Trae 实测3.1 环境准备与前置条件在安装 superpowers 之前先确认你的环境一个支持 Skill 机制的 AI 编程工具。目前我用过且确认能跑的是 Codex CLI 和 Claude Code。Trae 的规则机制也可以对接但配置方式稍有差别我下面单独讲。Node.js 环境。Codex CLI 是 npm 包安装前先确认 Node 版本建议 18 以上。Git。安装脚本会从 GitHub 拉取仓库。可用的 API 权限。无论是 OpenAI 还是 Claude 的后端都要能正常对话。还要提一点superpowers 对模型的推理能力有一定要求。我实测下来GPT-4 级别以上的模型才能较好执行 Skill 里的复杂流程太弱的模型会出现读了说明书但不按说明书做的情况。3.2 Codex CLI 安装 superpowers 的完整步骤先把 Codex CLI 装上如果你已经装过可以跳过这步npm install -g openai/codex安装验证codex --version然后安装 superpowers。官方推荐一条命令搞定curl -sSL https://install.superpowers.dev | bash这条命令会自动完成以下事情下载 superpowers 项目源码到本机一般是~/.superpowers。把 Skills 目录链接到 Codex CLI 的配置目录通常是~/.codex/skills。在 Codex CLI 的配置里写入基础指令让模型启动时了解可以使用哪些技能。如果你不放心直接跑 curl 管道 bash也可以手动克隆git clone https://github.com/obra/superpowers.git ~/.superpowers然后手动把~/.superpowers/skills下的内容复制或软链到~/.codex/skills/mkdir -p ~/.codex/skills ln -s ~/.superpowers/skills/* ~/.codex/skills/接着编辑 Codex 的配置文件一般位于~/.codex/config.toml加入[instructions] file ~/.superpowers/AGENTS.md这个 AGENTS.md 是总入口文件作用就是告诉模型你有哪些技能什么情况下用哪个。配置好后重启 Codex CLI输入有哪些技能可用如果模型能列出 skill 清单就说明安装成功了。3.3 Trae 中如何使用 superpowers skillTrae字节出的 AI IDE是我最近常用来做轻量开发的环境。它的机制和 Codex CLI 不太一样更偏向项目内规则的方式。我实测可行的接法是这样的先克隆 superpowers 仓库到本地然后把需要的 Skill 目录复制到项目的.trae/rules目录下。比如git clone https://github.com/obra/superpowers.git ~/superpowers-src mkdir -p /path/to/your-project/.trae/rules cp -r ~/superpowers-src/skills/* /path/to/your-project/.trae/rules/然后在 Trae 里打开项目确认规则文件被加载。Trae 通常会在对话输入框上方显示已加载的规则数点开能看到每个 Skill 的说明。这里有个注意点Trae 的规则机制不保证所有 Skill 都能被及时触发尤其是那些需要在对话中按需读取的 Skill表现不如 Codex CLI 稳定。我的建议是在关键项目里只挑两个最常用、最核心的 Skill 放进去比如brainstorming和system-thinking效果反而比全量灌入更可控。3.4 增量更新与验证安装superpowers 社区迭代很快我大概每两周就会看到新增或改进的 Skill。更新方式很简单如果你是脚本安装的curl -sSL https://install.superpowers.dev | bash再做一次即可它不会清除你之前对 Skill 的自定义修改但保险起见有自定义修改前先做个备份。如果你是 git clone 方式cd ~/.superpowers git pull origin main然后重启工具。验证是否更新成功我一般会在对话里问模型现在有哪些可用的 superpowers 技能或者在启动时让它简要列出 Skill 清单。如果模型能说出brainstorming、planning、debugging、TDD这些名字基本就说明加载正常。另外建议装完之后跑一个最简单的全流程测试让它帮你实现一个非常小的功能比如写一个斐波那契函数要求先测试后实现。如果它启动了 TDD 流程先写测试、跑挂、再写实现说明 Skill 链路通了一半如果它仍然一步到位甩代码那大概率是某个环节没配好或者用的模型太弱。4. 核心 Skill 模块功能与使用指南4.1 Brainstorming把模糊需求变清晰的提问机器我最早用 superpowers 是从 brainstorming 这个 Skill 开始的。因为工作里经常遇到的场景是产品扔过来一句话需求我想做一个用户积分系统细节什么都没有。如果是裸用 AI它会直接帮你设计表结构和接口但设计是否合理完全看运气。而 brainstorming 这个 Skill 做的事情是强制 AI 进入提问模式通过多轮追问把需求里的模糊地带一个个挖干净。以用户积分系统为例它会先问积分的获取途径有哪些是否支持过期清零积分能否兑换现金涉及合规问题负向积分怎么处理然后再进入技术细节并发扣减的幂等性、积分流水记录粒度、与订单系统的交互边界。第一次用的时候我就觉得这方式挺反直觉的因为大多数开发者的习惯是先做再说但实际踩坑往往都来自没想清楚就写。这个 Skill 逼着 AI 在一开始就把隐性需求显性化省下来的返工时间远比提问消耗的时间多。如果你值班遇到领导临时丢来一个含糊需求我强烈建议你让 AI 开 brainstorming 模式它会变成你最好的需求澄清助手而且问出来之后你自己对需求的把握也会上一个台阶。4.2 Planning从目标到任务的拆解引擎需求澄清后接下来就是规划。superpowers 的 planning Skill 是我日常使用频率最高的一个它解决的痛点是AI 在面对多步骤任务时容易局部正确、整体失控。这个 Skill 的执行流程大概是这样把目标用一句话写清楚。列出所有需要做的任务拆成粒度足够小的清单一般每个任务不超过半小时工作量。标出任务之间的依赖关系。识别风险点和可能需要外部输入的地方。给每个任务指定验证方式。我之前让它规划过一个内部工具的重构任务输出结果让我有点惊讶。它不只列了技术步骤还把旧代码中哪些地方可能会影响存量逻辑哪些模块需要先写测试再重构什么时候应该和业务方确认这类内容都标了出来活像一个经验丰富的技术主管在排期。我拿这个结果去跟组里的同事对方案他们都说这个计划可以直接放进迭代里排期用。4.3 TDD给代码上保险再动手superpowers 里的 TDD Skill 贯彻的思路是测试先行-看到失败-再写实现-看到通过-重构不是让你手动敲这些步骤而是让 AI 自己按这个节奏来。我印象最深的是有一次让它实现一个带有复杂边界条件的日期计算函数。裸用 AI 的时候它喜欢直接给我一段看起来对的代码边界情况全靠测试才能发现但开着 TDD Skill 之后它先写了一批测试用例包括闰年、跨月、时区切换这些边界然后跑测试确认失败再开始写实现最后全部跑通。这背后的原理其实很朴素当你让 AI 先表达什么是正确时它对如何实现正确的约束会强很多。没有测试约束时模型容易生成一个统计上看似合理的函数但实际上忽略了角落里的异常。而测试用例本身就是最明确的约束。我现在的习惯是凡是要写核心业务逻辑都会在 Codex 里明确告诉它use TDD mode。这也带来了一个好处生成的代码自带测试后续做回归验证轻松不少。4.4 调试与系统思考不瞎试先建模调试这个 Skill 被被很多人低估但我认为它才是 superpowers 里含金量最高的一个。它要求 AI 在拿到一个 bug 时先解释问题的可能原因再验证假设然后才动手修完全摒弃了看到报错就直接改的坏习惯。有一次线上环境有个偶发性的并发问题日志只显示数据库锁等待超时。我让 Codex 开着调试 Skill 来排查。它没有直接让我改连接池配置而是先列出可能导致锁等待的多个假设包括长事务未提交、索引失效导致锁范围扩大、批量操作占用了过多行锁等然后针对每个假设设计验证方式查慢查询日志、看事务持续时间、检查索引使用情况。最后定位到是一个批量更新语句的查询条件导致全表扫描锁范围从几行扩大到整表。这个过程跟我们人工排查的思路完全一致但 AI 能把所有的可能性列得比我更全而且不遗漏。至于system-thinkingSkill更适合中大型项目的全局审视。它会要求 AI 关注模块间交互、数据流、瓶颈位置。我在做一次模块拆分评审时用过一次它指出我方案里一个缓存和数据库的一致性风险点如果不是系统思考提示我根本不会注意到那个环节。对于要重构老项目的朋友这两个 Skill 一定别浪费。5. 常见问题与排查技巧5.1 模型工具的技能列表为空或无法加载这个问题的典型表现是问 AI 有哪些可用技能回复说没有找到。我排查步骤一般按顺序来看 skills 目录是否正确链接。命令行里执行ls ~/.codex/skills/确认 Skill 文件夹存在。如果为空检查脚本执行过程中有没有权限错误。确认配置文件里 instructions 路径写对没有。注意~符号在config.toml里是否可以解析。如果不确定直接写绝对路径。如果目录和配置都没问题把模型换成更强的新版本再试。有些老模型支持工具调用的能力差SKILL.md 读取不成功但不会报错。5.2 模型在读 Skill 文件时敷衍了事这个问题其实挺普遍的Skill 文件读是读了但模型的执行流程没有真正按 SKILL.md 的步骤来。比如 planning 技能要求先列计划再动手它却直接写代码。我的解决方案是在对话里给一个明确的高层级指令例如使用 planning 技能完成任务。在开始动手前先向我展示你的计划并等待我确认。这样等于把按流程走变成了当前任务的明确要求模型就不太会跳过。还有一个技巧是缩小范围不要在一个任务里同时加载太多 Skill。上下文里同时有 5 个 Skill 说明时模型会不知道该听谁的高手的选择是每次专注于一到两个 Skill。5.3 上下文窗口被 Skill 文件撑爆如果项目复杂同时启用多个 Skill模型可能因为上下文过长而出现响应变慢或遗忘早期指令。这时候渐进式披露的优先级就体现出来了但如果你用的工具没有做按需加载比如某些简易接入方式就很容易碰到这个问题。我的做法是分层使用项目规划阶段只开 planning 和 brainstorming编码阶段只开 TDD 和 code-review调试阶段再开 debugging。不要幻想一个会话里全程开满所有技能。5.4 Skill 与工具链冲突有时候 superpowers 的 Skill 会要求执行诸如运行测试、检查文件等操作如果你的 AI 工具本身没有很好的工具调用权限就会出现 Skill 建议做但工具做不了的情况。解决办法是确认这些操作是否可用如果不可用就在对话里人工执行并把结果贴回去。这虽然多了一步但总比让 AI 凭空猜测测试是不是通过了要强。5.5 我的独家使用心法最后分享三个我个人总结的心得第一超能不是越多越好。新用户最容易犯的错是装了全套 Skill然后抱怨 AI 行为变得啰嗦。它的每个 Skill 本质上都是一套行为约束约束越多模型的自由度越低。我建议新手先只保留brainstorming、planning、debugging三个等熟悉了再逐步加 TDD 和系统思考。第二好的任务描述比 Skill 更关键。Skill 是放大器不是无中生有的魔法。你给的任务上下文越清晰、验收标准越明确Skill 发挥的空间越大。如果你扔一句帮我优化一下这段代码再强的 Skill 也救不了。第三把 Skill 当团队规范来用。我在小组里推广 superpowers 的方式不是让大家去装个工具而是让大家用它的流程来结对编程。一个人写需求描述另一个人按 Skill 的规划流程拆解任务这个方法比单纯让 AI 自动干活更有收获因为拆解过程本身就是一次高质量的设计评审。用了一段时间 superpowers 之后我的整体感受是它没有让我少写代码但确实让我少了很多写完发现方向错了的崩溃时刻。AI 编程的瓶颈从来不是模型不够聪明而是我们太急着让它输出没有给它足够的思考结构。superpowers 提供的恰好就是这套结构。
