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 变聪明而是让你自己把那些模糊的、隐性的工作规范想清楚、写下来。写技能的过程其实是在梳理你自己的工作方法。这个价值可能比技能本身还大。 superpowers安装指南：AI编程助手技能扩展框架从入门到实践
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 变聪明而是让你自己把那些模糊的、隐性的工作规范想清楚、写下来。写技能的过程其实是在梳理你自己的工作方法。这个价值可能比技能本身还大。