1. 从“superpowers”这个热词说起：它到底指什么
第一次看到“superpowers”这个词挂在热搜上，我下意识以为是某部新上映的超级英雄电影，或者是某个游戏里新出的技能系统。翻了一圈讨论才发现，大家嘴里的“superpowers”其实指向一个很具体的东西——一套给 AI 编程助手用的技能扩展框架。它的核心思路特别朴素：把那些你反复要跟 AI 解释的流程、规范、检查清单，提前写成一份份“技能包”，等真正干活的时候，AI 自己按需调用，而不是每次都要你从头交代一遍。
这个定位很关键。很多人第一次接触它，脑子里想的是“装个插件让 AI 变聪明”，但实际用下来会发现，它解决的不是“聪明不聪明”的问题，而是“稳不稳定、听不听话”的问题。你让 AI 写代码，它可能这次记得跑测试，下次就忘了；这次按你的命名规范来，下次又自由发挥。superpowers 想干的事，就是把这些“应该做但容易忘”的动作固化下来，变成一套可复用、可组合的技能体系。
那“想要安装 superpowers”这个诉求背后，用户到底在找什么？我观察下来大致分三类人。第一类是已经在用 AI 辅助写代码的开发者，被“每次都要重复交代上下文”折磨得够呛，想找个办法把常用流程沉淀下来。第二类是团队里负责规范落地的人，希望把代码审查、提交规范、测试要求这些东西变成 AI 能自动执行的技能，减少人为遗漏。第三类是纯粹被热词吸引过来的新手，想搞清楚这玩意儿到底值不值得折腾。
这篇文章我打算按“先搞懂它是什么、再动手装、装完怎么用、用的时候踩哪些坑”这条线来写。不管你是哪一类人，看完应该都能判断出这东西适不适合自己的场景，以及如果适合，具体该怎么落地。我会尽量把每一步背后的“为什么”讲清楚，而不是甩一堆命令让你照抄——因为这类工具最大的坑，往往就藏在“照抄但没理解”里面。
2. superpowers 的底层逻辑：技能包机制到底怎么运转
2.1 它和普通插件、提示词模板的本质区别
要理解 superpowers，得先把它和两个容易混淆的东西区分开：普通插件和提示词模板。
普通插件通常是往工具里加功能，比如加个新命令、接个新模型。提示词模板则是你手动复制粘贴一段话给 AI。superpowers 介于两者之间，但机制完全不同——它是一套按需加载的技能库。每个技能是一个独立文件，里面写清楚了“什么情况下用这个技能”“用的时候按什么步骤走”“做完之后怎么验证”。AI 在干活的过程中，会根据当前任务自动判断该不该调用某个技能，而不是你每次手动喂给它。
这个“自动判断”是它最值钱的地方，也是最容易出问题的地方。因为 AI 判断“该不该用某个技能”靠的是技能描述里的触发条件，如果描述写得含糊，它要么该用的时候不用，要么不该用的时候乱用。我后面会专门讲怎么写好这个触发描述。
2.2 技能文件里到底装了什么
一个典型的技能文件，结构上大致包含这几块内容。第一块是元信息，包括技能名称、一句话描述、适用场景。这块决定了 AI 能不能在正确的时机想起它。第二块是执行步骤，也就是这个技能被调用后，AI 应该按什么顺序做什么事。第三块是约束条件，比如“不要修改测试文件”“提交前必须跑 lint”这类硬性要求。第四块是验证方式，告诉 AI 做完之后怎么确认自己没搞砸。
我拿一个真实场景举例。假设你有个技能叫“新增 API 接口”，那它的执行步骤可能是：先看现有接口的目录结构，再按同样的模式建文件，然后补上路由注册，接着写对应的测试用例，最后跑一遍测试确认通过。约束条件可能是“不要动已有的接口文件”“测试用例必须覆盖正常和异常两种情况”。验证方式就是“测试全绿才算完成”。
这套结构看起来简单，但真正写起来，难点在于步骤的颗粒度。写太粗，AI 自由发挥的空间太大，等于没约束；写太细，又变成死板的脚本，遇到稍微不一样的情况就卡住。我的经验是，步骤写到“一个动作一个意图”这个层级比较合适，具体怎么实现留给 AI 判断。
2.3 为什么“按需加载”比“全量塞入”更靠谱
有人可能会想，那我干脆把所有规范、所有流程一次性写进系统提示词里不就行了，何必搞什么按需加载？
这个问题我实测过。把一大堆规范全塞进上下文，有两个直接后果。一是上下文被占满，真正跟当前任务相关的信息反而被挤到边缘，AI 的注意力被稀释。二是规则之间会打架，比如你同时写了“提交前必须跑全量测试”和“小改动快速提交”，AI 遇到具体情况时不知道该听谁的。
按需加载的好处就在这儿：每个技能只在它该出现的时候出现，上下文干净，规则之间也不会互相干扰。代价是你得把技能的触发条件写准，否则该加载的时候加载不出来，那就白搭了。这其实是一种权衡——用“写清楚触发条件”的成本，换“运行时上下文干净”的收益。
3. 安装前的环境盘点：别急着敲命令
3.1 先确认你的 AI 助手支持技能扩展
superpowers 不是独立运行的程序，它依附在某个 AI 编程助手之上。所以安装前第一件事，是确认你用的助手支不支持这类技能扩展机制。不同助手的支持程度差别很大，有的原生支持，有的需要借助配置文件，有的压根不支持。
怎么确认？最直接的办法是翻你所用助手的官方文档，搜“技能”“扩展”“自定义指令”这类关键词。如果文档里明确提到了技能目录、技能文件格式，那基本就没问题。如果翻遍了都找不到，那可能得换个思路，或者考虑换一个支持该机制的助手。
我见过不少人卡在这一步，装了半天发现助手根本不认，白折腾。所以这一步别省，花十分钟确认清楚，比后面返工强。
3.2 目录结构规划：技能放哪儿、怎么分类
确认支持之后，接下来是规划技能存放的目录。这里有个容易被忽略的点：技能目录的位置和结构，直接影响 AI 能不能正确找到并加载技能。
常见的做法是在项目根目录下建一个专门的技能目录，比如.skills或者skills，然后在里面按类别分子目录。比如coding放编码相关技能，review放审查相关技能，deploy放部署相关技能。分子目录不是为了好看，而是为了让技能列表在加载时更有层次，AI 在检索时也更容易定位。
这里有个实操细节：技能文件的命名要能自解释。别用skill1.md、skill2.md这种，用add-api-endpoint.md、run-integration-test.md这种一看就知道干什么的名字。因为 AI 在判断该不该加载某个技能时，文件名和描述都是重要线索，命名清晰能显著提高触发准确率。
3.3 版本与依赖：那些文档里不会写的坑
环境盘点里还有一块是版本和依赖。这块官方文档通常写得比较简略，但实际踩坑最多。
第一个坑是助手版本。技能扩展机制在不同版本里可能有差异，老版本可能不支持某些字段，新版本可能改了文件格式。装之前先确认你的助手版本，然后对照文档看这个版本支持哪些特性。如果版本太老，可能得先升级。
第二个坑是技能文件里的路径引用。如果你的技能步骤里写了“读取./config/settings.json”这种相对路径，那这个路径是相对于项目根目录还是相对于技能文件所在目录，不同助手的行为可能不一样。这个必须实测确认，否则技能执行时会找不到文件。
第三个坑是编码和换行符。技能文件如果是 Windows 下编辑的，可能带 BOM 头或者 CRLF 换行，某些助手解析时会出问题。建议统一用 UTF-8 无 BOM、LF 换行保存。这个坑很隐蔽，出问题时往往报错信息也不明确，排查起来费劲。
4. 一步步把 superpowers 装起来
4.1 获取技能文件：自己写还是用现成的
安装 superpowers 的第一步是搞到技能文件。这里有两条路：用别人写好的现成技能，或者自己从零写。
现成技能的好处是省事，坏处是不一定贴合你的项目。别人的技能里可能写了他自己的目录结构、命名规范、测试框架，直接拿来用，AI 会按那套规范干活，跟你的项目对不上。所以我的建议是，现成技能可以拿来当参考，但真正要用，还是得按自己项目的情况改一遍。
自己写的好处是贴合度高，坏处是前期投入大。不过这个投入是值得的，因为写技能的过程本身，就是把你脑子里那些“隐性规范”显性化的过程。很多人写着写着才发现，原来自己团队里对“什么叫完成”都没有统一标准。
4.2 技能文件的最小可用模板
下面给一个最小可用的技能文件模板，你可以直接拿去改。注意这是通用结构，具体字段名可能因助手而异，以你所用助手的文档为准。
--- name: add-api-endpoint description: 当需要新增一个 API 接口时使用此技能，包括建文件、注册路由、写测试 trigger: 用户要求新增接口、添加路由、创建 endpoint --- ## 执行步骤 1. 查看现有接口目录结构，确认文件组织方式 2. 按现有模式创建新的接口文件 3. 在路由注册文件中添加对应路由 4. 编写测试用例，覆盖正常和异常情况 5. 运行测试，确认全部通过 ## 约束条件 - 不要修改已有的接口文件 - 测试用例必须包含至少一个异常场景 - 提交前必须运行 lint ## 验证方式 - 测试全部通过 - lint 无报错这个模板里，trigger字段是最关键的。它决定了 AI 在什么情况下会想起这个技能。写得太窄，该用的时候用不上；写得太宽，不该用的时候乱用。我的经验是，把用户可能说的几种典型表述都列进去，覆盖常见说法。
4.3 让助手识别技能：配置与验证
技能文件写好后，得让助手知道去哪儿找。这一步通常需要在助手的配置文件里指定技能目录路径。具体配置方式因助手而异，有的是在设置里填路径，有的是在项目配置文件里写。
配置完之后，一定要验证。验证方法是：给助手一个明确会触发某个技能的任务，看它会不会自动加载并执行。比如你有个“新增接口”的技能，那就让助手“帮我加一个查询用户列表的接口”，观察它是不是按你写的步骤走。
如果没触发，先检查三件事：技能目录路径对不对、技能文件的元信息格式对不对、触发描述是不是太窄。这三个是最常见的原因。
4.4 第一次跑通：用一个简单任务验证全流程
别一上来就拿复杂任务试。找个最简单的、你闭着眼睛都能做对的任务，比如“给现有函数加个参数校验”，让助手带着技能跑一遍。
跑的时候重点观察三件事。第一，技能有没有被加载。第二，步骤有没有被遵循。第三，约束有没有被遵守。这三件事里任何一件出问题，都说明技能文件需要调整。
我第一次跑通的时候，发现助手确实加载了技能，但步骤执行到一半就跳步了。后来发现是步骤描述里用了“然后”“接着”这种模糊的连接词，AI 理解成了可选步骤。改成明确的编号列表之后就正常了。这种细节，不实际跑一遍根本发现不了。
5. 装完之后：怎么用才不白装
5.1 技能的组合与嵌套：让多个技能协同工作
单个技能能解决的问题有限，superpowers 真正的威力在于技能组合。比如你有一个“新增接口”的技能，一个“写测试”的技能，一个“代码审查”的技能。理想情况下，新增接口时自动触发写测试，写完测试自动触发审查，形成一条流水线。
但组合有个前提：技能之间的边界要清晰。如果两个技能都声称自己负责“写测试”，那 AI 就懵了。所以设计技能时，要明确每个技能的职责范围，避免重叠。
嵌套则是另一个层面的问题。有的技能步骤里会引用另一个技能，比如“新增接口”的步骤里写“调用代码审查技能”。这种嵌套要小心，因为如果被引用的技能触发条件没写清楚，可能导致无限递归或者加载失败。我的做法是，嵌套层级不超过两层，再深就容易出问题。
5.2 触发时机调优：为什么你的技能该用的时候没动静
技能该触发却没触发，这是最常见的问题。原因通常有三个。
第一个是触发描述太窄。比如你写的是“当用户说‘新增接口’时触发”，但用户实际说的是“加个 API”，那就匹配不上。解决办法是把常见同义表述都列进去。
第二个是技能描述和当前任务的相关度不够。AI 判断该不该加载某个技能，靠的是语义相关度。如果你的技能描述写得太泛，比如“用于处理代码相关任务”，那它跟任何任务的相关度都不高，自然不会被优先加载。描述要具体，最好带上领域关键词。
第三个是技能数量太多导致竞争。如果你有几十个技能，每个的描述都差不多，AI 在检索时就会犹豫。这时候要么精简技能数量，要么把技能分组，让 AI 先选组再选技能。
5.3 技能失效的排查链路
技能突然不工作了，怎么排查？我总结了一条链路，按顺序走基本能定位问题。
第一步，确认技能文件还在、没被误删或改名。听起来很蠢，但确实发生过。
第二步，确认配置文件里的路径没变。有时候项目结构调整了，路径没跟着改。
第三步，确认技能文件的格式没被破坏。比如元信息里的引号没闭合、缩进乱了，都会导致解析失败。
第四步，确认触发条件还能匹配当前任务。如果任务描述变了，可能就不触发了。
第五步，看助手的日志。大多数助手在加载技能失败时会打日志，日志里通常有具体原因。这一步最直接，但很多人忘了看。
5.4 团队协作场景：技能库怎么共享和维护
如果是一个人用，技能库怎么放都行。但如果是团队用，就得考虑共享和维护的问题。
共享方面，技能库最好跟代码一起进版本控制。这样每个人拉下来都是同一套技能，不会出现“你那儿能跑我这儿不能跑”的情况。
维护方面，得有个负责人。技能库跟代码一样，会随着项目演进而过时。如果没人维护，半年后技能里写的规范可能早就跟实际不符了，AI 按过时规范干活，反而添乱。我的建议是，把技能库的更新纳入代码审查流程，改规范的时候顺手把对应技能也改了。
6. 那些我踩过的坑和总结出的经验
6.1 技能写太细反而不好用
刚开始写技能的时候，我恨不得把每个动作都写死，比如“打开文件 A，在第 10 行插入代码 B”。结果发现，只要项目结构稍微一变，技能就失效了。后来我改成写意图而不是写动作，比如“在路由注册文件中添加对应路由”，具体在哪个文件、哪一行，让 AI 自己判断。这样灵活度高很多，适应性也强。
这个经验的核心是：技能应该描述“做什么”和“为什么”，而不是“怎么做”。怎么做留给 AI，因为 AI 比你更了解当前代码的具体情况。
6.2 约束条件写太硬会卡死流程
约束条件是必要的，但写太硬会出问题。我写过一个约束叫“提交前必须跑全量测试”，结果有次改了个注释，AI 也老老实实跑了半小时全量测试。后来我改成“提交前必须跑与改动相关的测试”，效率高多了。
约束条件的度怎么把握？我的标准是：约束应该防的是“错误行为”，而不是“所有行为”。跑全量测试防的是“没测试就提交”，但改注释这种情况本来就不需要全量测试，约束不该一刀切。
6.3 技能版本管理：改了之后怎么回滚
技能文件也是代码，改了之后可能出问题，所以需要版本管理。最土的办法是每次改之前手动备份一份，但太麻烦。正规做法是跟代码一起进 Git，每次改动都有记录，出问题直接回滚。
这里有个细节：技能文件的改动最好单独提交，别跟业务代码混在一起。这样回滚的时候不会误伤业务代码，排查问题也清晰。
6.4 什么时候该放弃某个技能
不是所有技能都值得保留。如果一个技能满足下面任意一条，我会考虑删掉它：触发率极低、每次触发都要手动纠正、维护成本高于收益、跟其他技能功能重叠。
技能库跟代码库一样，需要定期清理。留着不用的技能，不仅占地方，还会干扰 AI 的判断。我一般每个月过一遍技能库，把一个月内没触发过的技能标记出来，连续两个月没触发就删掉。
6.5 给新手的三个务实建议
如果你刚开始接触 superpowers，我给三个建议。
第一，从一个小技能开始，别一上来就搞一套完整的技能体系。先写一个你每天都要重复交代的流程，跑通了再扩展。
第二，技能描述用你自己的话写，别抄别人的。因为 AI 匹配的是语义，用你自己的表述习惯写，触发准确率更高。
第三，每次技能没按预期工作，都当成一次学习机会。记录下当时的情况、你的预期、实际结果，积累多了你就能摸清 AI 的脾气，写出来的技能也越来越准。
这套东西说到底，不是让 AI 变聪明，而是让你自己把那些模糊的、隐性的工作规范想清楚、写下来。写技能的过程，其实是在梳理你自己的工作方法。这个价值，可能比技能本身还大。
