1. 从“superpowers”这个标题说起：它到底是什么

第一次看到“superpowers”这个词，很多人脑子里蹦出来的可能是超级英雄、超能力这类画面。但在技术圈子里，尤其是最近一段时间，这个词频繁出现在各类开发者的讨论中，它指的其实是一个面向AI编程助手的技能扩展框架。简单来说，它是一套让AI编程工具变得更“能干”的插件系统——你可以把它理解成给AI装上了一套工具箱，原本只会聊天的助手，装上之后就能按照标准流程帮你写代码、做代码审查、管理Git分支、生成文档，甚至执行完整的开发工作流。

这个项目最早是在GitHub上开源出来的，核心作者是obra（Jesse Vincent）。它的设计理念非常直接：把软件开发中那些反复出现的、有固定套路的任务，封装成一个个可复用的“技能”（skill），然后让AI助手在合适的时机自动调用这些技能。比如你要做一个新功能，正常流程是先写设计文档、再拆任务、再写代码、再测试、再审查、最后合并——这一整套流程，superpowers把它变成了AI可以自动执行的标准化动作。

那它解决了什么问题？说白了，就是AI编程助手“会用但不会管”的问题。你用ChatGPT或者Claude写代码，它确实能写，但它不知道什么时候该写测试、什么时候该提交、什么时候该开分支。你得一步步指挥它，它才动一下。superpowers的思路是：把这些“什么时候该干什么”的规则和流程，提前写成技能文件，AI助手在对话中自动识别当前处于哪个阶段，然后调用对应的技能来推进工作。这就好比给一个刚入职的实习生配了一本详细的操作手册，他不用每次问你“下一步该干嘛”，照着手册走就行。

适合谁来参考？三类人最值得看：一是日常用AI辅助编程的开发者，想让AI从“代码生成器”升级成“开发流程管家”；二是技术团队的负责人，想统一团队的AI使用规范，让每个人用AI的方式都遵循同一套标准；三是对AI工作流自动化感兴趣的技术爱好者，想了解怎么把提示词工程和实际开发流程结合起来。不管你用的是Claude Code、Cursor还是其他支持技能扩展的AI编程工具，superpowers的思路都有参考价值。

2. 核心设计思路拆解：为什么是“技能”而不是“提示词”

2.1 技能与提示词的本质区别

很多人第一次接触superpowers会有一个疑问：这不就是写一堆提示词吗？有什么新鲜的？这个问题问到点子上了，但答案恰恰是superpowers最核心的设计决策——它把提示词从“一次性消耗品”变成了“可版本管理的工程资产”。

普通的提示词是什么？是你每次跟AI对话时临时敲进去的一段话，用完就没了，下次还得重新写。就算你保存了模板，它也是散落在你的笔记里、聊天记录里，没有统一的管理方式。而superpowers里的“技能”，是一个个独立的Markdown文件，有固定的目录结构，有明确的触发条件，有版本控制，可以像代码一样被审查、被修改、被复用。这个区别看起来小，实际上影响巨大。

我打个比方：普通提示词就像你每次做饭时凭记忆放调料，今天咸了明天淡了，全看状态。而技能文件就像一本写好的菜谱，盐几克、糖几克、火候几分钟，全部标准化。任何人拿着这本菜谱，都能做出同样味道的菜。对于团队协作来说，这个标准化带来的价值是巨大的——它意味着AI的输出质量不再依赖于某个人的提示词水平，而是依赖于团队共同维护的技能库。

2.2 技能文件的组织结构

superpowers的技能文件通常放在项目的特定目录下，每个技能是一个独立的Markdown文件，文件名就是技能名。文件内部有固定的结构：开头是技能的描述和触发条件，告诉AI“什么时候该用这个技能”；中间是具体的操作步骤，告诉AI“具体怎么做”；最后可能有示例和注意事项，告诉AI“做的时候要注意什么”。

