1. 从“superpowers”这个热词说起：它到底是什么

最近“superpowers”这个词在技术社区和效率工具圈子里被反复提起，很多人第一次看到它是在某个开源项目的讨论区，或者是在朋友分享的配置清单里。简单来说，superpowers 是一套面向 AI 编程助手的技能扩展体系，它通过一组预定义的“skills”（技能包）来增强 AI 在特定任务上的表现。你可以把它理解成给一个通用助手装上了一整套专业工具箱——原本它只能帮你写写简单代码、回答通用问题，装上 superpowers 之后，它就能按照你预设的规范去执行代码审查、自动化测试、文档生成、项目脚手架搭建等具体任务。

我第一次接触这个概念是在一个前端项目的重构过程中。当时团队里有人在讨论“怎么让 AI 更懂我们的代码规范”，有人甩出了一个 superpowers 的配置链接。我花了一个周末研究它的机制，发现它的核心思路其实很朴素：把重复性的、有固定套路的任务抽象成可复用的技能模块，让 AI 在遇到对应场景时自动调用。这和传统意义上“写更长的提示词”有本质区别——提示词是一次性的、散落的，而 skills 是结构化的、可版本管理的。

关键词里提到的“superpowers 具体使用”“有哪些 skills”“怎么引入这些技能”“想要安装 superpowers”，其实指向的是同一件事：如何把这套体系落地到自己的开发工作流里。这篇文章我会从实际操作的视角，把 superpowers 的安装、技能引入、常用 skills 清单、以及我在使用过程中踩过的坑，完整地梳理一遍。不管你是刚听说这个词的新手，还是已经尝试过但没跑通的开发者，都能从中找到可以直接抄作业的步骤。

需要提前说明的是，superpowers 本身是一个开源生态下的概念，不同项目、不同 AI 编程助手对它的实现方式略有差异。我下面讲的内容基于我实际用过的几套方案，核心逻辑是通用的，具体命令和配置路径你需要根据自己使用的工具做适配。

2. superpowers 的安装：从零到跑通的第一步

2.1 安装前需要想清楚的三个问题

很多人一上来就急着敲安装命令，结果装完了发现跟自己用的工具不兼容，或者技能加载不出来。我在第一次安装时就犯了这个错误——没搞清楚版本对应关系，装了一个跟当前 AI 助手版本不匹配的 superpowers 包，折腾了两个小时才定位到问题。所以在你动手之前，先花五分钟确认下面三件事。

第一，你用的 AI 编程助手是什么。superpowers 不是一个独立运行的软件，它需要依附在一个宿主环境上。常见的宿主包括各类支持插件或扩展的代码编辑器、命令行 AI 工具、以及一些支持自定义技能加载的对话式编程助手。不同宿主对 superpowers 的支持程度不一样，有的可以直接通过包管理器安装，有的需要手动配置技能目录。

第二，你的项目技术栈是什么。superpowers 的技能包通常是按领域划分的，比如前端技能包、后端技能包、数据库技能包、DevOps 技能包。你不需要全部安装，只装跟你当前项目相关的就行。装多了不仅浪费加载时间，还可能因为技能之间的优先级冲突导致 AI 行为异常。

第三，你期望解决什么问题。这个听起来有点虚，但实际很重要。如果你只是想让 AI 帮你写代码写得更规范，那核心技能包就够了；如果你想让它自动跑测试、自动生成提交信息、自动做代码审查，那就需要额外引入对应的技能模块。目标越明确，安装时越不容易被各种可选依赖绕晕。

2.2 标准安装流程与命令拆解

假设你用的是支持 npm 生态的 AI 编程助手（这是目前最主流的情况），superpowers 的安装通常分三步：安装核心包、初始化配置、引入技能包。

第一步，安装核心包。在项目根目录下执行：

npm install superpowers-core --save-dev

这里用--save-dev是因为 superpowers 属于开发辅助工具，不应该被打包到生产环境里。安装完成后，你的package.json的devDependencies里会多出一条记录。我建议你锁定版本号，不要用^或~，因为 superpowers 的技能加载机制在不同小版本之间可能有细微变化，锁定版本能避免“昨天还能用今天突然报错”的情况。

第二步，初始化配置。执行：

npx superpowers init

