1. 先搞清楚“superpowers”到底指什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是漫威电影里的超能力或者某个游戏里的技能系统。但如果你是在技术社区、开源项目或者开发工具语境下看到它那大概率说的不是超能力而是一个面向 AI 编程助手的能力扩展框架。我最早接触到这个概念是在折腾 Claude Code 的时候社区里有人提到“装上 superpowers 之后整个编码体验完全不一样了”。当时我第一反应是这又是什么花里胡哨的插件后来实际用了一段时间才发现它解决的痛点非常具体。简单来说superpowers 是一套给 AI 编程助手“加装技能”的机制。你可以把它理解成给一个原本只会通用对话的助手装上了一本本“专项操作手册”——需要写测试的时候它知道该按什么流程走需要做代码审查的时候它知道该检查哪些维度需要规划一个复杂功能的时候它知道该怎么拆解任务。这些“手册”就是所谓的 skills技能而 superpowers 就是管理、加载、触发这些技能的框架。它适合什么人如果你只是偶尔让 AI 帮你写个正则表达式、解释一段报错那可能感受不明显。但如果你是那种每天有大量时间在和 AI 编程助手协作的人——比如用它来重构模块、写单元测试、做代码审查、规划新功能——那 superpowers 带来的效率提升是肉眼可见的。它把“你每次都要手动告诉 AI 该怎么做”变成了“AI 自己知道该怎么做”。我写这篇东西的目的不是复述官方文档而是把我从零开始安装、配置、踩坑、调优的完整过程拆开来讲。网上关于 superpowers 的中文资料不算多很多人在搜索“想要安装 superpowers”的时候找到的要么是英文 README要么是零散的片段。我尽量把每一步都讲清楚包括那些文档里不会写的坑。2. 为什么需要给 AI 助手“装技能”2.1 通用助手的天然短板AI 编程助手有个很有意思的特点它什么都懂一点但在具体任务上往往不够“专业”。你让它写一个函数它能写你让它做代码审查它也能说几句你让它规划一个重构方案它也能给个大概。但问题在于它每次都是“从零开始思考”没有一个固定的、经过验证的工作流程。举个例子。你让 AI 帮你写单元测试它可能会直接开始写test_xxx函数但一个有经验的工程师写测试是有套路的先看被测函数的边界条件再考虑正常路径和异常路径然后决定用 mock 还是真实依赖最后才动手写。AI 如果没有被明确引导往往会跳过前面的分析步骤直接跳到写代码结果就是测试覆盖不全、边界情况遗漏。superpowers 的核心思路就是把这些“套路”固化下来变成可复用的技能模块。当你的请求匹配到某个技能时框架会自动加载对应的操作指南AI 就会按照那个指南的流程来工作。这就像给一个新员工一本《测试编写规范》他照着做质量就比自由发挥稳定得多。2.2 技能机制背后的设计逻辑我研究了一下 superpowers 的技能加载机制它的设计其实挺巧妙的。每个 skill 本质上是一个结构化的文档里面定义了这个技能什么时候触发、触发后应该按什么步骤执行、每一步的输入输出是什么、有哪些注意事项。这种设计的好处是可组合。比如你要做一个“添加新 API 端点”的任务它可能同时触发“代码规划”技能和“测试编写”技能两个技能的流程会叠加在一起形成一个完整的操作链。这比你在一个巨大的 prompt 里把所有要求都写一遍要清晰得多也更容易维护——改一个技能不影响其他技能。另一个好处是可验证。因为每个技能都有明确的步骤定义你可以检查 AI 是不是真的按流程走了。如果它跳过了某一步你能很快发现。这在做代码审查或者复杂重构的时候特别有用因为那些任务最怕的就是“漏掉关键环节”。2.3 和直接写长 prompt 的区别你可能会问我直接写一个很长的 system prompt把所有要求都塞进去不也能达到类似效果吗理论上可以但实际用起来差别很大。首先长 prompt 会占用大量上下文窗口而且随着你加的规则越来越多AI 对每条规则的注意力会被稀释。其次长 prompt 很难维护改一处可能影响另一处。最重要的是长 prompt 是“静态”的——不管你当前在做什么任务它都在那里。而 superpowers 的技能是“动态”的只在需要的时候才加载不相关的技能不会干扰当前任务。我自己的体感是用长 prompt 的时候AI 有时候会“过度遵守”某些规则在不该用的时候也套用而用技能机制触发条件更精确行为也更符合预期。3. 安装前的环境准备与依赖梳理3.1 确认你的运行环境在动手安装之前有几件事需要先确认清楚。superpowers 本身不是一个独立运行的软件它是依附于某个 AI 编程助手环境运行的。目前最常见的搭配是 Claude Code所以你需要先确保 Claude Code 已经能正常工作。具体来说你需要确认这几点你的操作系统是什么macOS、Linux、Windows 的安装路径和命令会有差异Node.js 版本是否满足要求一般需要 18 以上npm 或 yarn 是否可用以及你的 Claude Code 是否已经完成基础配置并能正常对话。我建议在安装 superpowers 之前先跑一个简单的测试让 Claude Code 帮你写一个 hello world 函数确认整个链路是通的。如果这一步就有问题那先解决基础环境不要急着装扩展。3.2 目录结构要提前规划这是很多人容易忽略的一点。superpowers 的技能文件需要放在特定的目录下而不同版本的 Claude Code 对目录位置的要求可能不一样。常见的位置包括用户主目录下的.claude文件夹或者项目根目录下的.claude文件夹。我的建议是先搞清楚你的 Claude Code 是从哪个目录读取配置的。你可以通过查看官方文档或者直接在 Claude Code 里问它“你的配置文件在哪个目录”来确认。确认之后再决定是把 superpowers 装在全局所有项目都能用还是项目级只在当前项目生效。全局安装的好处是省事装一次到处能用坏处是如果你同时在做多个不同类型的项目技能可能会互相干扰。项目级安装更干净但每个新项目都要重新配一遍。我个人的做法是常用的通用技能装在全局项目特有的技能放在项目目录里。3.3 网络与权限的注意事项安装过程中需要从代码仓库拉取文件所以网络要能正常访问。另外如果你用的是公司电脑或者有严格权限管理的环境可能需要确认是否有写入目标目录的权限。还有一个细节有些技能文件可能包含可执行脚本安装后需要赋予执行权限。这个在 Linux 和 macOS 上尤其要注意Windows 上一般不需要额外处理。提示如果你在安装过程中遇到权限报错先不要急着用管理员权限强行执行。先检查目标目录的归属和权限设置很多时候问题出在目录本身而不是命令上。4. 一步步完成 superpowers 的安装4.1 获取安装源superpowers 的安装方式通常有两种一种是通过包管理器直接安装另一种是从代码仓库克隆。具体用哪种取决于你使用的 AI 助手环境和 superpowers 的当前版本。如果你用的是支持插件市场的环境那最简单的方式是在市场里搜索 superpowers然后点击安装。这种方式的好处是版本管理和更新都比较省心。如果市场里没有那就需要手动克隆仓库。手动克隆的命令大致是这样的git clone superpowers-repo-url ~/.claude/skills/superpowers注意这里的路径~/.claude/skills/是示例你需要根据自己环境的实际配置来调整。克隆完成后检查一下目录里是否有SKILL.md或者类似的技能定义文件。如果有说明拉取成功。4.2 配置技能加载路径克隆完之后还需要告诉 Claude Code 去哪里找这些技能。这一步通常是通过修改配置文件来实现的。配置文件可能是一个 JSON 文件也可能是一个 Markdown 文件具体取决于你的环境版本。配置的核心内容是添加一个技能目录的路径。比如{ skills: { directories: [ ~/.claude/skills/superpowers ] } }改完配置后需要重启 Claude Code 或者重新加载配置才能生效。我建议每次改完配置都重启一次避免出现“改了但没生效”的困惑。4.3 验证安装是否成功怎么确认 superpowers 真的装好了最直接的方法是问 Claude Code“你现在有哪些可用的技能”如果安装成功它应该能列出一串技能名称比如“代码规划”“测试编写”“代码审查”之类的。如果它说“没有可用技能”或者列出的技能为空那说明配置有问题。这时候按以下顺序排查先确认技能目录路径是否正确再确认目录里确实有技能定义文件然后确认配置文件格式没有语法错误最后确认 Claude Code 是否真的读取了你修改的那个配置文件。我遇到过一种情况配置文件改了但 Claude Code 读的是另一个位置的同名文件。这种问题很隐蔽解决办法是在配置文件里加一个明显的测试技能看它能不能被识别到。4.4 首次触发的体验安装成功后你可以试着做一个简单任务来感受技能触发。比如让 Claude Code 帮你“给这个函数写单元测试”。如果 superpowers 正常工作你应该能观察到它的行为模式和之前不一样——它可能会先分析函数的输入输出再列出测试用例最后才写代码而不是一上来就写test_函数。这个“行为模式的变化”就是判断技能是否生效的最好标志。如果它还是老样子直接写代码那可能是技能没有被正确触发需要检查触发条件是否匹配。5. 核心技能模块的实操解析5.1 代码规划技能的使用要点代码规划是我用得最多的一个技能。它的作用是在你开始写代码之前先帮你把任务拆解清楚。触发方式通常是你说“帮我规划一下这个功能的实现”或者“这个重构该怎么做”。触发后它会引导 AI 按几个步骤走先理解需求边界再识别受影响的模块然后列出实现步骤最后评估风险和依赖。这个过程看起来简单但实际用下来它能显著减少“写到一半发现方向错了”的情况。我印象比较深的一次是重构一个订单处理模块。原本我打算直接让 AI 开始改代码但触发了规划技能后它先问了我几个问题这个模块有哪些外部依赖有没有正在运行的定时任务会受影响数据库 schema 需要改吗这些问题我原本没想清楚被问完之后才发现有几个隐藏的耦合点如果直接改代码肯定会出问题。注意规划技能的输出不是最终代码而是一个执行计划。你需要审查这个计划确认没问题后再让它按计划执行。不要跳过审查这一步。5.2 测试编写技能的触发与调优测试编写技能的默认行为是先分析被测代码的边界条件然后生成测试用例列表最后写测试代码。这个流程比直接写测试要慢一些但覆盖率高很多。我实测下来有几个调优点值得注意。第一如果你已经有一些测试规范或者命名约定可以在项目配置里告诉它这样生成的测试风格会更一致。第二对于特别复杂的函数可以分多次触发每次只覆盖一部分边界条件避免一次生成太多测试导致质量下降。第三生成完测试后一定要实际跑一遍因为 AI 有时候会假设一些不存在的 mock 方法。还有一个坑如果你的项目用的是特定的测试框架比如 Jest、Pytest、JUnit需要在配置里明确指定否则它可能按默认框架生成你还得手动改。5.3 代码审查技能的检查维度代码审查技能是我觉得最有价值的一个。它不只是简单地说“这段代码看起来不错”而是会按多个维度来检查逻辑正确性、边界处理、错误处理、性能隐患、可读性、安全性。每个维度下它都会给出具体的发现和建议。比如在错误处理维度它会指出哪些地方没有捕获异常哪些地方的错误信息不够明确。在性能维度它会标出可能的 N1 查询、不必要的循环嵌套、大对象拷贝等问题。我用它审查过一个数据处理脚本它发现了一个我完全没注意到的问题在处理空数组时代码会进入一个无限循环。这个问题在正常数据下不会暴露但一旦输入为空就会卡死。如果没有审查技能这个 bug 可能要等到线上出问题才会被发现。5.4 技能组合使用的实际案例单独用一个技能已经能提升效率了但真正厉害的是组合使用。我举一个实际案例给一个已有的 REST API 添加一个新的端点。这个任务触发了三个技能规划技能先拆解任务识别出需要改路由文件、控制器、服务层、数据模型和测试然后测试编写技能先写测试测试驱动的方式最后代码审查技能检查生成的代码。整个流程下来我只需要在关键节点做确认大部分机械性工作都由 AI 按技能流程完成了。而且因为每个环节都有明确的检查点最终代码的质量比我之前直接让 AI 写要高不少。6. 常见问题与排查技巧实录6.1 技能不触发怎么办这是最常见的问题。你明明装了技能但 AI 的行为没有任何变化。排查思路如下首先确认技能是否真的被加载了。问 AI“列出可用技能”如果列表为空说明加载环节有问题。检查配置文件路径、目录权限、文件格式。如果技能列表里有但特定任务不触发那可能是触发条件不匹配。每个技能都有触发关键词或场景描述你可以试着用更明确的表述。比如“帮我写测试”可能不如“用测试编写技能帮我给这个函数写单元测试”来得直接。还有一种情况是技能之间有冲突。比如两个技能都匹配当前请求框架可能只加载了其中一个。这时候可以手动指定要用哪个技能。6.2 技能输出质量不稳定的处理有时候技能触发了但输出质量时好时坏。这通常和上下文有关。如果当前对话已经很长或者上下文里有很多不相关的信息技能的流程可能会被打乱。我的做法是对于重要任务开一个新的对话窗口只放必要的上下文然后触发技能。这样输出质量会稳定很多。另外如果技能有配置项检查一下配置是否合理。比如测试编写技能如果配置的测试框架和项目实际用的不一致输出就会有问题。6.3 安装后原有功能受影响的恢复有少数情况下安装 superpowers 后Claude Code 的某些原有行为会发生变化。比如原本直接回答的问题现在会先走一遍技能流程导致响应变慢。如果遇到这种情况可以先检查是不是某个技能的触发条件太宽泛了。比如一个“代码规划”技能如果触发词设置成“代码”那几乎任何和代码相关的请求都会触发它这显然不合理。解决办法是调整触发条件让它更精确。如果确认是技能冲突导致的可以临时禁用部分技能只保留最常用的几个。等熟悉了之后再逐步开启。6.4 常见问题速查表问题现象可能原因排查步骤解决方式技能列表为空配置路径错误检查配置文件中的技能目录路径修正路径并重启技能不触发触发条件不匹配查看技能定义中的触发关键词用更明确的表述重新请求输出质量差上下文过长或干扰多检查当前对话历史开新对话精简上下文响应变慢技能触发过于频繁查看哪些技能被触发调整触发条件或禁用部分技能测试框架不匹配配置未指定框架检查技能配置项在配置中指定项目使用的框架权限报错目录权限不足检查目标目录归属调整权限或更换安装目录6.5 几个我踩过的坑第一个坑是路径中的波浪号。在配置文件里写~/.claude/skills有时候不会被正确解析尤其是当 Claude Code 以服务方式运行时。解决办法是写绝对路径比如/Users/yourname/.claude/skills。第二个坑是技能文件编码。有些技能文件如果包含中文注释在某些环境下会出现乱码导致解析失败。建议统一用 UTF-8 编码保存。第三个坑是版本不兼容。superpowers 的不同版本可能对 Claude Code 的版本有要求。如果你装完发现各种奇怪问题先检查一下版本兼容性。通常官方文档里会有一个兼容性表格花两分钟看一下能省很多时间。第四个坑是过度依赖技能。有一段时间我什么任务都想触发技能结果发现简单任务反而变慢了。后来我调整了策略只有复杂任务才用技能简单任务直接让 AI 处理。这个平衡点需要自己摸索没有统一标准。7. 让 superpowers 真正融入日常工作流装好只是第一步真正产生价值是在日常工作中持续使用。我的建议是先从一两个最常用的技能开始比如代码审查和测试编写用熟之后再逐步扩展。不要一上来就把所有技能都打开那样反而容易混乱。另外定期回顾一下技能的使用情况。哪些技能你从来没用过哪些技能的触发太频繁了根据实际使用情况做调整让技能集合越来越贴合你的工作习惯。这个过程本身就是一种效率优化。最后分享一个小技巧你可以把自己常用的操作流程写成自定义技能。superpowers 的技能格式是开放的你完全可以照着现有技能的模板写一个适合自己项目的技能。比如你们团队有特定的代码提交规范就可以写一个“提交前检查”技能让 AI 在提交前自动按规范检查一遍。这个自定义的过程才是 superpowers 真正发挥威力的地方。