这种结构的好处是AI可以自主判断该不该调用某个技能。比如你正在跟AI讨论一个新功能的设计，AI识别到当前处于“设计阶段”，就会自动加载“头脑风暴”或“写设计文档”的技能；等你确认设计后，AI又会自动切换到“拆解任务”的技能。整个过程你不需要手动说“现在请用某某技能”，AI会根据对话上下文自己判断。这个自动判断的机制，是superpowers区别于普通提示词模板的关键。

2.3 为什么选择Markdown而不是代码

有人可能会问：为什么技能文件用Markdown写，而不是用JSON、YAML或者某种DSL？这个问题我专门想过，结论是Markdown是AI理解成本最低、人类维护成本也最低的格式。

对AI来说，Markdown是训练数据里最常见的格式之一，模型对Markdown结构的理解非常成熟。标题、列表、代码块、引用，这些元素AI都能准确解析。对开发者来说，Markdown写起来没有门槛，不需要学新语法，改起来也方便。而且Markdown天然适合写“流程说明”这类内容——你本来就要写步骤、写注意事项，用Markdown写出来的东西直接就能给人看，也能给AI看，一份内容两种用途。

如果用JSON写技能，结构是清晰了，但写起来啰嗦，改起来也麻烦，而且AI理解JSON里的自然语言描述反而不如Markdown直接。superpowers选择Markdown，本质上是在机器可读性和人类可维护性之间找了一个最佳平衡点。

3. 安装与初始化：从零把环境跑起来

3.1 前置条件确认

在动手安装之前，有几件事需要先确认清楚，不然装到一半卡住了很浪费时间。

首先，你需要一个支持技能扩展的AI编程工具。目前superpowers主要适配的是Claude Code，也就是Anthropic推出的命令行编程助手。如果你用的是其他工具，需要先确认它是否支持类似的技能加载机制。其次，你的开发环境需要有Node.js运行环境，因为superpowers的安装和部分工具依赖Node生态。建议Node版本在18以上，太老的版本可能会有兼容性问题。最后，你需要有基本的命令行操作能力，因为整个安装过程主要在终端里完成。

提示：如果你之前没有用过Claude Code，建议先花半小时熟悉一下基本操作，知道怎么启动、怎么对话、怎么退出，再来装superpowers会顺畅很多。

3.2 安装步骤详解

superpowers的安装方式根据你使用的工具不同会有差异，但核心逻辑是一样的：把技能文件放到AI工具能读取到的目录下，然后配置工具去加载这些文件。

以Claude Code为例，常见的安装流程是这样的：先克隆superpowers的仓库到本地，然后把技能目录链接或复制到Claude Code的配置目录中。具体命令大致如下：

git clone https://github.com/obra/superpowers.git cd superpowers

克隆下来之后，你会看到仓库里有几个关键目录：skills目录存放所有技能文件，docs目录存放文档，可能还有scripts目录存放辅助脚本。接下来需要把skills目录配置到Claude Code能识别的位置。Claude Code通常会在用户主目录下的某个配置文件夹里读取技能，具体路径可以在Claude Code的文档里查到。

配置完成后，启动Claude Code，输入一个测试指令，比如“帮我看看当前项目有哪些可用的技能”，如果AI能列出superpowers里的技能列表，说明安装成功了。

3.3 安装后的验证方法

装完之后怎么确认真的能用？我自己的验证方法是做一个最小化的完整流程测试。

找一个空项目目录，启动Claude Code，然后跟它说“我想做一个简单的待办事项应用”。如果superpowers正常工作，AI应该会先触发“头脑风暴”技能，跟你讨论需求；然后触发“写设计文档”技能，生成一份设计文档；接着触发“拆解任务”技能，把开发任务拆成一个个小步骤。整个过程中你不需要手动指挥它“现在该干嘛”，它会自己按流程推进。

如果AI没有自动触发技能，而是直接开始写代码，那说明技能加载有问题。这时候需要检查：技能目录路径对不对、配置文件有没有写错、AI工具版本是否支持技能功能。排查的时候可以先看AI工具的日志输出，通常会有加载技能的相关信息。