这个命令会在你的项目根目录下生成一个.superpowers文件夹，里面包含一个config.json和一个空的skills目录。config.json是全局配置文件，里面有几个关键字段你需要关注：

{ "host": "auto", "skillPaths": ["./.superpowers/skills"], "autoLoad": true, "logLevel": "info" }

host字段告诉 superpowers 你的宿主环境是什么，填auto让它自动检测。skillPaths是技能包的搜索路径，默认指向刚生成的skills目录。autoLoad设为true表示启动时自动加载所有已安装的技能。logLevel建议先设为info，方便排查问题，等稳定运行后再改成warn减少日志噪音。

第三步，引入技能包。superpowers 的技能包通常以独立 npm 包的形式发布，命名规则是superpowers-skill-*。比如你想引入代码审查技能：

npm install superpowers-skill-code-review --save-dev

安装完成后，还需要在config.json的skillPaths里加上对应路径，或者运行npx superpowers link让工具自动扫描node_modules下的技能包并建立软链接。我推荐用link命令，手动改路径容易漏。

注意：如果你在安装过程中遇到EACCES权限错误，不要直接用sudo安装。正确的做法是配置 npm 的全局目录到用户目录下，或者用 nvm 管理 Node 版本。用sudo装出来的包权限归属是 root，后续更新和卸载都会很麻烦。

2.3 验证安装是否成功的三个检查点

装完之后别急着用，先做三个检查，确认环境没问题。

第一个检查点：运行npx superpowers doctor。这个命令会输出一份环境诊断报告，包括宿主检测结果、技能路径可读性、已加载技能数量、以及潜在的版本冲突。如果报告里出现红色警告，先解决警告再继续。

第二个检查点：查看已加载的技能列表。运行npx superpowers list，你应该能看到类似这样的输出：

Loaded skills: - code-review (v1.2.0) - test-runner (v0.9.3) - doc-generator (v1.1.0)

如果列表是空的，说明技能路径配置有问题，回到config.json检查skillPaths字段。

第三个检查点：在 AI 助手的对话窗口里输入一个触发指令，比如“帮我审查一下当前文件的代码质量”。如果 superpowers 正常工作，AI 的回复里应该会体现出代码审查技能的特征——比如按照固定的检查清单逐项分析，而不是泛泛地给几句评价。这个检查最直观，也最能说明问题。

3. 技能包（skills）的引入与管理：别让工具箱变成垃圾堆

3.1 常用 skills 分类与适用场景

superpowers 生态里的技能包数量不少，我按实际使用频率和场景覆盖度，把它们分成四类。你不需要全装，根据项目阶段挑着用就行。

代码质量类是使用频率最高的一类。code-review技能会在你提交代码前自动做一轮静态检查，按照预设规则给出改进建议；lint-fix技能能自动修复常见的格式问题；type-check技能针对 TypeScript 项目做类型完整性验证。这三个我建议所有项目都装上，尤其是团队协作的项目，能省掉大量代码评审时的扯皮时间。

测试与验证类适合对质量要求高的项目。test-runner技能能根据你当前的代码变更自动识别受影响的测试用例并执行；coverage-report技能生成覆盖率报告并标出未覆盖的分支；mutation-test技能做变异测试，验证测试用例本身的有效性。这类技能在 CI 流程里特别有用，但本地开发时按需加载就行，全开会影响响应速度。

文档与注释类适合需要维护长期项目的团队。doc-generator技能根据函数签名和代码逻辑自动生成 JSDoc 或 docstring；changelog-writer技能根据 git 提交记录生成结构化的变更日志；readme-updater技能检测到项目结构变化时自动更新 README 里的相关章节。这类技能我一般只在发布前跑一次，日常开发时不常驻。

项目脚手架类适合新项目启动阶段。scaffold-react、scaffold-vue、scaffold-node-api这些技能能根据你的技术选型快速生成项目骨架，包括目录结构、配置文件、基础依赖和示例代码。用这类技能的时候要注意，生成的骨架是通用模板，你需要根据实际业务做二次调整，不要直接拿来当生产代码用。

3.2 引入技能的三种方式与优先级规则

superpowers 支持三种技能引入方式，不同方式有不同的优先级和适用场景。

