1. 从“superpowers”这个热词说起它到底是什么第一次看到“superpowers”这个词挂在热词榜上的时候我下意识以为是某部新上映的超级英雄电影或者是某个游戏里的技能系统。结果点进去翻了翻讨论才发现大家嘴里的“superpowers”其实指向的东西相当具体——它是一套给 AI 编程助手用的技能扩展框架核心思路是把一整套可复用的工作流、领域知识和操作规范打包成一个个独立的“技能包”让 AI 在处理具体任务时能按图索骥而不是每次都从零开始瞎猜。说白了你可以把它理解成给 AI 装了一本“操作手册合集”。平时我们用 AI 写代码、做设计、整理文档最头疼的就是它有时候很聪明有时候又完全不在状态同一个需求问三遍能给你三个不同风格的答案。superpowers 想解决的就是这个稳定性问题把那些经过验证的、靠谱的做法固化下来变成 AI 可以直接调用的技能模块。你想让它帮你做代码审查就加载对应的审查技能你想让它按某个规范生成文档就挂上那个文档技能。每个技能包里写清楚了步骤、注意事项、输出格式AI 照着执行就行。这个思路其实挺对我胃口的。我做了这么多年项目最深的体会就是靠谱的产出从来不是靠灵感而是靠流程。一个老手和一个新手的差距往往不在于谁更聪明而在于老手脑子里有一套经过千锤百炼的检查清单和操作顺序。superpowers 干的事情本质上就是把老手的这套东西数字化、模块化然后喂给 AI。那它适合谁呢我觉得三类人最该关注。第一类是天天跟 AI 编程工具打交道、但总觉得产出质量忽高忽低的开发者第二类是想把团队内部的最佳实践沉淀下来、又不想写一大堆文档的 tech lead第三类就是纯粹好奇、想看看“给 AI 装技能”这件事到底怎么落地的技术爱好者。不管你属于哪一类理解 superpowers 的设计思路和安装使用方法都能让你对“怎么跟 AI 高效协作”这件事有新的认识。接下来我会从它的整体设计逻辑讲起然后拆解核心细节再给出一套完整的安装和实操流程最后把我踩过的坑和常见问题整理出来。内容会比较长但都是实打实的东西建议收藏着慢慢看。2. 整体设计思路拆解为什么是“技能包”而不是“大而全”2.1 核心问题AI 助手的“状态漂移”到底有多烦人在深入 superpowers 的设计之前得先把它要解决的问题说清楚。我用 AI 辅助编程有挺长一段时间了最大的痛点不是它不会而是它“不稳定”。同一个项目里我让它按某种风格写一个模块第一次写得挺好第二次再让它写类似的模块风格就变了——变量命名习惯不一样了错误处理的方式也不一样了甚至连注释的详细程度都飘了。这种“状态漂移”在单个文件里还不明显一旦项目规模上去代码风格五花八门维护起来简直是灾难。更麻烦的是领域知识的缺失。比如你让 AI 帮你写一个数据库迁移脚本它可能给你一个能跑但完全不考虑回滚的方案你让它做代码审查它可能只挑些无关痛痒的格式问题真正的逻辑漏洞一个没发现。这不是 AI 笨而是它没有被明确告知“在这个场景下什么才是重要的”。superpowers 的设计出发点就是冲着这两个问题去的。它的核心假设是与其指望 AI 每次都超常发挥不如把靠谱的做法固化下来让它稳定地执行。这个假设我觉得非常务实因为在实际工作中稳定比惊艳重要得多。2.2 技能包的结构一个技能里到底装了什么那一个 superpowers 技能包里具体包含哪些东西呢根据我的使用和拆解一个完整的技能包通常由这么几部分组成。首先是触发条件。这部分定义了“什么情况下该用这个技能”。比如一个代码审查技能它的触发条件可能是“当用户要求审查代码”或者“当检测到有新的 pull request 时”。触发条件写得越精确AI 就越不容易在不该用的时候乱用。其次是执行步骤。这是技能包的核心把完成这个任务的标准流程一步步写清楚。好的技能包不会只写“检查代码质量”这种空话而是会拆成“第一步检查命名规范第二步检查错误处理第三步检查边界条件”这样可执行的动作。步骤的粒度很关键太粗了 AI 会自由发挥太细了又显得死板。然后是输出规范。这部分定义了技能执行完之后结果应该以什么形式呈现。是生成一个 Markdown 报告还是直接修改代码还是输出一个检查清单输出规范的存在让整个流程的终点变得可预期。最后是注意事项和边界条件。这部分往往是区分一个好技能包和普通技能包的关键。它记录了“在什么情况下这个技能不适用”、“有哪些常见的坑要避开”、“遇到特殊情况该怎么处理”。这些内容通常来自实际踩坑的经验是真正有价值的部分。2.3 为什么选择模块化而不是单体式方案理解了技能包的结构就能明白 superpowers 为什么选择模块化这条路了。市面上也有一些方案是做一个“大而全”的提示词模板把所有场景都塞进去用的时候整段丢给 AI。这种做法的问题很明显提示词越长AI 的注意力就越分散真正重要的指令反而被淹没了。模块化的好处在于按需加载。你处理前端任务就加载前端相关的技能处理数据库就加载数据库技能每次 AI 面对的指令都是聚焦的、干净的。这就像你修车的时候不会把整个工具箱都倒在引擎盖上而是需要什么扳手就拿什么扳手。聚焦带来的直接好处就是执行准确率的提升。另一个好处是可组合。不同的技能包可以叠加使用比如你先用一个“需求分析”技能把用户需求拆解清楚再用一个“代码生成”技能按拆解结果写代码最后用一个“代码审查”技能做检查。这种组合能力让 superpowers 的适用范围大大扩展而不是局限于某几个固定场景。还有一个容易被忽略的好处是可维护。当某个技能包发现有问题时你只需要修改那一个包不会影响到其他技能。而且技能包本身是纯文本的可以用版本控制工具管理谁改了什么、为什么改都清清楚楚。这对于团队协作来说太重要了。2.4 和传统提示词工程的本质区别有人可能会问这不就是高级一点的提示词工程吗我觉得两者有本质区别。传统提示词工程关注的是“怎么把一句话说清楚”而 superpowers 关注的是“怎么把一套工作流固化下来”。前者是语言技巧后者是工程方法。打个比方传统提示词工程像是你临时给一个新来的同事口头交代任务说得再清楚他执行起来还是会有偏差。而 superpowers 像是你给这个同事准备了一本详细的操作手册他照着做就行而且这本手册还可以不断迭代完善。两者的可靠性和可复用性完全不在一个量级上。理解了这层设计逻辑接下来就可以看看具体怎么安装和使用了。3. 核心细节解析与实操要点安装前必须搞清楚的几件事3.1 运行环境要求你的机器能不能跑起来在动手安装之前得先确认你的环境是否满足要求。superpowers 本身是一套技能框架它需要依附在某个 AI 编程助手或者开发环境上运行。根据我的实测比较常见的运行方式有这么几种。第一种是作为编辑器插件的扩展来用。如果你平时用 VS Code 或者类似的编辑器可以通过插件市场找到对应的集成方式。这种方式的好处是跟日常开发流程无缝衔接不用切换工具。第二种是作为命令行工具独立运行适合喜欢在终端里干活的人。第三种是集成到某个 AI 助手的配置目录里让助手在启动时自动加载技能包。不管哪种方式对系统的基本要求都差不多需要有一个较新的运行时环境通常 Node.js 或者 Python 的版本不能太老。我建议 Node.js 至少 18 以上Python 至少 3.10 以上太老的版本可能会遇到依赖包不兼容的问题。另外磁盘空间不用太担心技能包本身都是纯文本占不了多少地方但如果你要装很多第三方技能建议留个几百兆的余量。注意安装前先确认你的 AI 助手或者编辑器版本是否支持外部技能加载。有些老版本是不支持的硬装上去也不会生效白白浪费时间。3.2 技能包的获取渠道从哪里拿到靠谱的技能环境确认没问题之后下一步就是获取技能包。目前主要的来源有三个。第一个是官方维护的基础技能集。这部分通常包含了最常用的通用技能比如代码审查、文档生成、需求拆解这些。质量比较有保障建议新手从这里开始。第二个是社区贡献的技能包覆盖面更广从特定编程语言的规范到某个行业的专业流程都有但质量参差不齐需要自己甄别。第三个是自己编写这也是 superpowers 最有价值的地方——你可以把团队内部的规范写成技能包让 AI 按你们的标准来干活。获取方式上官方和社区的技能包一般通过包管理器或者 Git 仓库来分发。用包管理器的好处是版本管理和更新方便用 Git 仓库的好处是你可以直接看到源码方便二次修改。我个人的习惯是基础技能用包管理器装自己定制的技能用 Git 仓库管理这样既省事又灵活。3.3 目录结构规划别把技能包装得到处都是这一点是我踩过坑之后才重视起来的。刚开始用的时候我随手把技能包下载到各个项目的目录里结果时间一长完全记不清哪个项目用了哪个版本的技能更新的时候更是无从下手。后来我改成统一管理在用户主目录下建一个专门的技能仓库目录所有技能包都放在这里面然后通过配置文件告诉 AI 助手去哪里加载。这样不管我在哪个项目里工作用的都是同一套技能更新也只需要在一个地方操作。具体的目录结构我建议这样组织根目录下按来源分文件夹比如 official、community、custom 三个子目录每个技能包一个独立的文件夹文件夹名就是技能名。每个技能文件夹里至少有一个主描述文件说明这个技能的用途、触发条件和执行步骤。如果技能比较复杂还可以有辅助文件比如示例、模板、参考资料等。提示给自定义技能包起名的时候用英文小写加连字符的格式比如 code-review-strict、doc-gen-api这样在不同系统上都不会出问题也方便命令行操作。3.4 配置文件的关键参数几个容易设错的选项技能包装好之后还需要通过配置文件把它们注册到 AI 助手里。配置文件通常是 JSON 或者 YAML 格式里面有几个关键参数需要特别注意。第一个是技能搜索路径。这个参数告诉助手去哪里找技能包可以配置多个路径助手会按顺序查找。我建议把自定义技能的路径放在最前面这样同名的技能会优先使用你自己定制的版本。第二个是自动加载开关。有些助手支持启动时自动加载所有技能有些则需要手动触发。自动加载方便但会占用一些启动时间手动加载启动快但每次都要多一步操作。我的建议是常用技能设成自动加载不常用的设成手动折中一下。第三个是技能优先级。当多个技能都能处理同一个任务时优先级决定了用哪个。这个参数在技能包多起来之后特别重要设不好会出现“该用 A 技能的时候用了 B 技能”的情况。一般来说越具体的技能优先级应该越高越通用的技能优先级越低。第四个是日志级别。调试阶段建议设成详细模式能看到技能加载和执行的完整过程稳定之后可以调低减少噪音。这个参数很多人会忽略但排查问题的时候特别有用。3.5 版本兼容性升级之前先看这一条superpowers 本身和它依赖的 AI 助手都在不断更新版本兼容性是个绕不开的问题。我遇到过好几次升级助手之后技能突然不生效的情况排查半天才发现是技能包的格式变了。我的经验是升级任何一方之前先去看更新日志里有没有提到技能格式的变更。如果有先把技能包备份一份升级完再逐个测试。另外技能包本身也建议用版本号管理在描述文件里写清楚它兼容的助手版本范围这样加载的时候如果版本不匹配至少能给出一个明确的提示而不是默默失效。4. 实操过程与核心环节实现从零到跑通的完整记录4.1 第一步环境准备与依赖安装好前面把该了解的背景和细节都过了一遍现在进入动手环节。我以最常见的“编辑器插件加命令行工具”组合为例把完整流程走一遍。首先确认运行时环境。打开终端检查 Node.js 版本node --version如果输出低于 v18建议先升级。升级方式取决于你的系统用官方的版本管理工具会比较省心。Python 环境同理检查一下版本python3 --version确认版本没问题之后安装 superpowers 的命令行工具。如果它发布在包管理器上直接用对应的安装命令npm install -g superpowers-cli或者用 Python 的包管理器pip install superpowers-cli安装完成后验证一下superpowers --version能正常输出版本号就说明命令行工具装好了。这一步看起来简单但实际安装过程中最容易出问题的就是权限和网络。如果遇到权限报错Linux 和 macOS 下可以在命令前加 sudoWindows 下用管理员权限打开终端。如果下载慢或者超时检查一下包管理器的源配置换成访问更顺畅的镜像源。4.2 第二步初始化技能仓库与目录搭建命令行工具装好之后用它来初始化技能仓库superpowers init这个命令会在你的主目录下创建一个默认的技能仓库目录通常是~/.superpowers/这样的路径。初始化完成后进去看看目录结构ls -la ~/.superpowers/你应该能看到 skills、config、logs 这几个子目录。skills 用来放技能包config 放配置文件logs 放运行日志。如果 init 命令没有自动创建这些目录手动建一下也行不复杂。接下来在 skills 目录下按来源建子目录mkdir -p ~/.superpowers/skills/official mkdir -p ~/.superpowers/skills/community mkdir -p ~/.superpowers/skills/custom这样分类之后后面找技能和更新技能都会方便很多。我强烈建议不要把所有技能都堆在一个目录里技能一多就会乱。4.3 第三步安装基础技能包目录建好之后开始装基础技能。用命令行工具从官方源安装superpowers install code-review superpowers install doc-generator superpowers install requirement-analyzer每装一个工具会把它下载到对应的目录并自动注册到配置文件里。装完之后可以列一下已安装的技能确认superpowers list输出应该会显示每个技能的名称、版本、来源和状态。如果某个技能显示为“未启用”检查一下配置文件里的加载路径有没有写对。这里有个小技巧安装技能的时候可以指定版本号比如superpowers install code-review1.2.0。在团队协作场景下锁定版本号能保证所有人用的技能完全一致避免“我这边好好的你那边报错”这种扯皮。4.4 第四步配置文件详解与参数调优技能装好之后打开配置文件看看。配置文件的位置通常在~/.superpowers/config/config.json用任意文本编辑器打开{ skillPaths: [ ~/.superpowers/skills/custom, ~/.superpowers/skills/official, ~/.superpowers/skills/community ], autoLoad: true, logLevel: info, priority: { custom: 100, official: 50, community: 30 } }这个配置的意思是技能搜索路径按 custom、official、community 的顺序查找启动时自动加载所有技能日志级别为 info自定义技能的优先级最高。几个参数我逐个解释一下怎么调。skillPaths 的顺序决定了同名技能的覆盖关系把 custom 放最前面意味着你自己写的技能会覆盖同名的官方技能这在你想定制某个官方技能的时候很有用。autoLoad 设成 true 会稍微拖慢启动速度但省去了每次手动加载的麻烦技能不多的话建议开着。logLevel 在调试阶段可以设成 debug能看到技能加载的详细过程稳定之后改回 info 或者 warn 减少日志量。priority 的数值越大优先级越高这个在技能有重叠功能的时候特别关键。改完配置之后重启一下 AI 助手或者重新加载配置让改动生效。4.5 第五步验证技能是否正常工作配置改完最激动人心的时刻到了——验证技能到底能不能用。我一般会用一个简单的测试任务来验证比如让助手执行一次代码审查。在助手对话框里输入类似这样的指令“请用 code-review 技能审查下面这段代码”然后贴一段有明显问题的代码进去。如果技能正常工作你应该能看到助手按照技能包里定义的步骤一步步地检查代码最后输出一份结构化的审查报告而不是像平时那样随便说几句。如果技能没有生效先看日志tail -f ~/.superpowers/logs/superpowers.log日志里会记录技能加载的过程和任何报错信息。常见的失败原因有这么几个路径配置错了导致技能没被找到、技能包格式不对导致解析失败、版本不兼容导致加载被跳过。对着日志里的报错信息逐个排查一般都能解决。4.6 第六步编写你的第一个自定义技能基础技能跑通之后强烈建议动手写一个自己的技能。这是 superpowers 真正发挥威力的地方。写技能包本质上就是写一个结构化的 Markdown 文件把某个任务的执行流程描述清楚。我以一个“提交信息规范检查”技能为例展示一下技能包的基本写法。在 custom 目录下新建一个文件夹mkdir -p ~/.superpowers/skills/custom/commit-message-check然后在里面创建一个skill.md文件内容大致是这样的结构先写技能名称和描述说明这个技能是干什么的再写触发条件定义什么情况下该用这个技能接着写执行步骤把检查提交信息的流程一步步列出来最后写输出规范定义检查结果以什么形式呈现。写自定义技能有几个心得。第一步骤要具体到可执行不要写“检查提交信息是否规范”这种空话要写“检查提交信息的第一行是否在 50 个字符以内”、“检查是否使用了祈使语气”这样的具体动作。第二把你们团队的实际规范写进去比如提交信息必须关联任务编号、必须说明变更类型等。第三留出例外情况的处理方式比如紧急修复时的提交信息可以简化到什么程度。写完保存重新加载配置你的第一个自定义技能就可以用了。那种“我教了 AI 一招”的感觉还是挺爽的。4.7 第七步技能组合与工作流编排单个技能用熟了之后就可以玩组合了。superpowers 支持在一个任务里串联多个技能形成完整的工作流。比如一个典型的“新功能开发”工作流可以这样编排先用需求分析技能把用户需求拆解成具体的任务点再用代码生成技能按任务点写代码接着用代码审查技能做质量检查最后用文档生成技能产出对应的接口文档。编排的方式有两种。一种是手动串联你在对话里一步步指定用哪个技能适合需要人工判断的环节。另一种是自动编排在配置里定义好技能的执行顺序和触发条件助手会根据当前任务自动选择合适的技能组合。自动编排效率高但配置起来复杂一些建议先把单个技能用熟再尝试。编排的时候有个坑要注意技能之间的输出格式要能对接上。比如需求分析技能输出的任务列表格式要能被代码生成技能正确解析。如果格式对不上中间就需要一个转换步骤或者干脆调整其中一个技能的输出规范。这个问题在技能少的时候不明显技能一多就容易出乱子所以从一开始就统一输出格式是个好习惯。5. 常见问题与排查技巧实录5.1 技能加载失败从日志里找线索技能加载失败是最常见的问题表现是助手完全不按技能定义的流程走或者直接报错说找不到技能。排查的第一步永远是看日志。日志里通常会告诉你失败发生在哪个阶段。如果是“技能目录不存在”那就是路径配置错了检查配置文件里的 skillPaths 有没有写对路径里的波浪号在某些环境下可能不会被正确展开可以试试写成绝对路径。如果是“技能描述文件解析失败”那就是技能包的格式有问题检查一下 Markdown 的语法特别是标题层级和列表缩进。如果是“版本不兼容”日志里会显示技能要求的版本范围和当前版本升级或者降级对应的一方就行。还有一种比较隐蔽的情况是技能加载了但没生效。这通常是因为触发条件没匹配上。检查一下你的指令里有没有包含技能定义的触发关键词如果没有助手就不会调用这个技能。解决办法要么是调整你的指令措辞要么是放宽技能的触发条件。5.2 技能冲突两个技能抢同一个任务技能装多了之后难免会遇到两个技能都能处理同一个任务的情况。这时候如果优先级没设好助手可能会随机选一个导致结果不稳定。判断是否存在技能冲突可以看日志里同一个任务触发了哪些技能。如果发现有多个技能被触发就需要调整优先级了。原则是越具体、越定制化的技能优先级越高。比如你有一个通用的代码审查技能和一个针对你们团队规范的代码审查技能后者的优先级应该更高。如果调整优先级还是解决不了可以考虑给技能加上更精确的触发条件让它们在不同场景下各司其职。比如通用审查技能只在没有指定团队规范时触发团队审查技能在检测到项目里有团队配置文件时触发。这样两者就不会打架了。5.3 执行结果不符合预期是技能的问题还是指令的问题有时候技能正常加载了也正常触发了但输出结果就是不对。这时候要先判断问题出在哪一环。一个简单的判断方法是把技能包里定义的执行步骤拿出来对照助手的实际输出看它漏了哪一步或者哪几步做得不对。如果步骤本身写得没问题但助手没执行到位那可能是指令不够明确需要在技能包里把步骤描述得更具体。如果步骤本身就有问题那就直接改技能包。还有一种情况是技能包里的步骤没问题但你的输入信息不够导致助手没法完整执行。比如代码审查技能需要知道项目的编码规范但你没提供助手就只能按通用规范来审。解决办法是在技能包里加上“如果缺少必要信息先向用户询问”这样的步骤或者在触发技能时主动提供上下文。5.4 性能问题技能太多导致响应变慢技能装到几十个之后可能会感觉到助手的响应速度变慢了。这是因为每次启动或者每次对话助手都要加载和匹配所有技能技能越多开销越大。优化办法有几个。第一把不常用的技能从自动加载改成手动加载需要的时候再启用。第二精简技能包的内容去掉冗余的描述和示例只保留核心的触发条件和执行步骤。第三定期清理不再使用的技能很多人装了技能之后就忘了删日积月累就拖慢了系统。第四如果助手支持技能分组把相关的技能分到一组按组加载而不是全量加载。我自己的习惯是每个月清理一次技能仓库把过去一个月没用过的技能标记出来考虑是否删除或者归档。保持技能仓库的精简比装一大堆用不上的技能要高效得多。5.5 常见问题速查表为了方便大家快速定位问题我把上面提到的和实际遇到过的典型问题整理成一张表问题现象可能原因排查方法解决方式技能完全不生效路径配置错误检查配置文件 skillPaths改为绝对路径或修正波浪号技能加载报解析错误技能包格式问题查看日志中的具体报错行修正 Markdown 语法技能加载但未触发触发条件不匹配对比指令和触发关键词调整指令或放宽触发条件多个技能同时触发优先级冲突查看日志中的触发记录调整 priority 数值输出结果不稳定技能步骤描述模糊对照步骤检查实际输出细化技能包中的执行步骤响应速度变慢技能数量过多统计已加载技能数量改为手动加载或清理技能升级后技能失效版本不兼容查看更新日志和版本要求升级技能包或回退助手版本5.6 几个我踩过的坑和独家技巧最后分享几个我在实际使用中踩过的坑以及总结出来的小技巧。第一个坑是技能包里的示例代码用了特定项目的路径换一个项目就报错。后来我学乖了技能包里的所有路径都用相对路径或者占位符让助手根据当前项目自动填充。这个习惯能省掉很多跨项目使用时的麻烦。第二个坑是技能包的触发条件写得太宽泛导致助手在不该用的时候也调用它。比如一个“生成文档”的技能如果触发条件只是“用户提到文档”那用户说“这个文档写得不好”也会触发它。后来我把触发条件改成“用户明确要求生成或创建文档”误触发的情况就少多了。第三个技巧是给技能包加一个“自检”步骤。在技能执行完之后让助手自己检查一下输出是否符合规范不符合就重新执行。这个自检步骤看起来多余但实际能拦住不少低级错误特别是格式类的错误。第四个技巧是版本控制。把整个技能仓库用 Git 管理起来每次修改都提交这样既能追溯变更历史又能在改坏的时候快速回滚。团队协作的时候大家通过 Git 共享技能包比用聊天工具传来传去靠谱多了。第五个技巧是定期回顾。每隔一段时间把技能包拿出来重新读一遍看看有没有过时的内容、有没有可以合并的技能、有没有需要补充的新规范。技能包不是写完就一劳永逸的它需要跟着项目和团队一起成长。这套东西用下来我最大的感受是superpowers 的价值不在于它自带了多厉害的技能而在于它提供了一种把经验固化成流程的机制。你用得越久积累的自定义技能越多它就越贴合你的工作方式。刚开始可能觉得配置麻烦但一旦跑顺了那种“AI 终于按我的规矩干活了”的踏实感是单纯调提示词给不了的。