superpowers：用SKILL.md为AI编码代理立规矩

我最近一直在折腾Claude Code做日常重构说实话体验时好时坏。模型经常在答应你和干得漂亮之间反复横跳最典型的情况就是你说先跑测试再动手它嘴上答应得很好下一条消息就把代码改了改完还不告诉你。这让我意识到缺的其实不是模型能力而是能把工程纪律固化成流程的东西。后来我找到了superpowers这个开源技能包它以SKILL.md文档为核心给Claude Code和Codex这类AI编码代理装上了一套完整的技能工作流。这篇文章会把我的安装过程、核心技能拆解、SKILL.md内部结构和实际使用心得完整写一遍给想给AI编码代理加buff的人做个参考。简单交代一下背景superpowers由Jesse VincentGitHub上叫obra发起在GitHub上以开源项目形式维护。它的理念很直接——不要指望模型自己知道什么时候该脑暴、什么时候该写测试、什么时候该逐行review而是把这些方法论的执行步骤写成模型能够加载和遵循的SKILL.md文档。你装上之后模型在你需要时会主动加载对应技能强制自己按照流程走。效果最直观的一句话就是它让AI从一个爱自由发挥的实习生变成一个按规章制度办事的工程师。1. superpowers到底是个什么东西与其说是插件不如说是一套模型行为协议先说结论superpowers不是库不是框架也不产生任何API调用。它本质上是几百份经过实战打磨的Markdown文档每一份文档就是一个技能Skill里面写清楚了这个技能适用的场景、具体要执行的步骤、每一步的验收标准、以及遇到偏差时的处理方式。举一个生活化的类比。平时我们给AI的提示词相当于对着临时工口头交代一句你去把这个桌子擦了。而superpowers里的技能相当于把一整套《客房清洁SOP手册》递给服务员里面写着先检查桌面物品再用什么清洁剂擦完后如何确认没有遗漏如果遇到顽固污渍应该换什么方案。模型执行的底层能力没有变变的是它读到的工作指令的详细程度和结构强度。superpowers能解决一个我一直觉得特别别扭的问题通用大模型的讨好型人格。你问可以吗它说可以你问是不是该这样做它说对。但真要落地产出时它倾向于选择最短路径、最少步骤而不是最稳妥的路径。superpowers做的不是改变模型的权重而是通过SKILL.md这套外部结构把选择权从模型手里夺回来一部分。它让你在对话里随时可以喊一声brainstorm然后模型就必须先跟你对齐方案再动手而不是直接甩一堆代码出来。从项目结构上看superpowers的核心目录就是skills/下面按不同场景拆成若干技能。每个技能自带frontmatter元信息包括技能名称、适用场景描述、何时使用等。Claude Code在对话中会通过何时使用这个字段自动判断要不要加载技能也可以由你手动通过技能名按需唤醒。我整理了它最核心的几个技能方便直观理解覆盖面技能解决的问题使用场景brainstorm需求模糊时直接写代码导致返工拿到新需求、改架构、设计方案test-driven development不做测试盲目改代码修复bug、新增功能systematic-debugging凭感觉乱试越改越糟线上问题、复现困难bugcode-review审代码时顺手就改引入新问题团队协作、合并请求前root-cause-analyzer只修表面不解决根因反复出现的故障validate改完不验证就提交每个功能合入前很多人第一次打开这个项目会觉得这不就是一堆提示词吗我最初也是这么想的但用下来就明白提示词和技能之间存在决定性差异提示词是一次性的、被淹没在上下文里的、容易丢失的技能是持久化的、可索引的、带触发条件的。它构建的是模型的行为协议而不是模型的语言修饰。2. 安装和环境准备最容易被目录层级坑到的步骤安装本身不难但我在装的时候被目录结构卡了将近一个小时社群和热搜里也经常看到superpowers安装以后不出来的提问所以这块值得单独说一说。先交代环境前提。我本地是macOS装了最新版Claude CodeNode.js是20.xgit是标配。Windows和Linux也可以正常用配置方式完全一致只是路径换一下。我走的安装路径是直接从GitHub克隆项目到本地的全局技能目录。命令大概是这样的# 进入Claude Code的全局技能目录 mkdir -p ~/.claude/skills cd ~/.claude/skills # 克隆superpowers仓库 git clone https://github.com/obra/superpowers.git # 确认目录结构 ls -la ~/.claude/skills/superpowers如果你用的是Codex对应的目录会略有不同一般是~/.codex/skills逻辑完全一样。关键在于Claude Code只会扫描技能目录下固定的层级结构。superpowers仓库本身是带skills/子目录的所以装完以后你需要在技能根目录下能看到一层是技能名、再一层是具体技能文件。我遇到的问题是克隆完之后技能目录里多了一层superpowers/skills/导致Claude Code扫描不到技能。解决办法有两个要么把superpowers/skills/里的所有文件往上一层拷出来要么在配置里显式指定完整路径。我自己最后选择的是直接把skills/下的内容拷贝到~/.claude/skills/这样最稳。除了手动clone之外如果你用的是Claude Code较新版本可以通过插件市场直接添加/plugin marketplace add obra/superpowers然后进入市场选择安装即可。社区里有部分插件市场机制在老版本上不稳如果执行报错回退用clone的方式就行。安装完怎么验证是否生效很简单新建一个会话在输入框输入看联想列表里是否出现技能名。如果输入brainstorm能正常弹出补全说明加载成功了。如果提示No skills available或者什么补全都没有基本都是目录结构问题先检查路径。还有一个很隐蔽但影响巨大的坑Claude Code的自动摘要机制。技能文档往往很长如果上下文比较拥挤模型或者编译器会把技能内容摘要压缩导致技能行为时灵时不灵。我建议在会话里主动关闭自动摘要或者在配置里把摘要阈值调低让SKILL.md的全文尽量保留在上下文中。这一点在官方文档里写得不显眼但对使用体验的影响比目录结构还大。3. 核心技能逐个拆解它究竟是怎么管住AI的安装只是第一步真正有价值的是理解这些技能具体怎么约束模型。我挑几个感受最深的展开说这些也是我日常用得最频繁的。3.1 brainstorm把我有个想法你帮我实现变成先聊清楚再动手以前我跟Claude Code说帮我实现一个xx功能它大概率会直接甩一段代码然后我就得在一堆半成品上返工。brainstorm技能的逻辑是任何需求先进入讨论流程不给出最终代码。模型加载这个技能后会按照文档里的步骤走先询问背景和目标然后自己提出2到3个候选方案每个方案都要做fact check——也就是说它要检查自己的假设是否合理、依赖是否真实存在、成本能否被接受。之后它会列出每个方案的权衡点再要求你拍板选一个最后才进入实施环节。我实际用下来的体会是这个技能最大的价值不是让你多聊几句而是强迫模型暴露它自己的思考假设。有一次我要做一个离线缓存模块模型本来打算直接用localStorage但在brainstorm流程里它自己检查到数据量可能超过单条存储上限主动换成了IndexedDB方案。如果按以前的方式这个坑大概率要等联调阶段才暴露。3.2 test-driven development把写完再补测试倒过来这个技能对模型行为的干预力度最大。加载之后模型的默认工作方式变成先读你项目的测试框架然后为要写的功能定义测试用例确认测试失败红再写最简实现让测试通过绿然后进入重构。每一步都很小模型不允许一次改一个文件里的几十处。有基础的读者可能觉得这就是TDD的常识但真正难点在于让模型遵守这个节奏。普通的提示词说先写测试模型真的会先写测试但它写测试的同时也把实现一起写了或者干脆等写完整段代码才补一个测试文件。在superpowers的TDD技能里文档会明确告诉模型在测试通过之前不允许写出非测试代码如果测试还没有变绿就不能进入下一步。这种状态机式的约束比语言层面的劝告有效得多。3.3 systematic-debugging一次只改一个变量排错场景最能体现AI的短板——它特别容易灵光一现地猜原因然后一次性改动多个位置把问题搞得更加不可收拾。systematic-debugging技能规定了一套排查流程先复现问题再检查最新的代码变更然后针对最可能的根因提出一个假设只能改一个变量验证一次再决定是继续还是回滚。有一次我遇到一个偶发的内存泄漏让Claude Code带着这个技能排查。它在整个过程中只改一处、跑一次验证最后锁定在一个没有正确释放的事件监听器上。如果用以前的模式它可能一口气改三个文件泄漏反而更严重了。3.4 逐行code-review只读不许改这个技能约束的是review时不越界改代码。它要求模型逐行阅读文件以评论形式输出发现的问题但禁止直接修改任何代码行。对团队开发来说这点特别重要——你并不想让AI审完代码直接把分支改了而是希望它给你一份有依据的问题清单由你决定怎么处理。3.5 root-cause-analyzer不满足于现象消失这个技能会要求模型把问题拆成现象、直接原因、根本原因、验证实验四层并且对为什么这个方案能解决问题给出逻辑链。效果是减少那种好了但不知道为什么好了的悬案。整体来说这些技能的共同点就是把工程方法论写成模型强制执行的步骤把模型的概率性行为锚定在流程轨道上。模型不是变聪明了而是变守规矩了。4. 技能内部结构解析看懂SKILL.md你就能自己写超能力如果你想从用技能的人进阶成造技能的人就必须理解SKILL.md的解剖结构。本质上它就是一个带元信息的Markdown文档但它对格式和逻辑分层有明确要求。一个标准的技能文档大概是这样的--- name: refactor-with-impact-check description: 在修改公共接口之前先生成影响范围清单并征求用户确认 when_to_use: 当需要重构函数签名、修改公共API、或者调整模块间依赖时 layers: - thinking - acting --- # 重构前的影响清单 ## 第一步读取当前实现 - 找到目标函数/接口的定义 - 找到所有调用方搜索项目内全部引用 - 列出调用方所在文件与调用方式 ## 第二步整理影响范围 - 按直接影响和间接影响分层记录 - 评估每个调用方的风险等级 ## 第三步输出清单并等待确认 - 在回复中展示完整的调用方列表 - 明确写出可能破坏的兼容性点 - 等待用户明确同意后再修改代码前端字段是最关键的部分。name是技能的唯一IDdescription决定模型在什么语义环境下检索到它when_to_use是模型判断要不要主动加载技能的触发器layers用来声明这个技能的思考层级。superpowers的思路是把技能分两层thinking层负责分析、推理、制定方案acting层负责具体执行。这样分层的核心目的是防止模型跳步——它必须先完成思考层的动作才能进入行动层。这也是我觉得superpowers设计中最精妙的地方。再看process和component的拆分。process是流程component是原子能力。还是拿brainstorm举例它内部会复用一些通用组件比如fact check、利益权衡分析、风险列举。这些组件本身是独立文档可以被多个流程复用。写新技能的时候不需要把所有细节都从零写一遍直接声明引用哪些组件即可。这跟写代码时的函数抽取是一个思路流程是主函数组件是工具函数。基于这套结构我自己写了一个公共接口变更前的影响评估技能挂在本地技能目录下。新会话里输入refactor-with-impact-check就能唤醒模型在修改一个被多个模块调用的函数签名前会先把调用方全部列出来等我说确认才动手。这个技能帮我省掉了无数个改完A模块炸了B模块再回头救火的循环。还有一个容易被忽略的点技能的description质量直接决定模型是否会在正确时刻主动唤醒它。如果你写得含糊模型可能在该加载的时候想不起来。建议描述里带具体行为动词和明确触发条件比如当用户要求修改公共接口时比用于代码重构强得多。5. 实战使用体验变啰嗦了但返工率肉眼可见下降聊完原理说点真实的使用体感。装上superpowers之后最明显的变化是对话变啰嗦了。以前我让Claude Code改一个接口它直接给改动后的代码干净利落。现在同样的需求它会先来一段影响范围分析列几个方案问我要哪个然后才开始动手。刚上手的时候我甚至一度想卸载觉得太拖沓。但对比返工率之后我改变了看法。拿我最近做的一个项目举例把一个单体服务里的用户模块和订单模块拆分出独立接口。这个改动涉及十几个文件调用关系交叉得很复杂。老做法是让AI直接改结果经常是它改好了用户模块订单模块的引用全红了然后我再花半小时让AI修复那些红。用superpowers的brainstorm加TDD技能走了一遍之后整个过程多了大概20分钟的废话时间但最终一次性通过编译和测试联调阶段几乎没有返工。再补充一组我记录的对比数据。以前平均每个改动需求我要发5到7条消息才能收敛到一个稳定版本其中至少一条是你怎么把我的xx也改了这样的纠错指令。用superpowers之后同样的需求平均在3条消息内就能收敛纠错指令出现的频率明显下降。代价是上下文长度变长token消耗增加我粗估在30%到60%之间但考虑到一次全量调试排查的成本这个开销是值回票价的。关于Codex的适配问题我也试了。superpowers官方是支持Codex的安装路径换成~/.codex/skills即可。但因模型本身对长文档的遵从度存在差异实测下来Claude Code上的执行最稳定Codex偶尔会读了文档但不照做。这不是superpowers的问题是模型能力边界。如果你的主力工具是Codex建议装完先跑一次systematic-debugging或brainstorm这类流程性强的技能做验证确认模型遵守度再决定是否长期使用。再回答一个热搜里出现很多次的问题superpowers java。这个完全不用担心技能体系与编程语言无关。SKILL.md里写的都是工程流程比如先写测试、再写实现改一个变量验证一次Java项目、Python项目、Go项目都可以用。真正跟语言相关的是模型自身的代码能力不是这套技能。至于什么时候该开技能、什么时候不该开我自己的判断标准是探索期和原型阶段我反而会关掉大部分技能。因为那个阶段要的是快速发散模型给出一个思路、几段代码我看了有灵感就行不需要严谨的流程。一旦项目进入收尾、重构、上线排错这些稳定性优先的阶段再把superpowers开上。一个会话内同时激活的技能数量建议控制在2到3个太多技能会让模型检索和切换时出现混乱影响响应速度和质量。6. 失灵时的排查链路从技能没生效到技能救不了你最后这部分写给已经装上superpowers但遇到各种异常的人。技能不是装了就好它会以各种姿势失灵我把踩过的坑和排查方式按链路整理一遍。先说最常见的问题补全里看不到技能。排查第一步不是重装而是检查目录层级。打开技能根目录看是不是出现了skills/skills/这种嵌套目录。如果是把文件层级捋平让技能名直接位于根目录下一层。第二步确认你编辑的是正确的全局目录——有人把仓库clone进了项目本地.claude/skills换了一个项目后技能全没了这属于路径认知问题。第三步重启Claude Code会话因为技能列表是在会话启动时扫描加载的新clone的目录不会自动刷新到已打开的会话里。其次是看了brainstorm但模型行为完全不像加载了技能。这个情况大概率是技能被吃了而不是没加载。排查时新建一个空白会话只输入brainstorm这一个技能加上一句请执行你的技能流程看它是否按照脑暴步骤走。如果空白会话里能正常执行那就是旧会话上下文太长技能文档被压缩或者被其他指令淹没了。处理办法是关掉自动摘要、缩短会话长度、或者切换到一个新会话。如果空白会话里也不按流程走就要检查模型版本和遵守度换一个能力更强的模型再试。然后是技能加载了但只走了一半流程就跳步。比如TDD技能要求先写测试模型却直接连实现代码一起写了。这种跳步很难通过提示词修复我比较推荐在系统提示词里增加一条必须严格遵守已加载技能的步骤每一步完成后再进入下一步然后继续观察。另外降低模型温度也能减少跳步概率实测有效只是响应会变得更保守一些。最后不得不泼一盆冷水技能救不了能力不足的模型。如果你用的是参数量较小、执行能力较弱的模型即使它逐字读完了SKILL.md也可能在落实环节变形——比如让它找调用方它只搜了当前目录让它做fact check它编造事实。superpowers能管住流程但管不住模型本身的能力上限。这个边界心里要有数。还有一个常见的误区以为技能就是某种万能模板输入一个句子就能自动补全所有工程能力。实际不是。superpowers更像一个流程引擎它把方法论带上把约束补上但分析质量、代码质量、方案质量依然取决于底层模型的推理能力。工具和模型是乘法关系不是加法。颜色也比较容易出现的情况是开了太多技能导致模型选择困难。比如一个会话里同时挂上brainstorm、TDD、code-review三个技能模型会在对话中反复切换角色反而显得分裂。我现在每类任务固定只开一两个最匹配的技能效果稳定很多。我的整体建议是装上superpowers后不要急着把每个技能都试一遍先从brainstorm和test-driven-development这两个开始用一周时间适应它带来的变啰嗦。等适应了这种节奏再逐步引入排错和审查类技能。这套东西的核心价值不是某一项功能而是让AI编码代理从能回答变成有纪律地执行——而后者在整个工程链路上的价值远比多写几行代码要大。如果你也在被AI编码助手答非所问、反复返工的问题折磨我强烈建议从安装一个brainstorm技能开始。它可能不会让你立刻觉得超能力附身但会你第一次感受到原来AI不是在敷衍你只是从来没有人用结构化流程跟它认真打交道。