1. Superpowers 到底是什么一个被反复提起的“技能包”生态这两天我在整理自己的 AI 编程助手工作流时发现superpowers这个热词被反复提到。老实说第一次看到项目标题时我也愣了一下它到底是某个 CLI 工具、一组可以安装的 skills还是一个完整的技能生态带着这个疑问翻了文档、跑了几轮实测今天这篇文章就把它彻底讲清楚Superpowers 不是一个单一的插件而是一套“技能包skills”管理方案核心目的就是让 AI 助手具备更多开箱即用的专业能力而你只需要一条命令就能安装、引入和切换这些技能。它解决什么问题很多人用 AI 编程工具时都是从零开始写 prompt今天让它检查代码明天让它写测试后天让它补文档。每次都需要重新描述需求、反复调教效率很低。Superpowers 的思路是把这些常见任务固化成一个个标准化的 skills每个 skill 就是一份结构化的指令模板加执行逻辑。你安装它之后不需要再重复“把这段话复制给助手让它做什么”直接调用技能名AI 就知道该干什么、按照什么步骤干活。适合谁来用三类人最合适每天重度依赖 AI 编程助手写代码、做 code review、写测试的开发者刚接触 AI 工具想知道“到底还能做什么”的新手以及想在团队里统一一套 AI 使用规范、减少大家重复沟通成本的技术管理者。我会从安装、初始化、技能清单、自定义技能到排坑完整走一遍确保你看完就能自己装起来。1.1 为什么叫“超级能力”“Superpowers”这个名字起得很直白就是给你常用的 AI 助手加上一层“超能力”。普通模式下助手的能力边界取决于你临时给了它什么 prompt而装上技能包之后助手就变成一个有“工具箱”的专家。比如code-review技能它不只是简单说一句“帮我看看这段代码有问题吗”而是会按一套完整的审查流程执行先读代码、再检查潜在 bug、然后评估性能隐患、最后给出可落地的修改建议。这种“流程化的专业能力”就是 Superpowers 所说的超级能力。我从实际使用的感受来补充一点技能包的本质是一种“上下文压缩”。当你调起某个技能时系统会自动加载对应指令、规则和输出格式省去你每次手动粘贴一长串需求的过程。这就像你请了个实习生一开始你手把手教他每一步后来你只需要说“按流程走一遍”他自己就知道先做什么后做什么。Superpowers 就是这个“流程清单”的载体。1.2 它和普通插件的区别很多人会把 Superpowers 理解成“又一个插件”。其实差异挺明显普通插件通常是绑定某个具体编辑器或特定工具而 Superpowers 更多是围绕“技能定义文件”来工作迁移成本低。你的 skill 是一份 Markdown 或 JSON 格式的文本换工具时照着格式搬过去就能用普通插件的能力是写死的而 Superpowers 的 skills 你可以自己改、自己写也可以下载社区分享的版本普通插件通常是“打开软件后用 UI 操作”而 Superpowers 更偏向命令行和配置文件协同适合喜欢把工作流沉淀成文字的玩家。这也是它为什么在热词搜索里常和“具体使用”“有哪些 skills”“怎么引入这些技能”绑在一起的原因它太不像一个传统工具了更像一套“技能管理规范”大家上手第一件事就是先弄清楚它到底怎么组织技能、怎么把技能放进自己的工作流。1.3 当前版本的定位与整体架构我按常见实践整理了一下Superpowers 的整体架构大致分三层运行时层也就是superpowers命令行工具本身负责安装、列出、引入、执行技能技能层存放在本地目录下的一组 skills每个 skill 包含能力描述、参数定义和执行指令接入层通过与 AI 助手的会话桥接把技能内容注入到对话上下文中让助手能理解并执行。这里要特意说明具体对接方式会随 AI 工具版本变化但技能定义和目录结构相对稳定。理解了这三层你就能明白为什么引入一个 skill 只需要把它放到正确目录并跑一次导入命令而不需要大动干戈改配置。这个设计我很喜欢它让“能力扩展”变成了一件可积累、可共享、可以版本管理的事情。2. 安装前的准备与第一条命令在动手之前先把环境准备好。Superpowers 对系统其实挺友好但有几个前置条件没满足的话后面很容易反复报错。我自己实测下来最干净的方式是走 Node.js 这条线下面按这个思路来讲。2.1 环境要求与确认方法Superpowers 的运行时依赖 Node.js 环境和 npm 包管理器。建议使用 Node.js 18 及以上版本主要因为部分技能加载逻辑用到了较新的语言特性老版本跑起来会直接抛语法错误。在终端里先确认一下当前版本node -v npm -v如果输出类似v20.11.0和10.2.4就没问题。如果版本偏低建议先升级 Node.js别硬着头皮往下装。因为我试过在 Node 16 上装老版本能装上但一跑superpowers init就报SyntaxError: Unexpected token ?查了半天才意识到是版本问题。另外Windows 用户建议用 PowerShell 或 Windows Terminal 操作避免使用系统自带的 CMD因为某些技能命令的彩色输出在 CMD 里会乱码。macOS 和 Linux 用户则建议用 zsh 或 bash。2.2 三种安装方式的取舍Superpowers 的安装方式不止一种选择哪种取决于你的使用习惯和权限情况。我实测下来主流方式有以下三种方式一npm 全局安装推荐npm install -g superpowers/cli安装完成后执行superpowers --version如果有版本号输出说明安装成功。这种方式的好处是升级方便执行npm update -g superpowers/cli就能搞定。方式二Homebrew 安装macOS / Linux如果你平时习惯用 Homebrew 管理软件可以试试brew install superpowers不过我要提醒一句Homebrew 仓库里的版本可能会比 npm 上的慢一点如果刚发布新版本brew 源还没来得及更新建议切回 npm 安装。方式三直接从源码运行想尝鲜或者二次开发的话可以 clone 项目仓库后手动链接git clone https://github.com/example/superpowers.git cd superpowers npm install npm link这种方式适合想改源码的人日常使用不推荐因为后续更新需要手动 pull 再重新 link比较麻烦。我个人的建议是不是改代码就老老实实用 npm 全局装省心。2.3 初始化与目录结构说明安装完成后的第一件事是初始化superpowers init运行之后它会在你的用户目录下生成一个.superpowers文件夹里面主要有几个部分.superpowers/ ├── config.json ├── skills/ │ └── builtin/ └── cache/config.json保存全局配置比如默认启用的技能列表、是否开启彩色输出等skills/builtin是内置技能存放目录cache用来缓存技能拉取信息。初始化过程中会问几个问题要不要开启自动更新检查、使用什么默认输出语言、是否允许技能执行本地脚本。前面两个按个人喜好选就行第三个我建议认真考虑一下。这里有个重要提醒允许技能执行本地脚本需要谨慎。因为技能包往往来自社区你无法百分之百确定里面的脚本行为是否安全。如果只是日常使用建议选择“不允许”后续需要时再针对单个技能单独授权。安全意识一定要有这也是我自己踩过坑之后转变的习惯。初始化结束后可以跑一条命令确认目录状态superpowers status它会列出当前版本、技能总数和启用状态。看到绿色的 OK 提示就说明环境已经准备好了可以开始浏览技能了。3. 核心技能skills拆解与使用场景有了环境之后大家最关心的就是“有哪些 skills”。我把 Superpowers 内置的一批常用技能按类别拆开讲附上使用场景方便你照着选。3.1 代码质量类技能检查、测试、重构这类技能是日常使用频率最高的几乎每天都会用到。code-review代码审查调用方式一般是superpowers run code-review --input ./src/xxx.ts它做的事比我预想的要细致先拆解文件结构和主要逻辑再逐段扫描异常处理、边界条件、命名规范最后生成一个分级报告把“必须修改”和“建议优化”分开。我试过对一段自己写的业务代码跑了一遍结果还真发现了一个漏掉的空指针判断这比我肉眼 review 靠谱多了。test-gen测试生成这个技能会根据你的函数或模块生成测试用例。它不会简单复制一个测试模板而是先分析输入输出类型、分支逻辑和边界情况再设计一组覆盖率相对完整的用例。对于新写的模块我习惯跑一下test-gen把生成的用例作为初始测试骨架再手工补充业务相关场景效率明显提升。refactor重构建议它和code-review的区别在角度review 是指出问题refactor 是给出可执行的修改方案。它通常会输出“基于策略的重构建议”比如把过长的函数拆成小函数、消除重复逻辑、简化嵌套条件。尤其适合接手老代码时快速摸清改进方向。3.2 文档与协作类技能提交信息、README、接口文档这类技能解决的是“写文档痛苦症”。commit-msg生成提交信息执行方式superpowers run commit-msg它会读取当前的 git diff分析变更内容然后按 Conventional Commits 规范生成提交信息比如feat: 新增用户注册接口。我在团队里推动过用它来统一提交格式效果不错至少再也没人提交一堆“update”这样的废话了。doc-gen生成 README / 接口文档给它一个项目入口或者一堆源文件它就能生成结构化的文档。我看到它生成的 README 会包含功能简介、安装方式、使用示例、配置项说明。接口文档也能自动列出每个路由的方法、参数、返回示例。不能说完全替代人工润色但作为初稿已经能省很多时间。3.3 排障与优化类技能容器、性能、依赖这类技能适合线上出了问题或者性能不达标时快速定位。docker-debug专门排查容器问题。比如镜像构建失败、容器启动后退出、日志刷屏找不到根因。它会检查 Dockerfile 的层级缓存、启动命令、环境变量、网络配置给出可能性排序和验证命令。perf-analyze性能瓶颈分析这个技能适合分析一段代码的性能问题。它会从时间复杂度、内存占用、IO 频率、循环次数等角度给出建议。我测过一个双层循环嵌套导致的响应慢问题它很快就定位到内层循环做了太多重复查询并给出了“先查出结果再组装”的优化方案。dep-scan依赖安全检查这个技能会扫描项目依赖列表对照公开漏洞库检查是否有已知问题。对于 Node.js 项目它内置了一个简化版的依赖审计逻辑能帮你快速找出高危版本。3.4 如何查看当前可用的全部技能如果你想看完整清单不用翻文档直接在终端执行superpowers list输出会以表格形式展示每个技能的名称、描述、版本和启用状态。大概长这样┌──────────────┬──────────────────────────┬───────┬────────┐ │ name │ description │ ver │ status │ ├──────────────┼──────────────────────────┼───────┼────────┤ │ code-review │ 执行代码审查并输出报告 │ 1.2.0 │ enabled│ │ test-gen │ 为模块生成测试用例 │ 1.1.0 │ enabled│ │ refactor │ 提供重构建议 │ 1.0.3 │ enabled│ │ commit-msg │ 生成 git 提交信息 │ 1.0.0 │ enabled│ │ doc-gen │ 生成项目文档 │ 1.0.2 │ enabled│ └──────────────┴──────────────────────────┴───────┴────────┘如果某个技能你暂时用不到可以单独禁用superpowers disable doc-gen需要时再重新启用superpowers enable doc-gen这个机制挺实用因为技能数量一多全部注入上下文会让每次对话变慢按需启用才是正确姿势。我自己的习惯是常用 3~4 个保持开启其他用到哪个开哪个。4. 引入自定义技能的方法与实战内置技能再多也架不住每个人业务场景差异大。真正让 Superpowers 有价值的地方在于你可以自己写技能也可以从社区引入别人分享的技能。这一章我重点讲引入路径和实战写法。4.1 skills 目录与配置项解析技能文件的存放位置是有规则的。默认情况下Superpowers 会从两个地方加载技能安装包自带的builtin目录用户目录下.superpowers/skills/中的自定义技能。每个技能必须以独立文件夹形式存在文件夹名称就是技能名称文件夹内必须有一个SKILL.md文件。如果想给技能附加脚本或资源文件也放在同一个文件夹内。看一下config.json的结构重点配置项大概是{ skillDirs: [ ~/.superpowers/skills, ./.superpowers/skills ], defaultLanguage: zh, autoUpdate: true, allowLocalScript: false, enabledSkills: [code-review, test-gen] }skillDirs技能加载目录可以追加团队的共享目录defaultLanguage技能输出默认语言autoUpdate是否自动检查内置技能更新allowLocalScript是否允许技能执行本地脚本enabledSkills默认启用的技能白名单。改完配置记得重启会话或重新执行superpowers status让它重新加载配置。4.2 写一个最小可用的自定义技能我拿一个实际例子来演示写一个“SQL 优化助手”技能作用是根据输入的 SQL 语句和相关表结构输出索引优化建议。在.superpowers/skills/sql-optimizer/SKILL.md里写入--- name: sql-optimizer description: 分析 SQL 并给出索引和查询优化建议 version: 1.0.0 arguments: - name: sql description: 待分析的 SQL 语句 required: true - name: schema description: 相关表结构信息可选 required: false --- # SQL 优化助手 ## 角色 你是一名资深的数据库性能优化工程师。 ## 任务 分析用户提供的 SQL 语句按以下步骤输出 1. 解析查询涉及的表和字段 2. 检查是否存在全表扫描风险 3. 根据字段选择性和 WHERE 条件给出索引建议 4. 检查是否有不必要的子查询或重复扫描 5. 输出优化前后对比和预期收益说明。 ## 输出格式 - 疑似问题列表 - 优化建议 - 等价改写后的 SQL如果适用保存之后执行superpowers reload superpowers list就能看到sql-optimizer出现在列表里了。调用方式superpowers run sql-optimizer --sql SELECT * FROM users WHERE age 18 ORDER BY created_at DESC --schema users(id, name, age, created_at)这个技能就会按 SKILL.md 里定义的流程进行分析。从这个例子上可以看到所谓“技能”本质就是一份结构化的角色定义操作流程输出规范。理解了这一点你就能根据自己的工作流写一堆顺手的小工具。4.3 引入第三方技能包的完整流程除了自己写更多时候是从团队或社区里引入现成的技能包。引入方式有两种。方式一从本地目录导入如果别人把技能包发给你或者你们团队共享了一个技能目录可以这样导入superpowers install ./skills/someone-skill这条命令会把整个文件夹复制到.superpowers/skills/下然后自动执行superpowers reload。方式二从远程仓库导入如果技能包发布在 Git 仓库里可以执行superpowers import https://github.com/example/someone-skill.git导入前它会在终端里提示你确认来源然后开始拉取。这里提醒一下远程导入后建议先执行superpowers inspect someone-skill查看技能包内的文件结构和脚本内容确认没有可疑操作再启用。我踩过的一个坑是引入某个第三方技能后启用时一直报“找不到命令”。后来发现是技能包里的SKILL.md名称和文件夹名不一致导致加载器无法匹配。解决办法是让文件夹名和name字段保持一致。这个细节很容易被忽略但十次八次有人踩。引入之后如果发现技能有问题想卸载也很简单superpowers uninstall someone-skill不用担心污染环境它只会把对应文件夹和配置里的启用项清理掉不会动其他数据。5. 踩坑记录与高频问题排查前面把流程说完了这一章专门汇总我在实际使用中遇到的问题和对应的解决办法。工具类项目踩坑是最能积累经验的这一章就当送你的避坑指南。5.1 问题速查表我整理了几个高频问题的表现、原因和解决方式方便你有问题的时候快速对照问题表现可能原因解决办法superpowers: command not foundnpm 全局安装目录不在 PATH 中执行npm bin -g找到路径加入 PATH初始化时报SyntaxErrorNode 版本过旧升级 Node.js 到 18 以上superpowers list输出为空技能目录未被正确识别检查config.json中的skillDirs执行superpowers reload导入第三方技能后不生效文件夹名和 SKILL.md 的 name 不一致改成一致后重新 reload启用技能后对话依然调不起来会话上下文未刷新重启 AI 助手会话或者重新执行superpowers statusWindows 输出乱码终端编码问题使用 Windows Terminal或在配置中设置defaultLanguage为简体中文执行耗时长启用了太多技能用superpowers disable关掉不常用的只保留 3~4 个核心技能5.2 权限类的坑EACCES 与脚本安全我第一次用 npm 全局安装时遇到过EACCES权限错误原因是系统目录权限不够。网上建议用sudo npm install -g可以解决但我不推荐因为用 sudo 装全局包可能会改变文件所有权后续维护很麻烦。更稳妥的做法是用 npm 的 prefix 指定一个用户可写的全局目录。比如在 macOS 上我自己的做法是mkdir ~/.npm-global npm config set prefix ~/.npm-global然后把下面这行加到~/.zshrcexport PATH~/.npm-global/bin:$PATH重新打开终端再安装就不会有权限问题了。另外就是前面提到的allowLocalScript。如果你允许技能执行本地脚本那等于把一段未知代码的运行权利交给了技能包作者。这个权限一旦开启风险就跟着上来了。我的原则是默认关闭只有对一个技能包的内容完全信任时才在技能包的权限配置里单独放行而不是全局打开。别图省事在安全上省的那点事往往要用更大的代价来还。5.3 上下文与参数使用的经验之谈最后聊聊更进阶一点的细节。技能包的使用效果很大程度取决于参数传得是否到位。比如code-review这个技能如果你只是简单传一个文件路径它就只能基于代码本身做静态分析如果你能把相关的需求背景、历史 bug 信息一并传进去它的分析就会带着业务视角给出的建议会明显更贴合实际。在传参数的时候注意长参数用--key value的格式带空格的值用双引号包起来否则会被拆成多个独立参数。下面是个常见的错误示例和正确做法# 不推荐描述信息被截断 superpowers run code-review --input ./src/index.ts --desc 修复登录功能 # 推荐用引号包含 superpowers run code-review --input ./src/index.ts --desc 修复登录功能主要改动在 session 处理对于那种临时性、一次性的需求我不会新建一个技能而是直接用参数方式在调用时补充上下文。只有当某个流程反复出现时才值得把它固化成技能。这个判断标准能避免你创造一个充满“一次性技能”的目录然后还得定期清理。还有一个小技巧跟 AI 助手搭配使用时把superpowers list的输出结果直接粘给助手让它知道你现在有哪些能力、哪些技能处于启用状态。这样助手在回答问题时会优先考虑用已有技能来完成任务而不是绕远路走通用路径。实测下来这种方式能让任务完成的准确率提升一个档次因为你给模型提供了一份“可用的工具清单”它自然更倾向于调用工具。最后分享一点我的实际体会装 Superpowers 只是第一步真正增值的是你持续往里面沉淀自己的技能。我最近养成的习惯是每完成一个重复三次以上的任务就停下来想想能不能把它做成一个 skill。比如“DNS 排查”“日志切片分析”“API 接口设计评审”这些本来要写很长 prompt 才能说清楚的事现在都固化成了一个个小技能团队里的小伙伴拿去就能直接用。再提供一个扩展方向你完全可以把这些技能文件放进私有 Git 仓库里作为团队资产管理。新成员入职时克隆一份技能库、执行一次superpowers init和superpowers reload就等于把团队多年的 AI 使用经验一次性复制到了他本地。这种知识沉淀方式比文档更直观也比口头传授更持久。所以别把这篇文章看完就关掉建议你现在就装一个试试跑一遍superpowers list找一个你最想提升的任务场景写你人生中第一个SKILL.md。用不了十分钟你就会发现自己打开了另一扇门。