全局引入是在config.json的skillPaths里配置一个全局技能目录，所有项目共享。这种方式适合那些你每个项目都会用到的通用技能，比如code-review和lint-fix。全局引入的优点是配置一次到处可用，缺点是不同项目对同一技能可能有不同的配置需求，全局配置没法做项目级覆盖。

项目级引入是在项目根目录的.superpowers/skills下放置技能包，只对当前项目生效。这种方式适合项目特有的技能，比如某个项目专用的代码规范检查技能。项目级引入的技能优先级高于全局技能，同名技能会以项目级为准。

临时引入是在单次对话或单次命令中通过参数指定技能，比如npx superpowers run --skill code-review。这种方式适合临时试用某个技能，或者做一次性任务。临时引入的优先级最高，但不会持久化，下次还得重新指定。

优先级规则是：临时引入 > 项目级引入 > 全局引入。当多个来源存在同名技能时，高优先级的会覆盖低优先级的。我在实际使用中会把核心通用技能放在全局，把项目特有的规范检查放在项目级，临时任务用命令行参数指定。这样既保证了通用性，又保留了灵活性。

3.3 技能冲突的排查与解决

技能装多了之后，最常见的问题就是冲突。冲突的表现形式有好几种：AI 行为异常、技能加载失败、响应时间明显变长、或者两个技能对同一段代码给出矛盾的建议。

我遇到过一次典型的冲突：code-review技能和另一个第三方审查技能同时对同一个文件做检查，前者要求函数不超过 50 行，后者要求不超过 30 行，结果 AI 在回复里反复纠结，一会儿说“建议拆分”，一会儿说“当前长度可接受”。排查这种问题的步骤如下。

第一步，运行npx superpowers list --verbose，查看所有已加载技能的详细信息，包括版本号、来源路径、以及技能声明的触发条件。重点关注那些触发条件有重叠的技能。

第二步，运行npx superpowers trace，这个命令会输出最近一次 AI 交互中各个技能的调用顺序和耗时。如果某个技能被调用了多次，或者两个技能在极短时间内交替调用，基本可以确定是冲突。

第三步，解决冲突。最直接的办法是禁用其中一个技能，在config.json里把对应技能加入disabledSkills数组。如果两个技能都有用，那就调整它们的触发条件，让它们在不同场景下生效。比如把code-review的触发条件设为“文件变更时”，把另一个技能的触发条件设为“手动调用时”。

提示：每次新增技能后，建议跑一遍npx superpowers doctor和npx superpowers list，确认没有引入意外的依赖或版本冲突。这个习惯能帮你省掉很多事后排查的时间。

4. 把 superpowers 用起来：四个真实场景的完整操作

4.1 场景一：提交前的自动化代码审查

这是 superpowers 最常用的场景。在没有这套体系之前，我要么手动跑 lint 工具，要么在提交前自己逐行看一遍，效率很低。引入code-review技能后，流程变成了这样。

首先，在项目根目录的.superpowers/skills下确认code-review技能已安装。然后，在 AI 助手的对话窗口里输入触发指令，比如“审查当前暂存区的代码变更”。superpowers 会自动调用git diff --cached获取变更内容，把变更文件列表和具体 diff 传给code-review技能。

技能内部会按照预设的检查清单逐项分析：命名规范、函数长度、圈复杂度、重复代码、潜在的空指针、未处理的异常、以及项目特有的规范（这些规范可以在技能的配置文件里自定义）。分析完成后，AI 会输出一份结构化的审查报告，按严重程度分级列出问题。

我实测下来，这套流程能把代码审查的时间从平均 20 分钟压缩到 5 分钟左右，而且漏检率明显降低。但有一个坑要注意：技能默认只检查变更部分，不会检查整个文件。如果你的变更引入了一个跨文件的依赖问题，技能可能发现不了。解决办法是在触发指令里明确说“检查变更文件及其直接依赖”，或者在技能配置里把检查范围设为full-file。

4.2 场景二：根据代码变更自动生成测试用例

test-runner技能配合test-generator技能，能做到“改完代码自动生成对应的测试用例并执行”。这个场景特别适合那些测试覆盖率要求高、但手动写测试又很费时间的项目。

操作流程是这样的：你先完成业务代码的修改，然后在对话窗口输入“为当前变更生成测试并运行”。superpowers 会先调用test-generator分析变更的函数签名和逻辑分支，生成对应的测试用例草稿。生成的测试用例会放在一个临时目录里，你可以先审查一遍，确认没问题后再合并到正式的测试文件里。