注意：不同版本的Claude Code对技能目录的路径要求可能不同，安装前最好先查一下你所用版本的官方文档，确认正确的配置路径。我见过不少人卡在这一步，其实就是路径写错了。

4. 核心技能解析：superpowers里到底有哪些能力

4.1 开发流程类技能

superpowers最核心的一类技能，是覆盖完整开发流程的系列技能。这些技能按照软件开发的自然顺序排列，从需求讨论到代码合并，每个阶段都有对应的技能来支撑。

“头脑风暴”技能负责在项目初期帮你理清需求。你跟AI说“我想做一个某某功能”，它会通过一系列提问帮你把模糊的想法变成清晰的需求描述。这个技能的关键在于它不会直接给你方案，而是先问问题。比如它会问“这个功能的目标用户是谁”“你希望解决什么核心问题”“有没有参考的类似产品”。这些问题看起来简单，但能帮你避免“想当然”式的开发。

“写设计文档”技能在需求明确后触发，AI会根据讨论结果生成一份结构化的设计文档，包含功能概述、技术方案、数据模型、接口设计等部分。这份文档不是摆设，后续的开发步骤都会以它为基准。我自己的经验是，设计文档写得越细，后面返工的概率越低。superpowers的设计文档技能会强制AI把关键决策点写清楚，比如“为什么选这个数据库”“为什么用这个架构”，这些记录在后期维护时非常有用。

“拆解任务”技能把设计文档转化成可执行的任务列表。每个任务都有明确的完成标准，比如“实现用户登录接口，返回JWT token，包含单元测试”。这个技能的价值在于它把大块工作切成了小块，每块都能独立验证。开发的时候你不需要一次性想清楚所有细节，做完一个任务再做一个，节奏很稳。

4.2 代码质量类技能

写完代码之后，superpowers有一套质量保障技能来兜底。

“代码审查”技能会让AI以审查者的视角重新审视刚写的代码，检查潜在问题。它关注的维度包括：逻辑是否正确、边界条件是否处理、命名是否清晰、是否有重复代码、是否有安全隐患。这个技能的特点是AI会切换角色，从“写代码的人”变成“挑毛病的人”，视角一变，确实能发现不少自己写的时候忽略的问题。

“写测试”技能负责生成单元测试和集成测试。它不是简单地给每个函数生成一个测试，而是会分析代码的分支逻辑，针对每个分支生成对应的测试用例。我实测下来，它生成的测试覆盖率通常比自己手写要高，因为人写测试容易漏掉边界情况，而AI会系统性地遍历所有分支。

“调试”技能在遇到bug时触发。你把错误信息贴给AI，它会按照一套固定的排查流程来分析：先确认错误类型，再定位可能的代码位置，然后提出验证方法，最后给出修复方案。这套流程的好处是避免瞎猜，每一步都有依据。

4.3 版本控制类技能

superpowers对Git操作也有专门的技能支持。

“提交代码”技能会帮你生成规范的commit message。它遵循Conventional Commits规范，根据改动内容自动判断是feat、fix、refactor还是docs，然后生成对应的描述。这个技能看起来简单，但实际用起来很省心，再也不用纠结commit message怎么写。

“管理分支”技能负责创建、切换、合并分支。它会根据当前任务自动建议分支名，比如“feature/user-login”或“fix/header-style”。合并的时候它会检查是否有冲突，有冲突会提示你先解决。

“创建PR”技能在功能完成后触发，自动生成Pull Request的描述，包含改动概述、测试情况、审查要点。这个描述不是随便写的，它会从设计文档和commit记录里提取关键信息，生成一份让审查者能快速理解的说明。

5. 实操全流程：用superpowers做一个完整功能

5.1 从需求到设计文档

假设我们要做一个“用户头像上传”功能。启动Claude Code，输入“我想给用户加一个头像上传功能”。AI识别到这是新需求，自动触发“头脑风暴”技能，开始提问：头像支持哪些格式？文件大小限制是多少？存储在哪里？是否需要裁剪？这些问题一轮问下来，需求就清晰了。

