1. 从“superpowers”这个热词说起它到底是什么最近一段时间superpowers这个词在技术社区里出现的频率明显高了起来。很多人第一次看到它会以为是某个新出的编程语言或者框架其实不是。它本质上是一套面向 AI 编程助手的技能扩展体系你可以把它理解成给 AI 助手装上一批“专业工具箱”让它在处理具体任务时不再只会泛泛而谈而是能按照一套经过验证的流程去干活。我最初接触superpowers是因为团队里有人在讨论“怎么让 AI 助手写代码更靠谱”。当时大家的痛点很一致直接让 AI 写一个功能它往往能给出能跑的代码但结构混乱、边界情况不考虑、测试也不写。后来有人提到了superpowers这套东西说它把很多工程实践固化成了可复用的技能模块。我花了两天时间研究它的组织方式和使用逻辑实测下来确实解决了不少问题。这篇文章适合几类人看一是已经在用 AI 编程助手、但觉得输出质量不稳定的开发者二是想了解“技能skills”这种扩展机制到底怎么运作的技术爱好者三是想给自己团队搭建一套 AI 辅助开发规范的技术负责人。我会从它的整体设计思路讲起然后拆解核心技能模块再给出完整的安装和引入步骤最后分享我在实际使用中踩过的坑和总结出来的排查技巧。整篇内容基于我对这套体系的实操理解涉及具体操作的地方都会给出可直接参考的方案。需要提前说明的是superpowers本身不是一个独立运行的软件它依附于特定的 AI 编程助手环境。所以你在看后面的安装步骤时要先确认自己用的助手是否支持这种技能扩展机制。如果不支持那后面的内容可以当作了解设计思路来读也能帮你判断未来要不要迁移到支持的环境。2. 整体设计思路拆解为什么要把技能拆成模块2.1 核心问题AI 助手的“通用性陷阱”AI 编程助手有一个天然矛盾它被训练成什么都能聊、什么都能写但真正落到工程场景里通用性反而成了负担。你让它写一个 HTTP 接口它可能给你一个能跑但没有任何错误处理、没有参数校验、没有日志的版本。你让它改一个 bug它可能顺手把周围代码也重构了引入新的问题。这个矛盾的根源在于AI 助手没有一个明确的“当前任务应该遵循什么流程”的约束。它每次都在根据你的 prompt 即兴发挥而 prompt 本身很难把所有工程规范都写进去。你不可能每次都说“请遵循分层架构、请写单元测试、请处理边界情况、请加日志”那样 prompt 会长得没法维护。superpowers的思路就是把这些约束从 prompt 里抽出来变成独立的、可组合的技能模块。每个技能模块定义了一类任务的标准流程和检查清单。当 AI 助手识别到当前任务属于某个技能范畴时就自动加载对应的流程来执行。这样既保证了输出质量的一致性又不用每次都在 prompt 里重复写规范。2.2 技能模块的粒度设计我研究下来发现superpowers的技能粒度设计得比较讲究。它不是按“语言”或“框架”来分而是按工程活动来分。比如有专门负责“写测试”的技能、专门负责“代码审查”的技能、专门负责“调试”的技能、专门负责“重构”的技能。这种分法的好处是跨语言通用——不管你写 Python 还是 TypeScript调试的流程逻辑是相似的。另一个设计特点是技能之间可以串联。比如你先用“需求分析”技能把模糊需求拆成具体任务再用“实现”技能写代码最后用“审查”技能检查。每个技能的输出会成为下一个技能的输入形成一条流水线。这比让 AI 一次性完成所有事情要可靠得多因为每一步都有明确的输入输出边界出了问题容易定位。2.3 为什么这种设计比“大 prompt”更有效我试过两种方式一种是把所有规范写在一个超长 prompt 里另一种是用superpowers的技能模块。实测下来技能模块的方式在三个方面明显更好。第一是可维护性。规范变了只需要改对应的技能文件不用去翻几十个 prompt 模板。第二是可组合性。不同项目可以按需启用不同技能比如一个脚本项目可能不需要“架构设计”技能但一个大型服务就需要。第三是可解释性。当 AI 输出不符合预期时你可以去看它加载了哪个技能、技能里定义了什么流程从而判断是技能定义有问题还是 AI 执行有问题。大 prompt 方式下你很难知道 AI 到底关注了哪部分指令。提示如果你现在还在用大 prompt 方式建议先挑一个最常做的任务比如写单元测试把它抽成一个独立的技能文件试试。不用一次性全改逐步迁移更容易看到效果。3. 核心技能模块解析与实操要点3.1 需求拆解类技能把模糊描述变成可执行任务这类技能解决的是“用户说了一句模糊的话怎么变成具体开发任务”的问题。比如用户说“帮我加个登录功能”这背后涉及路由、表单、校验、会话管理、错误提示等一系列子任务。需求拆解技能会引导 AI 按固定维度去提问和拆解而不是直接开始写代码。我在实际使用中发现这类技能最关键的是提问清单。好的技能会定义一组必问问题比如“认证方式是什么”“是否需要记住登录状态”“失败几次锁定”“密码强度要求”等。AI 会带着这些问题去和用户交互把答案补全后再进入实现阶段。这比直接写代码然后反复改要高效得多。实操要点使用这类技能时你要有耐心回答 AI 的提问。我见过有人嫌麻烦直接说“你看着办”结果 AI 按默认假设做出来的东西和预期差很远。技能的价值就在于把隐含假设显式化你配合得越好输出越准。3.2 代码实现类技能约束输出结构和边界处理代码实现类技能是使用频率最高的。它定义了一套代码组织规范比如函数长度限制、错误处理模式、日志埋点位置、命名约定等。AI 在写代码时会参照这些规范而不是自由发挥。我对比过启用和未启用这类技能的输出差异。未启用时AI 写的函数经常超过一百行错误处理就是一句console.log边界情况基本不考虑。启用后函数会被拆成多个小函数每个都有明确的职责错误处理会区分可恢复和不可恢复边界情况会有显式判断。代码量可能多了百分之二三十但可维护性提升明显。这里有个细节值得说技能里通常会定义代码审查清单AI 在写完后会自己对照清单检查一遍。我实测发现这个自检环节能拦下不少低级问题比如忘记处理空值、忘记关闭资源、硬编码配置等。虽然不能完全替代人工审查但能减少很多返工。3.3 测试与调试类技能让 AI 自己验证自己的输出测试类技能要求 AI 在实现功能后必须写对应的测试并且测试要覆盖正常路径、边界路径和异常路径。调试类技能则定义了一套排查流程先复现、再定位、再假设验证、最后修复并加回归测试。我特别喜欢调试类技能里的假设验证环节。传统调试时人容易凭直觉猜原因然后改一处试一处。技能会强制 AI 先列出可能的根因假设然后设计最小验证步骤去逐个排除。这个方法我在带新人的时候也经常强调但人往往做不到AI 反而能严格执行。注意事项测试类技能生成的测试用例质量参差不齐。我遇到过 AI 写的测试只断言了“函数被调用”没有断言实际行为。所以启用技能后还是要抽查测试代码必要时在技能定义里补充断言规范。3.4 代码审查类技能把 review 经验固化成检查项代码审查类技能把常见的 review 关注点整理成了检查清单比如安全漏洞、性能隐患、并发问题、资源泄漏、命名一致性等。AI 在审查时会逐项过一遍并给出具体行号和修改建议。我用这个技能审查过团队里一个老模块它找出了三处潜在的资源未释放问题和一处并发写入风险。这些问题人工 review 时因为代码太长被忽略了。当然它也有误报比如把一些有意的设计当成问题但整体上作为第一道过滤网很有价值。注意代码审查技能不能替代人工审查尤其是涉及业务逻辑正确性的部分。AI 不懂你的业务规则它只能从通用工程角度检查。建议把 AI 审查放在人工审查之前先过滤掉通用问题让人专注于业务逻辑。4. 完整安装与引入流程从零到跑通4.1 环境确认与前置检查在安装之前你需要确认三件事。第一你用的 AI 编程助手是否支持外部技能文件加载。目前主流的一些助手通过配置文件或插件机制支持具体要看官方文档。第二你的项目目录结构是否允许放置技能文件。通常技能文件放在项目根目录下的特定文件夹里比如.skills/或.assistant/skills/。第三确认你的助手版本是否支持技能串联老版本可能只支持单个技能加载。我建议先在一个测试项目里跑通流程不要直接在主项目上操作。因为技能文件加载后可能会影响助手的默认行为万一配置有问题在测试项目里排查成本更低。4.2 获取技能文件的几种途径获取superpowers技能文件通常有几种方式。一种是从社区维护的技能仓库里直接下载这种方式最省事但要注意版本兼容性。另一种是根据自己的需求手写技能文件这种方式最灵活但需要你清楚技能文件的格式规范。还有一种是基于现有技能修改适合在通用技能基础上加入团队特定规范。我个人的做法是先从社区仓库拉一份基础技能集跑通流程后再根据团队情况逐步替换和补充。这样起步快也不会一开始就陷入写技能文件的细节里。社区技能集通常覆盖了需求拆解、实现、测试、审查这几个核心环节够用一阵子了。4.3 技能文件的目录组织与加载配置技能文件的目录组织直接影响加载效率。我推荐按“活动类型”分文件夹比如skills/analysis/、skills/implementation/、skills/testing/、skills/review/。每个技能一个文件文件名用动词开头比如analyze-requirements.md、implement-feature.md、write-tests.md、review-code.md。加载配置通常在助手的配置文件里你需要指定技能目录路径和启用哪些技能。有些助手支持自动扫描目录有些需要显式列出。我建议显式列出这样你能清楚知道当前启用了哪些技能排查问题时也方便。# 示例配置具体字段名以你使用的助手文档为准 skills: directory: ./.skills enabled: - analyze-requirements - implement-feature - write-tests - review-code auto_load: true4.4 验证技能是否生效的实操方法配置完成后怎么确认技能真的生效了我的方法是设计一个对照测试。先在不启用技能的情况下让助手写一个简单功能记录输出特征。然后启用技能再让助手写同样的功能对比输出差异。如果技能生效你应该能看到输出结构更规范、边界处理更完整、测试用例更全面。另一个验证方法是直接问助手“你当前加载了哪些技能”。有些助手会列出已加载的技能列表。如果列表和你的配置一致说明加载成功。如果为空或缺少就要检查配置路径和格式。我踩过的一个坑是技能文件里的格式标记写错了导致助手加载了文件但解析失败表现是技能列表里有名字但行为没变化。后来发现是文件头部的元数据字段少了一个冒号。所以配置完后一定要做行为验证不能只看列表。5. 常见问题与排查技巧实录5.1 技能不生效的排查顺序技能不生效是最常见的问题。我总结了一个排查顺序按这个顺序走基本能定位到原因。排查步骤检查内容常见问题1配置文件路径是否正确相对路径基准目录搞错2技能文件格式是否合法元数据字段缺失或拼写错误3助手版本是否支持老版本不支持技能串联4技能是否被其他配置覆盖多个配置文件冲突5任务类型是否匹配技能触发条件技能只对特定任务生效我遇到最多的是第二步技能文件格式问题。尤其是从社区下载的技能文件不同版本格式可能有差异。建议先用一个最简单的技能文件测试确认格式没问题后再批量导入。5.2 技能之间冲突怎么处理当你启用多个技能时可能会出现指令冲突。比如一个技能要求“函数不超过 50 行”另一个技能要求“所有逻辑写在一个函数里”。这种冲突会导致助手行为不稳定。处理方法是明确技能优先级。在配置文件里给技能设置优先级高优先级的技能指令覆盖低优先级的。或者更彻底一点把冲突的技能拆成互斥组同一时间只启用一组。我在项目里把技能分成“开发阶段”和“审查阶段”两组开发时启用实现和测试技能审查时切换到审查技能避免冲突。5.3 技能输出质量不稳定的应对即使启用了技能输出质量也可能波动。我观察到的原因是助手对技能指令的遵循程度受任务复杂度影响。任务越复杂助手越容易“忘记”技能里的约束。应对方法有两个。一是把大任务拆小每个小任务单独走技能流程。比如不要一次性让助手实现整个模块而是按函数或按接口逐个实现。二是在 prompt 里显式提醒比如“请严格按照当前加载的技能流程执行”。这个提醒看起来多余但实测能提升遵循度。5.4 技能文件的版本管理建议技能文件应该纳入版本管理和代码一起提交。因为技能定义直接影响 AI 的输出行为相当于团队规范的一部分。我建议在技能文件头部加版本号和变更记录方便追溯。当输出质量出现变化时可以先检查技能文件最近有没有改动。另外不同项目可能需要不同的技能集。我通常会在项目根目录放一份技能配置然后在团队共享仓库里维护一份基础技能集。项目配置引用基础技能集再叠加项目特定技能。这样基础技能更新时所有项目都能受益同时项目特定需求也能满足。6. 我个人的使用体会与后续扩展方向用了一段时间superpowers之后我最大的感受是它把“AI 辅助开发”从“碰运气”变成了“可预期”。以前让 AI 写代码质量好坏很大程度取决于 prompt 写得好不好而 prompt 质量又取决于当时的状态。现在有了技能模块至少核心流程是稳定的输出质量的下限被抬高了。当然它也不是万能的。技能定义得再好AI 对复杂业务逻辑的理解仍然有限。我的做法是把 AI 定位成“执行者”而不是“决策者”——流程和规范由技能定义具体业务决策还是人来定。这样分工下来效率提升明显返工也少了很多。后续我打算在两个方面继续扩展。一是把团队代码审查中反复出现的问题补充到审查技能里让 AI 提前拦截。二是尝试把技能和 CI 流程结合在提交代码时自动触发 AI 审查技能作为人工审查前的预检。这两个方向都还在试验阶段等跑通了再整理出来分享。如果你刚开始接触superpowers我的建议是不要贪多。先挑一个你最痛的点比如测试写得少就只启用测试技能跑两周看看效果。有效果了再逐步加其他技能。一次性全启用反而容易因为配置复杂而放弃。技能体系的价值在于持续使用和迭代不在于一次配齐。