★ FEATURED ARTICLE 1. 从“superpowers”这个热词说起它到底指什么最近一段时间“superpowers”这个词在技术社区和效率工具圈子里被反复提起。很多人第一次看到它会以为是某个新出的超级英雄题材游戏或者某个性能优化框架的代号。实际上在当前的技术语境下superpowers 指的是一套面向 AI 编程助手的能力扩展机制——你可以把它理解成给 AI 助手安装的“技能包”或“插件系统”。它让原本只会聊天、写代码片段的助手能够调用一系列预定义好的、可复用的专业技能去完成更复杂、更贴近真实工程场景的任务。我最初接触这个概念是因为团队里有人在讨论“怎么让 AI 助手真正参与到项目里而不是每次都要重新解释一遍上下文”。当时大家的痛点很一致每次让助手帮忙写一个模块都要把项目结构、代码规范、依赖版本重新说一遍效率极低。而 superpowers 这套机制的核心价值就是把这些重复性的“前置说明”和“标准操作”固化下来变成助手可以直接调用的技能。换句话说它解决的是AI 助手在真实项目中“记不住、做不深、不连贯”的问题。这篇文章适合几类人看第一类是想把 AI 助手真正用进日常开发流程的工程师第二类是对“技能扩展”“能力编排”这类概念感兴趣、想自己动手配置的技术爱好者第三类是被各种热词绕晕、想搞清楚 superpowers 到底能干什么的普通用户。我会从它的基本概念讲起然后拆解它包含哪些技能、怎么引入、怎么安装最后分享一些我在实际配置过程中踩过的坑和总结出来的经验。全文不会堆砌术语尽量用“人话”把这件事讲透。需要先说明一点superpowers 本身并不是一个单一的工具而更像是一套约定和框架。不同的平台、不同的助手实现对它的支持方式可能略有差异。但核心思路是一致的——通过定义清晰的技能描述文件让助手在需要的时候能够“加载”对应的能力。理解了这一点后面所有的操作都会变得顺理成章。2. superpowers 的核心机制技能是怎么被“唤醒”的2.1 技能不是插件而是一份“可执行的说明书”很多人第一次听到“技能”这个词会下意识地把它等同于浏览器插件或者 IDE 扩展。这个理解有偏差。在 superpowers 的体系里一个技能本质上是一份结构化的说明文档里面写清楚了这个技能是干什么的、什么时候该用它、用了之后要执行哪些步骤、需要哪些输入、会产生什么输出。它更像是一份写给 AI 助手看的“操作手册”而不是一段直接运行的代码。这个设计的好处非常明显。传统的插件需要你写代码、编译、调试门槛不低。而技能文件通常就是 Markdown 或者类似的纯文本格式你只要把步骤写清楚助手就能理解并执行。我试过把一个团队内部的“代码提交规范”写成一个技能文件内容包括提交信息格式、分支命名规则、需要跑的检查命令。写完之后助手在帮我生成提交信息时就会自动按照这个规范来不再需要我每次提醒。这种“用自然语言定义能力”的方式是 superpowers 最吸引人的地方。当然纯文本描述也有它的边界。如果技能涉及非常复杂的逻辑分支或者需要调用外部 API光靠文字描述就不够了通常还需要配合一些脚本或配置文件。但对于大多数日常任务来说一份写清楚的说明书已经足够。2.2 技能的触发方式主动调用与自动匹配技能写好之后怎么让助手知道该用它目前常见的有两种触发方式。第一种是主动调用也就是你在对话里明确说“使用某某技能”或者“按照某某规范来做”。这种方式最直接适合那些你很清楚当前任务需要什么能力的场景。比如你要生成一个数据库迁移脚本就可以直接调用对应的技能。第二种是自动匹配。助手会根据你当前的任务描述去技能库里找语义上最接近的技能然后自动加载。这种方式更智能但也更容易出问题。我遇到过好几次助手自动匹配了一个不太相关的技能导致输出结果偏离预期。后来我的做法是对于关键任务尽量用主动调用的方式把技能名字说清楚对于探索性的任务才依赖自动匹配。这里有个经验值得分享技能的名字和描述要写得足够具体。如果你把技能命名为“代码助手”描述写成“帮助写代码”那自动匹配的准确率会很低。但如果你命名为“Python 单元测试生成”描述写成“为指定的 Python 函数生成 pytest 风格的单元测试包含边界值用例”匹配精度就会高很多。这个细节看起来不起眼但直接决定了自动匹配能不能用。2.3 技能之间的组合与依赖单个技能能做的事情有限真正体现 superpowers 价值的地方是多个技能的组合使用。比如一个完整的“新功能开发”流程可能涉及需求拆解技能、接口设计技能、代码生成技能、单元测试技能、文档更新技能。这些技能可以串成一条流水线前一个的输出作为后一个的输入。我在配置这条流水线的时候最大的体会是技能之间的接口要约定清楚。比如“接口设计技能”输出的格式必须和“代码生成技能”期望的输入格式对得上。如果前者输出的是自然语言描述后者期望的是结构化的 JSON中间就会断掉。解决办法是在技能文件里明确写出输入输出的格式要求必要时用示例来说明。这一点在官方文档里往往不会强调但实际用起来非常关键。另外技能之间也可能存在依赖关系。比如某个技能需要先读取项目配置文件才能正确执行。这种情况下要么在技能里写明前置条件要么单独做一个“环境准备”技能在流程开始时先跑一遍。我倾向于后者因为这样逻辑更清晰排查问题也更容易。3. superpowers 里到底有哪些技能3.1 开发流程类技能从需求到提交的完整链路这一类技能是使用频率最高的基本覆盖了日常开发的各个环节。我把自己常用的几个列出来并说明它们各自解决什么问题。技能名称主要作用典型使用场景需求拆解把一段模糊的需求描述拆成可执行的任务列表接到一个新需求还没想清楚怎么动手时接口设计根据任务列表生成接口定义和数据结构前后端联调前需要先定契约代码生成按照项目规范生成指定模块的代码重复性的 CRUD 或样板代码单元测试生成为已有函数生成测试用例补测试覆盖率或者重构前先加保护代码审查检查代码是否符合规范、有无明显问题提交前自查或者审查别人的代码提交信息生成按照团队规范生成 commit message每次提交前这些技能单独拿出来都不算新鲜很多工具都能做。但 superpowers 的优势在于它们可以共享同一套项目上下文。比如“代码生成”技能知道项目用的是哪个框架、哪个版本的依赖“单元测试生成”技能知道测试文件放在哪个目录、用的是什么测试框架。这种上下文共享让每个技能的输出都更贴合项目实际情况而不是泛泛而谈。我特别想提一下“需求拆解”这个技能。很多人觉得拆解需求是人的事AI 做不好。但实际用下来如果技能文件里写清楚了拆解的维度和粒度要求助手给出的任务列表质量相当不错。我的做法是在技能里规定每个任务必须能在半天内完成必须明确输入和输出必须标注依赖关系。按照这个标准拆出来的任务直接放进任务管理工具就能用。3.2 代码质量类技能让规范真正落地代码规范这件事说起来重要做起来容易走样。因为规范是死的人是活的忙起来就容易“先这样吧以后再改”。superpowers 里的代码质量类技能价值就在于把规范变成了可执行的检查步骤而不是挂在墙上的文档。这类技能通常包括命名规范检查、注释完整性检查、异常处理检查、日志规范检查、安全漏洞扫描等。每个技能都会定义具体的检查项和判定标准。比如命名规范检查会规定变量名必须用驼峰、常量必须全大写、布尔值必须以 is 或 has 开头等等。助手在执行时会逐条对照给出具体的修改建议。我用得最多的是“异常处理检查”。以前写代码经常出现 catch 了异常但什么都不做的情况或者直接把异常吞掉。后来写了一个技能规定每个 catch 块必须要么记录日志、要么重新抛出、要么有明确的降级处理并且要在注释里说明为什么这样处理。这个技能跑了几次之后团队里这种“静默失败”的问题明显减少了。这里有个坑要注意检查项不要一次加太多。我一开始贪心把能想到的规范全写进去了结果助手每次检查都要输出一大堆问题反而让人不想看。后来精简到最核心的十条并且按严重程度分级体验就好多了。技能不是越多越好关键是每一条都能被执行、被验证。3.3 文档与协作类技能减少沟通成本开发过程中有很多时间花在“写文档”和“对齐信息”上。这类技能的目标就是把这些工作自动化或者半自动化。常见的包括接口文档生成、变更日志生成、会议纪要整理、代码注释补全等。接口文档生成这个技能我的使用频率很高。只要接口定义写好了助手就能自动生成符合 OpenAPI 规范的文档包括请求参数、响应结构、错误码说明。以前这件事要专门花时间做现在基本是顺手就完成了。而且因为文档是从代码里生成的不会出现“代码改了文档没改”的情况。变更日志生成也很实用。每次发版前助手会根据提交记录自动整理出本次版本的新增功能、修复的问题、破坏性变更。当然提交信息本身要写得规范否则生成出来的日志也没法看。这就又回到了前面提到的“提交信息生成”技能——技能之间是相互依赖的前面的输出质量决定了后面的输出质量。协作类技能里我觉得最有意思的是“上下文摘要”。当对话很长、或者需要把任务交接给别人的时候助手可以把当前讨论的核心结论、待办事项、关键决策点整理成一份简短的摘要。这个功能在跨时区协作或者异步沟通的场景下特别有用能省掉大量“爬楼”的时间。3.4 自定义技能把自己的经验变成可复用的能力前面说的都是通用技能而 superpowers 真正强大的地方是允许你定义自己的技能。每个团队、每个项目都有自己的特殊流程和约定这些是通用工具覆盖不到的。自定义技能就是把这些“只有你们团队知道”的东西固化下来。我举一个自己的例子。我们项目有一个特殊的发布流程需要先跑一遍数据迁移脚本然后检查某个配置开关的状态最后才能部署。这个流程以前只存在于老员工的脑子里新人来了要手把手教。后来我把它写成了一个技能文件内容包括每一步的命令、预期输出、失败时的回滚操作、需要确认的检查点。写完之后新人按照技能提示就能独立完成发布我只需要在最后确认一下。写自定义技能有几个要点。第一步骤要具体到命令级别不要写“检查数据库状态”这种模糊的话要写清楚用什么命令、看哪个字段、什么值算正常。第二要包含失败处理每一步都可能出错出错之后怎么办要写清楚。第三要定期更新流程变了技能文件也要跟着改否则就会误导人。我见过太多团队文档写了一次就再也没更新过最后变成“考古资料”。技能文件如果也这样那就失去意义了。4. 怎么引入这些技能从零开始的配置思路4.1 先搞清楚你的助手支持哪种技能格式在动手之前有一件事必须先确认你用的 AI 助手支持什么样的技能定义方式。不同的平台对 superpowers 的实现不一样有的支持 Markdown 格式的技能文件有的要求用 YAML 或 JSON还有的通过特定的目录结构来识别技能。如果不搞清楚这一点后面写出来的技能文件可能根本加载不了。我的建议是先花十分钟翻一下你所使用平台的官方文档找到“技能”“扩展”“自定义指令”相关的章节。如果文档写得不清楚就找一个最简单的示例照着跑通一遍。跑通之后再开始写自己的技能这样能避免很多低级错误。我一开始就是没看文档凭感觉写了一个技能文件结果格式不对助手完全识别不了白白浪费了一个下午。确认格式之后还要注意技能的存放位置。有的平台要求技能文件放在特定目录下有的支持通过配置文件指定路径。这个细节文档里通常会写但容易被忽略。我建议把技能文件统一放在项目根目录下的一个固定文件夹里比如.skills/或者skills/然后在配置里指向这个目录。这样既方便管理也方便团队共享。4.2 技能文件的编写结构一个可复用的模板虽然不同平台的格式要求有差异但一个技能文件的核心结构是相通的。我总结了一个通用的模板你可以根据自己的平台做调整。# 技能名称 ## 描述 用一两句话说明这个技能是干什么的什么情况下应该使用它。 ## 触发条件 - 当用户提到 xxx 时 - 当任务涉及 xxx 时 ## 前置条件 - 需要先读取 xxx 文件 - 需要确认 xxx 状态 ## 执行步骤 1. 第一步具体操作包含命令或检查项 2. 第二步具体操作说明预期结果 3. 第三步具体操作说明失败时的处理方式 ## 输出格式 说明技能执行完成后应该输出什么最好给一个示例。 ## 注意事项 - 容易出错的地方 - 需要人工确认的环节这个模板看起来简单但每一条都有讲究。“描述”决定了自动匹配的准确率“触发条件”帮助助手判断什么时候该用“前置条件”避免在环境没准备好的情况下执行“执行步骤”是核心“输出格式”保证结果可预期“注意事项”则是把经验沉淀下来。我写自定义技能的时候基本都按这个结构来效果比较稳定。有一点要提醒步骤不要写得太抽象。比如“检查代码质量”这种话助手不知道具体检查什么。要写成“检查所有新增函数是否有对应的单元测试检查所有公共方法是否有文档注释”。越具体执行结果越可控。4.3 引入过程中的常见报错与排查引入技能的过程中最常见的报错有这么几类。第一类是格式错误比如 YAML 缩进不对、Markdown 标题层级混乱。这类问题通常会有明确的报错信息按照提示改就行。第二类是路径错误技能文件放的位置不对或者配置里写的路径和实际不符。第三类是权限问题技能需要读取某些文件或执行某些命令但当前环境没有权限。我遇到过一次比较隐蔽的问题技能文件本身没问题但助手加载的时候总是失败。排查了半天才发现是因为技能文件里引用了一个不存在的文件路径。助手在加载阶段就会去检查这些引用找不到就直接报错。这个问题的教训是技能文件里引用的所有路径和资源都要确保真实存在。写的时候顺手确认一下能省掉很多排查时间。还有一个经验先用一个最简单的技能做测试。不要一上来就写一个包含十几个步骤的复杂技能那样出了问题很难定位。先写一个只有两三个步骤的技能确认能正常加载和执行然后再逐步增加复杂度。这个思路和写代码是一样的先跑通最小闭环再迭代。5. 安装 superpowers不同场景下的操作路径5.1 在本地开发环境中安装如果你是在本地开发环境里使用支持 superpowers 的助手安装过程通常比较简单。核心步骤是找到助手的配置目录创建技能文件夹把技能文件放进去然后在配置里启用技能功能。具体来说大多数工具会在用户主目录下有一个隐藏的配置文件夹比如~/.config/下面某个以工具名命名的目录。你可以在里面创建一个skills文件夹把写好的技能文件放进去。然后打开工具的配置文件找到类似enable_skills或者skills_path的选项设置成对应的值。重启工具之后技能就应该能被识别了。这里有个细节不同操作系统下路径的写法不一样。Windows 用反斜杠macOS 和 Linux 用正斜杠。如果你在配置文件里写路径要注意转义问题。我建议尽量用相对路径或者用工具提供的路径变量这样跨平台兼容性更好。安装完成之后怎么验证技能是否生效我的做法是直接问助手“你现在有哪些可用的技能”如果安装成功助手会列出技能列表。如果列表是空的就说明配置有问题需要回去检查路径和格式。这个验证步骤花不了一分钟但能避免后面很多困惑。5.2 在团队协作场景中部署团队场景下的安装比本地环境要复杂一些因为涉及到技能的统一管理和分发。如果每个人都在自己电脑上维护一套技能文件很快就会版本不一致有人用的是旧版有人用的是新版协作起来反而更乱。我的做法是把技能文件放在项目的代码仓库里和代码一起做版本管理。具体来说在项目根目录下建一个skills/文件夹所有技能文件都放在里面。然后在项目的 README 或者专门的文档里说明怎么配置助手来加载这些技能。新人克隆项目之后按照文档配置一下就能获得和团队一致的技能集。这样做的好处是技能文件的变更可以通过代码审查来管理。谁改了哪个技能、为什么改都有记录可查。而且技能文件和代码在同一个仓库里不会出现“代码更新了但技能没更新”的情况。我们团队用这个方式之后技能文件的维护质量明显提高了因为大家都知道这些文件是要被 review 的。有一点要注意技能文件里不要包含敏感信息。比如数据库密码、API 密钥、内部服务器地址等这些绝对不能写进技能文件。如果某个技能确实需要用到这些信息应该通过环境变量或者单独的配置文件来提供技能文件里只写引用方式。这个原则和写代码是一样的技能文件也是要进仓库的必须当作公开内容来对待。5.3 安装后的验证与首次运行安装完成之后不要急着写复杂技能先做一次完整的验证。我的验证流程是这样的第一步确认助手能列出所有技能第二步选一个最简单的技能手动触发一次看输出是否符合预期第三步选一个涉及文件读取的技能确认权限和路径都没问题第四步如果有技能之间的组合跑一遍完整的流程。这个验证过程大概需要十几分钟但非常值得。我见过太多人安装完就直接开始用结果遇到问题不知道是安装的问题还是技能本身的问题排查起来很痛苦。先把基础验证做扎实后面用起来就顺了。首次运行的时候建议打开详细日志。大多数工具都有日志级别设置把级别调到 debug 或者 verbose能看到技能加载和执行的详细过程。如果某个技能没有按预期触发日志里通常会有线索。这个技巧在排查自动匹配问题时特别有用。6. 实际使用中的经验与避坑指南6.1 技能不是越多越好关键是“可维护”我一开始犯过一个错误觉得技能越多越强大于是把能想到的都写成了技能文件。结果没过多久就发现很多技能根本没用过或者用了一两次就发现写得不好需要改。技能文件多了之后维护成本直线上升改一个地方要确认好几个文件有没有受影响。后来我调整了策略只保留高频使用的技能低频的用的时候再临时写。判断标准很简单如果一个任务我一周内重复做了三次以上就值得写成技能如果一个月才做一次就没必要。按照这个标准筛选之后我的技能库从三十多个精简到了八个但实际效率反而更高了因为每个技能都是经过验证的、真正有用的。另外技能文件也要定期清理。项目流程变了、工具升级了、规范调整了对应的技能文件就要更新或者删除。我现在的做法是每个季度过一遍技能库把过时的删掉把需要改的改掉。这个习惯让技能库始终保持“新鲜”不会变成一堆没人看的死文件。6.2 自动匹配失灵时的手动兜底方案自动匹配虽然方便但确实会出现失灵的情况。有时候是技能描述写得不够准确有时候是当前任务的表述和技能触发条件对不上。遇到这种情况不要死磕自动匹配直接手动调用就行。我的做法是在技能文件里给每个技能起一个简短好记的别名。比如“生成单元测试”这个技能别名就叫“单测”。需要的时候直接说“用单测技能处理这个函数”比等自动匹配快得多。这个别名不需要多正式自己记得住就行。还有一个兜底方案把常用技能的关键步骤直接写在提示词里。比如我经常需要生成符合特定规范的提交信息与其依赖技能匹配不如直接在对话里说“按照 feat/fix/docs 的格式生成提交信息scope 用模块名描述用中文”。这样虽然每次都要打一遍但胜在稳定可靠。对于特别关键的任务我倾向于用这种方式避免因为技能匹配问题导致输出不符合要求。6.3 技能执行失败后的回滚与重试技能执行失败是难免的关键是要有回滚和重试的机制。我在写自定义技能的时候会在每个关键步骤后面加上“如果失败执行某某操作”的说明。比如生成代码失败就回滚到上一个版本部署失败就恢复到之前的配置。对于涉及文件修改的技能我强烈建议先备份再执行。虽然大多数助手在执行修改前会征求确认但批量操作的时候很容易点快了。我的习惯是在执行任何会修改文件的技能之前先手动备份一下相关文件或者确保项目在版本控制之下随时可以回滚。这个习惯帮我避免了好几次“改错了但没法恢复”的尴尬。重试的时候要注意不要盲目重试。如果同一个技能连续失败两次大概率是环境或者输入有问题再试多少次结果都一样。这时候应该停下来检查前置条件是否满足、输入格式是否正确、依赖是否齐全。找到根因再重试比无脑重试有效得多。6.4 把个人经验沉淀成团队技能的方法最后想聊聊怎么把个人经验变成团队可用的技能。这件事的价值很大但做起来需要一点方法。我的经验是先观察自己重复在做什么再把这些重复动作写成技能。具体来说我会记录一周内自己重复执行三次以上的操作。比如“新建一个 API 接口”这个动作我一周做了五次每次都要创建控制器、服务、路由、测试文件步骤基本一样。这就是一个值得写成技能的场景。写的时候把每一步的具体操作、文件路径、命名规则都写清楚再附上一个完整的示例。写完之后先自己用几次确认没问题了再分享给团队。分享给团队之后要收集反馈并迭代。别人用的时候可能会发现你没想到的情况比如某个步骤在特定环境下不适用或者某个检查项太严格了。把这些反馈收集起来定期更新技能文件。我们团队现在有一个简单的机制任何人发现技能文件有问题都可以直接提修改改完之后在群里说一声。这样技能文件就能持续进化而不是写完就扔在那里。还有一点很重要技能文件要写“为什么”。不要只写“执行命令 A”还要写“执行命令 A 是为了检查配置是否生效”。这样别人在用的时候遇到特殊情况能自己判断该怎么调整而不是死板地照做。这个思路和写代码注释是一样的好的注释解释意图而不是重复代码在做什么。7. 关于 superpowers 的一些个人体会用了一段时间 superpowers 之后我最大的感受是它改变的不是 AI 助手的能力上限而是使用助手的效率下限。助手本身能做的事情其实没有因为技能机制而发生质变。但有了技能之后那些原本需要反复解释、反复纠正的环节变得顺畅了很多。这种顺畅带来的效率提升在长期使用中非常可观。另一个体会是技能的质量取决于写技能的人对流程的理解深度。如果一个人自己都没想清楚某个任务该怎么做写出来的技能文件也是模糊的。反过来写技能的过程其实是一次流程梳理逼着你把“凭感觉做”的事情变成“按步骤做”。这个梳理过程本身就有价值哪怕最后不用助手流程也变得更清晰了。当然superpowers 也不是万能的。它适合那些流程相对固定、重复性较高的任务。对于需要大量创造性判断的工作技能能提供的帮助有限。我的做法是把重复性的部分交给技能把创造性的部分留给自己。这样分工之后既享受了自动化的便利又保留了人的判断力。如果你刚开始接触 superpowers我的建议是从一个小技能开始不要贪多。选一个你每天都在做的、步骤明确的任务把它写成技能用一周时间打磨。等这个技能用顺了再考虑加第二个。技能库的积累是一个长期过程急不来。重要的是每个技能都真正有用、真正被用起来而不是躺在文件夹里吃灰。
阅读完成 · 觉得有帮助？