需求确认后，AI触发“写设计文档”技能，生成一份设计文档。文档里会包含：功能描述、接口设计（上传接口的URL、请求方法、参数、返回值）、存储方案（本地存储还是对象存储）、前端交互流程、异常处理（文件过大、格式不支持、上传失败）。这份文档会保存到项目目录里，后续开发以它为准。

实操心得：设计文档生成后，别急着往下走，花五分钟通读一遍。AI有时候会漏掉一些业务特定的约束，比如“头像需要审核”这种需求，你不说它不知道。发现遗漏就补充进去，改文档比改代码便宜得多。

5.2 任务拆解与逐步实现

设计文档确认后，AI触发“拆解任务”技能，把功能拆成若干任务。以头像上传为例，可能拆成：创建文件上传接口、实现文件存储逻辑、添加文件格式校验、添加文件大小校验、前端上传组件、上传进度显示、错误提示处理。每个任务都有明确的完成标准。

接下来AI会逐个任务推进。每完成一个任务，它会触发“写测试”技能生成对应的测试，然后触发“代码审查”技能自查一遍。你可以在每个任务完成后检查一下代码，确认没问题再让AI继续下一个。这种小步快跑的节奏，比一次性写完所有代码再调试要高效得多。

5.3 提交与合并

所有任务完成后，AI触发“提交代码”技能，生成commit message，比如“feat: add user avatar upload feature”。然后触发“创建PR”技能，生成PR描述。你在PR描述里可以看到整个功能的改动概述、测试覆盖情况、需要审查者关注的重点。

如果团队有代码审查流程，审查者可以在PR里提意见，AI根据意见修改后再提交。整个流程走完，功能就可以合并到主分支了。

6. 常见问题与排查技巧实录

6.1 技能不触发怎么办

这是最常见的问题。你明明装了superpowers，但AI就是不自动调用技能，还是像普通对话一样直接回答。排查思路如下：

先确认技能文件是否真的被加载了。在Claude Code里输入“列出所有可用技能”，如果返回空列表或者报错，说明加载失败。检查技能目录路径是否正确，配置文件里的路径是绝对路径还是相对路径，有没有拼写错误。

如果技能列表能列出来，但对话时不触发，那可能是触发条件不匹配。每个技能文件开头都有触发条件描述，比如“当用户提出新功能需求时触发”。如果你的表达方式和触发条件差距太大，AI可能识别不到。这时候可以手动引导一下，比如“我想做一个新功能，请用头脑风暴技能帮我理清需求”。

还有一种情况是技能优先级冲突。如果多个技能都声称自己该触发，AI可能选了一个你不想要的。这时候可以明确指定用哪个技能。

6.2 技能执行结果不符合预期

有时候技能触发了，但执行结果跟你想要的不一样。比如“写设计文档”技能生成的文档太简略，或者“拆解任务”技能拆得太粗。

这种情况通常是技能文件里的指令不够具体。superpowers的技能文件是开源的，你可以直接修改。比如你觉得设计文档应该包含“性能考量”这一节，但技能文件里没写，那就在技能文件里加上。改完之后AI下次生成设计文档就会包含这一节。

我自己的做法是，把技能文件当成团队规范来维护。每次发现AI的输出不符合团队标准，就去改对应的技能文件，而不是每次在对话里临时纠正。改一次，以后所有项目都受益。

6.3 与其他工具的兼容性问题

superpowers最初是为Claude Code设计的，如果你用的是其他AI编程工具，可能会遇到兼容性问题。比如某些工具不支持自动加载技能文件，或者技能文件的格式要求不同。

这种情况下有两个选择：一是等社区适配，superpowers是开源项目，已经有人在为其他工具做适配了；二是自己动手改，把技能文件转换成目标工具支持的格式。核心思路是一样的——把流程规则写成文件，让AI读取并执行，具体格式可以根据工具要求调整。

6.4 常见问题速查表

避坑技巧：修改技能文件之前，先备份原文件。我有一次改得太激进，把触发条件改得太窄，结果技能完全不触发了，还好有备份能快速恢复。

