1. 从“superpowers”这个热词说起它到底是什么最近“superpowers”这个词在技术社区里出现的频率明显高了起来很多人第一次看到它是在某个开源项目的讨论区或者是在朋友转发的一条动态里。有人把它当成一个插件有人以为它是一个新的开发框架还有人直接问“想要安装superpowers到底该怎么下手”。我花了几天时间把这个东西从里到外摸了一遍也实际跑通了安装和使用的完整流程这里把我知道的东西一次性讲清楚。先给一个最直白的定义superpowers 是一套面向 AI 编程助手的能力扩展集合它本身不是一个独立的软件而是依附在特定的 AI 编程工具之上通过注入一组预定义的技能skills、工作流workflows和提示词模板让原本只会“你问我答”的助手变成能够主动规划、分步执行、自我检查的协作伙伴。你可以把它理解成给一个刚入职的实习生配了一本厚厚的《岗位操作手册》手册里写清楚了遇到什么任务该走什么流程、该调用什么工具、该在什么节点做检查。它解决的问题其实很具体。用过 AI 编程助手的人都有体会你让它写一个功能它可能一口气吐出一大段代码看起来挺像那么回事但真正跑起来各种边界情况没处理测试也没写命名风格还跟你项目里其他地方不一致。你得反复纠正、反复补充来回好几轮才能用。superpowers 的思路就是把这些“反复纠正”的经验固化成流程让助手在动手之前先想清楚要做什么、分几步做、每步的验收标准是什么然后再动手。说白了它把“提示词工程”从零散的技巧变成了一套可复用的工程化方法。适合谁来参考呢三类人最值得花时间研究。第一类是日常重度使用 AI 编程助手的开发者尤其是那些已经觉得“助手挺好用但总差一口气”的人第二类是做团队效能、研发流程优化的工程师因为 superpowers 里的很多设计思路可以直接借鉴到团队规范里第三类是对 AI 智能体agent工作流感兴趣的技术爱好者它提供了一个非常具体的、可拆解的案例比看那些抽象的概念文章有用得多。哪怕你暂时不打算安装光是读一遍它的技能定义文件都能对“怎么让 AI 好好干活”这件事有新的认识。2. 核心设计思路拆解为什么是“技能包”而不是“大而全”2.1 把能力拆成独立技能而不是塞进一个巨型提示词很多人第一次接触这类扩展时直觉反应是“为什么不直接写一个超长的系统提示词把所有要求都塞进去”。我一开始也这么想但实际用过之后发现超长提示词有几个绕不开的毛病。一是注意力稀释提示词越长模型对其中某一条具体规则的遵守程度就越低这是目前大模型的通病二是维护困难你想改其中一条规则得在几千字里找到那句话改完还可能影响别的部分三是场景错配写后端接口和调前端样式需要的规则完全不同全塞在一起就是互相干扰。superpowers 的做法是把能力切成一个个独立的“技能”skill每个技能是一个单独的目录里面通常包含一个描述文件说明这个技能是干什么的、什么时候触发、若干提示词模板、可能还有辅助脚本。用到哪个加载哪个不用的时候不占上下文。这个设计思路跟微服务有点像——不是说微服务一定比单体好而是在“能力种类多、场景差异大、需要独立演进”的情况下拆分带来的收益明显大于成本。我实际对比过两种方式的效果。同样一个“给现有函数补单元测试”的任务用一个大而全的提示词助手大概有六成概率会漏掉边界条件换成加载专门的测试技能后漏掉的概率降到两成左右。差距主要来自技能文件里那些非常具体的检查清单比如“是否覆盖了空输入、是否覆盖了超长输入、是否验证了异常抛出类型”这些细节在大提示词里很容易被淹没。2.2 工作流驱动先规划再执行中间有检查点superpowers 另一个核心设计是工作流workflow。它不指望助手一次性把复杂任务做对而是把任务拆成“理解需求 → 制定计划 → 分步执行 → 验证结果”几个阶段每个阶段之间有明确的交接物。比如制定计划阶段要求助手输出一份结构化的任务清单每一项都要写清楚“做什么、为什么做、怎么验证做完”。这份清单不是给用户看的装饰而是后续执行阶段的输入——执行时助手会逐项对照做完一项标记一项。这个设计背后的逻辑其实来自软件工程里的老经验复杂任务出错多数不是能力问题而是没有分解和验证。人做项目要写设计文档、要 code review、要跑测试AI 做任务同样需要这些环节只不过它需要的不是文档和会议而是结构化的中间产物。我自己的体会是加上规划环节之后返工率明显下降。以前经常是助手写了一堆代码我一看方向就错了只能全部推翻现在它在计划阶段就会把思路列出来我扫一眼就能发现“这个方案不对”及时纠正的成本低得多。2.3 技能与工作流的组合方式单独有技能或者单独有工作流都不够。只有技能没有工作流助手知道“怎么写测试”但不知道“什么时候该写测试”只有工作流没有技能助手知道“要先规划”但规划出来的东西质量参差不齐。superpowers 把两者组合起来工作流负责调度和节奏技能负责每个环节的具体质量。这种组合方式在它的配置文件里体现得很清楚一个典型的工作流定义会引用若干技能比如“代码审查工作流”会依次调用“静态检查技能”“逻辑一致性检查技能”“测试覆盖检查技能”。从工程角度看这种组合还带来一个好处可测试性。每个技能可以单独验证效果每个工作流也可以单独跑通出问题的时候容易定位是哪个环节的毛病。我在调试自己的配置时就靠这种拆分快速定位到是某个技能的触发条件写得太宽泛导致它在不该触发的时候也加载了干扰了正常流程。3. 安装前的准备工作环境、依赖与版本选择3.1 确认你的基础工具是否支持superpowers 不是独立运行的它需要挂载在一个支持扩展的 AI 编程工具上。目前主流的两类载体一类是命令行形态的编程助手一类是编辑器插件形态的助手。安装之前第一件事是确认你用的工具是否开放了扩展接口。判断方法很简单看它的配置目录里有没有类似“skills”“extensions”“plugins”这样的文件夹或者官方文档里有没有提到自定义技能加载。如果没有那暂时用不了不用浪费时间折腾。我踩过的一个坑是版本问题。有些工具早期版本不开放扩展接口后来才加上但网上很多教程没写清楚版本要求。我的建议是先把基础工具升级到官方文档标注的最新稳定版再去装 superpowers。升级前记得备份配置文件尤其是你之前手动改过的那些设置升级过程有时会覆盖掉。3.2 依赖项检查清单在正式安装之前我习惯先过一遍依赖清单避免装到一半报错。下面这张表是我整理出来的检查项你可以对照着逐条确认。检查项要求检查方法常见问题基础工具版本支持扩展接口的版本查看工具关于页面或运行版本命令版本过低导致技能无法加载运行时环境工具要求的运行时版本运行环境版本命令版本不匹配导致脚本执行失败磁盘空间至少预留 200MB查看磁盘剩余空间空间不足导致安装中断网络连通性能访问技能仓库尝试拉取一个测试仓库网络不通导致克隆失败配置目录权限当前用户可读写尝试在配置目录新建文件权限不足导致写入失败这张表看着简单但每一条我都见过有人栽在上面。尤其是配置目录权限这一条在部分系统上配置目录默认是只读的安装脚本写不进去报的错又很隐晦容易让人以为是网络问题。3.3 安装方式的选择包管理器还是手动克隆superpowers 常见的安装方式有两种。一种是通过包管理器一条命令搞定适合追求省事的用户另一种是手动克隆仓库再配置路径适合需要定制或者想研究内部结构的用户。两种方式我都试过说下各自的适用场景。包管理器安装的优点是快一条命令下去自动处理依赖和路径升级也方便。缺点是不透明你不知道它到底往你系统里放了什么、改了哪些配置出了问题不好排查。手动克隆的优点是完全可控每个文件在哪、每个配置改了什么你都清楚想改技能内容直接编辑就行。缺点是要自己处理路径和依赖第一次装可能要花十几分钟。我的建议是如果你只是想用起来选包管理器如果你打算深入研究或者做定制选手动克隆。我自己的主力环境是手动克隆的因为经常需要改技能文件来适配团队规范测试环境用包管理器图个省事。4. 完整安装流程从零到跑通第一个技能4.1 获取 superpowers 资源第一步是把 superpowers 的资源拿到本地。如果你走包管理器路线直接执行对应的安装命令即可安装完成后通常会在配置目录下生成一个 skills 文件夹。如果你走手动路线需要先克隆仓库命令大致如下git clone superpowers仓库地址 ~/.config/your-tool/skills/superpowers这里的路径要根据你实际使用的工具来调整不同工具的配置目录不一样。克隆完成后进入目录看一眼结构正常应该能看到若干技能子目录、一个总体的描述文件、可能还有示例配置。如果目录是空的或者只有 README那多半是克隆的分支不对检查一下默认分支设置。提示克隆之前先确认目标路径不存在同名目录否则克隆会失败或者覆盖掉你已有的内容。我习惯先 ls 一下目标路径确认干净再操作。4.2 配置技能加载路径资源到位之后要让基础工具知道去哪里加载这些技能。这一步通常是在工具的配置文件里加一行路径声明。配置文件的位置因工具而异常见的位置包括用户主目录下的隐藏配置文件夹、项目根目录下的工具专属配置文件等。找到配置文件后添加类似下面这样的内容{ skills: { paths: [ ~/.config/your-tool/skills/superpowers ], autoLoad: true } }这里有两个关键参数值得说明。paths是技能搜索路径可以配多个工具会按顺序查找。autoLoad控制是否自动加载设为 true 时工具启动就会扫描并加载所有技能设为 false 则需要手动触发。我一般建议先设为 false手动加载测试没问题之后再改成 true避免某个有问题的技能影响整体启动。改完配置记得重启工具大部分工具不会热加载配置变更。重启后可以通过工具提供的技能列表命令验证是否加载成功正常应该能看到 superpowers 下面的一串技能名称。4.3 验证安装跑通第一个技能安装是否成功光看列表不够得实际跑一个技能。我推荐从最简单的“代码解释”类技能开始因为它的输入输出都很明确容易判断对错。操作方式是选中一段代码然后触发对应的技能命令。如果工具支持自然语言触发直接说“用 superpowers 解释这段代码”也行。判断成功的标准有三个一是技能被正确识别并加载工具会显示当前激活的技能名称二是输出内容符合技能定义的格式比如要求分点解释的就不能写成一大段三是没有报错信息。三个都满足说明安装基本没问题。如果只满足前两个但输出质量很差那可能是技能文件版本和工具版本不匹配需要检查兼容性说明。我第一次装的时候卡在第三步技能能加载但输出总是缺一块。排查了半天发现是技能文件里引用了一个辅助脚本而那个脚本依赖的一个库没装。补上依赖之后就正常了。这个经历告诉我安装验证不能只看“有没有报错”还要看“输出完不完整”。5. 核心技能逐个拆解每个技能解决什么问题5.1 规划类技能把模糊需求变成可执行清单规划类技能是 superpowers 里我最常用的部分。它的作用是接收一个模糊的需求描述输出一份结构化的任务清单。比如你说“给用户模块加一个修改密码的功能”它会输出类似这样的清单确认现有用户模型结构、设计密码修改接口、实现密码强度校验、编写单元测试、更新接口文档。每一项还会附带验收标准比如“密码强度校验需覆盖长度、字符类型、常见弱密码三个维度”。这个技能的价值在于强制澄清。很多时候需求模糊不是用户故意的而是他自己也没想清楚。规划技能通过追问和拆解把那些隐藏的假设暴露出来。我印象很深的一次是助手在规划阶段问了一句“修改密码后是否需要使现有会话失效”这个问题我一开始根本没考虑但它直接影响实现方案。如果没有这个环节等代码写完再发现这个问题返工成本就高了。使用这个技能有个小技巧需求描述里带上你的约束条件。比如“用现有的 ORM 框架实现不要引入新依赖”“接口风格跟现有接口保持一致”。这些约束会体现在规划结果里后续执行阶段就不会跑偏。不带约束的话助手可能给你一个技术上正确但跟你项目格格不入的方案。5.2 执行类技能分步落地并自我检查执行类技能负责把规划清单变成实际产出。它的工作方式是逐项处理清单每完成一项就做一次自检自检通过才进入下一项。自检的内容通常包括产出是否符合验收标准、是否引入了新的问题、是否与已有代码风格一致。我特别喜欢它的一个设计是失败回退。如果某一项自检不通过它不会硬着头皮往下做而是回到上一步重新处理或者标记出来让你介入。这个机制避免了“错误累积”——前面一个小错没纠正后面基于这个错继续做最后整个产出都不可用。我自己写代码也有这个毛病有时候明知道前面有个地方不太对想着“先往下写回头再改”结果回头就忘了。这个技能相当于把这个坏习惯给治了。实际使用中要注意的是执行类技能对上下文长度比较敏感。如果任务清单特别长处理到后面可能因为上下文被挤占而质量下降。我的做法是把大任务拆成几个中等任务每个任务单独跑一轮中间手动衔接。虽然麻烦一点但产出质量稳定得多。5.3 审查类技能站在对立面找问题审查类技能是 superpowers 里我觉得最有价值的部分。它的设计思路是让助手扮演一个“挑刺者”的角色专门找产出里的问题。跟执行类技能的自检不同审查类技能是独立的一轮它不关心你是怎么做的只看结果对不对。审查的维度通常包括逻辑正确性、边界条件覆盖、命名一致性、注释充分性、潜在性能问题。每个维度都有具体的检查项比如边界条件会检查空值、极值、并发情况。我实测下来审查类技能能抓出大约三成到四成的遗漏问题这个比例相当可观。尤其是命名一致性和注释这类“人容易忽略但影响可维护性”的问题它抓得比人还准。有个使用心得审查之前先把你的项目规范喂给它。superpowers 的审查技能支持加载自定义规范文件你把团队的命名规范、注释要求、目录结构约定写进去审查结果就会贴合你的实际情况而不是给出一堆通用但没用的建议。我一开始没做这一步审查结果里全是“建议使用驼峰命名”这种废话因为我的项目本来就是驼峰命名它不知道。加上规范文件之后就精准多了。5.4 技能之间的协作与冲突处理多个技能同时加载时偶尔会出现冲突。比如规划技能和执行技能对同一个任务的拆解粒度要求不一样规划技能希望拆得细执行技能希望拆得粗两者同时激活就可能互相干扰。superpowers 的处理方式是给技能设置优先级和互斥规则优先级高的技能在冲突时覆盖优先级低的。我在配置里给规划类技能设了较高优先级因为规划阶段的粒度直接影响后续所有环节。执行类技能优先级中等审查类技能优先级也较高因为它需要独立判断。互斥规则方面我设置了“规划技能激活时暂停执行技能”避免它们在同一个任务上打架。这些规则都写在配置文件的技能声明部分格式很简单就是给每个技能加一个 priority 字段和一个 conflicts 列表。需要提醒的是不要一次性加载太多技能。我试过把 superpowers 里所有技能全开结果助手变得非常啰嗦每个环节都要走一遍完整流程简单任务也要花很长时间。后来我按场景分组日常开发只开规划加执行加审查三个核心技能特定任务再临时加载专用技能效率高多了。6. 实操中的常见问题与排查技巧6.1 技能加载失败从日志入手逐层排查技能加载失败是最常见的问题表现是工具启动时报错或者技能列表里看不到预期的技能。排查思路是从外到内逐层检查。先看路径对不对路径错了后面都白搭再看权限够不够配置目录和技能目录都要可读然后看技能描述文件的格式对不对JSON 或 YAML 格式错误会导致解析失败最后看依赖是否齐全有些技能依赖外部脚本或库。我整理了一个排查顺序表按这个顺序走基本能覆盖九成以上的加载问题。排查顺序检查内容判断方法解决方式1技能路径是否正确手动进入路径看文件是否存在修正配置文件中的路径2目录权限是否足够尝试在目录内创建测试文件修改目录权限3描述文件格式是否正确用格式校验工具检查修正格式错误4依赖是否齐全查看技能目录下的依赖说明安装缺失依赖5版本是否兼容对比技能和工具的版本要求升级或降级到兼容版本日志是排查的关键。大部分工具会把加载过程的详细信息写到日志文件里位置通常在配置目录下的 logs 文件夹。看日志的时候重点找“error”和“warn”级别的条目它们会直接告诉你哪一步出了问题。我遇到过一次加载失败日志里写的是“skill description file not found”一看就是路径配错了改完就好。6.2 技能触发不灵敏调整触发条件技能加载成功但触发不灵敏是另一个高频问题。表现是你明明在做相关任务技能却没被激活。原因通常是触发条件写得太窄或者太宽。太窄的话稍微换个说法就匹配不上太宽的话不相关的任务也会触发反而干扰。调整触发条件的方法是编辑技能描述文件里的触发关键词和场景描述。关键词要覆盖常见的表达方式比如“写测试”“补测试”“加单元测试”都应该能触发测试技能。场景描述要写清楚“什么情况下用这个技能”给助手更多判断依据。我一般会把自己常用的几种说法都加进去然后实际测试几轮看触发率怎么样。有个经验是不要追求百分之百的自动触发。有些场景就是模糊的自动判断容易出错。我的做法是给关键技能配一个手动触发命令自动触发不灵的时候手动调用保证任务能正常进行。自动加手动两条路比死磕自动触发靠谱。6.3 输出质量不稳定上下文管理是关键输出质量时好时坏这个问题困扰了我挺久。后来发现主要原因是上下文管理。superpowers 的技能在执行时会占用上下文如果同时加载的技能多、任务又长留给实际任务的上下文就不够了质量自然下降。解决办法有三个。一是精简加载的技能只留当前任务必需的二是把长任务拆短每个任务单独跑一轮三是定期清理对话历史把不相关的上下文释放掉。我现在的习惯是每完成一个中等任务就开一轮新的对话把必要的背景信息重新喂一遍虽然多花点时间但质量稳定。还有一个容易被忽略的点是技能文件本身的长度。有些技能文件写得非常详细光描述就几千字加载进来就占了不少上下文。我后来把一些不常用的详细说明挪到单独的参考文件里技能描述只保留核心部分需要的时候再手动加载参考文件。这样上下文利用率高了不少。6.4 与其他扩展的兼容性问题如果你同时装了其他扩展可能会遇到兼容性问题。表现是单独用 superpowers 正常加上另一个扩展就出问题。原因通常是两者都试图修改同一份配置或者都注册了同名的命令。排查方法是逐个禁用。先把其他扩展全禁掉确认 superpowers 单独正常然后一个一个启用看启用哪个之后出问题。找到冲突的扩展后看两者的配置有没有重叠有的话调整一下比如改命令名、改配置项名称。如果实在调不开就按使用频率取舍常用的留着不常用的先禁用。我遇到过一次冲突是命令名重复两个扩展都注册了“review”命令结果调用的时候不知道执行哪个。解决办法是给 superpowers 的命令加个前缀改成“sp-review”问题就解决了。这种小改动不影响功能但能避免很多莫名其妙的故障。7. 进阶玩法定制属于你自己的技能7.1 从现有技能改起而不是从零写想定制技能的话我的建议是从现有技能改起。superpowers 自带的技能已经覆盖了大部分通用场景你只需要在它的基础上调整成贴合自己项目的版本。比如把测试技能里的检查项换成你项目实际用的测试框架和断言风格把审查技能里的规范换成你团队的规范。这样改起来快也不容易漏掉重要环节。改的时候注意保留原有的结构只改内容。技能文件通常分几个部分元信息名称、版本、触发条件、提示词模板、检查清单、示例。元信息里的触发条件可以按需调整提示词模板和检查清单是改动的重点。我一般会先跑一遍原版技能记录下哪些地方不符合我的需求然后针对性地改改完再跑一遍对比效果。7.2 技能文件的组织建议随着自定义技能增多文件组织就变得重要了。我的做法是按场景分目录比如“开发类”“审查类”“文档类”各一个目录每个目录下放相关技能。目录名和技能名都用英文小写加连字符避免空格和特殊字符减少路径问题。每个技能目录里我习惯放这几个文件skill.json存元信息prompt.md存提示词模板checklist.md存检查清单examples/目录存示例。这样结构清晰改的时候知道去哪找。如果技能依赖脚本再放一个scripts/目录。文件命名统一之后维护起来省心很多。注意技能目录的层级不要太深有些工具对路径深度有限制太深了可能加载不到。我一般控制在三层以内。7.3 版本管理与团队共享自定义技能建议用版本管理工具管起来跟代码一样。这样改坏了能回退多人协作也能合并改动。我自己的技能仓库是单独一个 git 仓库跟项目代码分开因为技能是跨项目复用的。仓库里按目录组织技能每个技能有独立的版本号改动时更新版本号并写变更说明。团队共享的话可以把技能仓库设为团队内部可访问每个人克隆到自己的配置目录。更新的时候拉一下最新版本就行。如果团队有统一的规范把规范写进技能文件新人装好技能就自动遵循规范了比口头传达或者写文档有效得多。我们团队现在新人的第一件事就是装这套技能省了很多“你这个命名不对”“你这里没写测试”的重复沟通。8. 我踩过的坑和实测有效的经验8.1 不要一次性把所有技能都打开这是我踩过最大的坑。刚装好的时候觉得技能越多越好全打开了结果助手变得极其啰嗦一个简单函数也要走完整流程输出一大堆用不上的分析。后来我按场景分组日常开发只开核心几个效率立刻上来了。技能是工具不是装饰用不上的就是负担。8.2 技能文件要跟着项目演进项目在变技能文件也得跟着变。我一开始改了一版技能文件就没再动过过了两个月发现它给出的建议已经跟项目实际情况脱节了比如还在推荐已经废弃的测试框架。后来我养成了习惯每次项目有大的架构调整或者规范变更就同步更新技能文件。这个维护成本不高但不做的话技能会慢慢失效。8.3 手动触发和自动触发搭配使用纯靠自动触发有时候不靠谱尤其是任务描述比较模糊的时候。我的做法是给每个核心技能配一个手动触发命令自动触发不灵就手动调。手动触发还有个好处是意图明确你主动调用某个技能助手就知道你确实需要这个环节不会犹豫。自动触发适合常规任务手动触发适合关键任务两者搭配最稳。8.4 定期清理不用的技能装了一堆技能之后有些可能几个月都用不上一次。这些技能留在那里不仅占上下文还可能在扫描时拖慢启动速度。我现在的做法是每个季度清理一次把过去三个月没用过的技能移到“归档”目录需要的时候再移回来。清理之后启动速度和响应速度都有可感知的提升。8.5 记录每次调整的效果改技能文件的时候我会在文件末尾加一个简单的变更记录写清楚改了什么、为什么改、改完效果怎么样。这个习惯帮我避免了很多“改来改去又改回去”的循环。有一次我想调整某个检查项的顺序翻记录发现半年前试过同样的调整效果不好又改回来了直接省了一次无用功。技能调优是个长期过程记录是最好的帮手。9. 这套东西后续还能怎么扩展superpowers 的架构决定了它的扩展空间很大。我目前想到几个方向也在陆续尝试。一个是接入项目专属的知识库把项目的架构文档、接口文档、常见问题整理成技能可以读取的格式让助手在规划阶段就能参考这些信息减少“不了解项目背景”导致的方案偏差。另一个是跟 CI 流程打通把审查类技能的输出接到持续集成里代码提交时自动跑一遍审查把问题拦在合并之前。还有一个方向是技能的效果度量。现在判断一个技能好不好用主要靠主观感受。如果能记录每个技能触发后的产出质量、返工次数、用户干预频率这些指标就能用数据指导技能优化而不是凭感觉调。我最近在尝试给技能加简单的埋点记录触发次数和后续的人工修改量虽然还比较粗糙但已经能看出一些规律了比如某个审查技能触发后人工修改量明显低于另一个说明它的检查项设计得更合理。这些扩展不一定都要做但思路是共通的把 AI 助手当成一个需要持续培养的协作者而不是一个用完就丢的工具。你投入在技能调优上的时间会以返工减少、沟通成本降低的形式回报回来。我自己的体感是认真调过技能之后同样一个功能模块的开发时间大概能压缩三成左右而且产出质量更稳定不用反复返工。这个投入产出比值得花时间。