1. 从“superpowers”这个热词说起它到底是什么最近“superpowers”这个词在技术圈和效率工具圈里被反复提起很多人第一次看到它是在各种项目仓库、开发者社区或者效率工具的讨论帖里。有人把它当成一个插件有人以为它是一个新的编程语言还有人直接问“想要安装superpowers到底该怎么装”。我花了大概两周时间把这个东西从概念到落地完整跑了一遍踩了不少坑也总结出了一些真正能用的经验。先把结论说清楚superpowers 本质上是一套面向 AI 编程助手的能力扩展框架它的核心思路是给原本只会“聊天”的 AI 助手装上一批可复用的“技能包”让它在处理具体开发任务时能够按照预设的流程、规范和工具链去执行而不是每次都靠临时发挥。你可以把它理解成给一个聪明的实习生配了一本厚厚的《标准作业手册》手册里写清楚了遇到什么任务该走什么流程、该调用什么工具、该产出什么格式的结果。它解决的问题非常具体AI 助手在真实项目里经常“不听话”或者“不专业”。比如你让它写一个接口它可能给你写一个能跑但完全没有错误处理、没有日志、没有参数校验的版本你让它改一个 bug它可能顺手把不相干的代码也重构了。superpowers 就是通过“技能skills”的方式把这些工程规范固化下来让 AI 在特定场景下自动遵循。适合谁来参考这篇文章三类人最值得往下看第一类是日常用 AI 助手写代码的开发者想让 AI 产出更稳定、更符合团队规范第二类是技术团队的负责人想给团队统一 AI 协作的标准第三类是对 AI 工程化感兴趣的技术爱好者想搞清楚这套东西的底层逻辑自己动手搭一套。不管你之前有没有接触过类似概念我都会从最基础的结构讲起把安装、配置、编写技能、调试排错整个流程拆开讲透。2. 核心设计思路拆解为什么是“技能包”而不是“提示词”2.1 提示词工程的瓶颈在哪里大部分人用 AI 助手的方式是“对话式”的打开对话框敲一段提示词等结果不满意再改提示词。这种方式在简单任务上没问题但一旦任务变复杂问题就暴露了。我实测过一个典型的场景让 AI 帮我写一个带分页的用户列表接口。第一次它给了一个能跑的版本但没有做参数边界检查我补充要求后它加了检查但把之前的分页逻辑改坏了我再要求它别动分页它又忘了加日志。来回折腾五六轮最后我自己动手改的比它写的还多。这个问题的根源在于提示词是“一次性”的它不沉淀。每次对话都是新的上下文你上次强调的规范这次它不一定记得。而且提示词很难版本化管理团队里每个人写的提示词风格都不一样产出质量自然参差不齐。2.2 技能包的核心机制superpowers 的思路是把“怎么做一件事”从提示词里抽出来变成一个独立的、可版本化的、可复用的文件。这个文件就是技能skill。一个技能通常包含几个部分触发条件什么情况下用这个技能、执行步骤按什么顺序做什么、工具依赖需要调用哪些外部工具、输出规范结果应该长什么样。我用一个生活化的类比来解释提示词像是你临时给厨师口述一道菜的做法每次都要重新说一遍而且说得不全技能包像是把菜谱写下来贴在厨房墙上厨师每次做这道菜都照着菜谱来味道稳定新人来了也能照着做。技能包的价值不在于它多聪明而在于它把“聪明”固化成了“流程”。2.3 为什么选择这种架构我研究了一下它的设计取舍发现几个关键决策背后都有明确的理由。第一技能是文件而不是数据库记录这意味着你可以用 Git 管理它可以 review、可以回滚、可以分支这对团队协作至关重要。第二技能是声明式的而不是命令式的你描述“要做什么”和“验收标准”而不是写死每一步的具体代码这样 AI 在不同项目里能灵活适配。第三技能可以组合一个复杂任务可以拆成多个技能按顺序调用就像搭积木一样。提示如果你之前用过类似“自定义指令”或“系统提示词”的功能可以把技能理解成它们的升级版——更结构化、更可维护、更适合团队场景。3. 安装前的环境准备与依赖梳理3.1 你需要提前确认的三件事在动手安装之前有三件事必须先确认清楚否则后面会反复卡壳。第一你的 AI 助手客户端是否支持扩展机制。不是所有客户端都开放了技能加载的接口具体要看你用的工具版本和文档说明。第二你的项目目录结构是否规范。技能通常需要放在约定的目录下才能被识别如果项目结构混乱加载会失败。第三你的运行环境是否有文件读写权限。技能加载过程需要读取技能文件权限不足会直接报错。我踩过的第一个坑就是目录问题。当时我把技能文件随手放在了项目根目录结果 AI 助手完全没识别到。后来查文档才知道它默认只扫描特定目录。这个细节官方文档写得很隐蔽我是翻了源码才确认的。3.2 依赖清单与版本要求下面这张表是我实测下来能稳定运行的依赖组合供你参考。注意版本号不是越新越好某些新版本反而有兼容性问题。依赖项推荐版本作用备注AI 助手客户端支持扩展的版本加载并执行技能版本过低不支持技能机制运行时环境主流稳定版执行技能中的脚本避免使用测试版版本控制工具任意现代版本管理技能文件强烈建议启用文本编辑器支持 Markdown编写技能文件需要语法高亮3.3 目录结构的约定技能文件的存放位置是有讲究的。我建议采用下面这种结构清晰且不容易冲突project-root/ .skills/ skill-name/ skill.md # 技能定义文件 config.json # 技能配置 scripts/ # 可选技能用到的脚本 src/ # 你的项目代码把技能集中放在.skills目录下的好处是第一和业务代码隔离不会互相干扰第二方便整体纳入版本控制第三迁移项目时直接拷贝这个目录就行。我试过把技能散落在各个子目录里结果维护起来非常痛苦后来统一收拢才清爽。4. 编写你的第一个技能从零到能跑4.1 技能文件的基本结构一个技能文件的核心是几个字段名称、描述、触发条件、执行步骤、输出要求。我用一个“生成规范的 REST 接口”的技能作为例子把结构拆开讲。--- name: rest-api-generator description: 生成符合团队规范的 REST 接口代码 trigger: 当用户要求新增接口时 --- ## 执行步骤 1. 确认接口的路径、方法、入参、出参 2. 生成参数校验逻辑 3. 生成统一的错误处理 4. 生成结构化日志 5. 生成单元测试骨架 ## 输出要求 - 所有入参必须有校验 - 所有异常必须被捕获并返回统一格式 - 必须包含日志埋点这个结构看起来简单但每个字段都有讲究。trigger决定了 AI 什么时候会主动调用这个技能写得太宽泛会导致技能被滥用写得太窄又会在需要时不被触发。我一开始把 trigger 写成“当用户要求写代码时”结果几乎所有任务都触发了这个技能反而干扰了正常对话。后来改成“当用户明确要求新增接口时”才正常。4.2 触发条件的写法技巧触发条件是整个技能里最难写好的部分。我的经验是用具体的动作词而不是宽泛的领域词。“新增接口”“修复空指针异常”“重构重复代码”这种是动作词AI 容易识别“后端开发”“代码质量”这种是领域词太模糊。另外触发条件可以组合。比如“当用户要求新增接口且项目使用特定框架时”这样能进一步缩小范围。我实测下来一个技能覆盖的场景越聚焦执行效果越好。贪多求全的技能最后往往哪个场景都做不好。4.3 执行步骤的颗粒度控制执行步骤写多细这是新手最容易纠结的问题。写太细AI 变成了执行脚本的机器失去了灵活性写太粗AI 又会自由发挥产出不稳定。我的建议是步骤写到“决策点”为止具体实现留给 AI。举个例子“生成参数校验逻辑”是一个合适的颗粒度它明确了要做这件事但没规定用哪个库、写多少行。而“引入校验库定义校验规则在入口处调用”就太细了等于把代码写死了。反过来“处理入参”又太粗AI 可能直接忽略校验。4.4 输出规范的约束力输出规范是保证结果一致性的关键。我建议用可验证的清单形式来写而不是描述性语言。“必须包含日志埋点”比“注意日志”有效得多因为前者可以被检查后者只是提醒。我在团队里推行的时候把输出规范做成了 checklist每次 AI 产出后逐条核对不符合就打回重做几轮下来 AI 的产出质量明显提升。5. 技能加载与调试的完整实操5.1 加载流程与验证方法技能写好后怎么确认它被正确加载了我的做法是分三步验证。第一步检查文件是否在正确目录用文件管理器或命令行确认路径无误。第二步触发一次技能给 AI 一个符合触发条件的任务观察它是否按技能步骤执行。第三步检查执行日志大部分客户端会记录技能调用情况日志里能看到哪个技能被触发、执行到哪一步。我第一次加载时技能完全没反应。排查了半天发现是文件编码问题——我用了一个带 BOM 的编码保存解析器读不了。改成无 BOM 的 UTF-8 后立刻正常。这个坑很隐蔽因为文件内容看起来完全正常。5.2 调试技能的实用手段调试技能最有效的手段是加日志。在技能的关键步骤里插入输出语句观察 AI 执行到哪一步、跳过了哪一步。我常用的做法是在每个步骤后加一句“当前步骤X”这样执行完就能看到完整的执行路径。另一个手段是最小化复现。当技能行为异常时把技能内容删到只剩最核心的几步确认基础流程能跑通再逐步加回内容定位是哪部分导致的异常。这个方法虽然笨但非常有效我用它定位过好几个诡异的问题。5.3 常见加载失败原因速查现象可能原因排查方法技能完全不触发目录不对或文件编码错误检查路径和编码触发但步骤乱序步骤描述有歧义简化步骤明确顺序触发后报错依赖工具缺失检查工具是否可用时触发时不触发触发条件太模糊收窄触发条件输出不符合规范输出要求不可验证改成清单形式这张表是我踩坑踩出来的基本覆盖了新手会遇到的大部分问题。建议收藏遇到问题先对照排查。6. 进阶玩法技能组合与团队协作6.1 把大任务拆成技能链单个技能能做的事有限真正的威力在于技能组合。比如一个完整的“新增功能”任务可以拆成“需求分析技能 → 接口设计技能 → 代码生成技能 → 测试生成技能 → 文档生成技能”这样一条链。每个技能专注一件事串起来就是一个完整的开发流程。我实测过一个组合流程先让 AI 用需求分析技能把模糊需求拆成明确的验收标准再用接口设计技能产出接口定义接着用代码生成技能实现最后用测试技能补测试。整个流程跑下来产出的代码质量比我手动写还稳定因为每一步都有规范约束。6.2 团队共享技能库的实践团队场景下技能库的共享和管理是个关键问题。我的做法是把技能库作为独立仓库维护团队成员通过版本控制工具同步。每个技能都要有负责人负责 review 和更新。新技能加入前要经过至少两人试用确认有效才合并。这样做的好处是第一技能质量有保障不会出现一个人随便写个技能就污染整个库第二技能有维护者不会用着用着就失效第三有 review 流程技能的可读性和规范性都能保证。我在团队里推行这套机制后AI 产出的代码返工率明显下降。6.3 技能版本管理与回滚技能也是代码也需要版本管理。我建议给每个技能打版本号重大变更时升级主版本号。当某个技能更新后导致产出质量下降时能快速回滚到上一个版本。这个机制在团队协作里特别重要因为技能的影响面是全局的一个坏技能会拖累所有人。注意技能更新后一定要在小范围先验证不要直接推给全团队。我吃过这个亏一个看似优化的改动导致所有接口生成都少了参数校验发现时已经生成了几十个文件。7. 实操心得与避坑指南7.1 我踩过的五个坑第一个坑是技能写得太贪心。一开始我想用一个技能覆盖所有后端开发场景结果触发条件模糊执行步骤冗长AI 执行时经常跳步。后来拆成五个小技能每个专注一个场景效果立刻好转。第二个坑是忽略输出验证。技能写完后我没做验证就直接用结果 AI 产出的代码虽然符合技能描述但不符合项目实际规范。后来我养成了习惯每个技能上线前用三个真实任务测试确认产出符合预期。第三个坑是技能之间互相干扰。两个技能的触发条件有重叠导致 AI 不知道该用哪个行为变得不可预测。解决办法是定期审查技能库确保触发条件互斥。第四个坑是忘记更新技能。项目技术栈升级后技能里的规范没同步更新导致 AI 产出的代码用了过时的写法。现在我给每个技能加了“最后审查日期”定期检查。第五个坑是过度依赖技能。有段时间我什么任务都想写成技能结果技能库膨胀到几十个维护成本极高。后来我定了个原则只有高频、重复、有明确规范的任务才值得做成技能一次性任务直接用提示词就行。7.2 提升技能效果的三个技巧第一个技巧是在技能里加入反例。告诉 AI“不要做什么”往往比“要做什么”更有效。比如在接口生成技能里加一句“不要生成没有错误处理的代码”能明显减少遗漏。第二个技巧是用真实代码片段作为参考。在技能里附上一段符合规范的示例代码AI 会模仿这个风格产出的一致性会大幅提升。我试过在技能里放一段团队的标准接口代码生成结果的风格立刻统一了。第三个技巧是定期回顾技能执行日志。日志里能看到哪些技能被频繁触发、哪些步骤经常被跳过、哪些输出经常被修改。根据这些数据优化技能比凭感觉改有效得多。7.3 什么任务适合做成技能不是所有任务都值得做成技能。我的判断标准是三条高频每周至少用几次、重复每次做法基本一致、有规范存在明确的正确做法。三条都满足才做技能缺一条就用提示词解决。这个标准帮我砍掉了一半不必要的技能技能库清爽了很多。8. 常见问题排查实录8.1 技能不生效的排查路径技能不生效是最常见的问题排查路径我总结成一条链先确认文件位置和编码再确认触发条件是否匹配然后确认技能内容是否能被正确解析最后确认客户端版本是否支持。按这个顺序排查九成问题都能定位。我遇到过一次特别诡异的情况技能文件内容完全正确但就是不生效最后发现是文件名里有个特殊字符导致解析失败。所以文件名也要用纯英文和连字符别用中文或空格。8.2 技能执行结果不稳定的处理结果不稳定通常有三个原因触发条件太宽、步骤描述有歧义、输出要求不可验证。对应的解决办法是收窄触发条件、明确步骤顺序、把输出要求改成清单。我处理过一个案例同一个技能有时生成带日志的代码有时不带排查后发现是输出要求里写的是“建议加日志”改成“必须包含日志埋点”后就稳定了。8.3 技能冲突的解决思路当多个技能同时被触发时AI 的行为会变得混乱。解决办法有两个一是合并把重叠的技能合并成一个内部用条件分支处理不同场景二是分层用优先级机制让高优先级技能先执行。我倾向于合并因为分层机制会增加复杂度而合并能让技能边界更清晰。8.4 性能问题的优化方向技能太多会导致加载变慢执行时也可能因为要匹配大量触发条件而变慢。优化方向有三个精简技能库删掉不用的技能优化触发条件用更精确的匹配减少遍历按需加载只在相关任务出现时才加载对应技能。我实测下来把技能库从三十个精简到十二个后加载速度提升了一倍多。9. 后续可以这样扩展技能库稳定运行之后我做了几个扩展效果不错分享给你参考。第一个扩展是给技能加指标记录每个技能的触发次数、成功率、平均执行时间用数据驱动优化。第二个扩展是做技能模板把常用结构抽成模板新建技能时直接套用减少重复劳动。第三个扩展是跨项目复用把通用技能抽成公共库不同项目按需引入避免重复造轮子。我个人在实际操作中的体会是superpowers 这类框架的价值不在于它本身多强大而在于它逼着你把“怎么做才对”这件事想清楚、写下来。很多时候技能写不下去不是因为工具不好用而是因为你自己都没想明白这个任务的正确做法是什么。写技能的过程其实是一次对工程规范的梳理。这个副产品可能比技能本身更有价值。
