1. 从“超能力”到可复用技能superpowers 到底在解决什么问题第一次听到 “superpowers” 这个词很多人会以为是某个游戏里的技能系统或者某个超级英雄题材的项目。但如果你最近在开发者社区、效率工具圈或者 AI 编程助手的讨论里频繁看到它那它大概率指的是一个更具体的东西一套给 AI 编程助手用的“技能包”体系。简单说它试图回答一个很实际的问题——我们每天都在用 AI 帮自己写代码、改配置、查问题但每次都要重新解释一遍“我是谁、我的项目长什么样、我习惯用什么工具”这种重复劳动能不能被固化下来变成一套可以随时调用的“超能力”这就是 superpowers 的核心价值。它不是某个单独的软件也不是一个需要你从头学起的新语言而是一组围绕 AI 助手工作流的技能定义、引入方式和调用规范。你可以把它理解成给 AI 助手装上的“技能插件”当你需要它帮你做代码审查时它知道你的审查清单是什么当你需要它帮你写提交信息时它知道你的团队规范是什么当你需要它帮你排查一个构建错误时它知道你的项目结构和技术栈是什么。这些“知道”就是 superpowers 想要沉淀下来的东西。我最初接触这个概念的时候第一反应是这不就是把 prompt 模板化吗但实际用下来发现它比单纯的 prompt 模板要深一层。普通的 prompt 模板是“你问一句它答一句”而 superpowers 更像是一套“技能注册机制”——你先告诉 AI 助手“我有哪些技能可用”然后在具体场景里它会根据上下文自动判断该调用哪个技能或者至少让你用更短的指令触发更复杂的操作。这个差别就像你手机里装了一堆 App和手机系统自带一个“场景建议”功能的区别。适合看这篇内容的人大概分三类。第一类是已经在用 AI 编程助手比如各种代码补全、对话式编程工具的开发者觉得自己每次都要重复交代背景效率还有提升空间。第二类是团队里的技术负责人想给团队统一一套 AI 协作规范让不同人用 AI 产出的代码风格、提交信息、审查标准尽量一致。第三类是对“技能包”这个概念好奇想先搞清楚它到底怎么引入、怎么用、值不值得投入时间折腾的人。不管你是哪一类接下来的内容都会从实际操作的视角把 superpowers 的引入方式、技能结构、常见坑和排查技巧讲清楚。2. 核心思路拆解为什么是“技能包”而不是“大而全的配置”2.1 从“每次重新解释”到“一次定义、多次调用”在没有 superpowers 这类机制之前大多数人用 AI 助手的方式是这样的打开对话框输入“帮我看看这段代码有什么问题”然后 AI 回复一堆通用建议。你觉得不够具体于是补充“我们项目用的是 TypeScript严格模式不允许 any”AI 再调整。下次你换一个文件又要把同样的话再说一遍。这种交互模式的问题不在于 AI 不够聪明而在于“上下文”没有被沉淀下来。superpowers 的思路是把这些上下文拆成一个个独立的“技能单元”。每个技能单元包含三部分触发条件什么时候用这个技能、执行逻辑这个技能具体做什么、输出规范结果应该长什么样。比如一个“代码审查”技能触发条件可能是“用户要求审查代码”或“检测到代码变更”执行逻辑是“按照团队清单逐项检查”输出规范是“按严重程度分级列出问题并给出修改建议”。这样一来你不需要每次都说“帮我审查代码注意 TypeScript 严格模式检查命名规范检查错误处理”只需要说“用代码审查技能看一下这个文件”剩下的交给技能定义去完成。这种拆法的好处很明显技能可以复用、可以组合、可以单独迭代。你今天觉得审查清单里少了一条“检查日志是否包含敏感信息”只需要改那个技能的定义所有调用这个技能的场景都会自动生效。这比每次在对话里补一句要高效得多也比维护一个巨大的“全局配置”要灵活——毕竟不是每个场景都需要所有规则。2.2 技能粒度怎么定太粗不好用太细管不过来在实际引入 superpowers 的过程中最容易踩的坑就是技能粒度定得不对。我见过有人把“写代码”定义成一个技能结果这个技能内部要处理几十种情况最后变得比不用还复杂。也见过有人把“变量命名”单独定义成一个技能导致每次写代码都要调用十几个技能维护成本极高。比较合理的粒度我自己的经验是“一个技能对应一个明确的动作或检查项”。比如“生成提交信息”是一个技能“检查提交信息格式”是另一个技能“根据变更内容推荐提交类型”又是一个技能。这三个技能可以独立使用也可以串起来用。再比如“排查构建错误”可以是一个技能它内部会调用“读取错误日志”“匹配常见错误模式”“给出修复建议”这几个子步骤但对外只暴露一个入口。这样既不会太粗也不会太细。还有一个判断标准如果一个技能的定义超过一屏大概 30 到 50 行那大概率需要拆。因为太长的技能定义AI 在调用时容易丢失重点你自己维护起来也费劲。反过来如果一个技能的定义只有一两行那它可能更适合作为另一个技能的子步骤而不是独立技能。2.3 引入方式的选择全局引入还是项目级引入superpowers 的引入方式目前常见的有两种全局引入和项目级引入。全局引入是指把技能定义放在用户级别的配置目录里所有项目都能用。项目级引入是指把技能定义放在项目仓库里只对这个项目生效。这两种方式没有绝对的好坏关键看你的使用场景。如果你有一套通用的个人习惯比如“我写任何项目都要求提交信息用英文、代码注释用中文”那这些习惯可以做成全局技能。如果你有一些项目特有的规范比如“这个项目用 Jest 不用 Vitest”“这个项目的 API 路径必须以 /api/v2 开头”那这些就应该做成项目级技能。我自己的做法是“全局放通用技能项目级放专属技能项目级可以覆盖全局”。比如我有一个全局的“代码审查”技能定义了通用的审查清单然后在某个具体项目里我再定义一个同名的项目级技能在里面补充这个项目特有的检查项。这样既保持了通用性又兼顾了特殊性。需要注意的是不同工具对“覆盖”的支持程度不一样有些工具会合并有些会替换引入之前最好先确认一下具体行为。3. 核心细节解析superpowers 的技能结构长什么样3.1 一个技能定义通常包含哪些字段虽然不同工具、不同版本的 superpowers 实现细节可能有差异但一个典型的技能定义通常包含这几个核心字段名称、描述、触发条件、执行步骤、输出格式、依赖项。名称是技能的标识符一般用英文短横线命名比如code-review、commit-message。描述是一句话说明这个技能做什么方便在技能列表里快速浏览。触发条件决定了什么时候这个技能会被调用可以是一个关键词、一个命令、或者一个上下文匹配规则。执行步骤是技能的核心通常是一组有序的操作说明。比如“代码审查”技能的执行步骤可能是第一步读取目标文件内容第二步按照清单逐项检查第三步对每个问题标注严重程度第四步输出审查报告。输出格式定义了结果的结构比如“用 Markdown 表格列出问题、位置、严重程度、建议”。依赖项是指这个技能是否需要其他技能或工具的支持比如“代码审查”可能依赖“读取文件”这个基础技能。这里要特别说一下触发条件的设计。很多新手会把触发条件写得太宽泛比如“当用户提到代码时触发”结果导致技能被频繁误触发反而干扰正常对话。比较好的做法是让触发条件尽量具体比如“当用户输入/review命令时触发”或者“当用户明确说‘审查这段代码’时触发”。如果你用的工具支持自动匹配那也要给一个明确的匹配规则而不是让 AI 自己猜。3.2 技能之间的组合与调用关系superpowers 真正强大的地方不在于单个技能有多厉害而在于技能之间可以组合。比如你可以定义一个“完整代码提交”技能它内部依次调用“检查代码风格”“运行测试”“生成提交信息”“创建提交”这四个子技能。对外你只需要说“帮我提交这次变更”剩下的交给组合技能去编排。这种组合关系通常有两种形式串行和并行。串行就是前一个技能的输出作为后一个技能的输入比如“生成提交信息”需要先“读取变更内容”。并行就是多个技能同时执行最后汇总结果比如“代码审查”可以同时检查命名规范、错误处理、日志安全最后合并成一份报告。实际使用中串行更常见因为大多数操作有先后依赖关系。设计组合技能的时候有一个经验法则尽量让每个子技能保持“无状态”。也就是说子技能不应该依赖上一次调用的结果而应该每次从输入中获取所需信息。这样做的好处是子技能可以独立测试、独立复用不会因为调用顺序变化而出错。如果确实需要共享状态那最好把状态显式地作为参数传递而不是藏在某个全局变量里。3.3 技能定义的存放位置与加载顺序技能定义放在哪里直接决定了它什么时候被加载、被谁加载。常见的存放位置有三种用户主目录下的配置文件夹、项目根目录下的特定文件夹、以及工具自带的技能市场或仓库。用户主目录下的技能对所有项目生效项目根目录下的技能只对当前项目生效工具自带的技能通常需要先安装再使用。加载顺序也很关键。一般来说工具会按照“工具自带技能 → 用户全局技能 → 项目级技能”的顺序加载后面的可以覆盖前面的。但有些工具是反过来的或者只加载第一个匹配的技能。我踩过的一个坑是在项目里定义了一个和全局同名的技能以为会覆盖结果工具把两个技能都加载了导致同一个操作被执行了两次。后来查了文档才发现那个工具的同名技能是“合并”而不是“替换”需要在项目技能里显式声明“忽略全局同名技能”才行。所以引入技能之前一定要先搞清楚你用的工具是怎么处理同名技能的。如果不确定最简单的办法就是给项目级技能起一个不同的名字比如全局叫code-review项目级叫code-review-strict这样就不会有冲突。虽然名字长一点但省去了排查冲突的时间。4. 实操过程怎么一步步把 superpowers 引入到自己的工作流4.1 环境准备确认你的工具支持哪种引入方式在开始引入之前第一件事是确认你正在使用的 AI 编程助手支持哪种技能引入方式。目前市面上常见的支持方式有几种一种是基于配置文件的你需要手动编辑一个 JSON 或 YAML 文件把技能定义写进去一种是基于目录扫描的你只需要把技能文件放到指定目录工具会自动加载还有一种是基于命令的你通过特定命令来注册和调用技能。确认方式很简单打开你所用工具的官方文档搜索“skills”“custom instructions”“extensions”这类关键词。如果文档里提到了技能目录、技能文件格式、技能加载顺序那说明它支持类似 superpowers 的机制。如果文档里只有“自定义指令”这种单一入口那可能不支持多技能组合但你仍然可以用类似思路把常用指令拆成多个片段手动切换使用。我自己的环境是 macOS 加 VS Code用的工具支持目录扫描方式。技能文件放在~/.config/ai-assistant/skills/下面每个技能一个 Markdown 文件文件名就是技能名。工具启动时会扫描这个目录把所有.md文件加载成可用技能。项目级的技能放在项目根目录的.ai-skills/文件夹里加载时会覆盖同名的全局技能。这个结构我用了大半年整体比较稳定。4.2 编写第一个技能从“提交信息生成”开始如果你是第一次接触 superpowers我建议从“提交信息生成”这个技能开始。原因有三个第一这个场景足够简单不需要复杂的上下文第二它每天都会用到能快速感受到效率提升第三它的输出格式很明确容易验证对错。下面是我自己用的一个提交信息生成技能的定义示例你可以直接参考--- name: commit-message description: 根据变更内容生成符合 Conventional Commits 规范的提交信息 trigger: 当用户要求生成提交信息或执行提交操作时 --- ## 执行步骤 1. 读取当前暂存区的变更内容git diff --staged 2. 分析变更类型新增功能、修复缺陷、重构、文档、测试、构建、其他 3. 分析变更范围根据文件路径判断影响的模块 4. 生成提交信息格式为type(scope): subject 5. 如果变更较大在 body 中补充详细说明 ## 输出格式 - 第一行type(scope): subject不超过 72 个字符 - 空一行 - body每行不超过 80 个字符说明变更原因和影响 - 如果有破坏性变更在 footer 中标注 BREAKING CHANGE ## 注意事项 - type 只能从以下选择feat, fix, refactor, docs, test, build, chore - subject 用祈使句首字母小写结尾不加句号 - 如果变更涉及多个类型选择影响最大的那个这个技能定义不算长但包含了核心要素触发条件、执行步骤、输出格式、注意事项。你把它保存成commit-message.md放到技能目录里然后对 AI 助手说“帮我生成提交信息”它就会按照这个定义来执行。实测下来生成的信息比我手写的更规范而且不会漏掉 scope 和 body。4.3 技能调试怎么确认技能被正确加载和调用技能写完之后下一步是确认它真的被加载了。不同工具的确认方式不一样有的会提供一个“列出所有技能”的命令有的会在启动日志里打印加载的技能列表。如果找不到这些信息可以做一个简单的测试故意在技能定义里写一个明显的错误比如把输出格式改成“用 JSON 输出”然后调用这个技能看 AI 是否按照错误定义执行。如果执行了说明技能被加载了如果没执行说明技能没被加载或者触发条件没匹配上。触发条件没匹配上是很常见的问题。比如你定义的触发条件是“当用户要求生成提交信息时”但你实际说的是“帮我写个 commit message”AI 可能因为语言不匹配而没有触发技能。解决办法是把触发条件写得更宽松一些或者同时包含中英文关键词。我自己的习惯是触发条件里至少包含三种表达方式中文正式说法、中文口语说法、英文说法。这样不管怎么问都能匹配上。还有一个调试技巧在技能定义里加一个“调试输出”步骤比如“在开始执行前先输出一行[skill: commit-message] 已触发”。这样每次调用技能时你都能在对话里看到这行提示确认技能确实被触发了。等技能稳定运行之后再把这行删掉。这个方法虽然土但非常有效尤其是在排查“为什么技能没生效”的时候。4.4 从单技能到技能组合搭建自己的技能流水线当你有了几个独立技能之后就可以尝试把它们组合起来形成一条“技能流水线”。比如我日常的代码提交流水线是这样的先调用“代码审查”技能检查变更再调用“运行测试”技能确认测试通过然后调用“生成提交信息”技能生成信息最后调用“创建提交”技能完成提交。这四个技能可以单独使用也可以串起来用。串起来的方式有两种一种是在对话里依次说“先审查代码再运行测试然后生成提交信息最后提交”AI 会按顺序调用另一种是定义一个“完整提交流程”的组合技能把四个子技能写进去对外只暴露一个入口。我两种都用日常小变更用第一种快速灵活正式发布用第二种确保每一步都不遗漏。组合技能的定义里关键是要写清楚子技能的调用顺序和依赖关系。比如“生成提交信息”必须在“代码审查”之后因为审查可能会发现需要修改的地方修改后变更内容会变提交信息也要跟着变。如果顺序写反了生成的提交信息可能和最终代码不一致。这个坑我踩过一次后来在组合技能里加了一条“如果审查后有修改重新生成提交信息”的规则才解决。5. 常见问题与排查技巧实录5.1 技能不生效从触发条件到加载顺序的排查清单技能不生效是最常见的问题原因可能有很多。我整理了一个排查清单按照从简单到复杂的顺序排列你可以逐项检查排查项检查方法常见原因技能文件是否存在查看技能目录下是否有对应文件文件名拼写错误、放错目录文件格式是否正确检查 frontmatter 是否完整、YAML 是否合法缺少---分隔符、缩进错误触发条件是否匹配用触发条件里的关键词重新提问关键词不匹配、语言不一致技能是否被覆盖检查是否有同名技能在更高优先级目录项目级技能覆盖了全局技能工具是否支持查看工具文档中的技能加载说明工具版本过旧、不支持该机制加载顺序是否正确查看启动日志中的技能加载列表加载顺序导致预期技能被跳过这个清单我用了很多次基本上 90% 的问题都能在前三项里找到原因。剩下 10% 通常是工具本身的限制比如某些工具只支持全局技能不支持项目级技能或者只支持特定格式的技能文件。遇到这种情况要么升级工具版本要么换一种引入方式。还有一个容易被忽略的点技能文件的编码格式。我有一次在 Windows 上编辑技能文件保存成了 GBK 编码结果工具读取时乱码技能一直加载失败。后来改成 UTF-8 就好了。如果你在 Windows 和 macOS 之间同步技能文件一定要注意编码问题统一用 UTF-8。5.2 技能冲突同名技能、重复触发、输出格式打架技能冲突是第二个常见问题通常有三种表现同名技能导致行为不确定、多个技能同时触发导致输出混乱、不同技能的输出格式互相打架。同名技能的问题前面提过解决办法是给项目级技能起不同的名字或者在项目技能里显式声明覆盖关系。重复触发的问题通常是因为触发条件写得太宽泛导致一个操作同时匹配了多个技能。比如你有一个“代码审查”技能和一个“代码格式化”技能两者的触发条件都包含“检查代码”那你说“检查一下这段代码”时两个技能可能都会触发。解决办法是让触发条件更具体比如“代码审查”用“审查”“review”作为关键词“代码格式化”用“格式化”“format”作为关键词避免重叠。输出格式打架的问题通常出现在组合技能里。比如“代码审查”技能输出 Markdown 表格“生成报告”技能输出 JSON两者组合时AI 可能不知道该用哪种格式。解决办法是在组合技能里明确指定最终输出格式或者在子技能里约定统一的中间格式。我自己的做法是所有子技能都输出 Markdown组合技能最后再决定是否转换成其他格式。这样中间过程统一不容易乱。5.3 性能问题技能太多导致响应变慢怎么办当你积累了几十个技能之后可能会发现 AI 助手的响应速度变慢了。原因通常是工具在每次请求时都要加载和匹配所有技能技能越多匹配时间越长。这个问题在技能数量超过 50 个之后会比较明显。解决办法有几个。第一把不常用的技能归档只在需要时临时启用。比如一些季度才用一次的技能可以放到一个archived子目录里工具默认不加载需要时再手动移回来。第二合并功能相近的技能。比如你有“检查命名规范”“检查注释规范”“检查错误处理”三个技能可以合并成一个“代码规范检查”技能内部再分步骤执行。第三使用技能分组把技能按场景分成“日常开发”“代码审查”“发布流程”几组工具只加载当前场景需要的组。我自己的技能库目前有 30 多个技能响应速度还可以接受。我的做法是每季度清理一次把过去三个月没用过的技能归档。归档之前会先看一下技能定义如果里面的规则已经过时了就直接删掉如果还有用就移到归档目录。这样技能库始终保持精简不会无限膨胀。5.4 技能迭代怎么根据实际使用反馈优化技能定义技能定义不是写一次就完事的需要根据实际使用反馈不断迭代。我通常从三个来源收集反馈自己的使用体验、团队成员的反馈、以及 AI 执行技能时的“意外行为”。自己的使用体验是最直接的。比如我发现“生成提交信息”技能经常把refactor和chore搞混就在技能定义里加了一条更明确的判断规则“如果变更只涉及代码结构调整而不改变外部行为用 refactor如果变更涉及构建配置、依赖升级、工具配置用 chore。”加了这条之后准确率明显提升。团队成员的反馈也很重要。有一次同事说用我的“代码审查”技能时AI 总是漏掉“检查是否有未处理的 Promise rejection”。我检查了技能定义发现审查清单里确实没有这一项于是补了上去。后来另一个同事又建议加上“检查是否有硬编码的密钥”我也补上了。现在这个审查清单已经迭代了七八个版本比最初完善了很多。AI 的“意外行为”是最有价值的反馈来源。有时候 AI 会以一种你没想到的方式执行技能结果反而更好。比如我定义“生成提交信息”技能时只要求输出 type、scope、subject但 AI 有时候会额外输出一个“影响范围”的说明。我觉得这个说明很有用就把它正式加到了输出格式里。所以每次看到 AI 的意外行为不要急着纠正先想想是不是自己的技能定义可以改进。6. 我个人的实操心得与几个小技巧6.1 技能命名用“动词名词”而不是“名词动词”技能命名看起来是小事但实际影响很大。我试过用“名词动词”的命名方式比如code-review、commit-generate后来发现调用时容易混淆因为 AI 有时候会把code-review理解成“审查代码”这个动作有时候理解成“代码审查报告”这个产物。后来改成“动词名词”的方式比如review-code、generate-commit语义就清晰多了AI 每次都能正确理解。这个经验来自一个更底层的原则技能名应该描述“做什么”而不是“是什么”。review-code描述的是动作code-review描述的是概念。动作比概念更容易被 AI 正确执行。同样的道理check-format比format-check好run-tests比test-runner好。虽然只是词序调换但实际使用中的准确率差别很明显。6.2 技能描述一句话说清楚“什么时候用”和“用了会怎样”技能描述是 AI 决定是否调用技能的重要依据。我见过很多技能描述写得很模糊比如“这个技能用于处理代码相关的事情”结果 AI 根本不知道什么时候该用。好的技能描述应该包含两个信息什么时候用触发场景和用了会怎样预期结果。比如“生成提交信息”技能的描述我写的是“当用户完成代码变更并需要提交时使用会根据变更内容生成符合 Conventional Commits 规范的提交信息。”这句话里“当用户完成代码变更并需要提交时”是触发场景“生成符合规范的提交信息”是预期结果。AI 读到这个描述就能判断出什么时候该调用这个技能以及调用后会得到什么。还有一个技巧在描述里加入“不适用场景”。比如“这个技能不适用于生成发布说明发布说明请使用generate-release-notes技能。”这样可以避免 AI 在错误的场景下调用技能。虽然多写一句话但能减少很多误触发。6.3 技能测试用“边界用例”验证技能的鲁棒性技能写完之后除了正常场景测试还要用边界用例测试。比如“生成提交信息”技能正常场景是“修改了一个文件的一行代码”边界用例包括修改了 100 个文件、修改了二进制文件、修改了空文件、修改了只有空白字符变化的文件、同时包含新增和删除的文件。这些边界情况在实际工作中都会遇到如果技能定义没有考虑到AI 执行时就会出错。我自己的测试方法是准备一组“测试变更”每个变更对应一个边界用例然后依次调用技能看输出是否符合预期。不符合预期的就回去修改技能定义。这个过程比较耗时但一次投入之后技能就稳定了后面几个月都不用再改。比起每次遇到问题再临时修提前测试更省时间。6.4 技能分享怎么把技能包同步给团队成员如果你在团队里推广 superpowers技能分享是绕不开的一步。我的做法是把项目级技能放在项目仓库的.ai-skills/目录里和代码一起版本控制。团队成员拉取代码后技能自动生效不需要额外配置。全局技能则通过一个内部文档分享每个人根据自己的习惯选择性引入。分享技能时最重要的是写清楚“这个技能解决什么问题”和“怎么验证它生效了”。我通常会在技能文件开头加一段注释说明技能的用途、适用场景、以及一个简单的验证方法。比如“生成提交信息”技能的注释里会写“验证方法对任意变更调用此技能检查输出是否符合type(scope): subject格式。”这样团队成员引入技能后能快速确认是否生效。还有一个经验不要一次性分享太多技能。我一开始把 20 多个技能全部分享给团队结果大家不知道从哪个开始用反而没人用。后来改成“每次分享 3 个最常用的技能”并附上使用示例采用率明显提高。现在团队里最常用的三个技能是“生成提交信息”“代码审查”“排查构建错误”这三个也是我建议新手最先引入的技能。