如果你跟我一样把 Claude Code 当主力编程搭子用了几个月，一定遇到过同一个尴尬时刻：它昨天刚帮你重构过一个模块，今天又对着同样的坏味道犹豫半天；你让它写测试，它会用最简单的方式“凑”出覆盖率；你让它复盘一次失败的 CI，它能从日志里找出十个怀疑对象，却始终没定位到真正崩掉的那一行。
我一度以为是提示词写得不够细，后来发现根子在“无状态”三个字上。每次对话都是一次全新入职，它没有长期记忆，也没有固化的工作习惯。直到我把一个叫 Superpowers 的技能包装进 Claude Code，这个局面才算彻底扭转。
这篇文章就围绕 Superpowers 具体使用展开，聊聊它到底提供了哪些 skills、怎么引入这些技能、如何安装，以及在真实项目里用起来会遇到哪些坑。内容偏向实操，适合已经在用 Claude Code、并且想让 AI 从“会写代码”进化到“会干活”的人。
1. Superpowers 到底解决的是哪类问题
先说结论：Superpowers 不是一个“更聪明的模型”，它是一套给编程代理用的可复用工作流。它的安装单位是 skills——也就是 Claude Code 官方支持的 Agent Skills 机制下的一组说明文件。
1.1 为什么 Claude Code 需要“技能”，而不是靠现场发挥
Claude Code 这类编码代理的能力边界其实很分裂：模型本身很强，但每次会话都是“失忆”的，不知道上次用什么顺序排查了问题，不知道你团队代码库的潜规则，也不知道你自己踩过哪些坑。
你当然可以把这些规则写进 CLAUDE.md，但 CLAUDE.md 本质是“背景知识”，它不适合承载复杂的操作流程。比如“当一个测试失败时，应该先复现、再缩小范围、然后修根因、最后补回归测试”——这种流程写进 CLAUDE.md 会很臃肿，而且 Claude 不会把它当成必须执行的动作链。
Skills 就不一样。它本质是一份结构化的操作手册，包含明确的适用场景、执行步骤、检查清单和输出格式。当 Claude 判断当前任务匹配某份技能描述时，它会把这份手册读进来，然后按手册里定义的节奏干活。
Superpowers 恰好是这一机制的开源技能包合集，作者把多年结对编程的实战经验拆成了十几个技能文件，装进去就等于给 Claude 配了一套“标准作业程序”。
1.2 它是怎么和官方技能机制衔接的
这里要澄清一个常见误解：很多人以为 Superpowers 是独立插件或需要单独启动的守护进程。其实它只是把一堆遵循官方格式的 Markdown 技能文件放进全局配置目录，并用一个安装脚本顺带补全一些辅助命令。
安装完成后，Claude Code 会像扫描系统自带技能一样扫描这些文件。技能描述（description 字段）会被纳入代理的工具匹配过程——也就是说，Claude 自己就能判断“这个场景应该用哪个技能”，不需要你每次手动点名。
底层的原理并不玄乎：每个技能文件里有一小段 YAML Front Matter，标注了技能名称和触发条件；正文是 Markdown 写成的流程指引。Claude 在做工具选择时，会根据当前任务与技能描述的相关性来决定要不要加载某个技能，加载后它就会“照着手册执行”，而不再是纯粹的自由发挥。
2. 安装 Superpowers：一次干净的安装过程复盘
安装这件事本身不难，难点在于装完之后你根本意识不到它生效了。所以我建议按下面的顺序走一遍，每一步都做一次验证。
2.1 安装前置条件与环境检查
先确认环境满足基本条件，避免装到一半报错：
| 检查项 | 要求 | 验证方式 |
|---|---|---|
| Node.js 版本 | 18 及以上 | 执行node -v |
| Claude Code | 最新版且已登录 | 执行claude --version，且能正常发起对话 |
| 安装脚本执行权限 | 当前用户可写全局 Claude 目录 | 检查~/.claude/skills/是否存在且非只读 |
其中最容易踩坑的是 Node.js 版本。有些 skill 安装器内部会调用 node 脚本做文件迁移，版本太老可能直接静默跳过部分步骤。我建议装之前先统一升级到 LTS。
另外注意：安装脚本需要访问 GitHub 获取原始仓库内容。如果你的网络环境需要代理，请在安装前先在终端确认能正常访问 GitHub——这里不展开细节，但国内用户实际安装时卡住的话，十有八九是卡在这一步。
2.2 安装命令与目录清单
以官方 README 为准，现在我在仓库主页看到的安装方式是一段 pipe 到 bash 的 curl 命令，大致长这样：
curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash我当时安装后没有立即用最新版，其实更推荐的做法是先把仓库 clone 到本地扫一眼安装脚本再执行，毕竟把远程脚本直接喂给 bash 是个有风险的习惯。
如果你偏好手工安装，本质就三件事：
- 把仓库里的 skills 目录下的所有文件复制到
~/.claude/skills/； - 把仓库里的 commands 目录下的文件复制到
~/.claude/commands/（如果有的话）； - 确认权限和文件完整性。
装完后，重点检查这两个地方：
~/.claude/skills/下应该出现十几个子目录，每个子目录对应一个技能，比如code-review、debugging、refactoring，每个目录里至少有一个 SKILL.md 文件；~/.claude/commands/下应该有若干 slash command 文件，这是 Superpowers 给你提供的快捷指令入口。
我去翻了翻真实的安装输出，它还会提示你是否把超级项目经理（superpowers 本身）注册为首选入口，并且会建议你禁用一些容易过度干预的技能。我当时没细看直接默认全装，后面反而多花了不少调整时间。
2.3 安装完成后的第一件事：验证技能是否被识别
好，装完了，怎么知道有没有真生效？我的建议是开一个新会话，执行下面这一步：
请列出你现在可以使用的全部 skills，并告诉我每个 skill 的一句话用途。如果 Claude 回答里出现了Superpowers: ...之类的技能清单，说明加载正常。如果它说“我没有可用技能”，多半是目录路径不对，或者文件名不符合官方 SKILL.md 的命名规范，回去检查一下再重开会话。
更直接的验证方式是把一个轻量技能拉出来跑一遍。比如让 Claude“用 reading-docs 这个技能帮我看一下当前项目的 README 是否完整”，它会先声明“我将调用 reading-docs 技能”，然后按流程输出结果。
3. 开箱自带的 skills 清单：哪些技能值得先用
Superpowers 自带的 skills 数量不少，但没必要每个都精读。我按自己实际使用频率把它们分成了三组，先看这一张表：
| 分组 | 技能名称 | 核心用途 | 我最常使用的场景 |
|---|---|---|---|
| 问题定位 | analyzing-failures | 分析失败原因，要求先复现再下结论 | CI 红了但日志长到无从下手 |
| 问题定位 | debugging | 系统化调试，强制缩小怀疑范围 | 本地偶现 bug，没法稳定复现 |
| 质量保障 | reviewing-code | 按维度代码审查，输出结构化意见 | 合并请求合入前做一轮 Review |
| 质量保障 | running-tests-getting-coverage | 跑测试 + 查覆盖率，先摸清现状 | 准备重构前先看测试底子 |
| 变更实施 | making-changes | 小步修改，先拆任务再动手 | 改一个跨模块功能时防止“大爆炸” |
| 变更实施 | refactoring | 重构专用流程，先保行为再优化 | 清理老代码坏味道 |
| 规划与文档 | creating-technical-design-docs | 产技术设计文档 | 开发前先和团队对齐方案 |
| 规划与文档 | defining-tasks-plans | 把大目标拆成可执行任务 | 接到需求后先列实施步骤 |
| 文档学习 | reading-docs | 带步骤地阅读项目文档 | 接手新项目时快速梳理 |
3.1 问题定位组：analyzing-failures 和 debugging
这两个是我最先爱上 Superpowers 的原因。没装之前，Claude 遇到失败日志会直接开始猜，而且猜得很自信。装上 analyzing-failures 之后，它第一步就会“复现失败”——这是技能文件里写死的硬性要求，Claude 必须执行完这一步才能继续分析。
技能文件的正文里通常有检查清单：复现、保留现场、缩小输入、提出根因假设、验证假设、检查修复是否引入回归。整个流程被拆成了强制步骤，AI 的自由发挥空间被压缩在一个合理范围内。
debugging 更进一步。它会要求 Claude 在动手修之前先写清楚“你已经知道了什么、还不知道什么、下一步实验是什么”。这个习惯对人也同样受用，实际上是把你逼成一位更严谨的排查者。
3.2 质量保障组：reviewing-code 与运行测试
reviewing-code 不是简单说“有没有 bug”，它会把审查拆成几个维度：正确性、可读性、安全性、性能边界、测试覆盖。每个维度都有一组提问模板，Claude 按模板逐项过，输出一个带严重级别标注的审查意见。
我第一次看它输出时有些恍惚，这完全就是一位有多年 Review 经验的老同事开的单子。它会忽略代码风格吹毛求疵的地方，但会把“这里缺少边界判断”标成高优先级问题。
running-tests-getting-coverage 则是给那些“不跑测试就当没问题”的人准备的。它执行时的第一步永远是搞清楚测试命令是什么、哪些用例在跑、覆盖率报告在哪，而不是一上来就全量跑，非常实在。
3.3 变更与规划组：防止 Claude“大爆炸式”改代码
没装技能时，让 Claude 一次改完三处耦合逻辑，它经常一口气把所有文件全打开，改到一半状态就混乱了。Superpowers 的 making-changes 和 refactoring 强制它进入“增量修改”模式：先列变更清单，评估影响面，然后一次只动一个点，每动完一步就同步验证一次。
definining-tasks-plans 的玩法也很有意思：把一个大需求拆成若干小任务，并为每个任务写出验收条件。这就像项目经理替你把活拆好了，Claude 后续只需要按计划逐项执行，出错概率直线下降。
4. 怎么引入这些技能：三种用法与一个推荐姿势
安装好技能只是第一步，真正决定体验的是你怎样“请出”这些技能。我试过三种方式，各有适用场景。
4.1 显式调用：把技能名直接写进需求
最朴素的做法是在提示词里直接点名技能，比如：
请使用 reviewing-code 技能，对 src/api 目录下的代码做一次全面审查。这种方式的优点是可控性强，缺点是要求你对技能清单足够熟。而且如果你每次都需要手动点名，那和写一段长提示词也没有本质区别，并没有发挥出技能自动匹配的优势。
4.2 隐式触发：让 Claude 自己判断何时该用
这是我目前最推荐的方式。Claude Code 的工具匹配机制会读取每个技能的描述，当你的需求与之相关时，它会自动加载技能文件并遵循其中的流程。
比如你在对话里随手说一句“这段代码味道不太好，帮我看看”，Claude 如果判断这更符合 refactoring 的场景，它就会主动加载 refactoring 技能；如果它判断这是在说 bug 现象，就会去匹配 debugging 技能。
要让隐式触发稳定工作，你需要把技能描述写得足够细，这一点放到第五节展开。
4.3 用超级项目经理技能（superpowers）做入口编排
还有一条隐藏玩法：Superpowers 里本身有一个“元技能”，名字就叫 superpowers。它的作用不是直接做某一类任务，而是充当调度中心。
当你输入“使用 superpowers”时，它会先向你确认场景，然后基于场景自动择匹配的子技能。等于给 Claude 配置了一位领班，由领班分配活给各组专员。
我的个人建议：日常干活用隐式触发，遇到大型复杂任务时手动点名超级项目经理，让它拆解后再逐项调度具体技能。两者搭配远比手动逐个点名省心。
4.4 一个推荐姿势：把技能名写在项目记忆里
如果嫌每次说一遍太繁琐，可以在项目的 CLAUDE.md 里加一小段约定，把常用技能和典型场景的映射关系写进去。比如：
- 当需要对合并请求做审查时，始终使用 reviewing-code 技能。 - 当测试失败需要定位根因时，始终使用 analyzing-failures 技能。这样 Claude 在项目上下文里就会经常主动加载对应技能，相当于把“引入规则”固化成了团队规范。
5. 自定义技能的引入：把自己踩过的坑变成技能
真正的价值不在开箱技能，而在于你能把自己团队的经验沉淀成私有技能。这是 Superpowers 整个体系里我最喜欢的一部分。
5.1 自定技能的标准骨架
官方技能本质上就是一个目录里的 SKILL.md 文件，结构分成两部分：
--- name: my-team-review description: 当需要审查前端组件变更时使用，重点检查状态管理、样式隔离和可访问性。 --- # 审查流程 1. 先定位本次变更涉及的所有组件文件。 2. 检查状态管理是否有跨组件耦合。 3. 检查样式是否为全局污染。 4. 检查表单控件是否暴露了可访问性标签。 5. 输出一份按严重程度排序的审查清单。YAML 区里的name和description是给 Claude 做“工具匹配”用的，正文则是给它签的“工作手册”。
5.2 引入自定义技能的三步操作
把上述内容保存成~/.claude/skills/my-team-review/SKILL.md后，重新开一个会话，再让 Claude“列出全部技能”，就能看到新技能出现了。
这里提醒三个我在实战中踩过的坑：
- description 写得越具体，被正确调用的概率越高。我一开始写的描述是“处理前端变更”，结果 Claude 经常在无关场景下强加载它。改成“当需要审查前端组件变更时使用，重点关注状态管理、样式隔离和可访问性”后，触发准确率明显提升。
- 目录名和 name 字段尽量保持一致。有些版本的工具解析器对目录名很敏感，目录名和技能名不一致会导致读取失败。
- 技能文件里不要放敏感信息。全局技能目录对所有项目、所有会话可见，把内部 IP、密钥、第三方账号写进去等于把这些信息交给每一次会话里的 Claude。敏感内容请放项目级
.claude/skills/里，并且做好访问权限管理。
5.3 把自己的复盘经验固化成一个技能，才是终极玩法
我有个习惯：每次解决完一个棘手的线上问题，会把处理过程整理成一份新的技能文件。比如有一次处理“redis 连接池被打满”的问题，我把排查链路写成了技能：“先查慢查询、再看连接池等待数、然后看大 key、最后看是否存在热 key 争抢”。下次再遇到类似问题，Claude 直接按这条链路走，不用再从零开始推理。
这比在团队 Wiki 里写文档更好用，因为它不是给人看的，而是给 AI 执行用的，颗粒度精确到操作步骤。
6. 用久了你才会发现的坑：Superpowers 的副作用
最后这部分，是我用了大半年之后才慢慢意识到的问题。开箱技能很好，但如果不加节制，它会带来一些反直觉的副作用。
6.1 技能过度调用，反而拖慢速度
技能文件加载是有代价的：Claude 每加载一个技能，都要消耗一次工具调用，且正文越长，上下文占用越多。如果描述写得过于宽泛，Claude 可能在简单任务里也强加载技能，结果一个“帮我把变量重命名”的小需求，也要先走一遍 refactoring 的完整流程。
我的解法是：把重技能拆出轻量版本。比如 refactoring 保留给大规模重构，常见小改动直接用普通对话让它处理，不强制挂载技能。
6.2 技能与 CLAUDE.md 的规则可能打架
我遇到过最典型的一次：Claude 已经加载了 running-tests-getting-coverage 技能，技能要求全量跑测试并输出覆盖率；但项目 CLAUDE.md 里明确写了“修改期间只运行相关用例，不要全量测试”。两者冲突时，Claude 夹在中间，行为变得摇摆不定。
这种时候需要在 CLAUDE.md 里明确技能的使用边界，比如：“运行测试时遵循技能流程，但最终以本文件的指令为准”，给项目规范的权威性兜底。
6.3 更新 vs 自定义内容：目录覆盖风险
Superpowers 仓库更新频率不低，有些版本在更新时会把整个 skills 目录重新同步。如果你把自己的自定义技能也放在同一个全局目录下，更新脚本可能直接覆盖同名文件。即使不同名，也建议把自定义技能放到~/.claude/skills/custom/这样的独立子目录，或者干脆用项目级技能目录做隔离，避免被同步脚本误伤。
6.4 我会禁用的技能和改写思路
我实际禁用了 creating-technical-design-docs，因为它产出的设计文档偏“工程八股”，对我们团队流水线式开发来说太重。我更常把它改成轻量版：只输出目标、改动点、风险、测试方案四段式。
我的经验是：Superpowers 不是圣旨，它是一个模板库。你消化完它的方法论后，完全可以裁剪成符合自己团队节奏的版本。禁用不丢人，盲抄才危险。
用 Superpowers 这段时间，我最深的体会是：它真正改的不是 Claude 的能力，而是“AI 干活的方式”。以前我总是在对话里反复铺垫“请按以下步骤来”，现在这些步骤沉淀成了文件，反而把提示词释放了。如果你还没用过，建议从 reviewing-code 和 analyzing-failures 这两个技能开始，跑一个真实的 MR 审查和一次真实的 CI 失败排查，你会立刻感受到“有工作手册的 AI 和没有工作手册的 AI”之间的差别。
