1. 从“superpowers”这个热词说起它到底指什么最近“superpowers”这个词在技术圈和效率工具圈里被反复提起很多人第一次看到它是在某个开源项目的讨论区或者是在朋友分享的终端截图里。简单来说superpowers 是一套面向 AI 编程助手的能力扩展框架它通过一组结构化的技能文件skills和指令集让原本只会“你问我答”的 AI 助手变成能够主动规划、分步执行、自我检查的“超级助手”。你可以把它理解成给 AI 装上了一套“工作手册”和“工具箱”——原本它只会聊天现在它能按照你预设的流程去读代码、改文件、跑测试、写文档甚至帮你管理整个项目的开发节奏。我第一次接触这个概念是在一个开源社区里当时有人分享说“装上 superpowers 之后我的 AI 助手终于不再乱改代码了”。这句话一下子戳中了我。因为但凡用过 AI 辅助编程的人都知道最大的痛点不是 AI 不会写代码而是它太容易自作主张——你让它改一个函数它顺手把你的配置文件也改了你让它加个注释它把你的变量名全重构了一遍。而 superpowers 的核心思路就是通过一套“技能协议”来约束和引导 AI 的行为让它在动手之前先想清楚“我要做什么、分几步做、每步的验收标准是什么”。这套框架适合谁呢如果你是经常用 AI 助手写代码的开发者它能帮你把 AI 从“随机发挥的实习生”变成“按流程办事的靠谱队友”如果你是团队里负责制定开发规范的人它能帮你把团队的编码习惯、测试要求、文档标准固化到 AI 的工作流里如果你只是对 AI 效率工具感兴趣的普通用户理解 superpowers 的设计思路也能帮你更好地驾驭各种 AI 产品。接下来的内容我会从它的核心机制、安装配置、实战用法、常见坑点几个维度把“superpowers”这件事讲透。2. superpowers 的核心机制技能文件与触发逻辑2.1 为什么需要“技能”这个概念大多数人用 AI 助手的方式是“对话式”的打开对话框输入需求等回复不满意就继续追问。这种方式在简单任务上没问题但一旦任务变复杂比如“帮我给这个模块加一个缓存层要求支持过期时间和手动失效并且写对应的单元测试”AI 很容易顾此失彼——要么忘了写测试要么缓存过期逻辑写错了要么改动了不该改的文件。superpowers 的解法是引入skill技能这个概念。一个 skill 本质上是一个 Markdown 文件里面写清楚了“这个技能是干什么的、什么时候触发、执行步骤是什么、验收标准是什么”。比如有一个 skill 叫test-driven-development它的内容可能是“当用户要求添加新功能时先写一个失败的测试然后写最少的代码让测试通过最后重构。每一步都要运行测试并确认结果。”当 AI 助手加载了这个 skill 之后它再遇到“加功能”的请求就会自动按照 TDD 的流程走而不是上来就写实现代码。这背后的逻辑其实很朴素AI 的行为是由上下文决定的。你给它什么样的指令它就做什么样的事。superpowers 做的事情就是把“资深工程师的工作习惯”写成结构化的指令在合适的时机注入到 AI 的上下文里。这比你在每次对话里重复交代“记得写测试啊”“别乱改文件啊”要高效得多也可靠得多。2.2 技能是怎么被触发的skill 的触发机制是 superpowers 设计里比较巧妙的一环。它不是一个全局开关而是基于任务类型和关键词的动态匹配。每个 skill 文件的开头通常有一段元数据描述了它的触发条件。比如--- name: code-review description: 当用户要求审查代码、检查代码质量、或者提交前检查时触发 triggers: - review - 审查 - 检查代码 - code review ---当你的请求里出现了这些触发词AI 助手就会自动加载对应的 skill然后按照 skill 里定义的步骤来执行。这样做的好处是精准且不打扰——你不需要手动切换模式AI 会根据你在做什么自动选择合适的“工作手册”。我实测下来这套机制在大多数场景下都很稳但有一个细节需要注意触发词的设计要足够具体。如果你把触发词设得太宽泛比如只写一个“代码”那 AI 可能在你想聊架构的时候突然开始做代码审查反而添乱。我的经验是触发词最好包含“动作 对象”的组合比如“审查代码”“重构函数”“添加测试”这样误触发的概率会低很多。2.3 技能之间的协作与优先级superpowers 不是只有一个 skill而是一组 skill 的集合。当多个 skill 同时被触发时就需要一套优先级规则来决定谁先谁后。常见的做法是按任务阶段划分优先级规划类的 skill 优先级最高执行类的次之检查类的最后。比如你让 AI“给用户模块加一个导出功能”可能会同时触发planning规划、coding编码、testing测试三个 skill。合理的执行顺序是先规划拆解任务、确认方案再编码写实现最后测试验证功能。这里有一个容易踩的坑skill 之间的依赖关系要显式声明。如果testingskill 默认假设代码已经写好了但codingskill 还没执行完就会出现“测试跑了个寂寞”的情况。我在配置自己的 skill 集时会在每个 skill 的元数据里加一个depends_on字段明确标注它依赖哪些前置 skill。这样 AI 在调度时就能自动排好顺序不会出现“跳过步骤”的问题。3. 安装与配置从零搭建你的 superpowers 环境3.1 安装前的准备工作在动手安装之前有几件事需要先确认清楚。第一你的 AI 助手是否支持自定义指令或插件机制。superpowers 本身是一个框架它需要宿主环境提供“加载外部指令”的能力。目前主流的 AI 编程助手比如基于编辑器的助手、命令行助手大多支持通过配置文件或插件目录来注入自定义指令但具体方式各有不同。你需要先查阅你所使用工具的文档确认它支持哪种扩展方式。第二准备好你的 skill 文件存放目录。superpowers 的惯例是把所有 skill 放在一个统一的目录下比如~/.ai-skills/或者项目根目录下的.skills/。我建议区分全局 skill 和项目级 skill全局 skill 放那些通用的工作习惯比如代码审查、提交规范项目级 skill 放这个项目特有的流程比如“改数据库 schema 前必须先写迁移脚本”。这样既能复用又能保持项目间的隔离。第三确认你的 AI 助手支持 Markdown 格式的指令注入。superpowers 的 skill 文件是纯 Markdown 的如果你的工具只支持 JSON 或 YAML 格式的配置就需要做一层转换。不过大多数现代 AI 工具都支持 Markdown所以这个问题一般不大。3.2 一步步完成安装安装 superpowers 的过程其实不复杂核心就是“把 skill 文件放到正确的位置然后让 AI 助手知道去哪里加载”。以下是我在实际操作中总结的步骤以常见的命令行 AI 助手为例创建 skill 目录。在你的用户主目录下创建一个隐藏文件夹比如mkdir -p ~/.ai-skills。这个目录将作为你的全局 skill 仓库。获取 skill 文件。你可以自己写也可以从社区获取现成的 skill 集合。自己写的话每个 skill 就是一个.md文件文件名建议用英文小写加连字符比如code-review.md、test-driven-development.md。配置 AI 助手加载路径。在你的 AI 助手的配置文件里通常是一个 JSON 或 YAML 文件找到“自定义指令”或“插件目录”相关的配置项把~/.ai-skills加进去。具体配置项的写法因工具而异你需要参考对应工具的文档。验证加载是否成功。重启你的 AI 助手然后输入一个会触发某个 skill 的请求比如“帮我审查一下这段代码”。如果 AI 的回复里出现了 skill 中定义的步骤比如“我先检查代码风格再看逻辑正确性最后看测试覆盖”说明加载成功了。注意不同 AI 助手的配置方式差异较大有些工具可能需要你把 skill 文件转换成特定的格式比如 JSON 数组有些工具则直接支持 Markdown 目录扫描。在动手之前务必先确认你的工具支持哪种方式避免白忙一场。3.3 配置文件的细节与常见错误配置文件是 superpowers 能否正常工作的关键。我见过最常见的错误是路径写错。比如在 macOS 上~会被正确展开为用户主目录但在某些工具的配置里~不会被解析你需要写完整的绝对路径比如/Users/yourname/.ai-skills。另一个常见错误是文件编码问题——如果你的 skill 文件里包含中文确保文件保存为 UTF-8 编码否则 AI 加载后可能会看到乱码。还有一个容易被忽略的点skill 文件的命名和内容要一致。我曾经把一个文件命名为code-review.md但里面的name字段写的是review-code结果 AI 在触发时找不到对应的 skill导致整个流程失效。后来我养成了一个习惯文件名、name字段、触发词三者保持一致这样排查问题时一目了然。另外如果你是在团队里推广 superpowers建议把 skill 文件纳入版本控制。这样每个人拿到的都是同一套工作流不会出现“张三的 AI 会写测试李四的 AI 不会”这种尴尬情况。我们团队的做法是在项目仓库里建一个.skills/目录所有 skill 文件跟着代码一起提交新成员克隆下来就能用。4. 实战用 superpowers 完成一个真实开发任务4.1 任务背景与初始状态为了让你更直观地理解 superpowers 的用法我拿一个真实的小任务来演示给一个现有的用户管理模块添加“批量导出用户列表为 CSV”的功能。这个模块是用 Python 写的已经有基本的增删改查接口但没有导出功能。按照传统的做法你可能会直接跟 AI 说“帮我加一个导出 CSV 的功能”然后 AI 会给你一段代码你复制粘贴进去跑一下发现有问题再回来追问来回折腾好几轮。而用 superpowers 的方式整个流程会变得更有条理。前提是你已经配置好了几个关键的 skillplanning任务规划、coding编码实现、testing测试验证、code-review代码审查。下面我按实际执行顺序来拆解。4.2 规划阶段让 AI 先想清楚再动手当你输入“给用户模块添加批量导出 CSV 功能”时planningskill 会被触发。AI 不会立刻写代码而是先输出一份任务拆解确认导出字段需要导出哪些用户属性ID、用户名、邮箱、注册时间等确认导出范围是导出全部用户还是按条件筛选确认文件格式CSV 的分隔符、编码、是否包含表头确认接口设计是新增一个 API 端点还是复用现有的列表接口加参数确认依赖是否需要引入额外的库比如 Python 的csv模块是标准库不需要额外安装确认测试方案需要覆盖哪些场景空列表、大量数据、特殊字符这一步的价值在于把模糊的需求变成明确的清单。很多时候我们跟 AI 沟通效率低就是因为需求本身没想清楚。planningskill 强制 AI 先做这件事相当于帮你做了一次需求梳理。我实测下来这一步能减少至少一半的返工。4.3 编码阶段按步骤执行并自我检查规划确认后codingskill 接管。AI 会按照规划里的步骤逐项实现。比如先写一个export_users_to_csv函数然后加一个 API 路由再处理参数校验。每完成一个步骤它会自己检查一遍函数签名对不对、参数有没有做类型检查、异常处理有没有覆盖。这里有一个很实用的细节codingskill 里可以定义“禁止事项”。比如我在自己的配置里加了一条“禁止在未确认的情况下修改数据库 schema”这样 AI 在实现导出功能时就不会突发奇想地去改用户表的结构。这种约束在团队协作里特别重要因为 AI 的“创造力”有时候反而是麻烦的来源。代码写完后AI 会输出一个变更摘要列出它改了哪些文件、新增了哪些函数、删除了哪些代码。你可以快速扫一眼确认没有误伤。4.4 测试与审查把问题拦在提交之前testingskill 会在编码完成后自动触发。AI 会为新增的导出功能写单元测试覆盖正常导出、空列表导出、包含特殊字符比如逗号、换行符的用户名导出等场景。然后它会运行测试如果失败会根据错误信息尝试修复修复后再跑一遍直到通过为止。测试通过后code-reviewskill 最后介入。它会从几个维度检查代码命名是否清晰、有没有重复代码、异常处理是否完善、有没有潜在的性能问题比如导出大量用户时是否用了流式写入。如果发现问题它会给出修改建议并询问你是否需要自动修复。整个流程走下来你从一个模糊的需求开始最终得到一个经过规划、实现、测试、审查的完整功能。你全程只需要做决策和确认不需要手动写代码或调试。这就是 superpowers 带来的效率提升——它不是让 AI 写得更快而是让 AI 写得更靠谱。5. 踩坑记录我在配置和使用中遇到的五个问题5.1 触发词冲突导致 skill 误触发最开始配置的时候我把code-review的触发词设成了“检查”结果每次我说“检查一下这个函数的时间复杂度”AI 都会启动完整的代码审查流程输出一大堆关于命名规范、测试覆盖的建议而我只是想知道时间复杂度。后来我把触发词改成了“审查代码”“代码审查”“review code”这种更具体的组合问题就解决了。经验总结触发词要尽量具体最好包含明确的动作和对象。如果你发现某个 skill 经常在不该触发的时候触发先检查它的触发词是不是太宽泛了。5.2 skill 加载顺序影响执行结果有一次我同时触发了planning和coding两个 skill但 AI 先执行了coding直接开始写代码完全跳过了规划步骤。原因是我的配置文件里 skill 的加载顺序是随机的而 AI 按照加载顺序来决定执行顺序。后来我在每个 skill 的元数据里加了priority字段规划类设为 10执行类设为 5检查类设为 1这样就能保证规划永远在编码之前执行。经验总结不要依赖默认的加载顺序显式声明优先级。尤其是当你的 skill 集越来越大时优先级管理会变得越来越重要。5.3 中文触发词在某些工具里不生效我一开始把触发词写成了中文比如“审查代码”“添加测试”但在某个 AI 助手里怎么都不触发。排查后发现那个工具在匹配触发词时做了英文小写化处理中文没有被正确处理。后来我把触发词改成了中英文混合比如“审查代码|review|code review”这样无论工具怎么处理总有一个能匹配上。经验总结如果你的工具对中文支持不好触发词里加上英文别名。多写几个同义词不费事但能避免很多莫名其妙的失效。5.4 skill 文件过大导致加载缓慢我一开始把所有的检查规则都写在一个code-review.md里文件有几千行。结果每次触发审查时AI 加载这个文件都要花好几秒而且因为内容太多它经常只执行了前面几条规则就“忘了”后面的。后来我把这个大文件拆成了code-review-style.md风格检查、code-review-logic.md逻辑检查、code-review-test.md测试检查三个小文件每个文件只关注一个维度加载速度和执行完整度都明显提升。经验总结一个 skill 只做一件事。文件越小AI 的执行越精准。如果你发现某个 skill 经常“漏步骤”先看看它是不是太臃肿了。5.5 团队协作时的 skill 版本不一致我们团队一开始是每个人自己维护自己的 skill 文件结果出现了“张三的 AI 会写类型注解李四的 AI 不会”的情况代码风格变得很不统一。后来我们改成统一维护一份 skill 仓库所有人从同一个仓库拉取 skill 文件并且定期同步更新。这样虽然牺牲了一点个性化但换来了团队代码风格的一致性整体收益更大。经验总结如果是在团队里用 superpowers一定要统一 skill 的来源。个人可以有自己的补充 skill但核心的工作流 skill 必须统一。6. 进阶玩法让 superpowers 更贴合你的工作习惯6.1 自定义 skill 的编写要点当你用熟了现成的 skill 之后自然会想写自己的 skill。写 skill 有几个要点第一步骤要可执行。不要写“检查代码质量”这种模糊的指令要写“检查每个函数是否有类型注解、是否有 docstring、是否有对应的单元测试”。第二验收标准要明确。每个步骤后面加上“完成标志”比如“所有函数都有类型注解”就是一个可验证的标准。第三控制篇幅。一个 skill 文件最好控制在 200 行以内太长了 AI 容易“读不完”。我自己的习惯是每当我发现自己在对话里重复交代同一件事超过三次就会把它写成一个 skill。比如我经常提醒 AI“改完代码后跑一下 lint”后来就写了一个post-edit-lintskill每次代码修改后自动触发 lint 检查。这种“从重复劳动中提炼 skill”的方式能让你的 superpowers 环境越来越贴合自己的习惯。6.2 把团队规范固化到 skill 里如果你是一个团队的技术负责人superpowers 可以帮你把团队规范“自动化”。比如你们团队要求“所有 API 接口必须有参数校验和错误处理”你就可以写一个api-standardskill在 AI 生成 API 代码时自动检查这两点。新成员加入后只要配置好 skillAI 就会自动按照团队规范来辅助他写代码大大降低了规范落地的成本。我们团队目前固化的规范包括提交信息格式、分支命名规则、代码审查检查项、测试覆盖率要求。这些规范以前是靠文档和口头传达现在变成了 AI 的“默认行为”效果好了很多。6.3 与其他效率工具的联动superpowers 不是孤立的它可以和你的其他效率工具联动。比如你可以写一个 skill让 AI 在完成代码修改后自动生成一条提交信息然后调用你的 Git 工具完成提交。或者写一个 skill让 AI 在检测到测试失败时自动创建一个任务项提醒你后续跟进。这种联动的关键在于skill 里可以调用外部命令。大多数 AI 助手支持在 skill 中定义“执行 shell 命令”的步骤你可以利用这个能力把 superpowers 接入到你的 CI/CD 流程、任务管理工具、通知系统里。我目前配置的一个联动是当testingskill 检测到测试失败时自动在终端输出一个醒目的提示并记录到日志文件里方便我事后复盘。7. 关于 superpowers 的一些个人体会用了大半年 superpowers 之后我最大的感受是它改变的不是 AI 的能力上限而是 AI 的稳定性下限。AI 本身能写代码、能改 bug、能写文档这些能力一直都有。但问题是它的输出质量波动很大同样的需求有时候写得很好有时候写得一塌糊涂。superpowers 通过结构化的 skill 和流程约束把 AI 的输出质量拉到了一个相对稳定的水平线上。另一个体会是写 skill 的过程其实是在梳理自己的工作流。为了写一个code-reviewskill我不得不认真思考“我平时审查代码时到底在看什么”这个过程本身就让我对自己的工作习惯有了更清晰的认识。所以即使你最后没有用 superpowers单纯把“自己重复交代给 AI 的事情写下来”这个动作就已经很有价值了。最后分享一个小技巧定期回顾和更新你的 skill 集。我每个月会花半小时翻一遍自己的 skill 文件看看哪些已经过时了、哪些可以合并、哪些需要补充新的规则。这个习惯让我的 superpowers 环境始终保持“轻量且有效”的状态不会因为 skill 越积越多而变得臃肿难用。