这里有个经验：生成的测试用例不要直接信任，一定要人工过一遍。我遇到过生成的测试用例里断言写反了的情况——本该断言结果为真的地方写成了假，结果测试通过了但实际逻辑是错的。所以我的做法是，生成的测试用例先跑一遍，看覆盖率报告，然后重点检查那些覆盖了边界条件的用例，确认断言逻辑正确后再合并。

test-runner技能在执行测试时还有一个实用功能：它会根据变更文件自动识别受影响的测试范围，只跑相关的测试用例，而不是全量跑。这在大型项目里能省很多时间。我试过一个有 3000 多个测试用例的项目，全量跑要 8 分钟，按变更范围跑平均只要 40 秒。

4.3 场景三：项目脚手架的快速搭建

新项目启动时，scaffold-*系列技能能帮你快速搭出可运行的项目骨架。以scaffold-react为例，操作步骤如下。

第一步，在空目录下初始化 superpowers：npx superpowers init。第二步，安装脚手架技能：npm install superpowers-skill-scaffold-react --save-dev。第三步，运行脚手架命令：npx superpowers run scaffold-react --name my-app --typescript --router。

这个命令会生成一个完整的 React + TypeScript + React Router 项目结构，包括src目录、public目录、tsconfig.json、vite.config.ts、以及基础的组件和路由配置。生成完成后，技能会自动运行npm install安装依赖，并执行一次构建验证，确保骨架是可运行的。

我对比过手动搭建和用脚手架搭建的时间：手动搭一个这样的骨架大概要 15 到 20 分钟，用脚手架技能大概 2 分钟就能跑起来。但要注意，脚手架生成的配置是通用最佳实践，不一定适合你的具体项目。比如它默认用的是 Vite，如果你的团队要求用 Webpack，那就得手动改。我的建议是，把脚手架当成起点而不是终点，生成后根据实际需求调整配置。

4.4 场景四：文档与变更日志的自动维护

doc-generator和changelog-writer这两个技能解决的是“代码写了但文档没跟上”的老大难问题。

doc-generator的用法很简单：在对话窗口输入“为当前变更的函数生成文档注释”，技能会分析变更的函数签名、参数类型、返回值类型、以及函数体内的关键逻辑，生成对应的 JSDoc 注释。生成的注释会以 diff 的形式展示，你可以逐条确认后应用。

我实际用下来的感受是，对于逻辑简单的函数，生成的注释质量很高，基本不用改；对于逻辑复杂的函数，生成的注释偏笼统，需要手动补充细节。所以我的做法是，先用技能生成一版，然后针对复杂函数手动完善。

changelog-writer的用法是：在发布前输入“根据上次发布以来的提交记录生成变更日志”。技能会读取 git log，按照提交类型（feat、fix、docs、refactor 等）分类整理，生成结构化的 CHANGELOG 条目。这里有个技巧：提交信息写得越规范，生成的变更日志质量越高。如果你的提交信息都是“fix bug”“update”这种，生成的日志也会很模糊。建议团队统一提交规范，比如用 Conventional Commits 格式。

5. 我踩过的坑与对应的解决方案

5.1 技能加载失败但没有任何报错

这是最让人头疼的问题——技能明明装了，list命令也能看到，但 AI 就是不用。我排查了很长时间才发现原因：技能的触发条件没有匹配上。

superpowers 的技能通常有一个trigger配置，定义了技能在什么情况下被激活。比如code-review的触发条件可能是“检测到代码变更且用户输入包含审查相关关键词”。如果你的输入是“帮我看看这段代码”，虽然语义上是在请求审查，但关键词没匹配上，技能就不会被调用。

解决办法有两个：一是调整技能的触发条件，把常见的关键词都加进去；二是在输入时使用技能文档里推荐的触发短语。我后来养成了一个习惯，把常用技能的触发短语记在便签上，用的时候直接复制，省得反复试。

5.2 技能执行时间过长导致对话超时

有些技能（比如全量代码审查、全量测试运行）执行时间比较长，如果宿主环境有对话超时限制，就会在技能还没跑完的时候中断。我遇到过一次，test-runner在跑一个大型测试套件时超过了 30 秒的超时限制，结果对话中断，测试也没跑完。

