1. 从“superpowers”这个热词说起它到底指什么最近“superpowers”这个词在技术圈和效率工具圈里被反复提起很多人第一次看到它是在某个开源项目的讨论区或者是在朋友分享的终端截图里。简单来说superpowers 是一套面向 AI 编程助手的能力扩展框架它的核心思路是给原本只会“聊天”的 AI 助手装上一整套可复用的技能包让它在真实的软件开发流程里真正能干活——写代码、跑测试、做代码审查、管理 Git 分支、生成文档甚至帮你规划一个完整的功能迭代。我第一次接触这个概念的时候直觉反应是“又是一个包装壳”但实际用下来发现它解决的问题非常具体大多数 AI 编程工具在单轮对话里表现不错一旦涉及多步骤、跨文件、需要验证的工程任务就会开始丢上下文、跳步骤、忘记约束。superpowers 做的事情就是把这些工程任务拆解成结构化的“技能”每个技能有明确的触发条件、执行步骤和验证标准AI 助手在需要的时候自动加载对应的技能按流程走完。这套东西适合谁如果你只是偶尔让 AI 帮你写个正则表达式、解释一段报错那暂时用不上。但如果你正在用 AI 助手做实际的项目开发——比如让它帮你实现一个完整的 API 接口、重构一个模块、或者搭建一套测试体系——那 superpowers 带来的效率提升会非常明显。它把“跟 AI 聊天”变成了“跟 AI 协作”这个区别很大。关键词里提到的“想要安装 superpowers”说明很多人已经意识到这套框架的价值但卡在了第一步。安装本身不复杂但有几个前置条件和配置细节容易踩坑后面我会详细拆解。2. superpowers 的核心机制技能包是怎么工作的2.1 技能即文件一切从 Markdown 开始superpowers 最让我欣赏的一个设计决策是所有技能都以纯 Markdown 文件的形式存在。这意味着你不需要学任何新的 DSL、不需要写 YAML 配置、不需要理解复杂的插件 API。一个技能就是一个.md文件里面用自然语言描述这个技能是干什么的、什么时候触发、执行步骤是什么、有什么注意事项。这种设计的聪明之处在于它把“扩展 AI 能力”这件事的门槛降到了最低。你想想传统的插件开发是什么流程读文档、学 API、写代码、调试、打包、发布。而 superpowers 的技能开发是什么流程新建一个 Markdown 文件用你平时跟同事交代任务的方式把步骤写清楚保存完事。我实测下来写一个可用的技能文件大概只需要 10 到 15 分钟前提是你对这个任务本身的流程足够熟悉。比如我写过一个“数据库迁移检查”的技能内容就是列出迁移前必须确认的五个事项、迁移执行的命令模板、以及迁移后的验证步骤。写完之后AI 助手在执行数据库相关任务时会自动参考这个技能按照我定义的流程走不会再出现“忘了备份”或者“跳过回滚测试”这类问题。2.2 触发机制AI 怎么知道该用哪个技能这是很多人好奇的点技能文件放在那里AI 助手怎么知道什么时候该调用哪个superpowers 的触发机制基于语义匹配加显式声明的组合。每个技能文件的头部会有一段元信息描述这个技能适用的场景。比如一个“代码审查”技能会写明“当用户要求审查代码、检查 PR、或者提到 code review 时触发”。AI 助手在处理你的请求时会先做一次意图识别判断当前任务属于哪个类别然后去技能库里找匹配的技能。但这里有个细节值得注意语义匹配不是万能的。我遇到过几次情况任务本身跨了好几个领域AI 助手选了一个不太相关的技能导致执行流程跑偏。后来我的做法是在技能文件的描述里尽量用具体的动词和场景词避免模糊表述。比如不要写“处理代码相关任务”而是写“当用户要求重构函数、提取公共逻辑、或者消除重复代码时触发”。越具体匹配越准。另外superpowers 支持手动指定技能。如果你明确知道当前任务该用哪个技能可以直接在对话里点名比如“用 TDD 技能来实现这个功能”。这种方式在复杂任务里特别有用因为你可以精确控制 AI 的执行路径。2.3 技能的组合与嵌套11 大于 2单个技能已经能解决很多问题但 superpowers 真正强大的地方在于技能可以组合和嵌套。举个例子我有一个“功能开发”技能它的执行流程里会依次调用“需求澄清”技能、“测试编写”技能、“实现”技能和“代码审查”技能。这四个子技能各自独立但组合在一起就形成了一条完整的开发流水线。这种嵌套结构的好处是复用性极高。比如“代码审查”技能不仅可以被“功能开发”调用还可以被“Bug 修复”技能调用也可以单独触发。你不需要为每个场景重新写一遍审查流程只需要在需要的地方引用同一个技能文件。我在实际项目里搭过一条比较完整的链路从需求分析开始到接口设计、测试用例编写、代码实现、静态检查、最后到文档更新一共串了七个技能。跑通之后AI 助手处理一个中等复杂度的功能需求从开始到提交 PR中间几乎不需要我干预。当然前提是需求描述足够清晰这个后面会细说。3. 安装 superpowers 前必须搞清楚的三件事3.1 你的 AI 助手支持技能扩展吗这是最容易被忽略的前置条件。superpowers 本身是一个框架它需要宿主环境提供技能加载和调用的能力。目前主流的几类 AI 编程助手对技能扩展的支持程度不一样有的原生支持有的需要通过配置文件开启有的完全不支持。你在安装之前先确认你用的工具是否在支持列表里。怎么确认最简单的办法是看你的 AI 助手有没有“自定义指令”“技能库”“插件”这类功能入口。如果有大概率可以接入 superpowers。如果没有那可能需要先升级工具版本或者换一个支持扩展的助手。我踩过的一个坑是在一个不支持技能扩展的旧版本上折腾了半天各种配置文件改了又改最后发现根本加载不了。所以第一步一定是确认宿主环境的能力别急着下载技能包。3.2 技能文件的存放路径有讲究superpowers 的技能文件需要放在特定的目录下才能被正确加载。不同的宿主环境对路径的要求不一样但通常遵循一个约定项目根目录下的.superpowers/skills/文件夹或者用户主目录下的全局技能目录。项目级技能和全局技能的区别在于作用范围。项目级技能只对当前项目生效适合那些跟项目技术栈强相关的技能比如“使用项目特定的 ORM 框架”或者“遵循本项目的代码规范”。全局技能对所有项目生效适合通用性强的技能比如“Git 提交信息规范”或者“代码审查通用流程”。我的建议是先把通用技能放在全局目录项目特有的技能放在项目目录。这样既保证了通用能力的复用又避免了项目之间的技能污染。另外技能文件的命名最好用英文小写加连字符比如code-review.md、tdd-workflow.md避免中文名或者空格减少加载时的兼容性问题。3.3 版本兼容性别让技能包和宿主打架superpowers 的技能文件格式在不同版本之间可能会有细微变化。比如早期版本可能不支持技能之间的嵌套引用新版本才加入了这个能力。如果你从网上直接下载了一个技能包而你的宿主环境版本比较旧可能会出现技能加载失败或者执行异常的情况。我的做法是先看技能包里的 README 或者版本说明确认它要求的最低宿主版本。如果没有说明就先拿一个最简单的技能文件做测试跑通了再批量导入。另外技能文件里的语法尽量用最基础的 Markdown避免使用宿主可能不支持的扩展语法比如自定义标签或者复杂的嵌套列表。还有一个细节有些技能文件会引用外部脚本或者命令。如果你的运行环境里没有对应的工具技能执行到那一步就会卡住。所以在导入技能之前先扫一眼技能文件里有没有依赖外部命令提前把环境准备好。4. 手把手安装与配置从零到跑通第一个技能4.1 获取技能包的几种途径superpowers 的技能包来源主要有三种。第一种是官方维护的基础技能集包含最常用的十几个技能比如代码审查、测试驱动开发、Git 工作流、文档生成等。这套技能包的质量最稳定建议作为起点。第二种是社区贡献的技能包。GitHub 上有很多人分享自己写的技能覆盖了各种细分场景比如“React 组件开发规范”“Python 类型注解检查”“数据库迁移安全流程”等。社区技能包的质量参差不齐用之前最好先读一遍技能文件的内容确认逻辑合理再导入。第三种是自己写。前面说过写技能文件的门槛很低如果你有某个特定的工作流程想固化下来自己写一个是最合适的。我自己的技能库里有一半是社区下载的一半是自己写的后者往往更贴合我的实际工作习惯。获取技能包之后通常是一个压缩包或者一个 Git 仓库。解压或者克隆下来你会看到一堆.md文件每个文件就是一个技能。有些技能包还会附带一个manifest.json或者index.md列出了所有技能的名称和用途方便你快速了解。4.2 目录结构与初始化配置假设你选择的是项目级技能操作步骤如下。首先在项目根目录下创建.superpowers/skills/文件夹。然后把技能文件复制进去。注意保持文件的目录结构如果技能包里有子目录比如skills/git/commit.md复制的时候也要保持同样的层级。接下来是初始化配置。大多数宿主环境需要一个配置文件来告诉它技能库的位置。这个配置文件通常叫.superpowers/config.json或者类似的名字放在项目根目录下。配置内容一般包括技能目录的路径、是否启用自动触发、以及一些全局参数。一个典型的配置长这样{ skillsDir: .superpowers/skills, autoTrigger: true, maxConcurrentSkills: 3, logLevel: info }autoTrigger控制是否允许 AI 助手自动匹配技能。如果你希望完全手动控制把它设为false这样只有你明确点名的时候才会加载技能。maxConcurrentSkills限制同时激活的技能数量设太大可能会导致上下文混乱一般 3 到 5 个比较合适。配置完成后重启你的 AI 助手或者重新加载项目让配置生效。有些宿主环境支持热加载改完配置直接生效不需要重启。这个因工具而异第一次配置的时候建议重启一下确保万无一失。4.3 验证安装跑通第一个技能安装完成之后怎么确认技能已经正确加载了最直接的办法是手动触发一个技能看 AI 助手的反应。选一个最简单的技能来测试比如“代码审查”。在对话里输入“请用代码审查技能检查这段代码”然后贴一段有明显问题的代码。如果技能加载成功AI 助手的回复应该会遵循技能文件里定义的审查流程比如先检查命名规范再检查逻辑漏洞最后给出修改建议。如果它只是泛泛地回复了几句没有按照结构化流程走那说明技能没有生效。另一个验证方法是查看日志。大多数宿主环境会在日志里记录技能加载的情况。你可以在配置里把logLevel设为debug然后看日志里有没有“skill loaded: code-review”之类的信息。如果有说明技能文件被正确识别了。我第一次配置的时候技能文件放对了位置但配置文件里的路径写错了导致加载失败。排查了半天才发现是路径多了一层目录。所以验证的时候一定要仔细看日志别凭感觉猜。4.4 常见安装报错与排查思路安装过程中最常见的报错有三类。第一类是文件编码问题。技能文件如果是 GBK 编码而宿主环境按 UTF-8 读取中文内容会变成乱码导致技能描述无法被正确解析。解决办法很简单把所有技能文件统一转成 UTF-8 编码。第二类是权限问题。在某些系统上技能目录的读写权限不够导致宿主无法读取文件。检查一下目录权限确保当前用户有读取和执行权限。第三类是版本不匹配。技能文件里用了新版本才支持的语法旧版本宿主解析不了。这种情况要么升级宿主要么把技能文件里的新语法改成兼容写法。排查的时候建议从最简单的技能文件开始一个一个加每加一个测试一次。这样出问题的时候能快速定位是哪个文件导致的比一次性导入所有技能再排查要高效得多。5. 让 superpowers 真正好用的几个关键习惯5.1 技能描述要具体别写“正确的废话”我见过很多技能文件描述写得像教科书目录“本技能用于提高代码质量”“帮助开发者更好地完成任务”。这种描述对 AI 助手来说几乎没有信息量触发匹配的时候很容易被忽略或者误匹配。好的技能描述应该像这样“当用户要求审查 Pull Request、检查代码变更、或者提到代码审查时触发。执行步骤包括检查命名规范、检查错误处理、检查边界条件、检查测试覆盖、生成审查报告。”具体、有动词、有明确的触发场景和执行步骤。我自己的经验是技能描述里的触发条件最好用“当……时”的句式执行步骤用有序列表注意事项用引用块标注。这样 AI 助手解析起来最顺畅执行的时候也不容易漏步骤。5.2 控制技能粒度太粗和太细都不好技能粒度是个需要反复调整的事情。太粗的技能比如“开发功能”里面塞了二十个步骤AI 助手执行到一半可能就丢了上下文。太细的技能比如“给变量命名”又过于琐碎触发频率太高反而干扰正常流程。我的经验值是一个技能包含 3 到 7 个核心步骤比较合适。如果超过 7 个考虑拆成两个技能用嵌套的方式组合。如果少于 3 个考虑合并到相邻的技能里。举个例子“测试驱动开发”这个技能我拆成了三个子技能“写失败测试”“实现最小通过代码”“重构”。每个子技能 3 到 4 个步骤组合起来形成完整的 TDD 流程。这样既保证了每个技能的清晰度又保留了流程的完整性。5.3 定期清理和迭代技能库技能库不是建好就一劳永逸的。随着项目演进和个人习惯变化有些技能会过时有些技能需要调整。我一般每个月花半个小时过一遍技能库做三件事删掉不再使用的技能、更新描述和步骤有变化的技能、把反复手动执行的操作固化成新技能。这个习惯带来的复利效应很明显。半年下来我的技能库从最初的 5 个技能扩展到了 20 多个覆盖了日常开发中 80% 以上的重复性流程。AI 助手在这些流程上的表现越来越稳定我花在“纠正 AI 行为”上的时间越来越少。还有一个技巧给技能文件加版本号和更新日期。比如在文件头部写version: 1.2, updated: 2025-01-15。这样你能快速判断一个技能是不是最新的避免用到过时的流程。6. 实战场景superpowers 在真实项目里怎么用6.1 场景一从需求到 PR 的完整流水线这是我用得最多的场景。假设产品提了一个需求“用户列表页面增加按注册时间筛选的功能”。我把需求描述丢给 AI 助手然后触发“功能开发”技能。技能执行流程是这样的首先调用“需求澄清”子技能AI 助手会问我几个问题比如“筛选是精确到日还是精确到秒”“默认排序是什么”“分页大小是否变化”。我回答完之后进入“接口设计”子技能AI 助手生成接口定义和参数说明。确认无误后进入“测试编写”子技能生成单元测试和集成测试。然后是“实现”子技能生成具体的代码变更。最后是“代码审查”子技能AI 助手自己审查一遍生成的代码检查有没有遗漏的边界条件。整个流程跑下来我只需要在需求澄清和接口设计两个环节做决策后面的步骤基本是自动的。一个中等复杂度的功能从开始到生成可提交的 PR大概 20 到 30 分钟。如果没有这套技能同样的功能我可能需要跟 AI 助手来回对话几十轮中间还要自己检查有没有漏掉步骤。6.2 场景二Bug 修复的标准化流程Bug 修复是另一个高频场景。我的“Bug 修复”技能包含五个步骤复现问题、定位根因、编写回归测试、修复代码、验证修复。触发技能后AI 助手会先要求我提供复现步骤。如果我没有现成的复现步骤它会根据错误日志和代码上下文尝试推断。定位根因环节它会分析相关代码路径列出可能的根因并按可能性排序。编写回归测试环节它会生成一个能复现 Bug 的测试用例确保修复之前测试是失败的。修复代码环节它会给出具体的修改建议。最后验证环节它会跑一遍测试确认回归测试通过且没有引入新的失败。这个流程最大的价值在于防止“修一个 Bug 引入两个新 Bug”。回归测试这个环节强制存在AI 助手不会跳过。我实测下来用了这个技能之后修复引入的回归问题减少了大概七成。6.3 场景三代码审查的自动化代码审查技能是我用得最频繁的。每次提交 PR 之前我都会先让 AI 助手用这个技能过一遍。审查内容包括命名规范、错误处理、边界条件、测试覆盖、性能隐患、安全风险。审查结果会以结构化的形式输出每个问题标注严重程度阻塞、警告、建议和具体位置。我一般会先处理阻塞级别的问题然后根据时间决定是否处理警告和建议级别的问题。这个技能的一个细节设计是它会区分“必须修改”和“可以讨论”。比如命名不规范属于必须修改但某个实现方式的选择属于可以讨论。这样我在处理审查意见的时候有明确的优先级不会在无关紧要的问题上浪费时间。7. 踩过的坑与对应的解决方案7.1 技能冲突两个技能同时触发怎么办这是实际使用中最常见的问题。比如我同时有“代码审查”技能和“安全审查”技能当我说“审查这段代码”的时候两个技能都可能被触发导致 AI 助手的回复里混杂了两套流程看起来很乱。解决方案有两种。第一种是在技能描述里明确区分触发条件。比如“代码审查”技能的触发条件写成“当用户要求审查代码质量、命名规范、逻辑正确性时触发”而“安全审查”技能的触发条件写成“当用户要求检查安全漏洞、注入风险、权限问题时触发”。这样语义匹配的时候就能区分开。第二种是设置技能优先级。在技能文件的元信息里加一个priority字段数值高的优先触发。当两个技能都匹配的时候只执行优先级高的那个。这个方案适合那些确实有重叠但你又不想合并的技能。我自己的做法是两种结合能区分触发条件的就区分区分不了的就设优先级。目前技能库里大概有 3 组技能设置了优先级运行下来没有再出现过冲突。7.2 上下文丢失长流程执行到一半忘了前面superpowers 的技能执行是有状态的尤其是嵌套技能执行链路可能很长。我遇到过几次情况一个包含五个子技能的功能开发流程执行到第四个的时候AI 助手忘了第一个子技能里确认过的需求细节。这个问题的根源是上下文窗口有限。技能执行过程中产生的中间结果如果太多早期的信息可能会被挤出上下文。解决方案是在技能文件里显式要求“在每个子技能开始时回顾并确认前置条件”。比如“实现”子技能的开头加一句“在开始实现之前先回顾需求澄清和接口设计的结论确认没有遗漏。”另一个技巧是把关键决策点记录下来。我在技能文件里加了一个“决策日志”的步骤每个子技能结束时把关键决策写到一个临时文件里。后续子技能执行时先读这个文件确保信息不丢失。这个做法稍微增加了复杂度但在长流程里非常有效。7.3 技能不生效明明加载了却没触发有时候技能文件明明放在目录里日志也显示加载成功了但实际对话的时候就是不触发。这种情况通常有三个原因。第一个原因是触发条件写得太窄。比如技能描述里写“当用户输入‘请审查代码’时触发”但用户实际说的是“帮我看看这段代码有没有问题”语义匹配不上。解决办法是把触发条件写宽一点覆盖常见的表达方式。第二个原因是技能被其他技能屏蔽了。如果两个技能的触发条件高度重叠优先级低的那个可能永远不会被触发。检查一下技能库里的优先级设置确保没有意外的屏蔽。第三个原因是宿主环境的自动触发开关没打开。前面提到过autoTrigger配置如果设成了false技能只能手动触发。检查一下配置文件确认这个开关的状态。排查的时候我一般先把logLevel调到debug然后发一条测试消息看日志里有没有技能匹配的记录。如果没有匹配记录说明触发条件有问题如果有匹配记录但技能没执行说明执行环节有问题。这样能快速缩小排查范围。7.4 性能问题技能太多导致响应变慢技能库大了之后每次对话的响应时间可能会变长。因为 AI 助手需要在更多的技能里做语义匹配匹配的计算量增加了。我实测下来技能数量从 10 个增加到 30 个的时候首次响应时间大概增加了 1 到 2 秒。这个延迟在可接受范围内但如果你觉得影响体验有几个优化方向。一是按项目拆分技能库只加载当前项目需要的技能而不是把所有技能都放在全局目录。二是定期归档不常用的技能把它们移到一个archived目录里需要的时候再移回来。三是优化技能描述去掉冗余信息让语义匹配更快。我目前的做法是全局技能保持在 15 个以内项目级技能按需加载。这样既保证了通用能力的覆盖又控制了匹配的计算量。8. 关于 superpowers 的一些个人体会用了一年多 superpowers最大的感受是它改变了我跟 AI 助手协作的方式。以前是我追着 AI 跑它跑偏了我拉回来它漏了步骤我补上。现在是我定好流程AI 按流程执行我只在关键决策点介入。这个转变带来的效率提升不是线性的而是结构性的。另一个体会是技能库的质量比数量重要得多。我见过有人收集了几百个技能但常用的就那么几个大部分技能从来没被触发过。与其追求数量不如把常用的几个技能打磨好让它们真正贴合你的工作习惯。还有一点不要指望技能能解决所有问题。superpowers 擅长的是流程固化和步骤标准化它不能替代你的技术判断和业务理解。需求是否合理、架构是否合适、方案是否最优这些还是得你自己想。技能只是帮你把想好的事情执行得更稳定、更一致。最后分享一个小技巧每次手动重复一个操作超过三次就考虑把它写成技能。这个规则帮我积累了不少实用的技能也让我对日常工作的流程有了更清晰的认知。写技能的过程本身就是一次流程梳理和优化的机会。