7. 进阶玩法：把superpowers改造成团队专属工作流

7.1 自定义技能文件的编写方法

superpowers最大的价值不在于它自带的技能，而在于它提供了一套让团队自己写技能的框架。你完全可以按照团队的开发规范，写一套专属的技能文件。

写自定义技能文件，核心是把团队的“隐性知识”变成“显性规则”。比如你们团队有个规矩：所有数据库操作必须走Repository层，不能直接在Service里写SQL。这个规矩以前只存在于老员工的脑子里，新员工来了得靠Code Review来纠正。现在你可以把它写成一个技能文件，AI在写代码时会自动遵守这个规则。

技能文件的写法没有固定模板，但有几个要点：触发条件要写清楚“什么时候用这个技能”，操作步骤要写清楚“具体怎么做”，示例要写清楚“做成什么样算合格”。写得越具体，AI执行得越准确。

7.2 技能组合与流程编排

单个技能解决单个问题，但实际开发中往往是多个技能串联使用。superpowers支持技能之间的组合调用，你可以定义一个“大技能”，内部按顺序调用多个“小技能”。

比如你可以定义一个“新功能开发”技能，内部依次调用：头脑风暴→写设计文档→拆解任务→逐个实现→写测试→代码审查→提交→创建PR。这样你只需要说“我要开发一个新功能”，AI就会自动走完整个流程。

这种流程编排的价值在于把最佳实践固化下来。团队里最资深的开发者怎么做事，就把它写成流程，让AI带着所有人按同样的方式做事。新人上手速度会快很多，因为AI会一步步引导他走完标准流程。

7.3 团队协作中的技能共享

技能文件是纯文本，天然适合用Git管理。团队可以建一个专门的仓库来存放技能文件，每个人都可以提交修改，通过Pull Request来审查变更。

这样做的好处是技能库会随着团队经验的积累不断进化。今天张三发现了一个更好的测试写法，提交到技能库里；明天李四发现了一个常见的坑，也写进技能库里。半年下来，这个技能库就成了团队最宝贵的知识资产。

我见过一个团队的做法是：每次Code Review发现一个反复出现的问题，就把它写进技能文件里。比如“日志里不能打印用户密码”这条规则，写进技能文件后，AI生成的代码就再也不会犯这个错了。这比每次Review时口头提醒高效得多。

8. 我个人的使用体会与几个实用建议

用superpowers有一段时间了，说几个真实的感受。

第一个感受是它改变了我跟AI协作的方式。以前我用AI写代码，是我指挥它干活，我说一句它动一下。现在更像是它带着我走流程，我只需要在关键节点做决策。这个角色转换一开始不太适应，但习惯了之后效率确实高很多。

第二个感受是技能文件的质量直接决定输出质量。superpowers自带的技能是通用型的，放到具体项目里往往需要调整。我花了不少时间把团队规范写进技能文件里，这个过程本身就是在梳理团队的开发流程。写技能文件的时候你会发现，有些规矩大家嘴上说得好，但从来没写下来过，一写就发现定义不清楚的地方很多。

第三个建议是不要一次性把所有技能都启用。superpowers自带的技能很多，全开的话AI可能会频繁触发各种技能，反而干扰正常对话。我的做法是先启用最核心的几个——头脑风暴、写设计文档、拆解任务、写测试、代码审查，等用熟了再逐步加其他的。

最后一个建议是定期回顾和更新技能文件。项目在变，团队在变，技能文件也得跟着变。我一般每个月花半小时过一遍技能文件，把过时的规则删掉，把新踩的坑加进去。这个习惯坚持下来，技能库会越来越贴合实际需求。

如果你刚开始接触superpowers，我的建议是从一个小项目开始试，别一上来就在核心项目上用。先熟悉它的工作方式，找到适合自己团队的配置，再逐步推广。这个东西的上手门槛不高，但要用好，需要花点时间打磨技能文件。一旦打磨好了，它带来的效率提升是实实在在的。