如果你最近在折腾 AI 编程工具大概率已经发现了一个问题模型本身越来越聪明但真正丢给它一个仓库、一句“帮我改个 bug”它还是经常东一榔头西一棒子改一半还得你亲自下场收拾。superpowers 这个 GitHub 项目最近在技术社区里讨论度很高就是针对这个痛点来的。它不是一个普通的提示词合集而是一套可以装进 Codex CLI、Trae、Claude Code 这类 AI 编程代理里的“技能包”skill让 AI 从“能聊代码”变成“会干活的工程师”。这套东西适不适合你我建议这么判断如果你只是用 AI 生成一段独立函数那用不上但只要你已经开始让 AI 接真实项目、处理多文件改动、按流程推进任务那 superpowers 提供的思考框架和工作流约束就非常值得折腾一下。本文我把它的机制、安装、使用和坑都捋一遍。1. superpowers 到底是个什么项目解码“技能包”机制先说结论superpowers 是 Jesse VincentGitHub 上叫 obra开源的一套 AI 编码代理技能包集合。它不是传统意义上的“提示词工程”而更接近一套结构化的指令协议——项目里有大量SKILL.md文件每个文件定义了一种 AI 可以调用的“技能”比如“先做调研再写方案”“按步骤重构代码”“写测试之前先列断言清单”等等。为什么要做成这种形态因为单独的 prompt 是一次性的。你这次跟 AI 说“先想想再动手”下次还得再说一遍换一个会话、换一个工具AI 又回到了“看一步走一步”的默认状态。技能包的思路是把这些行为准则固化到文件里AI 每次启动时能主动加载对应的SKILL.md相当于给它装了一套“职业习惯”。这套项目在 GitHub 上的核心能力可以拆成三类思维类技能比如 brainstorming、planning强制 AI 在动手前先做需求澄清、方案对比、风险列举而不是直接甩出第一版代码。工程类技能比如代码审查、重构、调试要求 AI 按照固定的检查清单逐项执行减少遗漏。流程类技能把多个步骤串联成工作流比如“先调研→再写计划→然后实施→最后自测”每一步都带着上一阶段的输出往下走上一个阶段的回退机制也定义好了。这套东西厉害的地方在于它不是在模型外面套壳而是把复杂的项目协作经验压缩成了一组组 AI 能“读得懂、照着做”的规范。用大白话说普通的对话式 AI 像一个临时工你指挥一下它动一下装了 superpowers 之后它更像一个有 SOP 的驻场员工知道接到任务之后第一步打开什么、第二步确认什么、什么时候该停下来问你。这里要额外说一句当时我去 clone 这个仓库的时候发现它其实和 Anthropic 后来提出的 agent skills 理念是互通的。区别在于 superpowers 更偏实战、更偏软件工程全流程而不只是一个“让 AI 会写 SQL”之类的单点小技能。2. 环境准备Codex CLI 与 Trae 的安装配置任何技能包都得有宿主才能运行。superpowers 目前最常见的宿主是 Codex CLI 和 TraeClaude Code 也能用但社区里讨论最多的还是前两者。先把环境搭好再谈装技能不然很容易出现“文件都在AI 就是不认”的情况。2.1 前提条件装 superpowers 之前你的机器上至少要满足这几个条件节点环境正常能跑 npm 或 bun因为很多 AI CLI 工具都是基于 Node 的有一个能访问 GitHub 的网络链路这个不是废话后面很多问题都出在这你选的 AI 工具能自己读写工作区文件这决定了技能包能不能被加载。如果你打算用 Codex CLI那它需要登录 OpenAI 账号并完成 API 授权。这一步别嫌麻烦我之前见过有人跳过登录直接往里塞技能包结果 AI 根本不知道SKILL.md的存在。2.2 Codex CLI 的安装方式Codex CLI 目前处于快速迭代期安装方式可能随版本变化但核心路径是类似的。最常看到的两种方式通过 npm 全局安装npm install -g openai/codex装完以后执行codex --version确认一下。如果你对版本敏感想装 nightly 版本也可以直接指定 dist-tagnpm install -g openai/codexnightly装完之后记得运行codex login完成授权它会生成一个配置目录通常在~/.codex/。这个目录很重要因为后面你要决定把 superpowers 装成“全局技能”还是“某个项目的局部技能”。2.3 Trae Work CN 环境下的注意点Trae 这边的做法不太一样。Trae尤其是国内版的 Trae Work CN本质上是 IDE有图形界面它的 AI 能力是基于内置 Agent 的。装 skill 的时候思路是这样的打开项目工程目录把 superpowers 仓库 clone 到工作区里或者 clone 到一个固定路径让 Trae 的 Agent 能读取到技能文件——有的版本支持在工作区里放一个特殊目录作为技能根目录有的版本你需要手动把技能内容通过自定义指令引入。我自己的体验是Trae 的版本差异挺大早一些的版本对技能包的支持没那么透明如果你在设置里看不到任何“技能包”相关入口那大概率就是当前版本还没放开这时候要么等更新要么优先用 Codex CLI 或 Claude Code 来跑。硬要装也不是不行但往往需要把技能内容以“系统 prompt 附加文本”的方式塞进去体验会差不少。提示别一上来就在几个工具之间反复横跳。先选定一个宿主把一套流程跑通再去适配其他工具。否则你很可能花了一个晚上最后只是折腾了三个不同的安装路径。3. 安装 superpowers 的完整操作流程从 clone 到验证下面进入正题怎么把 superpowers 装起来。我以 Codex CLI 为默认演示对象因为它的目录约定最清晰理解了它的结构Trae 那边就是举一反三的事。3.1 把项目文件拿到本地git clone https://github.com/obra/superpowers.git ~/superpowers建议 clone 到固定的路径比如用户目录下而不是某个临时目录。因为后面配置全局技能包时Codex CLI 需要一个稳定的路径去引用这些技能文件。clone 完以后可以先进去看一眼目录结构cd ~/superpowers ls -la里面会有一堆以技能命名的子目录或者skills/这样的分类目录比如brainstorming/、planning/、code-review/之类以仓库当前实际结构为准。每个目录里通常都有一个SKILL.md那就是 AI 要读的说明书。3.2 让 Codex CLI 认识技能文件这一步是最容易踩坑的地方。很多人以为“clone 下来了就完了”但 AI 工具不会自动扫描你的文件系统去找技能。你需要把技能目录告诉 Codex。常见做法是修改 Codex 的配置文件。先看配置文件在哪codex config list或者直接打开~/.codex/config.toml不同版本文件名可能是 json/yaml结构类似。找到和“指令”或“额外上下文”相关的配置项把 superpowers 技能目录的路径加进去。如果配置项是数组形式可以加一行类似instructions [ ~/superpowers ]具体字段名以你安装的版本为准但思路是一致的把技能目录的路径暴露给 Codex让它知道“每次对话时可以去这些地方找 SKILL.md”。如果你是高频 Codex 用户我还建议把AGENTS.md的继承逻辑一并考虑。Codex 本来就会读取项目里的AGENTS.md作为项目指令如果你只把 superpowers 装成指令文件AI 会把它当成“项目背景”来读而不是“可调用的技能”。所以严格来说最好的效果是放在技能目录机制里而不是简单混入指令。3.3 Trae 上的安装适配在 Trae Work CN 里安装思路可以这样走在 Trae 的终端里执行同样的 clone 命令把 superpowers clone 到一个工作区外但路径稳定的地方查看 Trae 是否提供“自定义技能”或者“Agent 扩展”这类设置项如果有直接把 skills 目录添加进去如果没有现成入口就在工程根目录下手动建一个skill或者.trae/skills目录然后把 superpowers 里的目录软链或复制进来在 Trae 的 AI 对话里直接问它“你有哪些技能”看它能否列出 superpowers 里的技能名。如果能列出来说明 AI 已经能感知到技能包了。这里多说一句国内版 Trae 不同时期的版本差异较大如果没有官方技能机制强行装它意义不大。你更值得做的是在 Trae 里把 superpowers 的某些技能内容手动粘贴成项目指令至少让 AI 具备“先规划再动手”的倾向就算没有完整技能菜单也比默认状态好用。3.4 验证安装是否成功装没装成功不要看文件落地没有要看 AI 的行为变没变。我的验证步骤是开一个新会话输入一句简单的任务“帮我给这个项目写一个 README”如果 AI 开始先问问题、列澄清清单、甚至说“我需要先了解一下项目”而不是直接甩出一段 README 正文说明它已经加载了某项技能再进一步明确要求它“使用 brainstorming 技能”看它会不会给出结构化的提问框架最后看技能文件的输出是否真的被保留下来比如 AI 是否在当前目录生成了一些中间文档。如果这些都满足安装基本算成功。如果 AI 对你的技能指令毫无反应回到第 3.2 步检查路径或配置格式。4. 内置技能包逐个拆解这些技能到底让 AI 做了什么装好之后你最该做的一件事是把 superpowers 仓库里的SKILL.md都读一遍别急着让 AI 跑任务。这个仓库的核心资产就是这些技能定义。我在本地翻了一遍把它最有代表性的几类技能拆开讲讲。4.1 需求澄清类brainstorming这个技能要解决的问题很典型用户自己都还没想清楚需求AI 就开写了。比如你说“给我做个待办事项应用”不做澄清的 AI 会直接掏出一个 Todo CRUD做了澄清的 AI 会先问你“你要命令行版本还是网页版要不要多用户数据存哪有没有移动端计划”brainstorming 技能的本质是把产品经理那套问问题的逻辑写成了 AI 可以执行的流程通常它会让 AI先用一两个开放式问题打开局面基于用户的回答收敛到具体方案把结论重新复述给用户确认。这套流程对大型项目尤其有价值。因为上下文窗口再大也不如一开始就把需求边界定清楚来得省事。我自己现在接一个新需求时会主动输入“请用 brainstorming 技能帮我澄清这个需求”它基本能逼着我把想法彻底说明白。4.2 规划拆分类planning / 开发计划规划类技能是 superpowers 里含金量最高的部分之一它相当于把架构师的工作流程压缩成了 AI 可执行的步骤。你给它一个已经澄清过的需求它会先拆分出功能模块评估每个模块的技术难点和依赖关系排出一个可执行的先后顺序标记清楚哪些地方需要你提供额外信息。比较有意思的是planning 技能还强调了一个反直觉的原则先写计划再写代码但计划写得不能太细。太细的计划会让 AI 变成“照着清单填空的机器”一旦中途发现需求变化整个计划就废了。它更推崇的是“里程碑式的粗计划 每步动态调整”。4.3 代码执行类实施、重构、审查实施类技能负责把写代码这件事从一个“偶发行为”变成“可验证过程”。superpowers 在这里做的事情很朴素强制 AI 写一段代码前先说明意图代码写完后马上自测而不是把所有代码一次性堆出来。重构技能则更像一个检查清单它会要求 AI确认是否影响现有接口是否有测试覆盖变更波及的范围能否控制在单个技能边界内。这些约束看起来很基础但恰好是默认 AI 编程模式最弱的地方。你回想一下让 AI 改代码的场景它是不是经常一次给出一大段完全重构后的代码根本不管你的 diff 是否可控重构类技能就是来治这个毛病的。4.4 验证类测试、代码审查、debugging调试类技能在实战里非常出彩。它让 AI 不再“猜 bug 原因”而是按照一套标准排查流程走先复现、再缩小范围、再提假设、再验证。听起来像是废话但默认状态下的 AI 很爱跳步直接跳到最后一步“改代码”然后告诉你“应该好了”。装上调试技能之后它会先跟你确认复现步骤甚至主动要求你提供更多日志信息。测试类技能则要求 AI 在写测试之前先列出断言清单。这个做法很妙因为大多数人让 AI 写测试的方式是“给这段代码写几个测试”AI 就广撒网嗯造用例。有了断言清单AI 会先想清楚“到底要验证什么”再落成代码测试的有效性高很多。5. 技能的组合方式与工作流机制它们是怎么协同工作的单个技能只是工具真正让 superpowers 好用的是技能之间的串联方式。这有点像你把一个专家团队的方法论写成了手册AI 只是拿着手册在干活。5.1 技能的调用与触发显式调用为主、隐式触发为辅superpowers 里的技能多数是“显式触发”的。也就是说你需要在对话里明确说“使用 xx 技能”AI 才会打开对应的SKILL.md并按流程执行。这不是缺点反而是优点——技能调用的透明度高你知道 AI 当前在用什么套路不会出现它悄悄换了套流程你却没察觉的情况。某些版本的宿主支持技能描述自动匹配AI 看到任务后会在技能列表里找相关性最高的那个然后自动使用。如果你发现 AI 没有自动触发直接手动点名技能就行不用勉强依赖自动触发。5.2SKILL.md的读取逻辑SKILL.md是技能包的最小单元。默认情况下AI 不会把一个目录下的所有文件都读一遍它只读SKILL.md从中获取技能的“使用说明”和“调用方式”。所以你在安装技能包时最关键的是确认SKILL.md能被找到而不是把整个目录一股脑塞给 AI。从我自己改技能的经验来看SKILL.md里最重要的部分是这几个字段技能的触发条件什么任务类别该用这个技能执行流程分步骤的指令清单输入输出约定该技能的输入信息是什么、执行完要产出什么。它像一份函数文档只是函数体是自然语言写的。5.3 一个典型的多技能串联流程我举个例子。假如我让 AI 做一个“给现有 CLI 工具增加一个子命令”的需求一个比较理想的执行顺序是用 brainstorming 技能澄清这个子命令的语法和交互方式用 planning 技能列出涉及的文件、风险点、测试方案让 AI 按规划实施每完成一步就停下来让我确认用测试技能给这个子命令写断言清单并执行最后用代码审查技能做一轮 self-review。你会发现这套流程里 AI 最核心的工作不是写代码而是把整个任务的“上下文”管理好。默认的 AI 聊天模式是“问一句答一句”而技能组合让它变成了“走完一个完整的工作流再向你汇报”。这才是它最有价值的地方。6. 实测效果与使用边界哪些场景收益最大哪些不算理想我自己在这套技能包上跑了大概两三周有很爽的时候也有觉得它多余的时候。这里说点大实话。6.1 收益最明显的场景第一个是“老项目小改动”类任务。比如一个有一定历史的代码库要求 AI 加一个日志模块或者调整某条报错处理逻辑。没有技能的时候AI 经常忽略既有风格直接按自己的习惯写有了代码审查和重构技能它至少会先看看现有代码结构再动手产出的代码风格明显更融合。第二个是“需求模糊”的场景。以前丢一句“帮我优化一下这个模块”AI 会直接给你一顿重构然后你发现它改了一堆不该改的东西。现在它会先问“你说的优化是指性能还是可读性有没有不可触碰的接口”效率反而上来了。第三个是全流程任务的推进。用它跑过一个小项目的完整开发流程后你会发现中间产物澄清记录、计划文档本身就有价值——即使最后代码推翻重来前期的思考过程依然是你做决策的参考。6.2 效果一般的场景反过来如果只是做一次性脚本、写个无状态的函数、问个语法细节那 superpowers 带来的收益就很有限甚至有点迟钝。因为这些场景不需要复杂流程你让 AI 走一套澄清规划反而拖慢节奏。另外如果你的项目上下文极其简单比如一个刚初始化的 React 模板技能包带来的限制可能大过帮助。它默认的流程会要求 AI 做很多解释和确认在一个 5 分钟能搞定的 demo 项目里这种克制感是有代价的。6.3 使用边界与“要不要全流程”的判断我的建议是把 superpowers 当成一个可选的“模式”而不是默认插件。接到任务时先判断一下复杂度需要动多个文件、涉及既有接口、需求不明确就点名让 AI 走到对应技能反之就直接对话式解决。这套项目本身的设计也承认了这一点。它不试图让 AI 在每一步都变成“谨慎的架构师”而是给你一套可以在关键节点强制 AI 切换思考模式的工具。用不用、什么时候用是用户自己的判断。7. 常见问题与完整排查链路装完不生效从头到尾查一遍最后这部分写给遇到问题的人。我见过太多人跑来问“为什么我装了 superpowersAI 完全没反应”其实九成都是路径和调用方式的问题不是技能包本身失效。这里给出一个我自己的排查顺序照着走一遍基本能解决。7.1 排查第一步确认技能文件真的存在别笑这一步真的有人跳过。先明确一个问题你 clone 下来的仓库里到底有没有SKILL.md、技能目录结构是什么样的不同的分支和版本目录结构会有差异。确认方式很简单find ~/superpowers -name SKILL.md | head -20如果一条结果都没有说明你 clone 的东西本身就不对或者仓库更新后目录结构变了。这时候去看仓库的 README找到最新的技能目录说明。7.2 排查第二步确认配置是否真的指向了技能目录Clone 下来文件只是第一步关键是宿主工具是否知道这个目录。打开~/.codex/config.toml检查那行和技能路径相关的配置。很多时候问题出在相对路径上——你用了./superpowers但 Codex 启动时的工作目录并不在用户目录所以它实际找不到。我的建议是配置里直接写绝对路径instructions [/Users/你的用户名/superpowers]改完配置后一定要重启 CLI让配置重新加载。7.3 排查第三步确认是不是权限和上下文设置问题如果路径没问题AI 还是不理不睬那很可能是因为宿主工具默认不启用技能自动加载需要你在对话里显式说“使用 xx 技能”来触发。别指望 AI 每次都能自己搜到技能包列表。还有一类问题是权限Codex 或 Trae 的 Agent 没有工作区写入权限导致它虽然读了技能文档但没法把中间产物写到磁盘上流程就跑不动。这通常在工具的设置里有一个“允许读写文件”之类的开关。排查链路小结问题现象排查顺序常见解法技能完全不被触发文件存在 → 配置指向 → 显式调用补齐SKILL.md、改用绝对路径、对话中点名技能技能被触发但流程中断看权限 → 看是否缺少依赖 → 看输出提示开启工作区写入权限、补充系统依赖AI 不按技能执行自作主张看版本 → 看上下文里是否混入了旧指令更新宿主版本、清理旧会话指令安装后没有任何变化看是否开了新会话技能包往往只对新会话生效注意第四点是最隐蔽的。我之前调完配置在旧会话里怎么测都没反应后来新开一个会话它立刻就加载了。很多 CLI 工具在会话启动时读取配置中途修改不会热更新别在这上面白耗时间。7.4 一个额外的经验如果你在多个工具之间来回切换使用这套技能包最好固定一套工作流比如“只在 Codex CLI 里用完整技能包在其他 IDE 里只保留 brainstroming/planning 几个核心技能”。原因是不同宿主的技能加载机制不同同样的技能包在不同工具里效果差异很大。与其追求全平台统一不如在不同环境里各取所长。我现在的工作习惯是Codex CLI 跑全流程、Trae 里做日常代码问答和快速编辑、需要深度重构时再回到 CLI 环境走一遍完整技能流程。这套搭配目前用下来最顺手也推荐你试试看。