先说个暴露年龄的事我第一次看到“superpowers”这个词在技术圈刷屏脑子里冒出来的是小时候看的动画片以为谁在聊超能力。直到有朋友甩给我一个GitHub仓库链接我才反应过来——这玩意儿是给AI编程工具装“战斗技能”用的而且是那种装上之后你明显能感觉到手底下这个AI助手从“听话但平庸”变成“有章法、能扛事”的存在。简单说superpowers是一个面向Codex CLI、Trae这类AI编程代理AI coding agent的技能增强包。它不是一套花哨的UI也不是一个IDE插件而是一堆结构化的“技能文件”Skills外加一整套工作流Workflows和协作规范Guidelines。装上之后AI代理在写代码、改需求、查bug、做代码评审这些环节里的表现会完全不同。这篇文章我就把自己从“clone仓库”到“摸清每个技能怎么用”的完整过程整理出来包括安装步骤、核心技能拆解、每个环节背后的设计逻辑以及我在实际项目里踩过的坑。1. 这个项目到底是什么重新认识superpowers1.1 给AI编程工具装上“战斗技能”先说结论superpowers是一个“技能集合包”它服务的对象不是普通用户而是已经在用AI编程代理的人——比如你习惯用Codex CLI在终端里让AI改代码或者用Trae这类AI IDE做日常开发。这个项目把AI代理需要掌握的能力拆成了一个个独立“技能”比如头脑风暴、制定计划、写测试、调试、代码审查、安全审计等。每个技能都不是一句简单的prompt而是一整套带步骤、带规则、带输出格式的“操作手册”。AI代理在收到任务时会根据需求主动调用合适的技能文件然后严格按照里面的流程来执行。我举个例子你就明白了。默认情况下你让Codex帮你“给登录模块加上忘记密码功能”它可能会直接甩出一版代码改动。但如果你装了superpowers它会先走一个brainstorming流程问你业务背景、确认用户流程、拆解边界条件然后生成一个实现计划最后才动手写代码。整个过程有讨论、有决策记录、有验收清单像是一个高级工程师在带你过需求而不是一个打字员在帮你填代码。1.2 它和普通prompt模板的本质区别很多人一听“给AI装技能”第一反应是“这不就是预设prompt吗”我一开始也这么想但深挖之后发现完全不是一回事。普通prompt模板是“一次性”的。你把一段精心设计的文字复制到对话里AI这次会表现得很好但下次换个任务、换个上下文它又回到原样。superpowers走的是“文件即技能”的路线每个技能都是一个独立的Markdown文件通常叫SKILL.md里面用结构化方式定义了触发条件、执行步骤、输入输出格式、质量标准。AI代理会在合适的时机主动去读这些文件然后按照文件里写的流程来行动。这个区别非常关键。前者是“你教会AI这一次”后者是“你让AI拥有一套可复用的能力”。而且这套能力是跟随项目走的——你可以在不同的项目仓库里复用同一套技能文件也可以按项目类型定制不同的技能组合。我自己的体会是装上之后AI代理的执行逻辑会变得“有迹可循”它每一步为什么这么做、下一步要做什么都清清楚楚出了问题你能顺着流程找到根因。1.3 它的适用人群与场景如果你属于下面哪一类我强烈建议你花半小时折腾一下这个项目重度使用Codex CLI或Trae的开发者觉得AI目前“只会写代码不会想问题”。团队里在推AI辅助开发想让所有成员的AI代理都遵循同一套工作规范、输出同等质量的结果。被AI“自作主张”坑过的人——比如它直接改了不该改的文件、跳过了测试、或者把需求理解跑偏了。希望把AI的思考过程、决策记录、测试结果留下书面痕迹方便复盘和追溯的人。反过来如果你只是偶尔让AI帮你写段脚本、翻译点文案那这个项目对你来说确实有点“杀鸡用牛刀”。它更适合那些把AI当“日常开发搭档”的人。2. 动手之前先搞懂它的核心设计2.1 技能包里的“技能”到底长什么样superpowers的仓库结构其实非常清晰。你clone下来之后会看到几个核心目录我建议你先花十分钟浏览一遍别急着配置。先说skills/目录这里放的就是一个个独立技能。每个技能一个子目录里面至少有一个SKILL.md文件。这个文件是整个技能的核心通常包含YAML格式的frontmatter元信息比如技能名称、触发条件、适用场景和正文部分具体执行步骤、规则、示例。比如skills/brainstorming/SKILL.md就是头脑风暴技能skills/writing-plans/SKILL.md是写实施计划的技能。然后是workflows/目录它定义的是“技能之间的协作流程”。你可以把skills理解成乐高积木workflows就是拼装图纸。比如一个完整的“从需求到上线”流程可能会依次调用brainstorming、writing-plans、coding、testing、code-review这五个技能。AI代理会根据当前任务所处阶段自动选择下一步应该激活哪个技能。还有guidelines/目录它是一些跨技能通用的行为准则。比如“在修改代码之前先确认测试方案”“所有重要决策必须写入项目文档”等。这层设计很像我带新人时讲的“团队默契”——不是某个具体操作而是做事的基本原则。2.2 为什么一定要走文件式的技能定义我一开始也疑惑为什么不用一个巨型prompt把所有规则塞进去后来用多了才明白文件式拆解有几个不可替代的优势。第一是可组合性。你可以只启用自己需要的技能比如我很多内部项目就用brainstorming、writing-plans、TDD、debugging这四五个不需要把整个仓库的所有内容都塞给AI。每个技能是独立的删掉或新增都不会影响其他技能。第二是可维护性。如果某个技能的执行步骤需要调整你只需要改对应的SKILL.md文件AI下次调用时就会按新规则执行。这一点对团队协作尤其重要——你可以像维护代码一样维护AI的工作方式还能通过git追踪每次调整的原因。第三是透明可控。那些“什么都能干”的通用prompt最大的问题是AI容易“自由发挥”。技能文件里定义了明确的触发条件比如“只有当用户明确要求生成方案计划时才使用writing-plans技能”AI就不会在不该用的时候瞎用也不会在该用的时候跳过。2.3 设计思路拆解从“听话的助手”到“有章法的搭档”用了一段时间之后我发现superpowers的核心设计哲学其实就一句话把AI当作一个需要管理的工程师而不是一个需要调教的搜索引擎。传统的AI编码方式本质上是“你下一个指令AI给一个答案”。superpowers则把整个过程拆成了“理解需求brainstorming→ 制定方案writing-plans→ 执行编码TDD workflow→ 验证质量testing / code-review→ 修复问题debugging”这样的工程流水线。AI在每个阶段都有明确的目标、方法和输出物不再是一股脑冲到代码里去。这种设计对个人开发者意义重大。以前我让AI改代码最怕它改完A又弄坏B然后我再花半小时去找它改了什么。现在AI会在动手前先读计划、写测试改完之后自己跑验证最后还会留下变更记录。我倒不是说要盲目信任这套流程而是它让AI的行为变得“可预期”出问题了你至少知道从哪个环节开始查。3. 从零安装Codex CLI 装 superpowers 实操记录3.1 准备工作确认环境与版本在动手安装之前先确认你手里的工具版本支持skills功能。以Codex CLI为例skills是在较新版本里才引入的试验性能力老版本是不认SKILL.md这套东西的。我建议大家先跑一遍版本检查codex --version如果版本过旧顺手升级一下。在npm环境下一行命令就能搞定npm install -g openai/codex升级完重新跑一遍codex --version确认版本号没问题再继续。这一步千万别省我见过好几个朋友搞了半天配置没生效最后发现是版本太老压根不支持。另外确认你本机已经安装了git并且能正常访问GitHub。superpowers本身是个开源项目安装过程本质上就是把它clone到本地。3.2 克隆项目与目录结构确认接下来把superpowers仓库clone到本地。我习惯把它们放到一个统一管理技能的目录下面比如~/.codex/skills这个路径mkdir -p ~/.codex git clone https://github.com/obra/superpowers.git ~/.codex/superpowers注意网上有些教程会让你直接clone到当前的某个项目目录里我不太推荐这么做。因为技能包最好全局维护、跨项目复用而不是被某个项目“绑架”。clone完之后你先看一眼根目录结构ls -la ~/.codex/superpowers正常情况下你会看到skills/、workflows/、guidelines/等目录还有一个README.md。我强烈建议你先把README通读一遍因为项目里的技能列表和最新用法说明永远比任何二手教程都准确。3.3 配置Codex CLI指向skills目录clone完成之后需要让Codex CLI知道去哪里找这些技能文件。Codex CLI的配置文件一般位于~/.codex/config.toml。如果没有这个文件你可以手动创建一个。打开配置文件检查有没有skills相关的配置项。不同版本的配置字段可能有差异我在较新的版本里用的是类似这样的写法[experimental] skills_dir /Users/你的用户名/.codex/superpowers/skills写完之后保存建议把skills_dir路径写绝对路径避免因为相对路径解析出问题。修改完配置之后重启Codex CLI然后跑一个最简单的问题测试一下codex 你好列出你的可用能力如果配置成功Codex应该会主动提到它加载了哪些技能或者在后续对话中体现出“流程化”的操作风格。如果没有别急着怀疑人生往下看第六节的排查方法。3.4 验证安装是否真的生效验证安装是否生效最直接的方式是给Codex一个需要“多步思考”的任务比如codex 我需要给现有项目增加一个命令行参数解析功能先梳理需求再给方案最后再动手如果superpowers生效了你会看到Codex会先去读brainstorming或writing-plans相关的技能文件然后按照里面的流程一步步来先问清楚你的输入输出期望再给出方案再问你是否可以动工。如果它直接开写代码那说明技能加载多半是失败的。这里我多说一句判断“是否生效”不要只看它“回答得有多好”要看它“是不是按照技能文件里定义的流程来走”。因为技能包的核心价值就是流程规范而不是单纯的话术优化。4. Trae 环境下的安装与使用差异4.1 Trae支持skills的版本与入口国内不少朋友用的是Trae字节推出的AI IDE它的界面做得比较友好所以“trae work cn 安装superpowers skill”这个关键词最近热度不低。Trae本身对Claude Code的skills生态做了一定兼容但入口和Codex CLI完全不一样——它没有config.toml而是通过IDE的设置界面或者环境变量来指定技能目录。我建议大家先确认自己安装的Trae版本是否包含“Skills”或“Agents”相关设置项。在Trae的设置里搜索“skill”关键词如果有对应选项说明你手里的版本支持如果没有可能需要升级到较新的版本。这个功能的更新速度很快直接看软件设置里的实际选项比看任何图文教程都靠谱。4.2 安装步骤与Codex的区别在Trae里安装superpowers核心思路和Codex一样都是“把skills目录告诉工具”但操作方式不太一样。我实测下来比较顺的流程是这样先把superpowers仓库clone到一个固定的全局目录比如~/ai/superpowers。然后在Trae的设置里新增一项“Skills目录”配置把路径指到~/ai/superpowers/skills。保存后重启Trae新建一个对话测试即可。如果你在国内网络环境下访问GitHubClone仓库比较慢可以考虑先从码云等平台找镜像同步或者直接下载仓库的zip包再解压到目标目录。skill文件本身没有依赖网络资源是纯本地文件所以只要文件到位配置正确就能用。4.3 中文语境下的适配经验Trae对中文场景做了不少优化这本来是好事但遇到superpowers这种英文编写的技能文件时偶尔会出现“水土不服”。我遇到的情况是AI读了英文技能文件后复盘和计划还是用英文来写导致我看得费劲。解决办法很简单找到技能文件里SKILL.md的开头部分在“输出规范”或“回答风格”里补一句“所有计划、讨论、总结请使用中文回复”保存后重新开启对话即可。如果你想深改也可以把整个技能文件的核心步骤翻译成中文但说实话没必要全翻——技能的结构化流程本身就是主要价值语言只是外壳。我自己的做法是保留原始英文文件只在文件末尾加一段“中文输出要求”既不影响技能逻辑又能让对话体验更顺滑。5. 核心技能拆解与实战用法5.1 brainstorming从模糊需求到可执行方案这是我觉得整个技能包里最实用、也最容易被低估的一个技能。很多人用AI编程时“需求说不清”主要是因为AI默认你脑子里的方案是清晰的于是直接照着猜。而brainstorming技能的核心机制是在动手之前强迫AI先和你做一轮多轮对话式的需求澄清。它会主动问你这类问题这个功能的核心用户是谁你希望用户在哪个入口触发它现有代码里哪些模块可能受影响哪些边界情况需要处理如果需求本身是开放的它还会给你两个以上的方案选择而不是直接挑一个。我自己在给项目加“批量导出Excel”功能时试过一次AI没有直接开写而是先让我确认导出字段、文件大小限制、异步还是同步处理这几个关键点。换做以前我可能就得自己反复改prompt让它别跑偏。这个技能能帮你把“模糊想法”打磨成一个“可执行的方案”而且整个讨论过程会留下记录方便你回看决策原因。5.2 writing-plans让AI先规划再动手如果说brainstorming解决的是“要做什么”那writing-plans解决的就是“怎么做、按什么顺序做”。这个技能被触发时AI会先输出一份结构化的实施计划一般包含改动目标、涉及的文件清单、每个文件的具体改动点、测试策略、风险点和回滚方案。我自己用下来最大的感受是AI计划做得越细写出来的代码越稳返工越少。因为计划本身就是一次对问题的全局思考那些“改A会牵扯B”的问题在计划阶段就会被发现而不是等写完了代码才炸出来。你可以在和AI对话中直接要求“请先使用writing-plans技能生成这份功能的实施计划评估没问题后再开始编码。”这样AI就会被“约束”到先规划后动手的正确节奏上。如果计划里有你觉得不合适的地方直接让它改计划比让它边写边改要省事得多。5.3 TDD workflow测试驱动的编码闭环superpowers对测试的执念从它内置的TDDTest-Driven Development工作流就能看出来。这个工作流不是简单让AI“顺手写几个测试”而是要求它在写业务代码之前先把测试用例写出来然后以“让测试先红、再写实现、最后让测试变绿”的节奏来完成任务。我一开始觉得这样很费时间但真正跑过一轮之后才发现它的价值AI先写测试时其实是在逼自己把需求理解明确。比如你要它“给用户列表加搜索功能”它得先写搜索命中、无结果、关键字为空这几个测试用例这一下就把需求的边界条件钉死了后面写实现自然不会跑偏。使用TDD工作流时我建议你不要中途打断AI去改业务代码而是让它跑完整个“测试驱动”循环后你再来查看代码和测试的匹配度。中途打断要么让测试白写要么让流程变得混乱。5.4 debugging技能别再让AI瞎猜在没有技能约束的情况下AI面对bug最常干的事就是“瞎猜”——根据报错信息猜一个可能的原因然后直接改代码不行再换一个原因直到碰对为止。这个过程极其消耗时间而且容易在原本健康的代码里留下新的坑。debugging技能要改变的就是这件事。它会强制AI先“复现问题”让AI问你有没有稳定复现的步骤错误信息具体是什么最近改动过哪些代码然后它会要求你提供日志、异常堆栈等证据再基于这些证据形成关于根因的假设最后才动手修复。我在实际项目里试过一次服务端偶发超时AI没有急着改配置而是先检查了日志里超时集中在哪条SQL再结合慢查询报告确定是缺索引最后给了一个“加复合索引改写查询”的组合方案。整个过程有理有据比我自己排查还细致。5.5 code-review与安全审计让AI当项目守门人最后说一下code-review和安全审计这两个带“质检”属性的技能。code-review技能被触发时AI会像团队里的资深同事一样做代码审查从代码风格、潜在逻辑问题、异常处理、可维护性几个维度逐条给出评审意见而不是简单说一句“看起来不错”。安全审计技能则偏重于排查漏洞比如路径遍历、SQL注入、硬编码密钥、危险的反序列化等。它会把发现的问题和修复建议列成清单并标注风险等级。这两个技能我建议你把它们设为“每次改完代码之后默认执行”的步骤。虽然会多花一点时间但能挡住大量“低级但致命”的问题。以前我上完代码后总担心哪里埋了雷现在让AI先自审一轮心里踏实很多——当然AI的审查只是第一道防线关键逻辑还是得自己把关。6. 常见问题与排查技巧实录6.1 技能没被加载的排查方法这是问的人最多的问题。配置了路径、也clone了仓库但AI仍然不按技能流程走怎么排查先确认配置文件里的路径和实际目录是否一致。这一步最常见的坑是路径写错或者路径写的是相对路径。我建议在终端里先跑一下ls确认目录存在再用绝对路径写进配置。然后确认AI有没有“主动读取”技能文件。你可以直接在对话里问它“请查看你的skills目录列出你已经加载的技能。”如果它能列出来说明加载是通的。如果它说不知道说明配置文件没有生效重点检查配置格式和版本兼容性。最后要看是不是被上下文窗口“挤掉”了。有些情况下如果对话历史太长AI会在处理过程中“丢”掉技能文件的内容。这时新开一个对话窗口再试试往往就好了。6.2 模型版本与技能兼容性不同模型对技能文件的理解能力差异很大。简单说推理能力越强的模型越能严格遵循技能文件里的步骤小模型则容易“读了但做不到”经常跳过关键步骤或者自己发挥。我自己的经验是这个项目更适合在Codex CLI这类能和较强大模型配合的工具里使用。如果你在某个工具里装了superpowers但效果不佳先别急着骂项目换个更强的模型试试看。另外工具的版本更新也可能会改变配置字段的命名。遇到升级后技能失效优先去项目仓库的README和发布记录里看看有没有Breaking Change的说明。6.3 权限问题导致技能写入失败有些技能在工作过程中需要AI写入文件比如制作实施计划、生成测试报告、记录决策日志等。如果项目目录没有写权限AI在执行到“写入产物”这一步时会报错。解决思路是要么给项目目录授权要么在技能文件里把产物输出路径改到当前用户有权限的位置。我更推荐后者因为你没必要为了让AI写文件就把整个系统目录权限放大。在Linux/macOS下还有一个隐蔽问题仓库clone下来后某些文件的权限可能被压缩包保留了奇怪的值。如果出现“文件明明存在但读不了”的诡异问题跑一下chmod -R ur ~/.codex/superpowers看能不能解决。6.4 多工具共用一套技能的技巧如果你像我一样同时在Codex CLI和Trae之间切换不想维护两份技能副本可以把skills目录固定在一个公共位置比如~/ai/superpowers/skills然后让两个工具都指向这个路径。这样做的另一个好处是你只需要更新一处就能同步全部工具。但我建议你同时建立一个“技能更新记录”因为工具版本和技能文件的兼容性可能会因为更新而改变记录下“什么时候更新到什么版本、当时有哪些工具可用”会帮你省下不少排查时间。7. 我的实际体会与进阶建议以上都是操作层面的东西最后聊点我个人的真实体会。superpowers真正让我留下来的原因不只是AI写出来的代码质量变好了而是我重新找回了“把控感”。以前用AI编程总有种“赌徒心态”——不知道它这次会不会搞砸改了哪里我也没法完全掌握。现在AI会先跟我讨论需求、生成计划、写测试再慢慢动手每一步我都能看到、都能干预这种感觉非常踏实。进阶的话我的建议是不要“照单全收”地启用所有技能而是根据自己的项目节奏挑选最需要的几个。技能太多未必是好事反而会让AI在简单任务上也走一堆流程变得啰嗦。先上brainstorming、writing-plans、TDD这三个跑顺了再加入debugging和code-review。最后分享一个我自己的“小聪明”我在skills目录里加了一个PROJECT_RULES.md里面写了自己项目的技术栈约定、目录结构偏好、注释风格要求。因为superpowers本身就支持按项目加载自定义规则这样做相当于给AI植入了一份“团队文化说明书”效果有时候比专门的技能还好用。你们也可以试试。