1. 从“superpowers”这个热词说起它到底是什么最近“superpowers”这个词在技术社区里出现的频率突然高了起来很多人第一次看到它是在某个开源项目的讨论区或者是在朋友转发的一条动态里。有人把它当成一个插件有人以为是一个新的框架还有人直接问“想要安装superpowers到底该怎么下手”。我花了几天时间把这个东西从里到外摸了一遍也实际在自己的工作流里跑了几轮今天就把我理解到的、踩过的、以及觉得值得分享的东西一次性讲清楚。先给一个最直白的定义superpowers 是一套面向 AI 编程助手的能力扩展集合它本身不是一个独立的软件也不是一个需要单独启动的服务而是以“技能包”的形式挂载到已有的 AI 编码工具上让原本只会聊天、补全代码的助手变成能够按照固定流程完成复杂任务的“工程搭档”。你可以把它理解成给一个刚入职的聪明实习生发了一本《公司标准作业手册》手册里写清楚了遇到什么任务该走什么流程、该调用什么工具、该产出什么格式的结果。它解决的问题其实很具体。用过 AI 写代码的人都有体会让 AI 写一个函数很容易但让它完整地做一个功能模块它经常会漏掉测试、忘记处理边界情况、或者写出来的东西跟你项目的既有风格完全不搭。superpowers 的思路就是把这些“隐性经验”显性化变成一条条可复用的技能指令AI 在执行任务时会自动加载对应的技能按照预设的流程一步步走完。适合谁来了解这个东西三类人最应该关注。第一类是日常已经在用 AI 辅助编码的开发者你会发现装上之后 AI 的输出质量有明显的台阶式提升第二类是做团队效能、研发流程建设的工程师superpowers 的技能组织方式本身就是一套可借鉴的流程沉淀方法论第三类是对 AI Agent 编排感兴趣的技术爱好者它的技能加载机制是一个很好的学习样本。2. 核心设计思路拆解为什么是“技能包”而不是“大而全”2.1 一个核心矛盾通用能力和专业能力不可兼得AI 编程助手面临一个根本性的矛盾。如果把它训练得足够通用它能跟你聊任何话题、写任何语言的代码但在具体某个任务上的表现就会很“泛”就像一个什么都懂一点但什么都不精的通才。如果把它训练得足够专精那它就只能干那一件事换个场景就废了。superpowers 选择了一条中间路线底座保持通用能力通过外挂技能包按需注入。这个思路其实在软件工程里非常常见操作系统内核保持精简功能通过驱动和应用程序扩展浏览器内核保持通用能力通过扩展插件增强。superpowers 把这个模式搬到了 AI 助手的技能管理上。这样做的好处是显而易见的。你不需要为了写 Python 后端去换一个助手也不需要为了做前端调试去换另一个助手同一个助手在不同任务场景下加载不同的技能包就行。技能包之间相互独立一个技能包的更新不会影响另一个维护成本被摊薄了。2.2 技能包的组织逻辑按“任务类型”而非“技术栈”划分我仔细看了 superpowers 的技能组织方式它没有按照编程语言或者框架来划分技能比如“Python 技能”“React 技能”这种而是按照任务类型来划分。比如“写测试”“做代码审查”“重构”“写文档”“调试问题”这些每一个都是一个独立的技能。这个选择背后有很深的考量。按技术栈划分的话技能数量会爆炸式增长Python 要一套、JavaScript 要一套、Go 又要一套而且很多内容是重复的。按任务类型划分就不一样了“写测试”这个任务的流程和原则在 Python 和 JavaScript 里本质上是相通的只是具体语法不同而语法部分 AI 本来就会不需要额外教。提示如果你自己打算整理一套类似的技能包强烈建议从任务类型入手而不是从技术栈入手。我一开始就是按语言分的结果维护了三个月就放弃了重复内容太多改一处要同步改五处。2.3 技能加载的触发机制自动识别还是手动指定superpowers 的技能加载有两种模式。一种是自动模式AI 会根据你当前的任务描述判断应该加载哪些技能。比如你说“帮我给这个模块补一下测试”它会自动加载测试相关的技能。另一种是手动模式你可以明确指定“用代码审查技能来看一下这段代码”。自动模式的好处是省心但有时候会判断失误加载了不相关的技能反而干扰了输出。手动模式更精准但需要你对技能库有足够的了解知道什么场景该用什么技能。我个人的习惯是日常简单任务用自动模式重要任务或者复杂任务用手动模式确保加载的技能完全匹配当前需求。这两种模式并不是互斥的实际使用中可以混合。比如你可以先让 AI 自动判断然后手动补充一两个你觉得必要的技能或者手动排除掉它自动加载的某个不合适的技能。3. 核心细节解析与实操要点3.1 技能包的目录结构长什么样一个标准的 superpowers 技能包目录结构大致是这样的skills/ code-review/ SKILL.md examples/ good-review.md bad-review.md templates/ review-checklist.md write-tests/ SKILL.md examples/ unit-test-example.md templates/ test-plan.md核心文件是SKILL.md它定义了技能的元信息、触发条件、执行流程和输出要求。examples目录放的是正反示例帮助 AI 理解什么样的输出是好的、什么样的是不好的。templates目录放的是输出模板确保 AI 产出的结果格式统一。这个结构看起来简单但每个部分都有讲究。SKILL.md里的触发条件写得越精确自动加载的准确率就越高。示例的质量直接决定了 AI 模仿出来的输出质量。模板则保证了不同人、不同时间使用同一个技能产出的结果结构是一致的。3.2 SKILL.md 里到底写了什么我拆了一个“代码审查”技能的SKILL.md核心内容大概分这么几块。第一块是元信息包括技能名称、版本号、适用场景的一句话描述。这部分主要是给人看的方便管理和检索。第二块是触发条件用自然语言描述什么情况下应该加载这个技能。比如“当用户要求审查代码、检查代码质量、或者提交了代码变更请求审查时”。这里的关键是描述要覆盖用户可能的各种表达方式不能只写一种。第三块是执行流程这是最核心的部分。它把代码审查拆成了几个步骤先看整体结构再看具体逻辑然后检查边界情况接着看测试覆盖最后给出分级建议。每个步骤都有明确的检查点和判断标准。第四块是输出格式要求规定审查结果必须包含哪些部分比如问题列表、严重程度分级、修改建议、示例代码等。格式统一之后不管是人看还是机器处理效率都高很多。第五块是注意事项列出这个技能使用时的禁忌和边界。比如“不要对未提交的草稿代码做正式审查”“不要在没有上下文的情况下给出架构级建议”等。3.3 写一个自己的技能包从零到可用的完整过程我拿自己写的一个“API 设计审查”技能包来举例完整走一遍流程。第一步是明确技能边界。我要解决的是“审查 RESTful API 设计是否合理”这个问题不包括 GraphQL不包括 gRPC就是纯粹的 RESTful API。边界划清楚之后后面所有内容都围绕这个边界来写。第二步是梳理执行流程。我把自己平时审查 API 时的思考过程写下来先看 URL 结构是否符合资源导向再看 HTTP 方法使用是否正确然后看状态码是否恰当接着看请求和响应体设计是否合理最后看错误处理是否完善。这五步就是技能的骨架。第三步是补充判断标准。每一步都要给出具体的判断依据。比如 URL 结构这一步标准是“资源用名词复数层级不超过三层避免动词出现在路径中”。有了这些标准AI 才能做出判断而不是泛泛地说“看起来还行”。第四步是准备示例。我找了两个真实的 API 设计一个是我认为设计得好的一个是有明显问题的分别写清楚好在哪里、问题在哪里。示例不用多每个技能两三个就够但质量一定要高。第五步是定义输出模板。我要求审查结果必须包含总体评价、问题清单按严重程度排序、每个问题的详细说明和修改建议、修改后的示例代码。这个模板固定下来之后每次审查的输出都是一致的。第六步是实际测试和迭代。写完初版之后我拿它跑了十几个真实的 API 设计看输出质量怎么样哪里判断不准哪里遗漏了重要检查点然后回头修改SKILL.md。这个迭代过程大概持续了两周改了七八版才稳定下来。注意写技能包最忌讳的就是一开始追求大而全。我见过有人写了一个“后端开发”技能包想把所有后端相关的东西都塞进去结果写了两千多字AI 加载之后反而不知道该干什么了。技能包要小而精一个技能解决一个明确的问题。3.4 技能之间的依赖和冲突怎么处理当技能数量多起来之后依赖和冲突就不可避免了。比如“写测试”技能可能依赖“代码分析”技能先理解代码结构“重构”技能可能和“代码审查”技能有重叠的检查点。superpowers 的处理方式是显式声明依赖。在SKILL.md里可以声明这个技能依赖哪些其他技能加载时会自动把依赖的技能也加载进来。冲突的处理则靠优先级声明当两个技能对同一件事有不同要求时优先级高的技能覆盖优先级低的。我自己的经验是技能数量控制在 15 到 20 个之间比较合适。太少了覆盖不了日常任务太多了管理成本高而且 AI 在自动选择时容易选错。如果确实需要更多技能可以考虑分层把一些低频技能放到二级技能库里需要时手动加载。4. 实操过程与核心环节实现4.1 安装和初始化第一次跑通全流程假设你已经有了一个支持技能扩展的 AI 编程助手安装 superpowers 的过程大致如下。首先获取技能包仓库。通常是一个 Git 仓库里面包含了所有官方技能和社区贡献的技能。你可以直接克隆到本地也可以只下载你需要的技能。git clone skills-repo-url ~/.ai-assistant/skills然后配置助手加载技能目录。不同的助手配置方式不同有的是改配置文件有的是在启动参数里指定。以配置文件方式为例通常是在配置里加一行技能目录路径skills: directories: - ~/.ai-assistant/skills auto_load: true max_skills: 5auto_load控制是否自动加载技能max_skills控制单次最多加载几个技能防止加载过多导致上下文过载。配置完成后重启助手让它重新读取配置。然后你可以用一个简单任务测试技能是否生效比如让它审查一段有明显问题的代码看输出是否包含了技能定义的审查步骤和格式。4.2 技能加载的优先级和数量控制这里有一个很关键的参数单次加载的技能数量上限。我试过不设上限结果 AI 一次性加载了十几个技能上下文被塞得满满的反而影响了它对当前任务的理解。后来我把上限设成 5 个效果明显好了很多。优先级的设置也有讲究。我一般把技能分成三档核心技能比如代码分析、问题定位优先级最高常用技能比如写测试、写文档次之辅助技能比如格式化、命名建议最低。当加载数量达到上限时低优先级的技能会被自动排除。还有一个技巧是按任务阶段动态调整技能。比如在“理解需求”阶段加载需求分析相关的技能在“编码实现”阶段换成编码相关的技能在“验证”阶段再换成测试和审查相关的技能。这样每个阶段加载的技能都是最相关的不会互相干扰。4.3 一个完整任务的实操记录从需求到交付我拿一个真实任务来演示给一个已有的用户管理模块增加“批量导入用户”功能。阶段一理解需求。我先把需求描述给助手让它加载“需求分析”技能。助手按照技能定义的流程先确认了输入格式CSV 还是 Excel、字段映射规则、错误处理策略、导入数量上限等关键问题。这一步产出了一份需求确认清单我核对之后确认无误。阶段二方案设计。切换到“方案设计”技能助手给出了三种实现方案同步逐条导入、批量插入、异步队列导入。每种方案都列出了优缺点和适用场景。我选了批量插入方案因为数据量在可控范围内实现简单且性能足够。阶段三编码实现。加载“编码实现”技能助手按照项目既有的代码风格生成了实现代码。这里技能包里的“代码风格”部分起了很大作用它定义了项目的命名规范、注释风格、错误处理方式等生成的代码几乎不需要调整就能融入项目。阶段四测试编写。切换到“写测试”技能助手自动分析了新代码的分支和边界情况生成了对应的单元测试和集成测试。测试覆盖了正常导入、空文件、格式错误、字段缺失、重复数据等场景。阶段五代码审查。最后加载“代码审查”技能助手对自己的产出做了一轮审查发现了两个问题一个是批量插入时没有处理事务回滚另一个是错误提示信息不够具体。修正之后整个任务完成。整个流程走下来我的感受是技能包最大的价值不是让 AI 写出更好的代码而是让 AI 的工作过程变得可预期、可复现。同样的任务不同时间、不同人来做只要加载相同的技能产出的流程和结果结构都是一致的。4.4 技能包的版本管理和团队协作当技能包在团队内使用时版本管理就变得很重要。我们团队的做法是把技能包仓库作为项目的一个子模块跟代码一起做版本控制。每次技能包更新都要经过至少一个人的审查确保改动是合理的。技能包的更新日志要写清楚改了什么、为什么改、影响哪些任务。比如“代码审查技能 v1.3增加了对并发安全性的检查项调整了问题严重程度的分级标准”。这样团队成员在更新技能包时能清楚知道会带来什么变化。团队协作中还有一个常见问题不同人对同一个技能的理解不一致。解决方式是在技能包里加一个“使用说明”文档写清楚这个技能的设计意图、适用场景、不适用场景以及一些常见的使用误区。这个文档不需要很长但能省掉很多沟通成本。5. 常见问题与排查技巧实录5.1 技能不生效或者加载失败这是最常见的问题表现是 AI 的输出跟没加载技能时一样或者加载了错误的技能。排查思路按以下顺序来。先检查技能目录配置是否正确。路径写错了、目录权限不对、配置文件格式有误都会导致技能加载失败。可以先用一个最简单的技能测试确认基础配置没问题。再检查SKILL.md的格式是否符合规范。元信息字段缺失、触发条件描述不清晰、执行流程步骤不完整都会导致技能被跳过或者加载后不执行。我遇到过因为SKILL.md里多了一个空行导致解析失败的情况排查了半天才发现。然后检查技能之间是否有冲突。两个技能对同一件事有不同要求且优先级设置不明确时AI 可能会困惑表现出来的就是技能“不生效”。可以先把其他技能都禁用只留一个技能测试确认单个技能没问题后再逐个加回来。5.2 技能加载过多导致输出质量下降技能不是越多越好。加载过多技能会占用大量上下文空间导致 AI 对当前任务的注意力被分散。表现是输出变得泛泛而谈或者开始胡言乱语。我的经验是单次加载技能不超过 5 个核心技能不超过 3 个。如果确实需要多个技能配合可以考虑把它们合并成一个复合技能或者按任务阶段分批加载。还有一个技巧是给技能设置互斥关系。比如“快速原型”技能和“生产级代码”技能是互斥的同时加载会导致 AI 不知道该按哪个标准来写。在技能配置里声明互斥关系后加载其中一个时会自动排除另一个。5.3 技能输出格式不符合预期有时候技能加载了流程也走了但输出格式跟模板不一致。这通常是模板文件的问题。检查模板文件是否存在、路径是否正确、格式是否符合预期。另一个可能的原因是 AI 对模板的理解有偏差。可以在SKILL.md里增加一个“输出示例”部分直接给出一段符合格式要求的输出样例让 AI 照着模仿。这个方法的有效率很高我试过之后格式问题基本消失了。如果格式要求比较复杂比如包含表格、代码块、分级列表等建议把模板拆成多个部分每个部分单独说明。一次性给一个复杂的模板AI 容易顾此失彼。5.4 常见问题速查表问题现象可能原因排查步骤解决方法技能完全不生效目录配置错误检查配置文件路径和权限修正路径确保读取权限加载了错误的技能触发条件描述模糊查看SKILL.md触发条件细化触发条件描述输出质量下降技能加载过多查看当前加载的技能列表减少加载数量设置优先级输出格式不对模板缺失或不清晰检查模板文件和示例补充模板和输出示例技能之间冲突优先级未定义检查技能依赖和优先级显式声明优先级和互斥关系技能更新后失效版本不兼容查看更新日志和变更说明回滚或适配新版本5.5 几个我踩过的坑和对应的技巧第一个坑是技能描述写得太抽象。我一开始写触发条件时写的是“当用户需要帮助时”结果几乎所有对话都触发了这个技能。后来改成“当用户明确要求审查代码、检查代码质量、或提交代码变更请求审查时”准确率立刻上来了。触发条件要具体到用户可能说的原话。第二个坑是示例质量不高。我一开始随便找了几段代码当示例结果 AI 模仿出来的输出质量也很一般。后来我花时间精心挑选了高质量的示例每个示例都写清楚好在哪里、为什么好AI 的输出质量跟着就上去了。示例的质量直接决定输出的质量这个投入是值得的。第三个坑是技能包没有版本管理。有一次我改了一个技能结果影响了团队其他人的使用因为大家用的都是最新版。后来我们改成版本固定更新需要显式操作问题就解决了。技能包也是代码需要跟代码一样的管理方式。第四个坑是过度依赖自动加载。自动加载确实方便但在复杂任务中容易选错技能。我现在的重要任务都用手动模式先想清楚需要哪些技能再手动加载。自动模式只用在简单任务或者探索性任务上。6. 技能包设计的一些进阶思路6.1 把团队规范沉淀成技能包superpowers 最吸引我的地方是它提供了一种把团队隐性知识显性化的载体。每个团队都有自己的编码规范、审查标准、发布流程这些知识通常散落在文档、代码注释、老员工的脑子里。技能包可以把这些知识集中起来变成 AI 可以执行的指令。我们团队已经把代码审查规范、API 设计规范、数据库变更规范都写成了技能包。新成员加入后不需要花大量时间读文档直接让 AI 加载对应技能就能按照团队标准来工作。这个效果比传统的文档培训好很多因为 AI 会在实际任务中一步步引导你走完流程。6.2 技能包的组合和编排单个技能解决单个问题多个技能组合起来可以解决复杂问题。superpowers 支持技能的组合你可以定义一个“复合技能”它内部按顺序调用多个子技能。比如“新功能开发”这个复合技能内部依次调用“需求分析”“方案设计”“编码实现”“写测试”“代码审查”五个子技能。使用时只需要加载这一个复合技能它会自动按流程走完所有步骤。这对于标准化程度高的任务非常有用能确保每个环节都不遗漏。组合技能的设计要点是明确每个子技能的输入和输出确保上一个的输出能作为下一个的输入。比如“方案设计”的输出是设计方案文档“编码实现”的输入就是这份文档。输入输出不匹配的话组合就会断掉。6.3 技能包的持续迭代技能包不是写完就完了需要持续迭代。我的做法是每次使用技能后花一分钟记录一下哪里好用、哪里不好用、哪里需要补充。积累到一定程度后集中做一次更新。迭代的频率不用太高一个月一次就够了。更新内容主要是补充新的检查点、修正不准确的判断标准、增加新的示例。每次更新后用几个典型任务测试一下确认没有引入新问题。还有一个技巧是建立技能使用反馈机制。在团队内鼓励大家使用技能后反馈问题可以是一个简单的表单也可以是一个共享文档。反馈积累多了就能发现技能包的共性问题和改进方向。7. 关于“想要安装superpowers”的一些实际建议如果你看完上面的内容决定动手试试我有几个实际建议。先从官方技能包开始不要一上来就自己写。官方技能包经过大量测试质量和稳定性都有保障。先用官方技能跑通流程理解技能包的工作方式再考虑自己写。安装之后不要急着用在重要任务上。先拿一些无关紧要的任务练手比如审查一段示例代码、给一个玩具项目写测试。熟悉了技能加载、输出格式、常见问题之后再逐步用到真实项目中。技能包的数量要克制。我见过有人一口气装了三十多个技能结果 AI 每次加载都像在抽奖输出质量极不稳定。从三五个核心技能开始用顺了再逐步增加。最后技能包是辅助工具不是万能药。它能提升 AI 输出的稳定性和规范性但不能替代你自己的判断。AI 给出的建议最终还是要你来把关。我在实际使用中的体会是技能包最大的价值是让我从“反复解释我要什么”中解放出来把精力集中在真正需要判断力的地方。