过去大半年我一直在跟 AI 协作工具打交道最头疼的事情不是它不会干活而是它每次干活的方式都不一样。同一个需求上午它能给你结构清晰的结果下午换个说法它就自由发挥得让我怀疑人生。后来我在一个开源社区项目里遇到了 Superpowers它不是普通意义上的插件也不是给你一堆新鲜提示词模板而是把“做一件事的完整方法”打包成可复用的技能。我用了大约三个月才真正摸清楚它的安装、技能清单、引入方式和各种坑。这篇文章把我从“听说”到“日常离不开”的全过程写出来希望能帮那些正被 AI 输出不稳定折磨的人少走一段弯路。1. Superpowers 到底解决了什么问题从“能聊天”到“能干活”1.1 技能和普通提示词的本质区别先说结论提示词是“这一次怎么做”技能是“每一次都怎么做”。很多人误以为把一段写好的提示词收藏起来就等于拥有了一个技能。其实差的非常远。我在早期就是这么干的收藏了几十段“金句提示词”真正用的时候发现今天的对话上下文和收藏那一刻完全不同。提示词里没有告诉 AI “你第一步该收集什么信息”“第二步按什么顺序输出”“最后要检查哪些点”所以 AI 只是表面听话底层的思考路径还是乱的。Superpowers 这种技能包的思路不太一样。它的核心单元叫 skill一个 skill 就是一套结构化的操作手册。AI 读到这份手册之后会知道自己在什么场景下被触发需要先向用户确认哪些信息按什么步骤执行任务最后以什么格式交付结果完成之后还要做哪些自检。简单类比一下提示词像你临时跟新手员工说“把这份报告写一下”技能则像给老员工发一张任务卡卡片上写着需求背景、输入材料、输出格式、验收标准。同样是干活后者的稳定程度完全不一样。1.2 设计思路拆解为什么这样设计有效我后来翻过 Superpowers 的技能文件发现它的核心设计逻辑非常朴素把隐性的做事方法显性化。真人带新人时会反复说“你先确认需求、再列大纲、再动手写”这些话都存在于师傅的脑子里。AI 没有这种长期记忆你不在每次对话里重复它就不知道。技能文件做的事情就是把这些隐性的工作方法写成 AI 可读的规则每次触发时自动加载进上下文。具体到文件层面一个技能通常包含几个关键部分触发条件告诉 AI 什么时候该主动使用它输入要求告诉 AI 缺什么信息时需要追问执行步骤把任务拆成几个固定阶段输出格式让结果保持统一。其中最有价值的是自检清单AI 交付完结果后会对照清单再过一遍这一步能直接把错误率压下去一截。1.3 适合谁用以及使用前提从我自己的经验看有三类人最适合接触这套东西正在用 AI 辅助开发或写文档但觉得结果质量忽高忽低的人。团队里想把内部规范和 AI 工具结合起来减少反复纠正成本的人。需要把个人经验沉淀下来不想每次从零开始指挥 AI 的人。使用前提也比较明确。第一你已经有一定使用 AI 工具的习惯知道什么时候该让它干活第二你愿意花一点时间整理自己的做事流程第三你手头有真实、重复出现的任务类型。如果每次任务都是全新创意技能反而会显得有些多余。这套东西天然是为“有节奏、成体系”的工作设计的。2. 安装 Superpowers三种方式、五个验证步骤2.1 安装前先做的环境检查很多人在安装阶段就翻车原因不是步骤复杂而是环境没确认清楚。我建议你先花两分钟做三个检查。第一确认 AI 工具的版本号建议升级到当前稳定版旧版本对技能文件语法的解析可能不完整。第二确认系统里有没有已经存在的同名技能如果你之前手动放过同名目录新装的版本会跟它打架。第三确认配置目录是否有写入权限特别是用 Linux 服务器或者公司统一管理的电脑时权限问题会表现成“安装了但加载不了”。这三个检查做下来能过滤掉后面至少一半的问题。千万别跳过直接跑到喝咖啡环节回头找不到技能时更耽误时间。2.2 方法一通过包管理器安装对多数人来说最省事的安装方式就是走包管理器。以常见的 npm 为例在终端里执行npm install -g superpowers superpowers doctor第一行完成安装第二行是对当前环境做体检。doctor这个命令会检查配置目录、技能目录、依赖版本和语法解析这几项如果哪一项有问题它会直接把原因打印出来。如果你是老版本升上来建议先卸载再装npm uninstall -g superpowers npm install -g superpowers不要直接在旧版本上覆盖我踩过这个坑。旧版本残留的配置文件会导致新版本加载出来的技能有一半是坏的而且报错还特别迷惑。2.3 方法二手动克隆到配置目录如果你用的是便携版工具或者公司网络环境不允许随意全局安装可以走手动放置的方式。核心思路是把技能仓库克隆到工具默认扫描的配置目录里mkdir -p ~/.config/superpowers git clone 你的技能仓库地址 ~/.config/superpowers/skills superpowers list这种方式的好处是你能直接看到技能源文件修改起来很直观对想二次开发的人特别友好。缺点是以后更新需要自己手动拉代码不能像包管理器那样一条命令解决。我的建议是个人使用用包管理器团队内部分享用手动克隆到项目目录后面这种场景待会儿细说。2.4 方法三项目内嵌安装第三种方式适用于团队项目。思路是在项目根目录建一个.superpowers目录把团队需要的技能放进去随仓库一起提交。新同事克隆项目之后就自带技能环境不需要额外操作。常见的做法是mkdir -p .superpowers/skills # 把技能文件按领域分目录放好例如 # .superpowers/skills/review/ # .superpowers/skills/plan/ # .superpowers/skills/doc/ git add .superpowers git commit -m add team superpowers skills这种方式的最大价值是规范统一。团队几十个人用同一套技能生成的文档、代码审查意见、方案结构都会往一个方向收敛。代价是更新技能要走一次代码评审流程不能随时想改就改。所以我觉得最合理的定位是全局目录放个人习惯项目目录放团队规范两者互不干扰。三种方式的适用场景我整理成了下面这个表方便你直接对照安装方式适合场景优点主要成本包管理器安装个人日常使用一条命令安装更新不支持自定义深度修改手动克隆想改源码、个性化配置完全可控更新需要手动操作项目内嵌团队协作、统一规范成员零成本同步更新走代码评审流程2.5 安装后必做的五个验证步骤装完不等于能用我每次在新环境部署完都会按下面这个清单过一遍执行superpowers list确认技能列表已经出现。执行superpowers doctor确认配置文件没有语法警告。用一句最简单的对话触发某个技能比如“使用 review 技能检查这段代码”看它是否真的进入了对应流程。打开工具日志看技能加载过程里有没有被跳过的文件。确认当前会话没有因为旧缓存导致异常必要时重启一个会话再测。这套验证流程十分钟内能跑完但能把后边使用阶段的神秘问题消灭大半。我见过太多人装完不验证直接拿真实任务来试结果技能没触发还以为自己配置写错了折腾半天发现只是缓存没刷新。3. 技能清单拆解Superpowers 到底带了哪些 skills3.1 规划与拆解类技能先讲我最常用的一类规划类。这类技能解决的核心问题是“把模糊需求变成可执行任务”。以plan这个技能为例它的典型触发场景是你说出“做个方案”“规划一下”“怎么实现”这类话。技能加载后AI 不会直接甩给你一段答案而是先反问你几个关键问题需求背景是什么目标用户是谁有没有明确的时间节点有没有约束条件信息补齐之后它才会按照“背景-目标-方案选项-风险-里程碑”的结构输出。还有brainstorm技能适合做创意发散。它跟plan正好相反不会急着收敛而是要求你批量提供几个方向然后对每个方向给出可能性评估。我通常在项目早期用它效果比直接问“你有什么想法”好得多因为它强制要求数量逼着 AI 给出多套方案再谈取舍。3.2 代码与工程质量类技能再讲开发环节里价值最直接的几类代码审查、测试生成、重构、提交信息规范化。review技能在团队协作里用得最多。你把一段 diff 或者一个文件丢给它它会按预设的检查点逐项审查比如潜在的空指针、边界条件、命名一致性、异常处理是否完整。最关键的还是审查完会输出一张问题清单每一条都对应具体代码位置和修改建议而不是泛泛说“这段代码可以优化一下”。test技能用来补单元测试。它先分析被测函数的外部依赖、边界输入和预期行为再按“正常路径-边界值-异常输入”的思路生成测试用例。生成的代码质量取决于你给它喂的信息量建议把函数签名、关键逻辑、你对哪些行为最担心都写清楚。commit技能是我个人很喜欢的它能按团队规定的格式把代码改动生成提交信息。以前我写 commit message 全靠缘分现在技能会读取 diff归纳出“做了什么-为什么做-影响范围”填进模板。虽然是一件小事但坚持用之后翻提交历史的效率高了很多。3.3 文档与知识管理类技能最后一类是我这个写文档重度用户的救星文档和知识处理技能。explain技能适合拿来解读复杂代码段。注意它跟 review 不同explain 的目标是让读的人理解所以输出风格是“整体流程-关键函数-调用链-易错点”你可以指定读者背景是新人还是资深工程师讲解深度完全不一样。doc技能负责生成技术文档比如 API 文档、使用说明、设计文档的初稿。它会先跟你确认目标读者和文档类型再按固定结构输出。我自己的体验是这类技能生成的初稿比我自己从零写快了三倍但你一定要记得后续人工校对技能能保证格式和逻辑框架却无法保证产品判断这一个层面。还有summary技能用来压缩长内容。你给它一份会议纪要或者一篇文章它能按指定的重点比例重新组织内容。3.4 技能类目速查表把上面这些技能按“类别-技能名-典型触发词-典型输出”整理一下类别技能名典型触发词典型输出规划类plan方案、规划、实现思路带背景、目标、里程碑的方案规划类brainstorm头脑风暴、多个思路多方向创意与初步评估工程质量review检查这段代码、审查按检查点输出问题清单工程质量test补测试、写单测覆盖正常与边界的测试代码工程质量commit生成提交信息符合规范的 commit message文档知识explain解释这段代码面向读者分级的解读文档知识doc生成文档结构统一的文档初稿文档知识summary总结、提炼要点压缩重组后的要点摘要表格里这些是我用得比较狠的其他技能很多都还在吃灰关键在于找到跟你日常工作节奏匹配的那个集合。4. 怎么引入这些技能加载顺序、触发方式和自定义方法4.1 全局引入还是项目引入取舍点在哪引入技能的第一步是决定放在哪个目录。全局目录对所有项目生效适合放“跟业务无关、跟你个人习惯有关”的技能比如解释代码、提交信息格式化、文档初稿。项目目录只对当前仓库生效适合放跟业务规范强相关的技能比如团队要求的方案模板、代码审查重点、发布检查清单。优先级也建议提前搞清楚项目目录的技能会覆盖全局目录里同名的技能。这其实是一个非常有用的机制同一个plan技能你在个人全局目录里放“通用版本”在公司项目里放“公司版本”AI 会自动选择公司版本执行。我第一次调试的时候没意识到这个规则发现在公司项目里调用plan输出的风格变了还以为是出 bug 了最后才反应过来是覆盖生效。4.2 三种触发技能的常见写法技能不是装了就自动会出现在每段对话里的你需要按一定的方式让它接管当前任务。我实际使用下来有三种触发方式最靠谱第一种是对话中显式指定最直白也最稳比如“使用 skill: plan 帮我梳理这个功能的实现思路”。关键词skill:后面跟技能名能直接锁定目标技能。第二种是斜杠命令方式比如输入/review、/test。这种方式适合你已经确认自己就是要干这件事的场景不需要 AI 去判断你的意图。第三种是自动匹配AI 根据你的描述自动选择技能。这种方式最好用也最容易失控。技能文件的描述字段写得越准确自动匹配越不容易误伤但如果你同时有多个描述相近的技能就可能出现技能 A 接走了技能 B 的任务。我自己的使用习惯是重要任务用显式指定零碎任务用斜杠命令自动匹配只在对输出要求没那么高的场景里用。4.3 自定义一个技能的全过程上面讲的是怎么用现成技能但 Superpowers 真正的杠杆在于把团队的做事方法变成新技能。自定义技能的步骤非常清晰核心是建一个目录放一个 SKILL.md 文件。先创建目录结构.superpowers/ └── skills/ └── team-plan/ ├── SKILL.md └── templates/ └── plan-template.mdSKILL.md 的格式大体长这样--- name: team-plan description: 按团队模板输出项目技术方案适合需求评审前的方案预研 trigger: 用户提到方案、技术选型、roadmap input: - 需求背景 - 核心目标 - 关键约束 - 交付时间 steps: - 先补充背景和约束信息信息不足时向用户提问 - 拆解关键问题至少给出两个候选方案 - 对每个方案标注优缺点和风险 - 输出背景-目标-候选方案-风险评估-推荐结论-里程碑 --- 执行以上流程调取 templates 下的方案模板进行渲染。写的时候有几个细节要注意。name字段必须跟目录名保持一致大小写也最好一致否则会加载不出技能。description写清楚你能覆盖的场景AI 的自动匹配很大程度上靠它。steps别写太长AI 的上下文窗口有限步骤越聚焦执行越稳定。你可以在templates目录下放模板文件这样输出的格式能被模板约束住。做完之后跑一遍superpowers list确认新技能出现在列表里再在项目里用一次真实任务试跑。第一个自定义技能往往会失败几次别灰心调整 steps 的描述、精简输入项很快就能稳定下来。5. 具体使用实录三个场景的完整操作路径与结果对比5.1 场景一从零到一产出技术方案有一次我需要做一个用户行为埋点系统的技术方案产品经理只给了一句话需求“记录用户在后台页面的关键点击和停留时长”。面对这种输入直接让 AI 写方案大概率会得到一个结构松散、不知道从何入手的东西。我的实际操作是显式调用plan技能。提示词大概是这样使用 skill: plan 帮我规划一个用户行为埋点系统方案。需求背景需要分析运营活动页面的用户行为数据。核心目标埋点覆盖关键点击、停留时长、页面跳转路径。约束条件前端不能影响页面性能数据量预计日均百万级。技能被触发后AI 没有立刻给结论而是先补齐了几个问题。它问我数据落库之后主要给谁看这决定了要不要做聚合报表又问我埋点方案偏向 SDK 还是无埋点这决定了实现复杂度。我把答案补充进去后它按“背景-目标-候选方案-风险评估-推荐结论-里程碑”的结构输出了一版 2000 字左右的方案。我的感觉是没有plan技能的时候AI 的方案像一篇百度百科词条什么都有但什么都没有真的定下来。用了技能之后方案里会明确写出每个候选方案的取舍标准和推荐理由这份方案的可用度至少提高了一个档次。5.2 场景二代码审查按团队规范执行代码审查是我觉得最能体现技能价值的场景。早期我直接用 AI 做审查它给的建议并不是不好而是太零散今天提命名、明天提性能没有一个稳定的框架。后来我把团队规范写进了review技能把检查点固定成这些维度空指针与异常处理、边界条件、并发安全、资源释放、命名与结构一致性、安全性隐患。同时要求每个发现都必须标注代码位置和严重级别。实际操作时我只需要给它一段改动提示词类似使用 skill: review 审查以下 diff重点关注用户列表分页查询的边界条件和数据库连接释放。那次审查它一共发现四个问题其中一个数据库连接在异常分支漏关的问题人工不仔细看根本发现不了。输出格式是分级问题清单我直接复制进评审记录里就能用。相比以前零散的建议这种结构化输出最大的优势是可追踪、可统计、可归档。5.3 场景三重复性文档任务批量处理第三个场景来自我的实际痛点给十几个微信服务接口批量生成 API 文档。如果一个个让 AI 写每个接口的格式、语序、术语风格都会漂移。我选择把文档规范做进doc技能然后反复调用。我先让技能加载项目背景说明和公共术语表保证每次生成文档时使用的名词一致。然后把接口参数逐个丢给它。每生成一个文档它都会先按固定的标题层级组织再写请求参数表、响应示例、异常码说明、调用注意事项。效果非常明显。以前生成 12 份接口文档每份的写法都有些小差异用技能生成之后整组文档看起来像同一个作者写的。后续我只需要逐一校对技术细节不用再关心格式和结构。这里也想提醒一句技能可以保证格式和结构的一致性但具体技术细节仍然需要人来把关。AI 生成的示例代码和参数说明一定要跟真实环境核对一遍再发出去。6. 我踩过的坑技能不加载、被覆盖、错配和语法错误6.1 技能一直显示“未找到”的排查链路我遇到的第一个大坑是装完技能后调用时一直提示技能未找到。这个问题最坑的地方在于表面上啥都没毛病目录也检查过文件也在就是不生效。后来我梳理了一套排查链路按顺序查基本能定位先确认技能目录路径扫描范围。不同工具的配置文件路径不同全局目录和项目目录建议都不要省略。检查name字段和目录名一致。我曾在目录名team-plan的情况下把 name 写成plan结果其他技能把我的覆盖了。看看 SKILL.md 的 YAML 语法有没有破。一旦某个字段解析失败整个技能都不会被加载。最后看是不是当前会话的上下文环境问题。已经启动的会话有时不会即时刷新技能列表重启一个新会话再试。如果没有按这个链路排查我可能会在配置语法上反复翻来覆去完全没想到是名字撞了。6.2 版本更新后旧技能残留第二个坑更隐蔽。我用包管理器升级 Superpowers 之后系统里同时存在新技能的目录和旧版本技能的目录。新版本改了部分技能的目录结构但旧目录没有被清理干净结果 AI 在一个特定场景下同时读到了两份定义行为变得很怪。之后的处理方式就三句话升级前导出自定义技能列表升级后清空旧技能目录再重新克隆或安装最后用superpowers doctor检查加载结果。别怕麻烦升级这件事越怕麻烦后面越麻烦。6.3 多个技能同时命中同一个请求第三个坑是多个技能描述相似自动匹配时全部命中。我有一次说“帮我看看这段代码怎么改”结果review、refactor、explain三个技能同时都想接管任务AI 最后选择的方式是混着执行输出的结果既有分析又有改法还有审查意见看起来就像是三个人同时在抢着发言。解决办法有两个。要么把技能的 description 写得边界更清晰让它们的适用场景尽量不重叠要么在关键任务里直接显式指定技能不给 AI 自己做决定的机会。我现在默认走显式指定自动匹配只留给那些无所谓的日常小任务。6.4 技能内容太长导致上下文细节丢失最后一个坑出现在我给技能添加了超长步骤之后。当时我为了把团队规范塞进去把 SKILL.md 写得非常长结果实际调用时后半段规则 AI 几乎记不住输出质量还不如不用技能。后来我把大技能拆成了两个子技能一个是“需求信息采集”一个是“方案输出”前者负责确认信息后者负责生成内容。拆分之后每次加载的上下文都变短了AI 的执行质量明显回升。这也是我吃了亏之后的体会技能不是越全越好每个技能聚焦一个完整动作效果才最稳定。技能不生效的问题和解决方案我用表格做个汇总方便你排查现象排查点常见修复技能未找到目录路径、name 字段、YAML 语法修正名称或重启会话行为混乱新旧版本残留清空旧目录、重新安装多个技能冲突description 重叠显式指定技能名输出偏离SKILL.md 过长拆分子技能控制长度7. 把 Superpowers 变成自己的工具箱维护习惯与团队推广7.1 我的技能目录组织经验用得久了我发现技能跟书一样是越多越乱。现在我的目录组织习惯是按领域分文件夹.superpowers/ ├── planning/ │ ├── plan/ │ └── brainstorm/ ├── engineering/ │ ├── review/ │ ├── test/ │ ├── refactor/ │ └── commit/ └── docs/ ├── explain/ ├── doc/ └── summary/这样按领域归类的最大好处是每次想找某个技能时不用在扁平列表里翻来翻去新增技能时也能一眼看出是不是跟已有的重复了。配合一个习惯每个季度清理一次不用的技能。我清理的标准很简单——三个月内没被真实任务调用过的技能直接移出主目录放到archived里。档案不会丢但不会再占用 AI 的扫描和匹配空间。7.2 技能的版本管理与团队同步我建议把技能目录纳入版本管理哪怕你只是个人使用。做法很直接把.superpowers目录放进 Git 仓库每次改动技能文件都提交一次。这样每次技能“变好”或“变坏”都有迹可循。团队同步的时候我们把技能目录直接放进项目仓库新同事克隆项目之后直接就能用。这里有两个细节想分享第一个是技能文件的改动要走 MR 评审不能谁想改就改否则规范会漂移第二个是仓库里建议放一个SUPERPOWERS.md说明文件写清楚每个技能的动作边界和使用场景给新人当快速上手指南。另外推荐在 CI 里加一个轻量校验比如用superpowers doctor检查每个提交是否破坏技能语法。这个动作看着小但能拦住绝大多数的低级错误。7.3 什么情境下我选择放弃使用技能还有一点我觉得非常重要不是所有任务都适合用技能。我用下来有三个情境会主动放弃技能调用。第一是探索性问题比如“我们做这个产品到底有没有价值”这种问题需要开放式的思考固定的输出框架反而会框住可能性。第二是高度依赖经验判断的任务技能能把流程整理清楚但无法替代你作为人对业务本质的理解。第三是一次性任务为它专门穿一次技能写配置成本比收益高得多。所以技能的定位应该是“高频、重复、有固定方法的事情”。低频、创新、非线性的事情保持用人脑直接对话就好。说到底Superpowers 这套东西给我最大的启发不是它有多少技能而是它逼着我去把自己平时“凭感觉做”的事情拆成可见的流程。当你把一个动作写成技能定义时你其实是在整理自己的方法论。所以我的建议也很简单先找一个你重复次数最多的任务把它做成技能用两周时间跑起来再按真实效果迭代。一个好的技能不是一次写完的是一边用一边改出来的。