1. 先搞清楚superpowers 到底解决的是什么问题1.1 为什么提示词技巧解决不了效率问题我差不多每天都泡在 AI 编程助手里从补全代码到自动改 bug、重构模块甚至写 commit message。用久了你会发现一个尴尬的事实同样一个助手在别人手里是超级工程师在我手里就是个听话但健忘的小实习生。你说一步它做一步稍微绕一点就断片同一个错误能犯三遍。一开始我以为是模型不够聪明于是开始疯狂囤提示词模板。什么 act as a senior engineer、什么 think step by step、什么 explain your reasoning before coding效果有但很有限。原因是这些提示词只是一时的状态注入换个会话、换个项目它又忘了。你不可能把几十个项目的工程经验都塞进一段咒语里而且上下文窗口也不允许。后来我在社区里看到一个叫 superpowers 的开源项目它的思路完全不一样不靠更长的提示词而是把干活的经验做成一个个可复用的技能文件让 AI 助手在需要的时候自己去读、去调用。这个概念一下就点醒了我——我们要给助手的不该是鞭子而是它自己的工具箱。这篇内容我想围绕它的实际安装、技能清单和引入方式把我自己的使用心得完整摊开来讲。1.2 superpowers 的核心思路把经验编译成可调用的技能所谓 superpowers你可以理解为一组技能包或者能力插件专门用来增强 AI 编程助手的稳定性。它的基本假设是人在写代码的时候会依靠经验模式比如遇到线上 bug 先复现、再定位、再修复、最后回归但 AI 助手每次都是从零开始推理没有这种模式记忆。如果能把这个模式写下来让助手在开工前先读一遍它的行为会立刻变得专业不少。这个项目本质上就是一堆 Markdown 文件每个文件描述一个特定的任务流程如何对代码做架构分析、如何拆解复杂任务、如何写可验证的测试、如何在改完代码后做自检……但是它的厉害之处在于组织方式。它不是让你把所有规则都堆在系统提示词里而是提供了一套按需加载机制助手根据用户当前的任务主动去翻对应的技能文件只把相关的那几段内容放到上下文中。从工程角度讲这其实是在做外部记忆 工作流管理。AI 助手本来上下文有限你没法让它同时记住一百条规矩但你可以让它知道有本手册在某处遇到什么问题就翻哪一章。这就好比一个新手厨师不必背下整本菜谱只需要知道红烧肉在菜谱第 12 页做的时候翻到那一页照着做就行。2. 打开技能清单它内置了哪些有用的 skills拿到 superpowers 之后我第一件事就是去看它到底有哪些 skills。很多人和我一样装上就想玩结果一股脑全启用上下文立刻爆炸。所以先弄清每个技能的职责比急着安装更重要。2.1 规划与分解类技能这类技能解决的是面对一个模糊的大需求怎么拆成可以逐步执行的子任务。比如brainstorming头脑风暴用于在正式动手前生成多个候选方案planning规划则把选中的方案细化成带验证步骤的实施计划task-breakdown任务分解负责把计划拆成 AI 能在单次会话中完成的小步操作。我实际用下来最常用的是planning。以前我说帮我实现一个用户登录模块助手会直接甩一堆代码出来结果往往和项目现有结构脱节。引入 planning 技能后它会先花二十秒问我要需求细节然后输出一个步骤清单每步都带验收条件。这一步相当于让助手从埋头写代码切换到了先当架构师再当程序员整体翻车率低了很多。2.2 代码修改与审查类技能这类技能负责让改动更稳妥。code-review代码审查用来对已完成的 diff 做同行评审refactoring重构着重在保持行为不变的前提下改进结构bug-fixing缺陷修复则定义了从复现到根因分析再到回归验证的标准流程。如果你用过 AI 修 bug一定体会过改一处坏一处的滋味。bug-fixing这个 skill 的流程特别接地气第一步是找最小复现路径第二步是定位根因而不是修表象第三步才是动手改改完还要跑相关测试。表面上看这些步骤多花了一点时间但它能帮你把碰运气式修复变成确定性修复。2.3 调试与跟进类技能再往下是debugging调试和test-writing测试编写。debugging专门用来应对跑起来报错但不清楚原因的场景它会引导 AI 先收集错误信息和调用栈再针对性地插入日志逐步缩小范围。test-writing则不是简单生成单测而是遵循一个先写失败用例再实现再让用例通过的 TDD 流程。这两个技能配合起来效果很好。我处理过一个诡异的内存泄漏之前助手只会建议我检查一下循环引用听起来像玄学。后来启用debugging技能它先让我用--prof跑一遍压测收集内存曲线再二分注释可疑模块最终定位到我在缓存清理时的边界条件写错了问题直接指向那一行。这种有流程的调试方式比随机猜测靠谱得多。2.4 文件与文档处理类技能还有一批技能和代码关系不大但非常实用。比如documentation文档生成用来维护 README、架构说明和 API 文档的时效性commit-message提交信息负责把改动拆成符合规范的多条 commitpr-description拉取请求描述可以自动生成给团队看的 PR 说明包含背景、改动点、测试结果和风险提示。这类技能的共同特点是输出结构化信息。以前让 AI 写 commit message它总是一股脑写一行 fix bugs没有逻辑。现在 superpowers 会为每次改动生成类型分明、带影响范围的提交说明甚至能自动判断是 feat、fix 还是 refactor。对我们这种需要维护多个分支的团队来说这一项就省了至少半小时的整理时间。技能分类典型 skill主要解决场景规划类brainstorming, planning, task-breakdown需求模糊、任务过大、方案不明修改类code-review, refactoring, bug-fixing代码质量、重构风险、缺陷修复调试类debugging, test-writing运行时报错、逻辑难定位、测试缺失文档类documentation, commit-message, pr-description文档过期、提交混乱、PR 描述空洞3. 实际安装步骤与引入技能的几种方式这一节聊大家都关心的到底怎么安装、怎么把技能真正引入到你的编辑器或终端里。市面上的教程大多只给一条命令但实际使用中你会发现有不同的安装需求我把最常见的三种路线列出来你可以根据自己的情况选。3.1 环境准备Node.js 与 Git在开始之前先确认你的机器上有 Node.js 18 和 Git。一般日常开发环境都满足但如果你用的是精简镜像或者远程开发机很可能缺这一步。我踩过这个坑项目拉到一半提示git: command not found而 superpowers 的安装脚本依赖 Git 来拉取仓库。检查命令很简单node -v git --version如果 node 版本低于 18建议先升级如果 git 没有就先把基础工具装好。这里不需要什么花哨配置版本满足即可。另外安装过程不需要管理员权限也不改全局系统路径这一点比较友好。整个工具会装在你当前用户的目录下对于公司电脑或者容器环境来说权限问题少很多。3.2 方式A用脚手架一次性安装如果你是想在项目里整个启用 superpowers最省事的方式是用它的安装脚本。在项目根目录执行npx superpowers/cli init这个命令会做几件事检查当前目录是不是 Git 仓库、下载官方 skills 库、在项目下生成.superpowers文件夹和配置文件。执行过程中它会问你要启用哪些技能包你可以先选全部看看效果也可以在后面的配置文件里随时增删。装完之后需要在助手的配置里指向这个项目目录。以我的使用习惯为例我通常在 VS Code 的 AI 对话插件中补充一句系统指令当任务涉及架构分析时先查看项目根目录下 .superpowers/skills 中的相关技能。这样助手才会知道去哪里找技能。如果你用的是终端类助手也可以把这句话加进项目级说明文件里保证每次会话都能看到。3.3 方式B手动 clone 来引入有些场景你不希望用 npx比如公司内网环境没有公共 npm 源或者你想直接基于源码进行二次改造。这时候手动 clone 反而更可控git clone https://github.com/superpowers-org/superpowers.git .superpowers然后自己写一个配置文件指向你 clone 下来的技能目录。手动方式的好处是你可以只保留自己需要的技能删除不用的甚至可以直接修改技能的 Markdown 内容。坏处是后续官方更新你需要自己去合并。如果你对 Git 比较熟我推荐这种方式因为你会对这个工具的内部结构有更清晰的理解——后续写自定义技能的时候特别有用。3.4 方式C只引入个别技能按需安装如果你不想为整个框架增加复杂度也可以只把单个技能文件复制到你的项目里。比如我只需要bug-fixing这个技能那就直接从 skills 目录里把它单独拷出来放到.superpowers/skills/bug-fixing.md。然后在你的助手系统提示词里说明若任务涉及缺陷修复优先参考 bug-fixing 技能。这种方式很轻量适合已经有一套成熟工作流、只想要某一环补强的团队。缺点是失去了技能之间的协作性——像planning和task-breakdown单独用效果远不如组合起来。我的建议是先全量安装感受整体流程再逐步按需瘦身。一上来就只引入单个技能很容易因为上下文不足而体验不到它的威力。4. 引入技能后的正确使用姿势安装只是开始真正能拉开体验差距的是怎么用。我发现很多人装上 superpowers 之后觉得没用往往不是因为工具不行而是命令方式不对或者期望它自动生效。技能文件本质上是一份说明书你得让它有机会被读到并且在合适的时机被触发。4.1 技能是怎么被调用的superpowers 的调用方式不是告诉 AI 去用技能而是把技能文件的内容暴露给 AI 的上下文读取机制。一般有三种路径自动触发当助手检测到任务关键词比如修复 bug时自动去技能目录里找匹配文件。显式引用你在提问时直接写参考 bug-fixing 技能完成修复助手会打开对应文件遵循流程。项目级常驻把常用技能的核心要点写进项目的.ai规则文件里让助手每次都在这些原则下工作。我实测下来最稳定的是显式引用。因为自动触发依赖关键词匹配很容易出现提到了 bug 但想让你加功能这种误判。而如果你在每次涉及关键操作时都明说按某个技能来做效果会立竿见影。不要担心这句话啰嗦AI 助手很吃这一套你等于是在给它指路。4.2 给技能传递上下文别忘了写背景说明技能文件是通用的但你的项目是特殊的。比如planning技能只能指导助手如何做计划它不自动知道你的项目是前端还是后端、用的是 Vue 还是 React、测试框架是 Jest 还是 Vitest。所以你在触发技能的同时得把必要的背景信息一起交给 AI。老实说这是很多人的误区。他们启动planning之后AI 输出的计划还是泛泛而谈因为缺少了项目背景输入。我现在习惯的做法是在提问的开头先用两三句话交代当前项目技术栈和本次目标再引技能。举个例子我们这是一个基于 Next.js 15 的电商后台数据库用的 PostgreSQL迁移工具是 Prisma。请参考 planning 技能帮我设计订单批量导出功能的实现步骤需要包含数据量限制和异步处理方案。同样是调用planning有背景和没背景出来的计划质量完全两个级别。技能负责怎么思考背景负责往哪个方向思考两者缺一不可。4.3 什么时候不要用技能这一点可能比怎么用更重要。superpowers 里的技能是面向复杂任务的但不意味着所有任务都要走一遍重流程。比如改一个按钮颜色你非要用planning技能做三步拆解纯属给自己添堵。我自己的判断标准是这段操作是否可能造成不可逆影响改样式、调文案、写简单函数直接用不要让 AI 走完整流程。重构模块、修改数据层、调整核心逻辑必须用技能。处理线上故障优先用bug-fixing/debugging并且明确跳过头脑风暴环节。另外如果当前会话的上下文已经很长接近模型上下文上限这时候再让 AI 去读一个几千字的技能文件大概率会丢失前面的重要信息。我一般在会话超过十轮之后会手动清理无用的历史消息或者开一个新会话并把关键背景摘要带过去再让 AI 触发技能。这不是 superpowers 的问题而是所有长上下文场景的共同坑。5. 我在实际使用中踩过的坑路径、优先级和上下文失控任何工具都是在踩坑中才能真正上手的。下面这几个问题我花了两个礼拜才摸透分享出来希望能帮你省掉这部分时间。5.1 技能文件的路径解析错位第一次我用方式 B 手动 clone 的时候把仓库放在了项目根目录的.superpowers下但配置里写成了相对路径.superpowers/skills导致某些技能死活加载不出来也没有任何报错。后来才发现AI 助手的工作目录可能和终端不一致特别是使用项目级配置文件时路径会被解析为相对于某个子目录的位置。解决方法是在配置里优先使用绝对路径或者统一约定所有文件都放在项目根目录下并在助手的配置文件中显式声明工作目录。我个人的习惯是写一条规则所有技能文件位于 /workspace/.superpowers/skills 目录下以 Markdown 格式存储。虽然看起来不够优雅但绝对不会有歧义。对于动态项目目录可以靠环境变量拼路径但一定要注意拼接方向。5.2 多个技能同时命中的优先级问题你会遇到这种情况任务描述是重构订单模块并且修复一个 bug此时refactoring和bug-fixing两个技能都可能被触发。如果两个技能的内容同时灌入上下文AI 会左右为难输出的方案既不像重构也不像修复反而更容易出错。我现在的处理方式是在显式引用时指定主技能。如果是先修 bug 再重构就明确说先按照 bug-fixing 技能完成修复再按照 refactoring 技能评估重构方案。如果确实需要多个技能协作我会把它们串成一个流程而不是并行。本质上一次聚焦一个核心目标AI 的完成度会高很多。实在要同时处理不如拆成两次会话减少认知负荷。5.3 上下文被技能描述刷爆superpowers 的每个技能文件都有相当篇幅包含了背景、步骤、示例和检查清单。如果你一次触发三个技能可能语音助手还没开始写代码上下文窗口已经用了上万 token。这会把主要任务的空间挤占掉导致输出质量下降。对这个坑我做了两个改进。第一是在技能说明里手动删减不需要的示例部分只保留步骤和关键提示。第二是在触发时告诉 AI请只提炼技能的核心步骤不需要复述示例。实验下来这样能省掉 40% 左右的上下文。尤其是项目整体能力已经稳定之后冗余的示例反而是噪音。5.4 技能对仓库行为的预估失灵技能文件是静态的但你的仓库是动态的。有时候refactoring技能建议的步骤依赖某些重构工具比如适用的 codemod而你的项目并没有安装这个工具。这时候 AI 会按照记忆中的推荐工具给你命令结果自然是报错。遇到这种情况我的做法是在技能文件里增加一个前置检查步骤明确要求 AI 在动手前先验证依赖是否存在。你可以改技能模板也可以在与 AI 对话时强调所有推荐的命令必须先做可行性确认再真正执行。这其实反映了技能生态的一个重要原则技能是指导原则不是银弹它必须结合你仓库的真实情况来调整。6. 把手上的经验沉淀成你自己的 skill用了一段时间 superpowers 之后我最大的感受是它提供的技能很好但真正的价值在于给我搭了一个框架让我能把团队内部的经验也结构化保存下来。这一节聊聊怎么写一个自己的 skill。6.1 一个最小技能的结构一个技能文件并不神秘说白了就是一份有固定结构的 Markdown。我的最小模板是这样--- name: api-field-migration description: 当你需要迁移或调整 API 字段时使用本技能避免破坏历史调用。 when_to_use: 涉及接口字段增删改、模型序列化变更时 --- ## 执行步骤 1. 梳理当前 API 的所有调用方和服务端定义 2. 列出字段变更清单标记 breaking change 与非破坏性变更 3. 按先服务端兼容、再客户端切换、最后清理废弃字段的顺序执行 4. 显式编写迁移测试验证旧字段在过渡期仍可用 ## 检查清单 - [ ] 是否修改了对外文档 - [ ] 是否更新了 mock 数据 - [ ] 是否保留了至少一个版本的兼容头部用 YAML 定义元信息正文字干净利落。把这样一个文件放进.superpowers/skills目录然后给 AI 一句提示当任务涉及 API 字段变更时请先参考 api-field-migration 技能。从此以后团队新成员用 AI 助手也不会踩同样的坑了。6.2 避免假技能可验证与可撤销写技能最忌讳的是正确的废话。比如确保代码质量注意边界情况这种描述AI 看了和没看一样因为它没法执行。一个真正有用的技能应该包含两类内容一是可验证的中间产物二是可回滚的兜底方案。我自己的检查标准是如果按照技能执行完你拿不出一个验收结果来证明做对了那这就不是技能只是一条建议。比如上面我的 api-field-migration 技能验收结果是迁移测试通过 文档已更新 旧字段兼容三条都满足才算完成。同时我要求 AI 在动手前先确认 Git 有干净的提交记录这样出问题能随时回退。可撤销性非常重要AI 执行多步骤任务时难免跑偏有一个退路会让人安心很多。6.3 版本管理技能也是代码最后强调一个容易被忽略的点技能文件本身也是项目资产需要做版本管理。我见过不少人直接往.superpowers/skills里扔了一堆 Markdown不写 commit不写变更记录。等到某天技能被改得面目全非再想查原来的规则是什么样的就完全无从下手了。最好的做法是把.superpowers目录纳入 Git 跟踪每次修改技能之后用一句 commit 描述变更原因。如果团队里有多个角色使用 AI 助手还可以用分支来维护不同方向的技能集稳定之后再合并。如果你定义了比较通用的流程也欢迎把它抽离成独立仓库分享给其他项目甚至社区。一旦开始写自定义技能你会发现这其实是在建立一个团队的集体经验库越积累越值钱。说实话superpowers 并不是什么黑魔法它只是把那些优秀工程师脑子里理所当然的经验显性化了。安装它、使用它、然后改造它这个过程中最受益的其实不是 AI而是你自己——你会被迫去思考自己平时到底是怎么解决问题的。愿意把这种思考落到文档里的人无论用不用这个工具写出来的代码都不会差。