1. 从“superpowers”这个标题说起它到底是什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是超级英雄电影里的超能力或者某个游戏里的技能系统。但如果你是在技术社区、代码仓库或者开发者聊天群里反复刷到这个关键词那它大概率指向的是另一个东西——一个围绕 AI 编程助手构建的技能扩展框架。我最早接触它是在一个自动化代码生成的项目里当时团队里有人丢过来一句“你试试 superpowers比手写 prompt 稳多了”从那之后我就开始认真研究这套东西。简单来说superpowers 是一套让 AI 编程助手比如 Codex 这类工具具备“可插拔技能”的机制。你可以把它理解成给 AI 装了一个工具箱原本它只会跟你聊天、补全代码但装上 superpowers 之后它能按照预定义的技能模块去执行更复杂的任务比如自动生成项目脚手架、批量重构代码、按照规范写测试用例、甚至帮你梳理需求文档。它的核心价值在于把零散的提示词工程沉淀成可复用、可组合、可版本管理的技能包而不是每次都要从头写一大段 prompt。这篇文章适合几类人看一是已经在用 AI 编程助手但觉得“每次都要重复描述需求”很烦的开发者二是想了解 superpowers 安装和使用教程的技术爱好者三是团队里负责搭建研发工具链的人想看看能不能把这套东西集成到自己的流程里。我会从整体设计思路、核心细节、实操过程、常见问题几个角度展开尽量把我知道的、踩过的坑都写清楚。2. 整体设计与思路拆解为什么要有“技能”这层抽象2.1 从“写提示词”到“装技能包”的思维转变早期用 AI 编程助手的人都有一个共同体验你写一段 prompt它给你一段代码但下次遇到类似任务你还得把那段 prompt 重新组织一遍。更麻烦的是不同人写的 prompt 风格不一样同一个人不同时间写的也不一样导致输出质量忽高忽低。这就像你每次做饭都要重新发明一遍菜谱而不是把菜谱存下来反复用。superpowers 的设计思路就是解决这个问题。它把“完成某类任务所需的指令、上下文、约束条件、输出格式”打包成一个技能skill每个技能有明确的名称、描述、触发条件和执行逻辑。当你在 AI 助手里调用某个技能时框架会自动把对应的指令集注入到对话上下文中让模型按照预设的方式工作。这样做的好处很明显输出一致性大幅提升团队协作时大家用的是同一套技能定义新人上手也快。我自己的体会是在没有 superpowers 之前我写一个“生成 RESTful API 控制器”的 prompt 大概要 200 字而且每次都要微调。用了技能包之后我只需要说“用 api-controller 技能生成用户模块的接口”剩下的交给框架。这个转变带来的效率提升不是线性的而是你终于可以把精力放在“做什么”而不是“怎么说”上。2.2 技能的组合与优先级机制superpowers 另一个让我觉得设计得比较巧妙的地方是技能可以组合。比如你有一个“代码风格检查”技能和一个“单元测试生成”技能你可以让 AI 先执行风格检查再基于检查结果生成测试。框架内部会维护一个技能栈按照调用顺序依次注入指令并且后面调用的技能可以覆盖前面技能的部分参数。这里涉及一个优先级的问题。假设两个技能都对“输出语言”做了设定一个要求用 Python一个要求用 Java那最终听谁的根据我的实测superpowers 通常采用“后调用优先”的策略也就是最后加载的技能会覆盖之前的同名配置。但如果你显式地在调用时指定了参数那显式参数优先级最高。这个机制在团队协作时特别有用基础技能定义通用规范项目级技能覆盖特定要求个人调用时再临时调整。注意技能组合不是越多越好。我试过一次调用里塞了五六个技能结果模型被各种指令绕晕了输出反而变得很奇怪。一般来说单次任务控制在两到三个技能以内比较稳妥。2.3 为什么选择这种架构而不是微调模型有人可能会问既然想让 AI 按特定方式工作为什么不直接微调一个模型这个问题我在项目初期也纠结过。后来想明白了微调的成本太高而且不灵活。你微调一个模型要准备数据集、租 GPU、跑训练周期至少几天而且一旦业务需求变了模型又得重新调。superpowers 这种基于提示词注入的方案改一个技能定义就是改一个配置文件的事几分钟就能生效。另外微调模型会把能力“焊死”在权重里你没法针对不同项目切换不同风格。而技能包是可以按项目、按团队、按任务类型灵活切换的。今天做前端项目加载前端技能组明天做数据管道加载数据技能组互不干扰。这种灵活性在实际工作中太重要了因为大多数开发者不可能只做一类任务。3. 核心细节解析与实操要点安装、配置与技能编写3.1 superpowers 安装与环境准备先说安装。superpowers 本身通常不是一个独立运行的软件而是作为某个 AI 编程助手平台的扩展或插件存在。以我用的环境为例它一般通过包管理器安装比如在 Node.js 生态里可能是npm install -g superpowers-cli这样的命令在 Python 生态里可能是pip install superpowers。具体命令取决于你用的平台但整体流程大同小异。安装之前有几个前置条件需要确认。第一你的 AI 编程助手版本要支持扩展机制太老的版本可能没有对应的接口。第二确保你的运行环境有足够的权限去读写配置目录因为技能包需要存放在特定路径下。第三如果你在公司内网环境可能需要配置包管理器的镜像源否则下载会很慢。# 以 Node.js 环境为例安装 superpowers CLI npm install -g superpowers-cli # 验证安装是否成功 superpowers --version # 初始化配置目录 superpowers init执行init之后通常会在用户目录下生成一个.superpowers文件夹里面包含skills子目录和config.json配置文件。skills目录就是放技能定义的地方每个技能一个文件夹或者一个 YAML/JSON 文件。config.json里可以设置默认技能组、日志级别、缓存策略等。实操心得我建议把.superpowers/skills目录纳入 Git 管理这样团队里每个人都能共享同一套技能定义。但config.json里的个人偏好设置比如默认输出语言可以放在本地不提交避免互相覆盖。3.2 技能定义文件的结构与关键字段一个典型的技能定义文件包含以下几个核心字段name技能名称、description技能描述、trigger触发条件、instructions指令集、parameters可配置参数、examples示例。其中instructions是最重要的部分它决定了 AI 实际执行任务时看到什么指令。我拿一个“生成数据库迁移脚本”的技能来举例。name叫db-migrationdescription写“根据模型定义生成数据库迁移脚本”trigger可以设置为当用户提到“迁移”“migration”“改表结构”等关键词时自动建议加载。instructions里要写清楚使用什么 ORM 框架、命名规范是什么、是否要生成回滚脚本、字段类型映射规则等。parameters可以暴露一些选项比如database_typeMySQL/PostgreSQL、include_rollback是否包含回滚。name: db-migration description: 根据模型定义生成数据库迁移脚本 trigger: keywords: [迁移, migration, 改表, schema change] parameters: database_type: type: string enum: [mysql, postgresql] default: postgresql include_rollback: type: boolean default: true instructions: | 你是一个数据库迁移脚本生成器。根据用户提供的模型定义生成对应的迁移脚本。 要求 1. 使用 AlembicPython或 KnexNode.js的语法风格根据项目技术栈自动判断。 2. 表名使用蛇形命名法字段名同样使用蛇形命名法。 3. 每个迁移脚本必须包含 up 和 down 两个方向的操作。 4. 如果 include_rollback 为 true额外生成回滚脚本文件。 5. 所有时间戳字段默认使用 timestamp with time zone。 examples: - input: 用户表包含 id、username、email、created_at output: 生成对应的 create_users_table 迁移脚本这个结构看起来简单但实际写的时候有几个坑。第一instructions不要写得太模糊比如“生成合理的代码”这种话模型没法执行要具体到命名规范、文件路径、依赖库版本。第二trigger的关键词不要设得太宽泛否则随便说句话就触发技能加载反而干扰正常对话。第三examples很重要它相当于给模型做少样本学习两三个好例子比一大段描述还管用。3.3 技能加载与调用的几种方式superpowers 的技能调用方式通常有三种。第一种是自动触发框架根据你的输入内容匹配trigger关键词自动加载对应技能。第二种是显式调用你在对话里直接写技能名称比如“使用 db-migration 技能”。第三种是配置文件预设在config.json里指定默认加载的技能组每次启动助手时自动生效。我个人的习惯是常用技能放在默认技能组里自动加载特殊技能用显式调用。自动触发虽然方便但有时候会误触发。比如我在讨论数据库设计时随口说了“迁移”两个字框架就把迁移技能加载进来了结果它开始给我生成脚本而我只是想讨论方案。后来我把自动触发的关键词收窄了只保留比较明确的指令性词汇。显式调用的好处是意图明确但需要你记住技能名称。我建议团队里维护一个技能清单文档列出所有可用技能及其用途新人来了先看一遍。另外有些平台支持技能别名你可以给长名字的技能设一个短别名调用起来更方便。4. 实操过程与核心环节实现从零搭建一套技能组4.1 需求梳理与技能拆分假设我们要为一个 Web 后端项目搭建一套 superpowers 技能组覆盖日常开发中最常见的任务。第一步不是急着写技能文件而是先梳理需求团队平时重复性最高的任务有哪些我列了一下大概包括生成控制器代码、生成数据模型、生成迁移脚本、生成单元测试、代码审查、生成 API 文档。接下来是技能拆分。一个技能不要太贪心试图覆盖太多功能。比如“生成控制器代码”和“生成数据模型”虽然相关但最好拆成两个技能因为它们的输入输出和约束条件不一样。拆分的粒度可以参考一个标准如果一个技能需要超过 500 字的指令来描述那可能就太大了考虑再拆。拆分完之后给每个技能定一个清晰的边界。比如api-controller技能只负责生成控制器层的代码不涉及路由注册和依赖注入配置那些交给route-config技能。边界清晰的好处是技能可以独立演进修改一个不会影响另一个。4.2 编写第一个技能以 api-controller 为例我们拿api-controller这个技能来完整走一遍编写过程。首先确定它的输入用户会提供资源名称比如 user、order、需要的操作CRUD 中的哪几个、以及一些可选参数是否分页、是否软删除。输出是一段符合项目规范的控制器代码。instructions部分要写清楚项目用的框架比如 Express、Koa、FastAPI、Spring Boot因为不同框架的控制器写法差异很大。我一般会在技能里加一个framework参数让调用时指定。然后写清楚代码风格是否用 async/await、错误处理用 try-catch 还是中间件、返回值格式统一成什么样。name: api-controller description: 生成 RESTful API 控制器代码 parameters: framework: type: string enum: [express, koa, fastapi, spring] default: express operations: type: array items: type: string enum: [list, get, create, update, delete] default: [list, get, create, update, delete] pagination: type: boolean default: true instructions: | 根据用户提供的资源名称和参数生成对应的控制器代码。 规范要求 1. 文件路径为 src/controllers/{resource}.controller.jsExpress/Koa或 app/controllers/{resource}_controller.pyFastAPI。 2. 每个操作对应一个函数函数名使用 camelCaseJS或 snake_casePython。 3. 列表操作如果 pagination 为 true必须支持 page 和 pageSize 查询参数默认 page1pageSize20。 4. 所有返回值统一为 { code: number, data: any, message: string } 格式。 5. 错误处理使用项目统一的 AppError 类不要直接抛出原始 Error。 6. 不要生成路由注册代码只生成控制器函数。 examples: - input: 资源名 user框架 express操作 list 和 get output: 生成 listUsers 和 getUser 两个函数写完这个技能后我会实际调用几次看看输出是否符合预期。第一次调用往往会有偏差比如模型可能多生成了路由代码或者返回值格式不对。这时候不要急着改instructions先看看是不是examples不够明确。我通常会在examples里加一个完整的输入输出对把期望的代码结构展示出来这样模型模仿起来更准。4.3 技能组的组织与版本管理当技能数量多起来之后就需要考虑怎么组织。我的做法是按领域分目录skills/backend/、skills/frontend/、skills/devops/、skills/common/。每个目录下放对应的技能文件。config.json里可以按目录加载比如后端项目就加载backend和common两个目录。版本管理方面我强烈建议用 Git 管理技能目录。每次修改技能定义都提交一次写清楚改了什么、为什么改。这样当某个技能的输出质量下降时你可以回溯到之前的版本对比。另外技能定义也可以打标签比如v1.0、v1.1方便不同项目锁定不同版本。注意技能定义里的instructions不要写死具体的项目路径或密钥信息。这些应该通过参数传入而不是硬编码在技能里。我见过有人在技能里写了数据库连接字符串结果提交到仓库后泄露了这种低级错误一定要避免。4.4 与现有研发流程的集成superpowers 不是孤立使用的它需要嵌入到日常研发流程里。我的做法是在项目的 README 或者开发者文档里加一节“AI 助手技能使用指南”列出本项目推荐加载哪些技能、每个技能怎么调用、常见参数怎么填。新人入职时先看这一节能省掉很多重复解释。另外在 CI/CD 流程里也可以集成。比如代码提交时自动调用code-review技能做一轮静态检查把结果作为评论发到 PR 上。虽然不能完全替代人工审查但能拦住一些低级问题比如命名不规范、缺少错误处理、硬编码配置等。我实测下来这种自动检查能减少大约三成的 review 往返次数。5. 常见问题与排查技巧实录5.1 技能不生效或输出不符合预期这是最常见的问题。表现是你明明加载了技能但 AI 的输出跟没加载一样。排查思路分几步走。第一确认技能是否真的被加载了。大多数框架会输出加载日志你可以打开 debug 模式看看。第二检查trigger关键词是否匹配上了有时候你用的词跟定义的不一样自动触发就不会生效。第三看看instructions是不是被后续加载的技能覆盖了前面说过后调用优先如果后面加载了一个通用技能可能会把前面的特定指令冲掉。如果确认加载了但输出还是不对那多半是instructions写得太模糊。我的经验是把模型当成一个非常聪明但完全不了解你项目背景的新人。你需要告诉它文件放哪、用什么库、命名规则是什么、异常怎么处理。不要假设它能猜到。另外examples的质量直接影响输出一个好的示例胜过十句描述。5.2 技能之间的冲突与优先级混乱当多个技能同时加载时冲突几乎不可避免。常见的冲突点包括输出语言Python vs Java、代码风格函数式 vs 面向对象、文件路径规范、依赖库版本。解决冲突的原则是显式参数 后加载技能 先加载技能 默认配置。我一般会在团队里约定一个技能加载顺序先加载通用规范技能比如code-style再加载领域技能比如api-controller最后加载项目特定技能比如project-xxx-conventions。这样项目特定技能可以覆盖前面的通用设定。如果还是冲突那就说明技能拆分不够清晰需要重新审视边界。下面这张表是我整理的一些典型冲突场景和解决方式冲突场景表现解决方式输出语言不一致一个技能要求 Python一个要求 Java在调用时显式指定 language 参数命名规范冲突驼峰 vs 蛇形通用技能定义默认规范项目技能覆盖文件路径冲突不同技能生成到不同目录统一在项目技能里定义路径规则错误处理方式不同抛异常 vs 返回错误码以项目技能为准通用技能只做建议依赖库版本不同一个用 lodash一个用原生在项目技能里锁定依赖版本5.3 性能问题与缓存策略技能加载多了之后每次对话都要注入大量指令会导致响应变慢。我实测过加载五个技能比加载一个技能的首字延迟大概多出 30% 到 50%。解决办法有几个一是按需加载不要把所有技能都放在默认组里二是启用缓存大多数框架支持把技能指令缓存到本地避免每次重新读取文件三是精简instructions把不必要的内容删掉只保留核心约束。还有一个容易被忽略的点技能定义文件不要太大。我见过有人把一个技能文件写到上千行里面塞了大量示例和边缘情况说明。结果模型处理起来很吃力输出反而变差。我的建议是单个技能文件控制在 200 行以内超出的部分拆成多个技能或者把详细说明放到外部文档里技能里只保留引用。5.4 团队协作中的技能管理问题团队用 superpowers 最大的挑战不是技术而是管理。每个人都有自己的使用习惯有人喜欢自动触发有人喜欢显式调用有人改了技能定义不提交导致别人拉到的还是旧版本。我的做法是技能目录必须纳入版本控制修改必须走 PR 流程至少一个人 review 后才能合并。另外定期组织技能评审会把大家踩过的坑和优化建议同步一下。还有一个实际问题是不同项目可能需要不同版本的同一个技能。比如 A 项目用 ExpressB 项目用 FastAPIapi-controller技能虽然可以参数化但默认值不一样。我的处理方式是给技能打标签A 项目锁定express-v1.2B 项目锁定fastapi-v1.0。这样各项目独立演进互不影响。6. 一些进阶玩法与个人体会6.1 技能链与自动化工作流当你熟悉了单个技能的编写和调用之后可以尝试把多个技能串成一条链。比如“生成数据模型 - 生成迁移脚本 - 生成控制器 - 生成测试”这一整套流程可以定义成一个工作流技能内部按顺序调用其他技能。这样你只需要说“为用户模块生成完整后端代码”框架就会自动跑完整个链条。我试过用这种方式做原型开发效率提升非常明显。原本需要手动调用四五次、每次都要检查输出现在一次调用就能拿到一套基本可用的代码。当然自动生成的代码还是需要人工审查和调整但至少省掉了从零开始写的功夫。我的经验是工作流技能适合用在标准化程度高的任务上如果任务本身变数很大强行串链反而会降低灵活性。6.2 技能的市场化与共享superpowers 生态里还有一个有意思的方向是技能共享。你可以把自己写的技能发布出去别人也可以下载使用。这有点像 npm 包或者 VS Code 插件的模式。我在社区里看到过一些质量很高的技能包比如专门针对某个框架的代码生成技能、针对特定云服务的配置生成技能。不过共享技能也有风险。你下载别人的技能相当于把一段指令注入到自己的 AI 助手里如果技能里包含恶意指令比如让模型输出敏感信息后果可能很严重。所以我在使用第三方技能之前一定会先打开文件看看instructions里写了什么确认没有奇怪的内容再加载。另外尽量从官方仓库或者可信来源下载不要随便从论坛附件里拿。6.3 我踩过的几个坑第一个坑是过度依赖自动触发。刚开始我觉得自动触发很酷不用记技能名说句话就自动加载。结果有一次我在写文档时提到“测试”两个字框架把单元测试生成技能加载进来了然后开始给我生成测试代码完全打断了我的思路。后来我把自动触发的关键词收窄到非常明确的指令性短语比如“生成测试”“写单元测试”而不是单个词“测试”。第二个坑是技能定义写得太细。我曾经写过一个技能把代码的每一行格式都规定死了连空行位置都写了。结果模型变得非常死板稍微换个场景就不会变通了。后来我明白了技能定义应该规定“必须遵守的约束”和“期望的输出结构”而不是逐行规定代码长什么样。给模型留一点发挥空间输出反而更好。第三个坑是忽略版本兼容。有一次我升级了 AI 助手的版本结果发现之前写的技能全部失效了因为新版本改了技能加载的接口。从那以后我在升级助手之前都会先看 changelog确认技能机制有没有变化。如果变化大就先在测试环境验证一遍再升级生产环境。6.4 后续可以扩展的方向如果你已经把基础技能用起来了可以考虑几个扩展方向。一是把技能和项目模板结合新项目初始化时自动加载对应的技能组省去手动配置。二是把技能和代码审查工具集成在 CI 里自动跑一遍技能检查把问题拦截在合并之前。三是把技能和文档生成结合根据代码自动生成 API 文档和变更日志。我个人最看好的方向是技能和测试的结合。现在很多团队写测试的积极性不高因为太耗时。如果能让 AI 根据代码自动生成测试用例再人工补充边缘情况整体效率会高很多。我试过用 superpowers 生成单元测试覆盖率能到 70% 左右剩下的 30% 需要人工补充但已经省了很多时间。最后分享一个小技巧定期回顾你的技能使用记录看看哪些技能调用频率高、哪些几乎没用过。把低频技能清理掉把高频技能的instructions持续优化。技能库跟代码库一样需要定期维护不然会越来越臃肿最后反而拖慢效率。