我第一次把superpowers装进 Claude Code是因为受够了一种体验下了一个稍微复杂的需求AI 马上兴致勃勃地开始改文件改到一半我发现方向不对重来。后来在一个技术社群里看到有人提到 superpowers说它能让 AI 学会“先动脑子再动手”。我抱着试试看的心态跑了一遍安装脚本之后的工作方式基本就回不去了。如果你也在找一套让 Claude Code 更“懂规矩”的用法想知道 superpowers 具体使用、里面到底有哪些 skills、怎么引入这些技能这篇应该能帮你省不少时间。这套东西不是单个插件而是一整套技能增强包。它解决的问题很直接默认情况下AI 编程助手更像一个“问答机器人”你问一句它答一句但做真实项目时我们需要的是一个“协作者”——会先梳理需求、会写方案、会按计划执行、会补测试、会自己审查代码。superpowers 就是把后面这套流程以 skills 的形式固化下来让 AI 在遇到对应场景时自动走规范流程。1. 先搞明白Superpowers 到底是“技能包”还是“行为规范”1.1 它的本质一群 SKILL.md 加一套工作纪律打开 superpowers 的仓库你会看到几个核心目录skills/、plugins/以及一个AGENTS.md文件。skills/下面每个子目录就是一个独立技能比如 brainstorming、writing-plans、executing-plans、creating-unit-tests。每个技能目录里都有一个SKILL.md这就是技能的完整定义包含触发条件、使用场景、执行步骤。我更喜欢把 superpowers 理解成“行为规范”。普通插件是给 AI 增加某个功能比如读文件、调 APIsuperpowers 是给 AI 增加一套“做事的习惯”。比如 brainstorming 技能它会要求 AI 在动手前先产出多个候选方案并且每个方案必须包含优点、缺点、成本、风险而不是直接说“我建议这样做”。这种差异在复杂任务里特别明显AI 一旦养成了先列方案再选择的习惯返工率会直线下降。1.2 和普通提示词模板的区别在哪里很多人第一次接触时觉得这不就是一组提示词吗我自己写一套 prompt 不就行了区别还真不小。普通提示词是一次性的你这次贴在对话框里它生效下次忘了贴就回到原样。superpowers 的 skills 是持久化存在的Claude Code 启动时会自动扫描技能目录把每个SKILL.md的描述加载进索引。之后哪怕你不提“brainstorming”这个词只要任务内容匹配技能的 descriptionAI 就会主动使用对应技能。举一个实际场景我让 AI“给日志模块增加一个告警功能”。在没有 skill 的情况下它直接开始写代码装上 superpowers 后它先触发 brainstorming 技能列出“应用内轮询告警”“基于日志量阈值触发”“接入外部监控系统”几个方案让我选。这种“先讨论再动手”的流程靠临时粘贴提示词很难稳定复现因为每次粘贴的内容、顺序、上下文都可能不一样。1.3 GitHub 仓库里到底放了些什么从仓库结构来看主要几块内容值得关注skills/各个技能的独立目录每个目录内有SKILL.md和配套的参考文件。这是核心资产。plugins/一些扩展插件比如 context-embedding、tomorrow、status 等负责会话上下文注入、跨会话任务管理等增强功能。AGENTS.md项目层面的行为守则。安装时会提示你复制到项目根目录让 AI 认识到“这个项目遵循 superpowers 工作流”。install.sh官方安装脚本负责把上述内容复制到 Claude Code 的全局或项目配置目录。我的建议是安装前先花十分钟浏览一下仓库里的AGENTS.md和几个核心SKILL.md你会对整套体系的设计意图有更直观的理解。它本质上是在教 AI“接到任务时先拆解再计划再执行再验证”而不是教它某一个具体的编程技巧。2. 装之前必须理解的加载机制skills 与 AGENTS.md 的关系2.1 SKILL.md 长什么样YAML 头部加正文如果你打算手动调整技能或者想自己写一个类似的技能SKILL.md的结构必须搞清楚。它通常由两部分组成开头的 YAML frontmatter 和后面的正文指令。frontmatter 里最关键的是name和descriptionAI 会拿着 description 去和当前任务做语义匹配。正文部分则写技能的具体工作流程、输入输出要求、注意事项。一个典型的SKILL.md结构大概是这样的不同版本字段可能略有差异以仓库实际文件为准--- name: brainstorming description: 当用户需要产生多个可选方案、评估不同做法的取舍、进行头脑风暴时使用 allowed-tools: - Read - Write --- # Brainstorming 工作流 ## 触发时机 - 用户提出一个目标但还没有明确实现路径 - 用户要求“给出几个方案”或“聊聊怎么做” ## 执行步骤 1. 先澄清需求确认约束条件 2. 产出至少 3 个候选方案 3. 每个方案列出核心思路、优点、缺点、实施成本、风险 4. 等待用户选择后再进入下一步注意这里的description是触发机制的核心。AI 在会话中会不断拿用户请求和技能描述做匹配所以 description 写得越精确技能被正确唤起的概率越高。这也是为什么我说它不只是“提示词”——提示词靠人记得贴技能靠 AI 自动匹配。2.2 技能是怎么被“唤起”的自动匹配与显式调用明白了SKILL.md的结构你就知道“怎么引入这些技能”其实分两层。第一层是自动唤起。只要技能装到了正确的目录并且description写得清楚AI 会在合适的场景自动使用。比如你问“帮我想想这个模块可以怎么重构”AI 大概率会匹配到 refactoring 或 brainstorming 技能。第二层是显式调用。自动匹配不是百分百准确尤其当任务描述不够清晰时。我通常会直接说“请使用 brainstorming 技能帮我梳理一下……”或者“用 writing-plans 技能为这个功能写一份实施计划”。显式调用等于给 AI 一个明确的指令跳过了它自己猜测的过程。对新手来说显式调用是最可靠的上手方式。2.3 为什么 AGENTS.md 是整套技能的灵魂AGENTS.md是容易被忽略但极其重要的一环。它放在项目根目录类似项目的“工作协议”AI 在项目里做任何事之前都会先读它。superpowers 提供的AGENTS.md里会写明一些全局纪律比如“在修改代码前先确认是否存在对应计划”“任务复杂时优先使用 writing-plans 技能拆分步骤”“每次提交前检查是否有足够测试覆盖”。我见过不少人只复制了 skills 目录但没管AGENTS.md结果技能装了却总感觉“AI 不按套路走”。原因很简单技能是工具AGENTS.md是使用工具的规则。没有规则AI 可能偶尔用一下某个技能但不会形成稳定的工作流。如果你希望 AI 在项目里始终表现出“先计划后执行”的素质AGENTS.md一定要同步放好。3. 把 Superpowers 装进本地环境两种路径与验证方法3.1 路径一官方 install.sh 一键安装安装的第一步是把仓库克隆到本地。我习惯放在~/tools/之类的目录下方便后续查看源码git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh安装脚本会做几件事检测当前 Claude Code 的配置目录通常是~/.claude如果你设置了CLAUDE_CONFIG_DIR环境变量则使用该目录把skills/下的技能复制到配置目录的skills文件夹把插件配置写入settings.json最后提示你重启 Claude Code 或开启新会话使配置生效。这里有个细节install.sh 默认安装的是全局配置也就是说你所有项目都能用这套 skills。如果你只希望某个特定项目启用就需要用手动复制的方式或者安装后把全局技能目录里不需要的部分删掉。3.2 路径二手动复制更适合多项目隔离手动复制其实不复杂而且可控性更高。假设项目经理要求“每个项目各自维护技能不要互相影响”那项目级安装就是正解# 在项目根目录执行 mkdir -p .claude/skills cp -r ~/tools/superpowers/skills/* .claude/skills/ cp ~/tools/superpowers/AGENTS.md ./AGENTS.md然后重启会话。项目级的.claude/skills只对这个项目生效不会污染其他项目。如果你还想进一步隔离插件项目级插件的做法也类似把plugins放到.claude/plugins/即可。不过插件通常偏全局我更建议 skills 做项目级隔离插件保持全局统一。3.3 验证是否生效一句话测试法装完最怕的是“看似成功实际没生效”。我的验证方法很简单在新会话里直接问 AI你现在有哪些可用的技能请根据当前技能索引按类别简要列出。如果它报出了 brainstorming、writing-plans、executing-plans、creating-unit-tests 这些名字说明技能已经被成功扫描到。如果它说“我没有找到相关技能”大概率是目录放错了或者没有开新会话。注意一定要新开会话因为技能索引是在会话启动时加载的正在进行的会话不会实时同步新装的技能。我还会再做一次显式调用测试比如让它“使用 brainstorming 技能围绕‘给现有 CLI 工具增加交互式配置向导’给出三个方案”。如果 AI 真的按 brainstorming 的结构输出方案列表那就说明整个链路通了。4. 内置技能清单拆解哪些值得每天用4.1 需求分析与规划三件套brainstorming / writing-plans / executing-plans先说最常用的三件套。brainstorming适合任务早期目标是把“模糊的想法”变成“清晰的候选方案”它强制 AI 多角度思考而不是憋一个答案就冲。writing-plans适合方案确定之后它会把复杂任务拆成分步计划并通常要求落成计划文件。executing-plans则负责按计划逐步执行每完成一步更新任务状态保证大任务不遗漏。我的使用经验是这三件套是配合使用的。brainstorming 收敛出路线writing-plans 把路线拆成任务清单executing-plans 按清单推进。这就像带了一个先做方案评审、再写施工图、最后按图施工的工程队。4.2 质量保障类creating-unit-tests / TDD / debugging质量保障类技能里creating-unit-tests是最容易感受到价值的。你给它一段代码它会先阅读逻辑然后设计测试用例生成测试文件再运行测试并修正问题。TDD技能更进一步它会按“红-绿-重构”的流程推进先写一个失败测试再写最小实现让测试通过最后重构优化结构。debugging技能在我这儿的定位是“刹车片”。默认情况下AI 遇到报错很容易直接猜一个原因然后改代码。debugging 技能会要求它先复现问题、收集日志、建立假设再逐个验证。我和它配合时经常说“用 debugging 技能排查这个问题先不要改代码”效果立竿见影——AI 不再急着下结论而是先把排查链路走完。4.3 协作与内容类commit / code-reviewer / PR这些技能不是每次写代码都用但在团队协作中价值很大。commit技能会帮你生成符合 Conventional Commits 规范的提交信息比如feat(user-service): add login retry limit比你自己敲更省事。code-reviewer技能会站在审查者角度挑问题并按严重程度分类。creating-and-reviewing-pr这类技能则把“提交信息、PR 描述、审查清单”串成一个完整流程。我经常在代码写完后只输入一句“用 code-reviewer 技能审查一下我刚才的改动”AI 就会从可读性、边界条件、测试覆盖等维度给出意见。这些意见不一定每条都对但能帮我发现自己忽略的盲区。4.4 容易被低估的辅助技能还有一些不那么起眼但很实用的技能比如update-todos用于维护长期任务的状态清单disciplined-goals用于目标管理。它们对“单次短对话”的用处不大但在多轮次、跨会话的大项目里能帮 AI 记住自己在哪一步、下一步该做什么。需要提醒的是不同版本、不同仓库分支里的技能列表可能会变化而且技能之间也有一定重叠。我的建议是不要追求把每个技能都用上先挑三到五个和你日常工作最匹配的用熟之后再扩展。技能太多反而会让 AI 在选择时犹豫拖慢响应速度。我整理了一个常用技能速查表方便对照使用技能解决什么问题典型触发场景brainstorming需求不明确需要多个方案对比“给几个方案”“怎么实现比较好”writing-plans复杂任务需要拆解步骤“做一个实施计划”“分步完成”executing-plans按已有计划推进执行“按计划开始执行”creating-unit-tests给代码补单元测试“补一下测试”“写测试用例”debugging定位并修复问题根因“排查这个报错”“为什么运行失败”commit生成规范的提交信息“帮我提交”“生成 commit message”code-reviewer审查代码质量“审查一下改动”“做个 code review”5. 实战在项目里把技能真正用起来5.1 一次完整的“头脑风暴到计划执行”为了让你更直观地理解具体使用我用一个实际经历过的例子说明。当时我要给一个内部 CLI 工具增加“定时清理临时文件”的功能。这个需求看着简单但牵扯到用什么调度机制、是否支持配置、失败重试怎么办等问题。我先输入请使用 brainstorming 技能围绕“给 CLI 工具增加定时清理临时文件功能”给出至少 3 个实现方案包括实施成本和维护难度。AI 很快给出了三个方案一是基于系统级 cron 调用 CLI 自身命令二是在应用内实现调度循环三是把清理任务做成独立服务。每个方案都列出了优点、缺点、风险和大致的改动量。我选了方案二因为当前工具本身就是常驻进程应用内调度改动最小也不依赖外部环境。接着我输入使用 writing-plans 技能基于“应用内调度循环”方案写一份实施计划保存到 plans/ 目录。AI 生成了计划文件包括读取现有配置结构、新增 scheduler 模块、提供启停命令、编写单元测试、更新使用文档等几个大步骤每步下面还有子任务和验收标准。这时候我觉得需求已经足够清晰于是让它执行使用 executing-plans 技能按 plans/ 下的计划文件逐步实现每完成一步更新任务状态。整个过程里 AI 始终知道自己进行到哪一步不会东改一下西改一下。最后我再补一句“对 scheduler 模块使用 creating-unit-tests 技能补全测试”整个功能的完成度就很好了。5.2 显式调用的提示词写法根据我的使用经验显式调用技能时话术里最好包含两个要素技能名 明确任务边界。技能名让 AI 知道用什么工作流任务边界让它知道不要跑偏。我常用的一个模式是“使用 X 技能完成 Y注意 Z”。比如场景推荐话术需要多个方案“使用 brainstorming 技能围绕……给出至少 3 个方案给出取舍”制定计划“使用 writing-plans 技能为……制定实施计划保存到 plans/”执行计划“使用 executing-plans 技能按计划文件……逐步执行每步更新 todo”排查故障“使用 debugging 技能分析这个报错先不要改代码”补测试“对 src/utils.py 使用 creating-unit-tests 技能补全单元测试”生成提交“使用 commit 技能为当前改动生成提交信息并检查规范”这个模式看起来很朴素但实际效果很稳定。尤其是“先不要改代码”这种约束能有效阻止 AI 在排查阶段就急着动手。5.3 和现有工作流结合的小建议我没有把 superpowers 变成唯一的工作方式而是让它和团队已有的流程共存。比如我们团队本来就用 Jira 管理任务我会让 AI 用 writing-plans 技能把计划写到plans/目录然后再在 Jira 里建对应子任务两边内容保持一致。这样 AI 的计划不会存在于对话里而是以文件形式沉淀下来团队其他成员也能看到。另外我建议给每个技能设置“止步点”。比如用 brainstorming 技能生成方案后不要直接让 AI 继续执行而是先自己看一下方案再下决策。技能是帮你降低重复劳动不是替你拍板。我在实际使用中的体会是把 AI 当成一个“流程严谨但需要你确认”的同事superpowers 的价值才能最大化。6. 多项目共存、隔离与常见问题排查6.1 全局与项目级配置的正确姿势安装在后期的维护重点其实是“隔离”。superpowers 的一套技能并非对所有项目都合适。比如给一个简单的静态网站写页面你并不希望 AI 每次都要先做一轮 brainstorming 再加一个 writing-plans那会显得很重。我的做法是默认不全局安装或者全局只保留少数通用技能比如 commit 和 update-todos。真正吃重的工作流比如 brainstorming、writing-plans、executing-plans 三件套只放到需要它们的项目的.claude/skills/里。这样大部分项目保持轻量核心项目获得完整能力。如果你用CLAUDE_CONFIG_DIR环境变量区分了多套 Claude Code 配置也可以在各自的配置目录里分别装不同的技能组合实现更彻底的隔离。6.2 我踩过的坑安装没生效、技能互相打架先说安装没生效。最常犯的错是没开新会话。有几次我装完技能后在原会话里测试AI 始终说找不到技能我当时以为装失败了反复检查目录。后来才意识到技能索引在会话启动时就固定了装完必须新开会话才能被感知。所以验证前先确认这一点能省不少排查时间。第二个坑是技能互相打架。装了全套技能后有时会出现 AI 同时触发多个相似技能的尴尬。比如你想让它写计划它却既匹配了 writing-plans 又匹配了 executing-plans导致动作变形。解决办法有两个一是显式指定技能明确当前只执行某一个二是精简技能列表只保留真正需要的。我个人倾向于第二种装得越多AI 在做技能选择时的开销就越大响应也会变慢。第三个坑和AGENTS.md有关。如果你项目里本来就有自己的AGENTS.md直接覆盖可能会导致原有规则丢失。我的处理方式是手动合并保留原有内容把 superpowers 的纪律性条款追加进去而不是整份替换。这样既不影响团队既有约定又能引入新的工作习惯。6.3 什么情况下我不建议装 Superpowers虽然我挺喜欢这套技能但它确实不是所有人的刚需。如果你的使用场景是“快速改个小 bug”“补个简单文案”或者你习惯完全手动控制 AI 的每一步那全套技能可能反而碍事。它更适合任务复杂度中等以上的项目开发场景——需要拆解需求、需要写测试、需要按计划推进。另外如果你用的是超大代码库要留意 context-embedding 这类插件。它会在会话启动时注入项目上下文遇到非常庞大的仓库会让首次响应变慢token 消耗也会增加。这时候可以关闭部分插件只保留 skills 的工作流能力。我现在的用法是在一个中型后端项目里启用了核心技能在另一个轻量项目里只留了 commit 和 debugging其他项目保持默认。这样既不增加不必要的开销又能在我需要的时候让 AI 进入“专业工作流”模式。整套 superpowers 用下来最大的感受是它把 AI 编程助手从“话痨回答机”变成了“有章法的执行者”。它改变的不是单个回答的质量而是整个任务推进的节奏。如果你也遇到过“AI 很聪明但总是跑偏”的问题建议先在新会话里装好这套技能用 brainstorming 技能和自己完成一次“需求对齐”——你会立刻明白我在说什么。