解决方案是给这类耗时技能配置异步执行模式。在config.json里把对应技能的async字段设为true，技能会在后台执行，完成后通过通知或日志输出结果。另外，也可以缩小技能的检查范围，比如把全量测试改成只跑变更相关的测试。

5.3 多个技能对同一文件写入导致冲突

lint-fix技能和doc-generator技能如果同时对同一个文件进行操作，可能会产生写入冲突——一个技能刚改完，另一个技能基于旧版本又改了一遍，结果前一个技能的修改被覆盖了。

这个问题的根源是技能之间没有协调机制。superpowers 本身不提供技能间的锁机制，需要你在配置里手动指定执行顺序。在config.json里有一个skillOrder字段，可以定义技能的串行执行顺序。比如：

{ "skillOrder": ["lint-fix", "doc-generator", "code-review"] }

这样配置后，技能会按顺序执行，前一个完成后再执行下一个，避免了并发写入的问题。代价是总执行时间变长，但对于涉及文件写入的技能，这个代价是值得的。

5.4 技能版本升级后行为突变

superpowers 的技能包更新比较频繁，有时候一个小版本升级就会改变技能的行为。我有一次升级了code-review技能，结果发现它开始强制要求所有函数必须有 JSDoc 注释，而之前的版本没有这个要求。这导致大量存量代码在审查时被标记为不合格。

应对策略是：升级技能前先看 changelog，在测试分支上验证后再合并到主分支。另外，可以在config.json里锁定技能版本，避免自动升级带来的意外。如果确实需要升级，建议先在项目的.superpowers/skills目录下放一份旧版本作为备份，出问题时可以快速回滚。

6. 关于 superpowers 的几个常见误解

6.1 它不是“装了就变强”的魔法

很多人看到“superpowers”这个名字，以为装上之后 AI 就无所不能了。实际不是这样。superpowers 提供的是一套结构化的任务执行框架，它能让 AI 在特定任务上表现得更专业、更规范，但它不能替代你的判断和决策。技能生成的代码、测试、文档，都需要你审查和确认。把它当成一个高效的助手，而不是一个全自动的替代品。

6.2 技能不是越多越好

我一开始也有“收集癖”，看到什么技能都想装。结果技能装到二十多个之后，AI 的响应速度明显变慢，而且经常出现技能冲突。后来我精简到八个核心技能，反而效率更高。技能的价值在于精准匹配你的工作流，而不是数量堆砌。建议每引入一个新技能，都问自己：这个技能解决了我当前工作流里的哪个具体问题？如果答不上来，就先别装。

6.3 它和提示词模板是互补关系

有人问，既然 superpowers 是给 AI 加技能，那是不是就不需要写提示词了？我的经验是，两者是互补的。提示词解决的是“这一次我要 AI 做什么”，技能解决的是“这一类任务 AI 应该怎么做”。好的工作流是：用技能定义标准化的执行流程，用提示词传递本次任务的具体参数和上下文。两者配合，效果最好。

7. 从我的实际使用经验出发的几点建议

如果你刚开始接触 superpowers，我建议从最小的技能集开始：先装code-review和lint-fix，跑通整个流程，感受一下技能是怎么工作的。等熟悉了之后再逐步引入测试、文档、脚手架相关的技能。

配置方面，我强烈建议把.superpowers目录纳入版本控制，但把node_modules排除掉。这样团队成员共享同一套技能配置，但不需要各自安装依赖。新成员拉下代码后，只需要跑一次npm install和npx superpowers link就能对齐环境。

性能方面，如果你的项目比较大，建议给技能配置缓存。superpowers 支持把技能的中间结果缓存到.superpowers/cache目录下，下次执行相同任务时直接读缓存，能省不少时间。缓存的失效策略可以在config.json里配置，我一般设为“文件内容变更时失效”。

最后分享一个我常用的调试技巧：当你不确定某个技能为什么没被触发时，把logLevel设为debug，然后执行一次操作，查看.superpowers/logs下的日志文件。日志里会详细记录技能的匹配过程、触发条件评估结果、以及执行耗时。这个日志我帮别人排查过好几次问题，基本看一眼就能定位到原因。