想给 AI 助手装上“外挂”，superpowers 是我今年试过的最实在的一套技能扩展方案。它不是某个大厂的云端产品，而是一套开源技能库：把日常开发中反复出现的需求拆分、代码审查、测试生成、仓库巡检等流程，封装成一个一个可复用的 skill，再通过一个轻量 CLI 和配置文件接入你常用的 AI 编程工具。装上之后，AI 不再是每次从空白的对话开始，而是能按预设的技能路径干活，输出稳定，效率提升非常明显。
这套方案尤其适合已经受够了“每次都要重新描述需求”的开发者，也适合团队想沉淀一套统一工作流的人。老手可以直接读源码改 skill，新手也能从内置技能目录开始，十几分钟跑通。本文不吹概念，只讲我实际安装和使用 superpowers 的完整过程、技能机制、编排方案，以及踩过的坑。
1. 先弄明白 superpowers 是什么，能帮你解决什么问题
1.1 为什么需要一套“技能库”而不是单个提示词
先讲痛点。用 AI 写代码的初级阶段，大家习惯在对话框里粘贴一段提示词。可是提示词是“一次性”的：这次让 AI 按你的规范生成单元测试，下次还得重新贴一遍，稍微改个措辞，输出就飘了。superpowers 把这类“一次性提示词”结构化、版本化，沉淀成独立 skill 文件。从本质上看，这和把散落各地的脚本收拢到 monorepo 是同一个道理——可复用、可维护、可评审。
我最初以为 superpowers 只是个 prompt 集合，后来看了它的源码才发现，每个 skill 不只有提示词，还包括触发条件、输入参数、输出规范、依赖工具链，以及失败时的回退策略。这意味着 AI 在执行时不是“凭感觉自由发挥”，而是像执行一个带参数的函数：传入 issue 描述，产出任务列表；传入代码文件路径，产出评审意见。这种工程化思维，让我立刻决定把它接入日常工作流。
1.2 核心设计：Skill、Trigger、Pipeline 三个层次
superpowers 的架构可以拆成三层。
Skill 是最小执行单元，描述“AI 在某种输入下应该执行什么动作”，包括名称、描述、输入 schema、执行指令和输出格式。一个 skill 通常对应一个明确任务，比如解析需求、生成测试、检查代码规范。
Trigger 是 skill 的触发规则，解决“什么时候自动调用这个 skill”。可以基于文件后缀、命令行参数、目录结构或者人工指定。比如你把一个.feature文件拖给 AI，trigger 会自动激活需求拆分技能。
Pipeline 则是多个 skill 的有序组合，解决“复杂任务需要多步协作”的问题。例如“从 issue 到测试用例”这条流水线，先走需求理解，再走任务拆分，最后走测试生成，每个环节由独立 skill 完成，中间产物可以持久化到项目目录。这套设计让我联想到 CI/CD 里的 pipeline，只是它编排的不是构建任务，而是大模型的思维流程。
个人体会：真正值钱的不是单个 skill 写得有多花哨，而是 Trigger 能不能准确触发、Pipeline 能不能把上下文正确传递给下一个环节。很多类似的工具死就死在第一步触发了，第二步却没拿到上一步的结果。
1.3 与裸 AI 助手相比的三大优势
第一个优势是输出稳定。因为每个 skill 都有明确的输出 schema，AI 返回的内容结构可以被上层脚本消费，而不是纯闲聊式的 Markdown。
第二个优势是团队共享。skill 文件就是普通代码，放进 Git 仓库之后可以走 Code Review、版本回滚、权限控制。团队里任何人改了一个 skill，全组人都能同步，不再靠复制聊天记录传递“咒语”。
第三个优势是可度量。每次执行会留下日志、耗时、token 消耗，你可以统计哪个 skill 经常失败、哪个 pipeline 效率最高，后续优化有数据依据。
我见过很多团队用 AI 很热闹，但最后没有沉淀任何资产。superpowers 至少帮你把“使用 AI 的方式”变成了可审计的工程资产，这一点在协作场景里价值特别大。
2. 从零安装 superpowers：环境准备与跑通流程
2.1 安装前置条件与版本选择
由于是本地运行的技能框架，安装前最好满足三个条件：第一，有 Node.js 环境，版本建议 18 以上，因为部分 skill 依赖现代 JavaScript API；第二，有 Git，便于拉取仓库和后续更新技能；第三，你已经有常用的 AI 编程工具或命令行助手，比如 Claude Code、Continue、Cursor 或者支持 OpenAI API 兼容接口的本地模型，superpowers 在接入层上是通用的。
我建议优先选稳定版，别追最新 commit。这类社区驱动项目迭代很快，但有些新功能还没经过大面积验证，我在早期版本遇到过配置字段不兼容的问题。安装前先用node -v和git --version确认基础环境，再根据你自己的 AI 工具选对应的接入脚本。
2.2 快速安装流程：拉取、注册、配置文件
安装分三步，我以 Linux/macOS 命令行环境为例。
第一步，拉取项目到本地目录。我通常放在~/tools/superpowers，方便统一管理。
git clone --depth 1 <项目仓库地址> ~/tools/superpowers cd ~/tools/superpowers npm install第二步，执行初始化，它会自动创建全局配置目录，并在你的 shell 配置里写入 alias。
npm run setup执行后，你会在~/.superpowers/config.json看到初始配置，里面包含默认模型参数、日志级别、skill 目录路径等。这里要注意，如果之前装过其他 AI 助手插件，可能会抢占同一个环境变量，建议检查配置文件里是否指向了你实际使用的 AI 工具。
第三步，导入内置技能。项目默认带一组官方 skills，你只需要运行：
superpowers skill import --source builtin这条命令会把内置技能复制到你的用户技能目录，而不是直接引用仓库原文件，这样做的好处是后续自定义不会污染上游，更新时也不容易冲突。
提示：如果你在公司内网环境，记得设置镜像源或离线安装，否则
npm install可能卡住。具体设置方式看你所在团队的镜像策略。
2.3 验证安装是否成功
跑通安装后别急着写复杂任务，先验证基础功能。我用的验证方法是执行superpowers skill list，如果能列出十几个 skill 名称，说明导入成功；再执行一个最简单的内置技能，比如superpowers run summarize --input README.md，如果能在终端看到输出 summary，说明整个链路没问题。
我踩过一个典型问题：命令能执行，但 AI 返回空白。后来发现是配置文件里的 API 地址多打了个斜杠，导致请求失败。所以验证时不仅要看命令退出码，更要看实际输出内容是否完整。
2.4 常见安装问题与解决
整理几个高频问题：
npm install速度极慢或卡住：多半是网络原因，换镜像源或离线包，另外检查是否缺少 lockfile 导致版本解析过慢。- 执行
superpowers命令提示 not found：初始化脚本没有正确写入 PATH，手动把~/tools/superpowers/bin加入环境变量即可。 - skill 导入后 list 看不到：检查当前 shell 是否读取了最新的配置文件，退出重开终端通常能解决。
- 日志里有认证失败：确认你配置的 API Key 或本地模型地址是否有权限，很多本地模型客户端还要额外开启服务端口。
这些问题基本都能在十分钟内解决，真正麻烦的是第二步配置环节，所以我建议把 config.json 当作一个正经配置文件来管理，不要随便手改。
3. skills 到底有哪些，以及怎么自定义一个自己的技能
3.1 内置技能清单与适用场景
superpowers 自带的 skills 覆盖了我日常开发的很大一部分。为了让你有个直观感受，我把常用的几个列出来：
| 技能名 | 核心动作 | 适用场景 |
|---|---|---|
| summarize | 总结文档或代码 | 快速读懂一个陌生仓库 |
| split-tasks | 把需求拆解为任务列表 | 从 issue 开始排期 |
| code-review | 检查代码改动并给出建议 | PR 合并前把关 |
| generate-tests | 为指定代码生成测试用例 | 补测试覆盖率 |
| refactor-plan | 制定重构方案 | 老代码改造前论证 |
| detect-tech-debt | 扫描技术债标记 | 仓库健康度巡检 |
| git-commit | 按规范生成 commit message | 日常提交 |
这些技能不是单独的 prompt 文件，每个都有自己的参数定义和执行逻辑。比如generate-tests会要求输入源代码路径、测试框架类型和覆盖率目标，输出则是一组可直接运行的测试文件路径。
3.2 技能运行机制与输入输出
从项目设计上看，一个 skill 目录里通常包含skill.yaml和若干模板文件。skill.yaml是核心描述文件，结构类似 OpenAPI 的简化版：
name: code-review description: Review code changes and provide actionable suggestions input: target: string strictness: enum[low, medium, high] output_format: string steps: - task: load_diff - task: analyze_by_rule - task: write_suggestions output: format: markdown schema: summary: string issues: array我理解它的执行逻辑是：CLI 读取 skill.yaml，把 input 和 steps 组装成一个任务指令交给 AI，AI 每执行一步，框架会检查中间结果是否符合 schema，不符合就反馈给模型修正。这也是为什么输出比裸 prompt 稳定——它不是一次生成，而是带反馈的“半自动闭环”。
3.3 实操示例：三步创建一个“代码评审”自定义技能
光用内置技能不够，很多团队有自己的代码规范，所以自定义 skill 是必学的。我拿“按团队规范做代码评审”举例子。
第一步，在你自己的技能目录下建一个文件夹和 yaml 文件：
mkdir -p ~/.superpowers/skills/team-review touch ~/.superpowers/skills/team-review/skill.yaml第二步，写入描述。重点是 input 和 steps 要写得足够具体，因为模型需要靠这些字段理解任务边界。比如 strictness=high 表示必须逐行检查，medium 只看关键逻辑。
name: team-review description: Review code according to team conventions input: target: path strictness: enum[low, medium, high] steps: - task: load_code - task: check_conventions - task: generate_advice output: format: markdown schema: passed: boolean comment: string第三步，放入团队规范文件。可以在 skill 目录下放一份conventions.md，并在 steps 中引用它。这样 AI 就能在评审时按你的规则来，而不是用通用道理糊弄你。
个人经验：自定义 skill 最关键的不是把提示词写长，而是把“输入参数”和“输出结构”定义清楚。你定义得越细，后续 Pipeline 组合时越容易衔接。我自己最开始写的几个 skill 就是大段中文描述，结果 AI 输出五花八门，后来改成结构化 YAML 才稳定。
4. 具体使用场景：从需求拆解到仓库巡检
4.1 场景一：用 split-tasks 把模糊需求变成可执行任务
先讲最常见的场景。产品经理丢过来一句话：“把登录模块改得更安全，顺便支持第三方账号。”这句话让 AI 直接写代码，结果大概率是灾难。我的做法是：把这句话丢给split-tasks，并指定输出格式为带优先级的列表。
superpowers run split-tasks --input "把登录模块改得更安全，顺便支持第三方账号" --priority high它会输出类似这样的结果：
- 梳理当前登录流程与安全缺陷
- 评估第三方账号接入方案（OAuth/OIDC）
- 设计改造方案，明确数据模型改动
- 分阶段实现，先补异常处理再改数据库
- 补充测试用例和安全验证
这个列表可以直接进入你的项目管理工具。我的体会是，第一次跑出来的结果通常偏理想化，需要你手动调整顺序，但它至少帮你避免了“漏场景”。
4.2 场景二：用 generate-tests 成批生成单测
第二个高频场景是补测试。我在接手一个旧项目时，发现核心服务类几乎没有单元测试。手工补测试太费时间，于是写了一个小脚本，遍历src/services下的所有文件，逐个调用 generate-tests：
for f in src/services/*.ts; do superpowers run generate-tests --input "$f" --framework jest --coverage 0.8 done跑完之后，每个文件旁边多了一个.test.ts。我抽查了三个文件，发现 AI 生成的用例覆盖了正常路径和部分异常路径，但缺少边界值，比如空数组、超长字符串。这个结论说明：AI 生成测试适合做“广度覆盖第一版”，不能直接当最终质量保证，代码评审仍然必不可少。
4.3 场景三：用 detect-tech-debt 做仓库健康度巡检
定期巡检仓库是个好习惯。人工巡检容易流于形式，我试着用 superpowers 做了一个每周巡检，命令是：
superpowers run detect-tech-debt --path . --exclude node_modules,dist --output docs/debt-report.md这条命令会扫描仓库里的 TODO、FIXME、HACK 标记，并结合作者的 git 历史给每个标记标出引入时间和优先级。生成报告后我发给团队，大家再也不用在代码里藏秘密了。不过要注意一点：这种扫描结果只能作为讨论依据，不要完全信它的优先级判断，毕竟 AI 不会知道某些技术债其实是业务上故意保留的。
4.4 组合技能：用 Pipeline 把 3 个技能串成自动化工作流
单独用 skill 是点状操作，Pipeline 才能形成线。我目前最常用的 pipeline 是“需求到测试”：从 issue 描述开始，先后执行 split-tasks、refactor-plan、generate-tests。配置方式如下：
pipeline: name: issue-to-tests stages: - skill: split-tasks output: tasks.md - skill: refactor-plan input: tasks.md output: plan.md - skill: generate-tests input: plan.md output: tests/执行时，前一个 stage 的 output 文件会自动成为后一个 stage 的 input 上下文。你只需要：
superpowers pipeline run issue-to-tests --input issue.md整个流程跑下来，原本要半天的人工分析，压缩到十几分钟，而且中间产物都在目录里，随时能改。我的教训是：Pipeline 里不要放超过 5 个 skill，否则 token 消耗大、上下文容易乱，而且一旦中间某个 skill 输出格式变了，后续全部失效。把大 pipeline 拆成几个小的，反而更好维护。
5. 实战排错与使用心得
5.1 三大典型坑与排查思路
在使用一个月后，我总结出三个最坑的地方。
第一是上下文超限。当 pipeline 的中间产物非常大时，后续 skill 会把整个文件读入上下文，模型直接报错。解决方法是把中间产物改成摘要文件，而不是把原始日志全量传递。
第二是输出 schema 不匹配。有时候 AI 会在 markdown 里附加解释文字，导致解析器拿不到结构化字段。这时要在 skill 的 output schema 里增加strict: true字段，并写明“除指定字段外不要输出任何内容”。
第三是 trigger 误触发。比如你把所有.md文件都关联到 summarize，那么 CHANGELOG 也会被拿去总结。排查时要学会看日志，确认是哪一条 trigger 匹配到了不该匹配的文件。
这些坑都不是致命问题，但每踩一次都要花时间调，尤其是第一条，越到项目后期越频繁。
5.2 性能调优与上下文管理
我的实际经验是，优化 superpowers 的使用体验，核心不是调模型参数，而是控制上下文。具体做法有三点：
- 给每个 skill 设置
max_input_length，超长内容先切片再处理； - 尽量让中间产物输出为简洁文本或表格，而不是大段原文；
- 定期清理不再使用的自定义 skill，减少触发器的干扰。
我用这三点优化后，一次 pipeline 的总耗时降低了约三成，模型回答的准确率也提高了不少。原因很简单：大模型拿到的上下文越干净，输出自然越稳。
5.3 什么情况下建议用 superpowers，什么情况下别用
不是所有任务都适合套 skill。我的判断标准是：任务一旦具备“可重复、有固定输出格式、需要一致性”这三个特征，就适合封装成 skill；如果是探索性的、需要大量开放性回答的任务，比如头脑风暴、技术选型讨论，用裸对话反而更灵活。
我目前把 superpowers 定位成“团队内部 AI 工作流的中枢”，而不是一个每天敲命令的工具。真正产生价值的场景是 CI/CD 里自动化跑代码评审、每周生成技术债报告、新需求进来先跑一轮任务拆分。至于临时让 AI 解释某段代码、写个一次性的正则，我反而不会特意走 skill，直接在对话里问更省事。
最后分享一个我自己的使用节奏：刚装上时兴奋，啥都想封装成 skill，后来发现维护成本不低，才学会克制。现在我只保留四个核心 pipeline，外加十几个常用 skill，剩下的需求宁可手动敲也不是每个都值得固化。如果你刚开始接触 superpowers，我的建议是从“每周技术债巡检”或“PR 代码预评审”这种低频但效果明显的场景切入，先跑通一条完整的流水线，再逐步增加新的技能。这样你既能感受到这套框架的价值，也不会一上来就被配置细节劝退。等你用顺手后回头看，AI 编程工具的真正差距，往往不在于模型本身，而在于你有没有一套可靠的、能沉淀的执行框架。
