1. 从“superpowers”这个热词说起它到底是什么最近“superpowers”这个词在技术社区里被反复提起连带着“想要安装superpowers”也成了高频搜索词。我第一次看到这个标题的时候脑子里蹦出来的第一个念头是这到底是一个具体的软件包、一个浏览器扩展、还是一套方法论后来花了不少时间把社区里的讨论、仓库说明和实际使用反馈翻了一遍才把它的轮廓拼出来。简单说superpowers 是一套面向 AI 编程助手的能力增强方案它的核心思路是给原本只会“聊天”的助手装上一整套可复用的技能模块让它在处理具体工程任务时能调用预设的流程、模板和检查清单而不是每次都从零开始即兴发挥。你可以把它理解成给一个聪明但没受过职业训练的实习生配了一本厚厚的《岗位操作手册》手册里写清楚了遇到什么场景该走什么流程、该检查哪些点、该产出什么格式的结果。它能解决的问题很具体很多人用 AI 助手写代码或者做项目时最大的痛点不是模型不够聪明而是输出不稳定。同一个需求今天问和明天问得到的结构、详略、甚至技术选型都可能不一样。superpowers 试图用“技能包”的方式把这种不确定性压下去让助手在特定任务上表现得像一个有经验的老手而不是一个每次都在重新摸索的新人。这套东西适合谁来参考我觉得有三类人最值得花时间研究第一类是日常重度依赖 AI 助手做开发、写文档、做方案的人他们最需要稳定可复现的输出第二类是想把自己团队内部的规范、流程沉淀成可复用资产的技术负责人第三类是对“如何给 AI 助手做能力扩展”这件事本身感兴趣、想自己动手改一改的折腾型玩家。哪怕你只是想搞清楚“安装 superpowers”到底装的是什么、装完能干嘛下面的内容也能给你一个清晰的答案。2. 整体设计思路拆解为什么是“技能包”而不是“大而全”2.1 核心问题AI 助手的“发挥不稳定”到底出在哪要理解 superpowers 的设计得先搞清楚它想解决的那个根子上的问题。我用 AI 助手做项目的这几年踩过最多的坑不是它不会而是它每次会的程度不一样。比如让它写一个数据清洗脚本有时候它会主动加上异常处理、日志、参数校验有时候就给你一个裸的 pandas 三行代码连列名都不检查。这种波动在单人随手用的时候还能忍一旦放到团队协作或者需要反复迭代的项目里就是灾难。问题的根源在于通用助手的行为是由“当前对话上下文 模型固有倾向”共同决定的而这两者都不稳定。上下文一变它的注意力分配就变了模型本身对不同表述的敏感度也不一样。superpowers 的思路很直接既然即兴发挥不稳定那就把“该怎么发挥”提前固化下来变成一个个独立的、可被显式调用的技能单元。每个技能单元里写死了这个任务该走的步骤、该产出的结构、该注意的边界。助手在需要的时候调用它相当于临时加载了一段“职业记忆”。这个思路和传统的“提示词模板”有本质区别。提示词模板是你在对话里手动粘贴一段话用完就没了而技能包是常驻的、可组合的、有明确触发条件的。它更像是一个工具箱里面每把工具都有固定的用途和使用说明而不是每次都要你现场教它怎么拧螺丝。2.2 方案选型为什么用“技能”而不是“微调”或“插件”这里有个很关键的取舍值得说清楚。要让 AI 助手在特定任务上变强理论上至少有三条路微调模型、开发插件、或者做技能包。superpowers 选了第三条这个选择背后有很实际的考量。微调的门槛太高需要准备大量高质量样本、算力成本不低而且一旦微调完想改一个细节就得重新训一遍迭代周期以天甚至周计。插件的方式更重需要处理宿主环境的接口、权限、分发开发成本高而且强依赖特定平台。相比之下技能包是纯文本层面的增强本质上是结构化的指令集合改一个技能就是改一个文件改完立刻生效不需要重新训练也不依赖特定平台的插件机制。这种轻量、可迭代、可版本管理的特性正好匹配了“快速试错、持续打磨”的实际需求。我自己的体会是技能包这种形态最大的好处是可读性和可维护性。你打开一个技能文件能直接看懂它在干什么、为什么这么干想改就改想删就删。而微调出来的模型是个黑盒插件则被平台接口绑死。对于大多数个人开发者和中小团队来说技能包是投入产出比最高的那条路。2.3 组合优于堆砌技能之间怎么协同superpowers 另一个让我觉得设计得聪明的地方是它没有试图做一个“万能技能”而是把能力拆成很多小单元然后靠组合来应对复杂任务。这就像做菜你不会买一袋“万能调料”而是买盐、糖、酱油、醋做不同菜的时候按比例搭配。举个实际的例子。一个完整的“新功能开发”任务在 superpowers 的体系里可能被拆成好几个技能需求澄清技能、方案设计技能、代码实现技能、测试编写技能、文档更新技能。每个技能单独看都很简单但串起来就能覆盖一个完整的工程流程。这种拆分的好处是每个技能可以独立打磨、独立复用。今天你在做 A 项目时优化了“测试编写技能”明天做 B 项目时直接就能用上不需要重新调。而且这种组合方式让边界很清晰。每个技能只负责一件事出了问题容易定位是哪个环节的锅。如果是一个大而全的技能输出不对你根本不知道是需求理解错了还是实现写歪了。拆开之后排查成本大幅下降。3. 核心细节解析与实操要点安装前必须搞清楚的几件事3.1 安装 superpowers 到底装的是什么很多人搜“想要安装 superpowers”但可能没想清楚安装这个动作具体在装什么。这里必须说清楚superpowers 不是一个传统意义上的可执行程序它没有双击安装包、没有图形界面、也不会在系统里注册服务。它本质上是一组文件通常是 Markdown 格式的技能描述文件加上一些配套的目录结构和索引配置。所以“安装”这个词在这里更准确的理解是部署和接入。你要做的是把这些技能文件放到 AI 助手能够读取到的位置然后通过某种机制让助手知道“有这么一批技能可用需要的时候去调用”。不同的助手宿主环境接入方式不一样有的支持自动扫描某个目录有的需要你在配置里显式声明技能路径有的则需要通过对话指令手动加载。注意在动手之前先确认你用的助手是否支持外部技能加载机制。如果不支持那 superpowers 对你来说就只是一堆参考文档能读但不能自动调用价值会打不少折扣。3.2 目录结构技能是怎么组织的一个典型的 superpowers 技能库目录结构大致是这样的根目录下有一个总索引文件负责列出所有可用技能和它们的触发条件然后每个技能一个子目录或者一个独立文件里面包含技能名称、适用场景、执行步骤、输出格式要求、注意事项这几个核心字段。有些实现还会加一个“依赖声明”说明这个技能需要哪些前置技能或者外部工具。我建议你在部署的时候不要把所有技能平铺在一个目录里而是按领域分组。比如coding/放编码相关技能writing/放文档写作技能analysis/放数据分析技能。这样做的原因是当技能数量涨到几十个的时候平铺结构会让你根本找不到东西而分组之后助手在匹配触发条件时也更容易缩小范围减少误触发。索引文件是整个体系的入口它的质量直接决定了技能能不能被正确调用。索引里每个技能至少要写清楚三件事技能名、一句话描述、触发关键词。触发关键词尤其重要写得太宽会导致助手动不动就调用写得太窄又会导致该用的时候用不上。我的经验是每个技能配三到五个触发词比较合适覆盖同义表达但不要泛化到无关领域。3.3 技能文件的写法决定成败的细节技能文件写得好不好直接决定了这套东西是“真管用”还是“花架子”。我见过不少人的技能文件写得像产品说明书全是抽象描述助手读了也不知道具体该干嘛。好的技能文件应该像给新人的操作手册具体到每一步做什么、产出什么、检查什么。一个高质量的技能文件通常包含这几个部分。第一是适用场景用一两句话说明什么情况下该用这个技能最好带一个正例和一个反例帮助手划清边界。第二是执行步骤按顺序列出每一步的动作每步都要具体到可操作比如“读取用户提供的输入文件检查是否包含缺失值”而不是“处理数据”。第三是输出格式明确说明产出应该长什么样是代码、是表格、还是分点列表有没有必须包含的字段。第四是检查清单列出完成前必须自查的点这是保证质量的关键。实操心得写技能文件时多用“必须”“禁止”“如果……则……”这类明确的约束词少用“尽量”“建议”“可以考虑”这类模糊表达。助手对明确指令的遵循度远高于模糊建议。3.4 触发机制什么时候该调用哪个技能触发机制是 superpowers 里最容易被忽视、但实际影响最大的部分。理想情况下助手应该在你提出需求时自动判断该调用哪个技能。但现实是自动判断经常出错要么该调不调要么不该调乱调。比较稳妥的做法是自动匹配加手动兜底。自动匹配负责处理大部分常规情况你正常提需求助手根据触发词去索引里找最匹配的技能。手动兜底则是给你一个显式调用的方式比如在对话里直接说“用 XX 技能来做这件事”强制指定。这两种方式结合既能享受自动化的便利又能在自动判断失灵时快速纠正。我自己的习惯是对于高频、成熟的技能信任自动匹配对于新写的、还在调试期的技能一律手动调用等验证稳定了再放开自动。这样能避免一个不成熟的技能在你不注意的时候污染了输出。4. 实操过程与核心环节实现从零到跑通的完整路径4.1 环境准备与前置检查动手之前先把前置条件确认一遍能省掉后面一大堆莫名其妙的报错。你需要确认的第一件事是助手宿主的版本不同版本对技能加载的支持程度不一样太老的版本可能压根没有这个机制。第二件事是文件系统的读写权限技能文件需要被助手读取如果放在权限受限的目录里读取会失败。第三件事是确认技能文件的编码格式统一用 UTF-8避免中文乱码导致触发词匹配不上。我建议在正式部署前先建一个最小可运行示例。就放一个技能文件写一个最简单的技能比如“把输入文本转成项目符号列表”然后测试助手能不能正确识别和调用。这个最小示例跑通了说明整条链路是通的再去批量导入正式技能。很多人一上来就把几十个技能全塞进去结果一个都不生效排查起来极其痛苦。4.2 技能库的导入与索引配置导入技能库的步骤不同宿主环境差异比较大但核心逻辑是一致的让助手知道技能在哪、有哪些、怎么触发。通常需要你指定一个根目录然后在根目录下放一个索引文件。索引文件的格式各平台不同有的是 YAML有的是 JSON有的就是纯 Markdown 列表。配置索引的时候有个细节特别容易踩坑路径的写法。相对路径和绝对路径在不同环境下表现不一样有的宿主只认绝对路径有的只认相对于某个基准目录的路径。我的做法是先用绝对路径把链路跑通确认没问题后再考虑要不要改成相对路径方便迁移。另外索引文件里技能的顺序也有讲究匹配优先级通常是从上到下所以把最常用、最明确的技能放在前面能减少误匹配。导入完成后一定要做一次全量校验。逐个检查每个技能是否都能被索引到、触发词是否能正确匹配、文件是否有语法错误。这一步花十分钟能避免后面用的时候才发现某个技能是坏的。4.3 单个技能的编写与调试流程写一个新技能的完整流程我总结成五步。第一步是明确边界想清楚这个技能只解决什么问题不解决什么问题边界越清晰后续越不容易出问题。第二步是写初稿按照前面说的结构把适用场景、执行步骤、输出格式、检查清单填进去初稿不用追求完美先把骨架搭起来。第三步是构造测试用例准备三到五个典型的输入覆盖正常情况、边界情况、异常情况。第四步是实际调用测试用这些用例去跑观察输出是否符合预期。第五步是根据结果迭代哪里不对改哪里改完再跑一遍。调试阶段最忌讳的是一次改太多。如果你一次改了三个地方结果输出变好了你根本不知道是哪个改动起了作用。正确的做法是每次只改一个点改完立刻验证确认有效再改下一个。这样虽然慢一点但每一步的因果关系是清楚的积累下来的经验才可靠。4.4 参数与触发词的调优过程触发词的调优是个细活需要反复试。我的方法是先广撒网再收口。初期给一个技能配比较多的触发词覆盖各种可能的表达方式然后观察实际使用中哪些触发词从来没被命中过哪些经常误触发。没被命中的删掉误触发的收紧或者加限定条件。举个例子假设你有一个“代码审查”技能触发词里放了“检查”这个词。结果发现每次你说“检查一下这个文件是否存在”的时候助手都去调用代码审查技能这就是典型的误触发。解决办法是把“检查”换成更具体的“代码检查”“审查代码”“review 代码”这类组合词把泛化的单字词去掉。注意触发词调优是个持续过程不要指望一次配好就一劳永逸。随着你使用场景的变化触发词也需要跟着调整。建议每隔一段时间回顾一下技能的实际调用记录看看有没有需要优化的地方。4.5 多技能协同的编排实践当技能数量多起来之后单个技能的调用已经不够用了你需要考虑多技能协同。比如一个完整的“数据处理”任务可能需要先调用“数据读取”技能再调用“数据清洗”技能最后调用“结果导出”技能。这种编排有两种做法一种是让助手自动串联根据任务进展自动决定下一步调用哪个技能另一种是你显式地分步调用每一步都指定用哪个技能。自动串联的好处是省事但风险是助手可能在中间步骤判断失误导致整条链路跑偏。显式分步的好处是可控每一步你都能看到中间结果出问题容易定位代价是操作步骤多。我的建议是关键任务用显式分步常规任务用自动串联。对于结果要求高、不能出错的场景多花点时间手动控制是值得的。5. 常见问题与排查技巧实录5.1 技能不生效的排查思路技能不生效是最常见的问题表现是助手完全无视技能的存在该怎么答还怎么答。排查的时候按这个顺序来先确认技能文件是否在索引目录里、索引文件是否被正确加载、触发词是否匹配当前输入、技能文件本身是否有语法错误。这四步能覆盖九成以上的不生效问题。我遇到过一次很隐蔽的情况技能文件和索引都正常触发词也对但就是不生效。最后发现是文件编码问题技能文件保存成了带 BOM 的 UTF-8导致索引解析时第一个字段名多了几个不可见字符匹配自然就失败了。这种问题肉眼看不出来只能用工具检查文件头。所以我现在养成了一个习惯所有技能文件保存后都用十六进制工具看一眼文件头确认没有奇怪的字节。5.2 触发词误匹配与漏匹配的处理误匹配和漏匹配是触发词调优的两个方向。误匹配是助手在不该调用的时候调用了漏匹配是该调用的时候没调用。处理误匹配核心是收紧触发条件把泛化词换成具体组合词或者给触发词加上下文限定。处理漏匹配核心是补充同义表达想想用户还可能用什么说法来描述这个需求把这些说法加进去。有个技巧很管用记录真实对话。把一段时间内你和助手的实际对话保存下来然后逐条分析哪些地方应该触发技能但没触发哪些地方不该触发却触发了。基于真实数据来调比凭空想象有效得多。我一般会攒够二三十条真实案例再统一调一次这样调整的方向更准。5.3 输出格式不稳定的应对即使技能文件里写清楚了输出格式助手有时候还是会跑偏。这种情况通常是因为格式要求写得不够具体。比如你写“输出一个表格”助手可能给你 Markdown 表格也可能给你纯文本对齐的表格还可能给你 CSV。解决办法是把格式要求写到不能再具体比如“输出 Markdown 表格表头必须包含 A、B、C 三列每列内容左对齐”。另一个原因是技能文件太长格式要求被淹没在中间。助手处理长文本时注意力会分散写在中间的要求容易被忽略。我的做法是把最关键的格式要求放在技能文件的开头和结尾各写一遍首尾呼应命中率明显提高。5.4 性能与响应速度的优化技能数量多了之后响应速度可能会变慢因为助手需要在索引里做匹配。优化方向有两个一是精简索引把不常用的技能从主索引里挪出去放到二级索引需要时再加载二是优化触发词减少模糊匹配的计算量多用精确匹配。还有一个容易被忽视的点是技能文件的体积。单个技能文件如果写得特别长加载和解析都会变慢。我的经验是单个技能文件控制在两千字以内比较合适超过这个长度就考虑拆成多个技能或者把详细的参考内容放到单独的文档里技能文件里只保留核心指令和指向参考文档的链接。5.5 常见问题速查表问题现象可能原因排查动作解决方向技能完全不生效索引未加载或路径错误检查索引文件是否被读取修正路径确认加载日志触发词匹配不上触发词与实际输入不符对比输入和触发词列表补充同义表达误触发频繁触发词过于泛化查看误触发时的输入收紧触发条件输出格式跑偏格式要求不具体或被忽略检查技能文件格式段落写具体首尾各写一遍响应变慢技能库过大或文件过长统计技能数量和文件体积精简索引拆分长文件中文乱码文件编码不统一检查文件编码格式统一转为 UTF-8 无 BOM6. 进阶玩法把 superpowers 用出你自己的风格6.1 从“用别人的技能”到“写自己的技能”刚开始用 superpowers 的时候大多数人都是直接用现成的技能包。但用着用着你会发现通用技能解决不了你的个性化需求。比如你们团队有一套特定的代码规范、特定的文档模板、特定的评审流程这些通用技能里不会有。这时候就该动手写自己的技能了。写自己的技能最大的价值在于把隐性知识显性化。很多老手做事快是因为脑子里有一套没写下来的流程。把这套流程写成技能文件一方面能让助手替你执行另一方面写的过程本身也是对自己经验的一次梳理。我写第一个自定义技能的时候写着写着发现自己原来有些步骤是多余的顺手就把自己的工作流程也优化了。6.2 技能库的版本管理与团队共享技能库一旦开始积累就需要版本管理。我的做法是用 Git 管理技能库每次修改都提交写清楚改了什么、为什么改。这样出问题可以回滚多人协作时也能看到谁改了什么。技能库的目录结构保持稳定新增技能只加文件不改结构减少合并冲突。团队共享的时候有个坑要注意不同人的助手环境可能不一样同一个技能在 A 那里能用在 B 那里可能因为路径或者版本问题用不了。解决办法是在技能库里放一个环境说明文档写清楚依赖的宿主版本、目录结构要求、必要的配置项。新人接入时先照着文档把环境配好再导入技能库。6.3 技能迭代的节奏把控技能库不是写完就完事了需要持续迭代。但迭代也要有节奏不能天天改。我的做法是按使用频率决定迭代优先级。高频使用的技能一旦发现问题立刻改低频使用的技能攒着等积累了几个问题一起改。这样既能保证核心技能的稳定性又不会因为频繁改动引入新问题。每次迭代后建议保留一份变更记录写清楚这次改了什么、解决了什么问题、有没有引入新的注意事项。这份记录在几个月后你自己回头看的时候会非常有用能帮你快速回忆起当时的决策背景。6.4 把技能包和日常工作流打通superpowers 最大的价值是把它和你的日常工作流打通。比如你每天都要写日报那就写一个“日报生成”技能把格式、内容要求、检查点都固化进去以后每天只需要提供当天的工作内容格式和结构交给技能处理。再比如你经常要做代码审查那就写一个“审查清单”技能每次审查前调用一下确保该检查的点一个不漏。打通工作流的关键是找到那些重复度高、有固定套路的环节。这些环节最适合用技能来固化投入产出比最高。而那些每次都不一样、需要大量创造性判断的环节就不太适合做成技能硬做反而会限制发挥。7. 我踩过的坑和几条实在建议回过头看我在 superpowers 上踩的坑主要集中在两个阶段。第一个阶段是贪多一上来就想把所有能想到的技能都写出来结果写了几十个大部分都没用过索引还变得很臃肿匹配速度明显下降。后来我学乖了只写当前真正需要的技能用起来之后再考虑扩展。第二个阶段是追求完美一个技能反复改总觉得还不够好迟迟不肯投入使用。后来想通了技能是工具不是艺术品先能用起来在实际使用中发现问题再改比闭门造车强得多。几条实在的建议。第一从最小可用开始先跑通一个技能再逐步增加不要一上来就搞大工程。第二重视触发词它决定了技能能不能在正确的时机被调用值得花时间反复调。第三保持技能文件简短具体抽象的描述对助手没用具体的指令才有用。第四定期清理用不上的技能果断删掉技能库不是越多越好是越精越好。第五把技能库当代码管用版本控制写变更记录这样你才能清楚地知道自己的技能库是怎么一步步长成现在这样的。最后分享一个我最近才想明白的点superpowers 这类东西的价值不在于它让助手变聪明了多少而在于它让助手的表现变得可预期。在工程场景里可预期比聪明更重要。一个每次都能稳定输出合格结果的助手比一个偶尔惊艳但经常跑偏的助手对实际工作的帮助大得多。想清楚这一点你就知道该往哪个方向投入精力了。