很多人第一次听说“Superpowers”时第一反应是又一个名字起得很大的前端框架其实不是。它是一套专门给 AI 编程助手用的“技能包”核心价值就是让你正在用的 AI 助手从“你问一句、它答一句”的被动对话模式变成“自己规划、拆解、执行、验证”的主动工作流。如果你正在用 Claude Code 这类终端型 AI 编码工具或者正在折腾怎么让 AI 更稳定地产出高质量代码那这套东西大概率能帮上忙。这篇文章我会把 Superpowers 是什么、怎么装、里有哪些 skills、怎么把这些技能真正引入到日常开发里以及我实际踩过的一些坑一次性说清楚。1. 先说清楚Superpowers 到底是个什么东西1.1 不是框架不是语言是一套“技能文件夹”Superpowers 本质上是一个开源仓库里面按照一定规范放了一堆 Markdown 文件和辅助脚本。每一个“技能”skill就是一个子目录目录里通常会有一个SKILL.md作为主文件用来描述这个技能是干嘛的、在什么场景下用、大概的执行步骤是什么有时还会附带一些脚本或模板文件。当 AI 编程助手被装上了 Superpowers 之后它在执行任务前会先去扫描这些技能目录然后根据当前用户的需求判断自己需不需要调用某个技能。比如说用户说“帮我写一个功能规划”AI 如果识别到有一个叫planning的技能它就会去读取对应目录下的SKILL.md按照里面写的步骤来组织自己的思考过程和输出格式。把它理解为“给 AI 发一本操作手册”最合适。你不需要写一堆复杂插件代码也不用改造模型本身只需要提供文字说明AI 就能照着做。这种设计的好处是门槛极低——你甚至不需要会写程序只要会写文档就能给 AI 增加新能力。1.2 为什么选择 Markdown 来写技能我一开始也好奇为什么不用 JSON 或者 YAML 来定义技能。实际用了之后才发现Markdown 是最适合给 LLM 读的格式。原因有几点可读性好既能给 AI 看也能给人类 review团队里谁都能上手改。天然支持结构化内容用#、##、列表、表格就能表达层次LLM 在解析时不容易混淆。版本管理方便每个技能文件都能用 Git 追踪变更回滚成本低。不需要编译改完直接生效只要让 AI 重新加载一下技能列表就行。这个思路其实和现在很多 AI Agent 项目里的“prompt 工程化”是一脉相承的。传统做法是把功能写死在代码里而 Superpowers 把“功能”描述成文本片段让模型自己理解和执行。它牺牲了一点点精确性换来了极大的灵活性和可扩展性。1.3 它能帮你解决哪些具体问题在遇到 Superpowers 之前我给 AI 下达任务时最常遇到的几个问题AI 回答得很聪明但做事情没有章法。比如让它重构一个函数它可能直接改完就结束不做回归测试。任务稍微复杂一点AI 就容易“飘”。比如拆解需求时漏掉边界情况写完代码后不检查是否破坏了其他模块。团队规范无法固化。每个人跟 AI 对话的方式不一样导致 AI 输出的代码风格也不一样。Superpowers 的解决思路很直接把资深工程师做事的“套路”沉淀成技能文件。比如brainstorming技能会要求 AI 先发散想法再进行分类和筛选debugging技能会要求 AI 先复现问题、提出假设、再动手改代码code-review技能会要求 AI 按“正确性、可读性、安全性、性能”逐项检查。AI 一旦加载了这些技能就会像实习生拿到了一本 SOP 手册做事明显有章法得多。2. 新手必看安装 Superpowers 的完整流程2.1 安装前需要准备什么Superpowers 不是一个独立应用它必须“寄生”在一个能够读取并执行技能文件的 AI 编程终端里。目前我接触到的、社区里最常用的是 Claude Code因为 Superpowers 最初的很多设计就是围绕它的工作方式来的。所以在安装之前你需要先满足这几个条件有一个可用的 Claude Code 环境并且已经能正常跑起来。能访问 GitHub 仓库因为安装过程本质上就是拉取代码。基本不挑操作系统macOS、Linux、Windows 的 WSL 环境都行主要看你的 Claude Code 装在哪。如果你用的是其他支持 skill 机制的 AI 编码工具也可以参考同样的思路只要它支持读取独立目录下的 Markdown 技能文件即可。2.2 安装步骤两种常用方式以我实际操作的 Claude Code 环境为例有两种安装方式一种是通过插件市场一种是手动 clone。先说明一下Superpowers 这个项目本身迭代很快具体命令可能会随着版本更新而变化所以你安装前最好去官方仓库 README 里扫一眼。我这里给出的是最近社区里比较通用的做法。方式一通过插件市场安装在 Claude Code 会话中输入/plugin marketplace add obra/superpowers然后底部会提示发现了一个新插件继续输入/plugin install superpowers安装完成后Claude Code 会提示需要重启会话才能让新技能生效。这一步不要偷懒不重启的话技能列表经常不会自动刷新。方式二手动 clone 到本地技能目录如果你更想手动控制版本或者想顺便看看技能文件长什么样可以这样操作git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers把仓库整个克隆到 Claude Code 的全局技能目录下。如果你想针对某个项目生效就把它放到项目的.claude/skills/目录里。这种方式比较适合喜欢“物理安装”的人。我第一次用这种方式时装完还能打开SKILL.md一个个翻直观感受到每个技能是怎么写的理解一下子加深了。提示两种方式不要混用否则可能出现同名技能冲突。选定一种用到底。2.3 验证安装怎么确认 AI 已经看到了这些技能装完以后不要急着开始干活先让 AI 确认一下自己的“武器库”。在 Claude Code 的输入框里直接问你现在加载了哪些技能请列出来如果安装成功AI 会按目录结构列出一串技能名比如brainstorming、planning、debugging、writing-code等等。如果它回答“没有技能”或者“不支持技能”那就是安装路径不对或者当前会话没有刷新。还有一个更隐蔽的验证方法故意用一个明显对应某个技能的任务比如“帮我做一个头脑风暴主题是给我们的 CLI 工具增加一个交互式菜单”。如果 AI 在回答中主动使用了类似“我先按照 brainstorming 技能来拆解”的说法说明技能已经被加载并进入了工作流。2.4 关于版本与更新Superpowers 是社区项目更新频率不低尤其初期阶段几乎每周都有新技能加进来。用git clone方式安装的话更新很简单cd ~/.claude/skills/superpowers git pull如果是通过插件市场安装的一般会在 Claude Code 启动时自动检查更新也可以用/plugin update手动更新。不过我不太建议每次都追最新版。有些新技能还在验证阶段可能会和你的使用习惯冲突。我自己的习惯是先看更新日志确认新技能确实有用再升级。稳定性比新鲜感重要。3. 开箱即用Superpowers 里到底有哪些 skills3.1 规划类技能brainstorming、planning这套技能包最有价值的地方就是让 AI 在动手之前先做规划。brainstorming技能主要用在“还不知道该做什么”的阶段。它会引导 AI 先围绕你的话题发散列出所有可能的想法不批判、不收敛然后再对想法进行分类、合并、打分最后帮你挑出值得执行的方向。我实际用下来的感受是它特别适合做技术方案选型或者产品功能点子征集。planning技能则更偏落地。它要求 AI 把一个目标任务拆解成可执行的步骤每个步骤标明输入、输出、验收标准、风险点。拆完之后往往会生成一个 TODO 列表让 AI 一步步照着做做完一项划掉一项。这对防止 AI 做着做着跑偏非常重要。3.2 代码编写与重构类技能writing-code、refactoringwriting-code技能不是简单的“写代码”它会要求 AI 在动手前先看清现有代码结构、明确接口约定、遵循项目风格甚至先写好使用示例再写实现。这样生成的代码会更贴合上下文而不是凭空造一个抽象接口。refactoring技能则专门处理“改动现有代码”的场景。它强调在重构前先建立测试基线然后小步重构、每步保持可运行最后再统一清理。比如你在重构一个老模块时如果 AI 按照这个技能来它不会一口气把所有文件都改完而是会先告诉你它准备怎么改再逐个文件操作并在每个关键步骤之间停下来确认。3.3 调试与排查类技能debugging、investigating调试是最容易浪费时间的环节Superpowers 里也有针对性的处理方法。debugging技能的核心是“先定位再修复”。它会要求 AI 先收集错误信息复现问题划定可能出问题的代码范围然后提出若干假设逐个验证而不是直接猜一个原因就开改。这一点实际用起来非常爽因为 AI 默认情况下会倾向于“盲修”——根据经验猜一个原因改完就跑失败了再猜。技能文件里会强制它先写下一个“调试记录”包括问题描述、环境信息、尝试过的方案和结果。investigating技能更适合“不知道出了啥事但感觉哪里不对”的场景。比如程序运行缓慢、内存占用异常、某个接口偶发超时。它会要求 AI 先收集指标、日志、调用链再逐步隔离因素。等于给 AI 植入了一点 SRE 的思路。3.4 工程化类技能testing、git-worktree、code-reviewtesting技能会指导 AI 如何编写有效的测试而不是无脑生成一堆断言。它会先分析代码的输入输出边界、异常分支再设计测试用例并且提醒 AI 不要只看覆盖率要看关键路径是否被覆盖。git-worktree技能比较进阶适合需要在并行分支上工作的场景。它会让 AI 使用 Git Worktree 创建独立工作目录避免多个分支切换导致本地文件被污染。如果你经常让 AI 同时做“修 bug”和“开发新功能”两件事这个技能就很重要。code-review技能则把代码审查的检查项拆得非常细可读性、边界处理、安全性、性能、依赖引入合理性等。你可以把它当作团队的强制审查标准让 AI 在提交代码前先自审一遍也可以让它评审别人提交的代码。为了方便快速查阅我把常用技能整理成了一张表技能名适用场景核心能力brainstorming想法发散、方案选型先发散再收敛筛选可行方向planning任务拆解、项目规划生成步骤清单、依赖关系和验收标准writing-code新功能开发按模块上下文写代码注重接口设计refactoring既有代码改造小步重构每步保持可运行debugging错误修复先假设后验证记录排查过程investigating性能问题、偶发故障收集指标逐步隔离变量testing单元测试编写关注关键路径和边界条件git-worktree多分支并行开发用 worktree 隔离工作区code-review代码审查按多维度检查代码质量注意不同版本的 Superpowers 技能列表会有差异有些技能名可能叫creating-a-plan而不是planning使用前让 AI 列一下实际加载的技能名最稳妥。4. 怎么引入这些技能实操中的三种方式4.1 用自然语言直接点单最直观的引入方式就是“开口说”。在 Claude Code 的对话框里直接给 AI 下一个包含技能名的任务请使用 brainstorming 技能帮我思考一下如何降低我们 API 服务的延迟AI 听到brainstorming这个词就会去加载对应技能目录下的说明然后照着里面的框架来回答。这种方式适合临时需要用某个技能的场景好处是灵活缺点是如果技能名记得不准AI 可能理解出现偏差。所以我更推荐用户先让 AI 列出技能清单然后照着清单里的名字来“点单”。这就像你去一家新餐厅先看菜单再点菜而不是凭感觉报菜名。4.2 在项目规则文件里预配置技能如果你希望 AI 在某个项目里“自动”使用某些技能而不需要每次手动指定可以把技能配置写进项目规则文件比如 Claude Code 里的CLAUDE.md或者其他兼容工具支持的AGENTS.md。举个例子假设你的项目要求所有新功能必须先规划再动手那可以在CLAUDE.md里写# 项目规范 - 当用户要求开发新功能时先使用 planning 技能生成执行计划。 - 当用户要求修改复杂逻辑时先使用 debugging 技能进行影响分析。 - 所有代码合并前必须使用 code-review 技能自审。这样 AI 每次读取项目上下文时就会把规则和技能绑定起来不用你每次重复叮嘱。这是让 AI“习惯养成”的关键一步也是我觉得 Superpowers 比普通 prompt 更好的地方——因为它不只是“记住规则”而是真正去执行一套有步骤的动作序列。4.3 把技能编排成工作流技能之间不是孤立的可以组合使用。比如我要为一个新模块写代码完整的链条可能是使用 brainstorming 技能确定模块边界 然后使用 planning 技能生成开发计划 再使用 writing-code 技能按计划实现 最后使用 debugging 技能自查问题。你把这句话发给 AI它就会依次调用多个技能。实际执行时AI 会在对话中留下明显的阶段性痕迹比如“按照规划接下来要完成第一项”“测试后发现两个边界情况现在处理”。这个过程很像带了一个有条理的实习生每个阶段都知道该干什么。我自己非常推荐这种“串技能”的用法。它不要求你写任何代码只需要用自然语言描述流程AI 就会自己把技能连起来跑。这也是这套工具最大的魅力。4.4 实战案例用一套流程完成用户注册模块光说不练没意思我拿一个真实案例拆解一下。假设你接到一个任务给现有项目新增一个用户注册接口。如果只是直接问 AI“帮我写注册接口”它大概率会立刻给你生成一段代码。但代码往往隐含很多假设比如数据库表结构、密码加密方案、参数校验逻辑、错误码规范等。一旦这些假设和项目实际不符后续就是无穷无尽的修修补补。但引入 Superpowers 之后我会这样操作我要新增一个用户注册接口。请先用 brainstorming 技能分析需求边界然后 planning 技能输出开发步骤。AI 会先加载brainstorming围绕注册接口问自己几个问题注册需要哪些字段是否支持第三方登录密码策略是什么要不要邮箱验证然后把问题集中反馈给你和你确认后再进入规划。之后加载planning把任务拆成设计表结构 → 定义接口协议 → 实现密码加密 → 写参数校验 → 生成单个用户记录 → 补充错误处理 → 编写测试。每一步还附上验收标准。你确认计划没问题最后让它使用writing-code去实现。最后再让 AI 用testing技能补测试用code-review技能自审一遍。整个过程虽然比一次生成多花了几分钟但产出的代码质量和后续返工成本完全不是一个量级。5. 常见问题与排查技巧实录5.1 技能没有被加载或找不到这是新手最容易遇到的问题。装上 Superpowers 之后AI 却说没听过这个技能。我遇到过的情况通常有三种会话没有重启。Claude Code 在运行时扫描技能目录安装后必须重启会话或使用 reload 命令。安装目录不对。如果你用的是手动 clone技能目录必须放进 Claude Code 默认扫描的路径比如全局的~/.claude/skills/或项目下的.claude/skills/。放进别的自定义目录AI 根本不会去看。技能名拼写不一致。比如你心里想的是code review但技能实际叫code-review。AI 对连字符和下划线有时候会敏感。排查思路很简单先确认技能文件在不在再确认路径对不对最后让 AI 列出已加载技能清单对照清单点名。5.2 技能之间互相冲突或覆盖当你装了很多技能或者跟别的插件混用时可能出现同名技能。比如 A 仓库里有个testingB 仓库里也有个testingAI 到底加载哪个这取决于技能扫描的优先级。常见的规则是项目目录下的技能优先级高于全局目录后加载的目录可能会覆盖先加载的。如果出现“哎呀这个行为怎么跟上次不一样”大概率就是技能被另一个同名文件覆盖了。解决办法也很简单尽量避免重复命名或者只保留一个来源。如果你确实需要两个相似但不同侧重点的技能就把它们改造成不同的名字比如testing-fast和testing-deep然后用场景区分。5.3 AI 抱怨技能文件格式不正确Superpowers 里的每个SKILL.md通常包含一个 YAML front-matter就是文件头部用---包裹的元数据用来声明技能名称、描述、适用场景等。如果 YAML 格式有问题比如缩进不对、多了个空格、冒号后面没空格AI 解析时会报错或者干脆跳过这个技能。我在自定义技能时踩过这种坑。前几次写name字段时冒号后面没加空格结果 AI 每次都说“技能加载失败”。后来学乖了写完先本地检查一下 YAML 语法或者直接复制现有技能的头部改不要自己手敲。提示所有技能文件都建议保存为 UTF-8 编码不要用带 BOM 的格式。BOM 会导致 front-matter 解析异常而且肉眼完全看不出来。5.4 上下文被技能文档塞满AI 反而变笨了这是另一个很反直觉的问题。技能文件本身是给 AI 读的但 AI 的上下文窗口有限如果安装了几十个技能每次对话都要扫描一遍所有技能描述很快就会把窗口占满导致它记住的代码上下文变少。我在项目里装了很多技能后明显感觉 AI 的响应变“啰嗦”了有时甚至忽略项目文件内容。解决方式有几个不要一股脑安装所有技能按需选择。全局技能目录只放最常用的 35 个。把不常用技能放到专门的子目录需要时再临时安装或通过命令引入。精简SKILL.md的描述把冗长的背景知识移到一个reference.md文件里主文件只保留精简指令。AI 可以在需要时再读取详细参考。这其实暴露了技能设计的一个原则技能文档应该像“地图上的地标”而不是“整张地图”。描述要短够触发行动就行具体细节留给需要时展开。5.5 如何自定义一个自己的 skillSuperpowers 最有扩展性的地方就是可以自己写技能。自定义一个技能并不神秘核心就是创建一个目录和一个SKILL.md文件。一个最简模板长这样--- name: my-skill description: 在用户要求做xxx时使用这个技能。 tags: - markdown - review --- # 技能名称 ## 什么时候使用 当用户需要xxx时使用。 ## 执行步骤 1. 第一步分析输入。 2. 第二步产出xxx。 3. 第三步自查并报告结果。 ## 输出格式 使用表格列出最终结果并附上关键理由。把这个文件放到~/.claude/skills/my-skill/SKILL.md然后重启会话。之后你让 AI “使用 my-skill 做xxx”它就会按照你写的步骤执行。我建议第一次自定义技能的人不要从空白开始写。去仓库里找一个现有技能比如brainstorming复制一份改个名字把里面的描述改成你自己的场景。既保留了原来的结构骨架又降低了写错格式的风险。6. 实操体会与进阶建议6.1 我踩过的几个坑用下来最大的一个感受不要指望装上 Superpowers 就万事大吉。它提供的是“工具包”不是“自动化流水线”。你还是要学会理解每个技能在做什么知道何时该让 AI 用技能何时直接对话。我踩过的坑主要有三个安装后只顾着惊叹没有及时检查技能列表结果后面发现 AI 一直在用默认方式回答等于白装了。给 AI 下达任务时把技能名说错AI 没找到技能但又不好意思说就“假装”按技能做了实际还是老一套。自定义技能时贪多一个技能里写了十几步导致 AI 执行到最后自己都忘了前面在干嘛。最后那句话很关键技能步骤不是越多越好。一般 3 到 6 步是合理区间超过 10 步AI 的注意力就会开始涣散质量明显下降。6.2 什么时候不需要使用技能不是所有任务都值得装技能。比如简单问答、查资料、格式化代码这类事情直接对话就够。硬套技能不但没有收益还会让反应变慢。技能的价值在于“处理有方法论的复杂任务”。如果一个任务你自己都觉得没什么流程可讲那 AI 也没必要去读一本“操作手册”。我现在的判断标准是如果这个任务我三句话能说清楚就不用技能如果这个任务需要写一页文档才能说清楚那就值得把它沉淀成一个技能。6.3 把 Superpowers 用起来的三个建议第一从三个核心技能开始brainstorming、planning、debugging。这三个覆盖了从需求到实现再到排查的闭环先玩熟它们再扩展其他。第二把团队规范写进技能。比如你团队要求所有代码提交前必须自审那就把code-review的检查项改成你们自己的规范让 AI 替你执行。第三定期回归技能。每次用完一个技能如果发现 AI 的输出不符合预期不要急着改代码先去看技能文件哪里写得不够清晰改一版再试。迭代几次之后这个技能会越来越像你想要的“超能力”。我个人在实际操作中最深的体会是Superpowers 的价值不在于它给了 AI 什么高端能力而在于它逼着我把自己的开发方法整理成了可复述、可执行的步骤。这个整理的过程本身让我对每个任务该怎么拆解、该按什么顺序执行有了更清晰的认知。而 AI 一旦把这种认知固定下来就能真正从“快但毛糙”变成“快且可靠”。这一点远比我最初想从工具里获得的东西值钱。