很多开发者第一次听说 superpowers 时，都会下意识觉得这是某个“锦上添花”的小工具，但实际上它是一套能直接改变你与 AI 协作方式的能力扩展包。我在自己的项目里用了一段时间之后，最大的感受就是：以前 AI 只是帮我写代码，现在更像是带了一个懂方法论、知道什么时候该干什么的结对工程师。这篇文章不绕弯子，直接说清楚 superpowers 是什么、能做什么、怎么装、怎么用，以及我在实际操作中踩过的坑。
如果你每天都在跟 AI 编程助手打交道，或者正在琢磨怎么让 AI 不只是“生成一段代码”，而是能独立完成“调研、写测试、调试问题、重构代码”这一整条工作链，那这篇内容正好适合你。下面从设计思路开始讲，一步一步带你把这套技能真正用起来。
1. 项目整体设计与思路拆解
1.1 “技能”到底解决什么问题
先聊一个很多人忽略的细节：大多数 AI 编程工具本身并不缺“能力”，缺的是“工作方法”。你让 AI 修一个 bug，它可能直接给你一段新代码；你让它写功能，它可能立刻开始写第一版实现。这些看似“高效”的响应，其实经常漏掉了关键的思考环节：问题边界清不清楚？有没有现成的测试保障？改正之后会不会引入新问题？
superpowers 的设计思路就是把“经验丰富的开发者会怎么做”这件事固化下来，拆分成一个个独立的“技能”。每个技能都对应一套完整的、可执行的流程，而不是一句笼统的指令。举例来说，调试技能不是“告诉我怎么改”，而是先引导 AI 建立失败的复现路径、分析根因、写出验证步骤，最后才动手修复。整个过程和人类专家排查问题的节奏几乎一致。
这种设计有一个很现实的好处：AI 的输出质量不再取决于运气，而是取决于你把它放进了哪套流程里。你调用的是一个定义好的工作流，而不是让 AI 自由发挥。项目的名称“superpowers”也暗示了它的野心——它想给你那些“单靠基础模型得不到的能力”。
1.2 技能包的文件结构与运行机制
superpowers 的底层机制本身并不神秘，核心就是“把技能定义成文件”。每一个技能通常包含一个描述文档（负责说明这个技能什么时候用、怎么用、要遵循什么步骤），以及若干个配套的脚本、模板或参考文件。AI 助手在运行时，会读取这些文档，把里面的方法转化成实际行动。
我用一个生活化的类比来解释：假设你雇了一个新厨师，他不认识中餐。你直接说“做一道红烧肉”，他容易翻车。但你给他一本《红烧肉标准作业手册》，里面写着选材标准、焯水时间、火候控制、收汁判断，他就能像模像样地做出来。superpowers 里的一个技能就是这本手册。
实际运行中，AI 会在开始执行任务前先加载相关技能描述，从里面提取步骤，然后按照步骤一步步做。因为流程是显式的，所以中间任何一步出现了偏差，你都能定位到具体环节，而不是对着结果干瞪眼。我更喜欢的是它把“为什么”也写进了技能说明里，AI 不只是照着做，还能理解每一步的目的，遇到边界情况时就懂得变通。
1.3 为什么这种“笨办法”反而更好用
你可能想问：为什么不直接把所有经验写进系统提示词里？答案很简单——提示词越长，模型的注意力越分散。superpowers 采用的是“按需加载”的策略，用到哪个技能就加载哪个技能，而不是把所有技能一股脑塞给模型。这样既节省上下文空间，又能保证每一步执行时信息密度足够高。
此外，把技能做成独立文件还有一个额外收益：可以进版本控制。你可以像管理代码一样管理技能，改动有记录，升级有依据，不同人之间也能方便地共享。这个设计看着不起眼，实际用起来参与感完全不一样，因为它让“AI 的工作方式”变成了可维护、可演进的工程资产，而不是黑盒里的一段咒语。
2. 安装 Superpowers 与引入技能
2.1 环境准备与版本选择
在安装之前，先确认几件事。superpowers 本身是依赖某个 AI 编程助手环境来运行的，目前支持比较完善的是命令行形态的 AI 编程工具（Claude Code、Codex 等命令行版本）。这些工具能直接读取本地文件，并且具备执行命令能力，所以技能文档里的脚本才能生效。如果你用的是网页版 AI 聊天框，那 superpowers 的很多功能发挥不出来，因为浏览器环境限制太多。
我建议的起步方式是：准备好一个干净的项目目录，并安装好你习惯的命令行 AI 工具。这个项目目录会成为你日常工作的主战场。只要保证本机能正常通过命令行启动 AI 编程助手，剩下的安装流程就很简单了。
2.2 安装步骤：克隆技能仓库到本地
superpowers 的安装本质上就是把技能仓库放到你的项目里，并让 AI 助手知道到哪里去找技能。以当前主流的做法为例，流程如下：
# 进入你的项目工作目录 cd ~/work/my-awesome-project # 克隆 superpowers 技能仓库 git clone https://github.com/your-user/superpowers.git .superpowers安装完成后，项目里会出现一个.superpowers目录，里面分层存放着各种技能子目录。之所以放在隐藏目录里，是为了不让技能文件跟业务代码混在一起，保持项目根目录整洁。如果你下载的不是完整的仓库，而是别人分享的单个技能，那只需要把对应技能文件夹复制到.superpowers/skills/路径下同样有效。
不过我不建议只放一个技能。superpowers 的价值在于技能之间可以搭配组合，比如先用调研技能搞清楚问题背景，再切换到调试技能定位根因，最后用测试技能兜底。单枪匹马不是它的正确打开方式。
注意：无论你用什么方式安装，都要确保目录层级和官方文档保持一致。技能目录放错位置是最常见的“装了但没用”的原因。
2.3 让 AI 助手识别技能目录
光把文件复制到项目里还不够，还得让 AI 工具知道去哪个目录找技能。这个动作在不同工具里叫法不太一样，但思路是统一的：在配置中加入你的技能加载路径。
以命令行工具为例，通常做法是在项目启动命令中指定技能来源，或者在你的全局配置文件中添加一行设置。举一个直观例子：
# 方式一：启动 AI 编程助手时通过参数指定技能目录 my-ai-tool --skill-dir .superpowers/skills # 方式二：在项目配置文件（如 .ai-config.json）中声明 # { # "skills": [".superpowers/skills"] # }配置完成之后，建议先做一次健康检查：直接列出现有技能清单。如果 AI 回应里能看到一堆技能名，那就说明加载成功了。如果提示找不到任何技能，大概率是路径写错，或者技能文件夹缺少完整的SKILL.md描述文件。
2.4 按需引入单个技能的正确姿势
有些场景下，你并不想把整个技能库都暴露给 AI，只希望它在某个特定任务里使用某一个技能。这相当于告诉 AI：“这次任务，请严格按照某某技能的方法论来做。”具体操作有很多种，但底层逻辑都是一样的：把技能的使用指令嵌入到你的任务描述里。
我在实践中比较喜欢用的句式是：“请使用 [技能名称] 来完成这项任务。”例如：
请使用“调试大师”技能，帮我定位并修复用户登录失败的 bug。这句话的作用是触发 AI 加载对应的技能文档，然后按文档里的流程执行。如果你不显式指定，AI 可能会根据自己的判断选择技能，效果就会不稳定。简单来说，引入技能不是一个“装完就自动生效”的过程，更像是在每一个具体任务里“点将”——你点谁，谁才上场。
3. 常用技能清单与实操要点
3.1 一套典型的 Superpowers 技能清单
不同版本的 superpowers 打包的技能不太一样，但核心技能基本是稳定的。我把自己常用的一套列出来，方便你对它的能力范围建立直观认知。
- 测试驱动开发技能（TDD）：要求先写红测试，再实现代码，最后重构。适合从零开发新功能。
- 调试大师技能（Debugging）：通过复现、二分定位、根因分析来排查问题，而不是盲目改代码。
- 代码审查技能（Code Review）：按“正确性、安全性、可维护性、性能”等维度逐项审查改动。
- 重构技能（Refactoring）：在行为不变的前提下改善代码结构，并且要求每一步都能跑测试验证。
- 规划技能（Planning）：把复杂需求拆解成步骤清单，预判风险，再进入编码阶段。
- 文档撰写技能（Writing）：负责生成结构清晰的技术博客、README 或接口文档。
- 流程编排技能（Pipeline）：把一个大型任务分解为多个子代理协作完成，有点像一个“总监”角色。
看了这个清单你就能理解，为什么它叫 superpowers——它不是教你写某一行代码，而是把软件工程里最值钱的几项软技能全部“代理”了出去。当然，实际项目中不是每次都要用全所有技能，按需取用就好。
3.2 实操案例：用“调试大师”技能定位崩溃问题
我举个例子说明一套技能的真实运行过程。之前我维护的一个服务出现偶发性崩溃，现象是数据量大时进程 OOM，但低峰期完全正常。按以前的习惯，我可能直接搜索代码里哪里分配了大内存，然后瞎猜着改。这次我调用了“调试大师”技能，流程完全不一样。
第一步，技能先让 AI 复现问题。它检查了配置和运行日志，发现每次崩溃前都有一次查询读取全表，确认这是触发点。第二步是建立假设，它给了三个可能方向：查询未分页、ORM 默认抓取全量字段、缓存穿透导致重复计算。第三步是分析根因，逐一排除后锁定在 ORM 的默认行为上。第四步才是给修复方案——增加分页限制，并补了一个最小复现测试。
整个过程下来，我感觉它不像在“猜答案”，更像在按侦探片里的节奏做排查。关键差别在于，调试技能要求 AI 在动手改代码之前，必须先把“证据链”整理完整。这对复杂项目的意义很大，因为你省掉的不只是排查时间，还避免了“修好了这个 bug，却引入了新问题”的尴尬。
3.3 实操案例：用 TDD 技能从零写一个功能
如果说调试技能是“事后补救”，那 TDD 技能就是“预防为主”。我最近用 superpowers 里的 TDD 技能写了一个订单金额计算模块，感受很深。
按照技能文档的要求，第一步是写一个必然会失败的测试，先定义业务预期的输出。第二步是运行测试，确认它确实失败了。第三步是编写最小实现代码，让测试通过。第四步是运行全部测试，确认没有破坏其他功能。最后一步是重构，在绿色测试的保障下优化代码结构。
因为我通常在测试里习惯偷懒，原来大部分时候是代码写完再补测试，所以第一次严格按照 TDD 流程走时很不适应。但跑完整个流程后我发现，这个模块的代码质量明显高过以往直接写实现，因为它从一开始就是被测试“逼”出来的。另一个细节是，TDD 技能里内置了失败测试的判定标准，AI 不会在你测试还没写对时就急着去实现，这一点非常关键。
这里分享一个真实心得：TDD 技能的体验，很大程度上取决于你给需求时的清晰度。需求越明确，红测试写得越准，后面实现阶段就越顺畅。别指望 AI 帮你补充业务细节，业务规则最好由你定。
3.4 自定义新技能的完整流程
使用一段时间之后，你会发现有些工作方法是自己的“独家秘方”，并不在默认技能库里。这时候就该自定义技能了。superpowers 的自定义机制并不难，核心就是创建一个文件夹，并在其中放一个描述技能用途的主文档。
最简单的自定义流程是：
- 在
.superpowers/skills/下新建一个目录，名称用简短清晰的英文，例如api-migration。 - 在目录里创建
SKILL.md，开头写清楚这个技能的适用场景、前置条件和执行步骤。 - 如果技能需要用到脚本或模板，一并放到同目录下。
- 重启 AI 助手，让它重新加载技能列表。
- 用一句话触发该技能，观察是否按预期流程执行。
我建议你第一条自定义技能别贪大，从一个小而高频的动作为开始，比如“提交信息规范”或者“安全检查清单”。这样打磨成本低，也容易验证效果。随着技能库越来越大，你会发现整个团队沉淀经验的方式从“写文档吃灰”变成了“把经验变成可执行流程”，这是一个非常明显的体验转变。
4. 常见问题与排查技巧实录
4.1 安装后 AI 完全感知不到技能
这类问题我遇到太多次了，大多数人的第一反应是重新安装，但真正的原因往往只是路径没对上。检查顺序如下：
.superpowers目录是否在项目根目录下？有些工具只扫描当前工作目录，不会向上递归。- 技能目录里是否有
SKILL.md？没有这个文件，任何工具都无法把它识别为技能。 - 配置文件里的路径是否是相对路径，且指向正确？
- 启动 AI 助手的工作目录，是不是你存放技能的同一个目录？
我建议你把“安装目录的绝对路径”直接写成配置内容，这样可以避免很多相对路径带来的玄学问题。
4.2 技能加载成功但执行效果跟预期差距很大
出现这个现象，先别急着迁怒 AI。通常是因为触发的指令不够明确。比如你说“帮我用技能处理一下这个 bug”，AI 可以选择加载哪个技能，甚至不加载技能直接回答。这其实不算故障，而是技能机制的设计特点——它靠你的指令把上下文约束住。
解决办法也很简单，把任务描述中关于方法的指令放在最前面，并且明确写出技能名称。如果你发现某个技能经常被 AI“选择但又不完全按流程执行”，可以再检查一下该技能的SKILL.md是否写得足够清晰。技能文件本身质量不高，AI 就会执行得歪七扭八。
4.3 多个技能之间出现流程冲突
当任务比较复杂时，AI 可能同时触发多个技能，导致流程之间相互打架。比如规划技能要求先拆解任务再动手，而调试技能却要求立刻定位问题，两个流程叠加后会变得混乱无序。
解决这个问题的关键在于给技能设优先级。你可以在任务描述里显式声明“主流程使用规划技能，当进入问题定位环节时再切换到调试技能”。superpowers 的技能机制本身允许嵌套调用，但它需要你给出明确的编排意图。你自己先想清楚流程，再让 AI 执行，就不会出现“一个身体两个灵魂”的情况。
4.4 效率优化与几个值得养成的习惯
最后分享几个我自己用了很久的习惯，算是这份实操报告里的“彩蛋”。
第一，尽量在项目早期就引入技能机制，而不是等技术债积累之后再翻盘。技能真正发挥价值的前提是 AI 有足够的上下文空间去执行流程，如果项目又乱又大，任何技能都会变得很吃力。
第二，定期更新技能仓库。superpowers 这种项目迭代速度很快，新技能和技能优化会不断出现。我一般会每个月拉一次最新版本，并检查有哪些技能的行为发生了变化，避免用旧版本的流程去套新场景。
第三，把你在真实项目中打磨好的自定义技能回供给社区。这既能帮到别人，也会让你自己把经验梳理得更清楚。我自己的好几个自定义技能，就是在写文档的过程中发现了更优的步骤设计。
第四，关注 AI 工具的版本升级。由于 superpowers 依赖 AI 工具的基础能力，工具版本升级后，同一个技能的表现可能变好也可能变差。升级工具后，建议挑一个核心技能做一次验证，确保流程没有被破坏。
我在实际使用中还有一个体会：刚开始接触 superpowers 时，很容易把它当做一个“插件”去理解，总希望装完就立竿见影。但真正它发挥威力的时候，往往是你已经习惯了“按流程工作”这个理念，并愿意把 AI 当成一个按方法论执行的对象，而不是一个随时替你答题的工具。从这个角度看，superpowers 改变的不只是 AI 的工作方式，也顺带改变了我们自己的 debug 思路和项目管理习惯。你可以先从一个技能用起，等尝到了流程化协作的甜头，再逐步把更多技能纳入日常开发节奏。
