前阵子我在梳理自己的 AI 编码工作流时翻到了 GitHub 上一个叫 superpowers 的仓库。第一反应是这名字多少有点中二病点进去之后才意识到它做的事其实非常务实——把一群资深工程师的“工作方法”拆成了一堆可以被 AI 助手直接调用的技能文件。简单说superpowers 就是给 Claude Code 这类 AI 编程工具装上一套“职业素养外挂”让它从“能写代码的工具”变成“知道怎么规范干活的老手”。这里说的“技能”不是指模型新学了一门语言而是一套能被 AI 读取和执行的工程流程。过去我们总觉得 AI 写代码缺的是智能实际用多了你就会发现它缺的往往是流程意识让它修个 bug它可能改完一行代码就告诉你“修好了”既不复现、也不回归、更不管副作用。superpowers 想解决的就是这个问题。这篇文章我会从我自己安装、配置、实际使用的完整过程出发把 superpowers 是什么、怎么装、自带哪些技能、实测有哪些坑、以及怎么定制自己的技能一步步讲清楚。不管你是已经在用 Claude Code 的重度玩家还是刚听说 skills 机制的小白按这个流程走都能把这套东西跑起来并且真的能改善你的 AI 编码体验。1. 我为什么需要一套“超能力”技能包AI 编程工具的真正短板先说一个反直觉的结论现在的 AI 编码助手在“单点能力”上已经很强了写个函数、改段逻辑、翻译代码基本能胜任。但你让它独立负责一个完整任务链条时它就开始露怯。我举一个最典型的场景你让 AI 排查一个偶现的内存泄漏它会立刻去猜原因然后丢给你一段“可能有用”的修修补补。而一个有经验的工程师会先想方设法复现问题再通过二分法定位到具体模块最后写一个能证明修复有效的测试。这种差异本质上是“知识密度”的差异。模型训练时看过海量代码但你没法保证它在具体项目里具备“怎么按流程做事”的上下文。superpowers 的出现就是在模型和好的工程习惯之间搭一座桥。它做的事情非常朴素把一套套成熟的工作流程写成结构化的技能文件放进 AI 工具能识别的目录。当任务符合技能描述的触发条件时AI 就会加载这个技能文件按照里面定义好的步骤一步步执行。你不需要在每轮对话里反复叮嘱“先复现再说”“记得写测试”技能文件会在关键时刻介入用规范约束模型的行为。我之所以觉得这套东西值得尝试还有一个很现实的原因团队协作环境里流程一致性太难保证了。五个人用同一个 AI 工具四个人提醒它“要按规范来”剩下一个不提醒产出的代码质量就出现断层。用技能包把这些流程固化下来等于把“资深工程师的工作素养”变成了团队基础设施谁调用 AI谁就自动获得这套素养。当然也要说清楚它不是什么。superpowers 不是模型本身不能提升 AI 的理解能力也不能保证每个技能都完美适配你的项目。它更像一套“操作手册检查清单”的集合核心价值是把隐性经验显性化、结构化。想用好它你需要先理解它的边界——它不是银弹是你和 AI 之间的流程翻译器。2. 动手之前先把这些前置条件理清楚2.1 你得先有一个支持 skills 机制的宿主环境superpowers 的技能机制本质上是依托宿主 AI 工具来运行的。目前我实测过最顺的是 Claude Code因为它原生支持从目录中加载技能文件并且会在任务上下文中自动检索匹配度最高的技能。其他工具我也试过几个有的需要靠插件系统变通实现有的压根不认识 SKILL.md 文件体验差距比较大。所以第一步不是装 superpowers而是确认你的工具链满足条件。我的建议是优先使用 Claude Code 的最新稳定版本并在首次启动时完成登录验证。如果你已经在日常工作中使用它那就直接跳到下一步。如果你还没装先花十分钟把环境跑通再回来折腾技能包否则排错时你会分不清是宿主的问题还是技能包的问题。需要注意的一个细节是Claude Code 的技能加载机制对项目工作目录敏感。技能文件的读取范围通常取决于你的工作目录位置所以建议在项目根目录下启动会话而不是在系统任意目录下。这个细节在我后续的实际使用中反复踩到先在这里提个醒。2.2 skills 目录的约定与识别规则理解 superpowers 的安装原理之前你得先知道宿主工具是怎么发现技能的。以 Claude Code 为例它会约定一个固定的技能目录通常是用户主目录下的.claude/skills/每个技能是一个独立的子目录子目录里必须有一个名为SKILL.md的文件这个文件就是技能的“说明书”。SKILL.md的格式很讲究。文件头部用 YAML 格式写元信息包括技能名称、描述、适用条件正文部分用 Markdown 写具体的执行步骤和注意事项。宿主工具在每次对话时会扫描技能目录下所有 SKILL.md 的元信息结合当前用户的对话内容做匹配。如果匹配度足够高AI 就会把这个技能文件的内容注入到当前上下文中后续回答就会按照技能的引导来走。这个机制听起来不复杂但理解它非常关键。它决定了后面所有的问题排查方向技能没生效八成是目录放错了、文件名不对、或者元信息描述写得不够精确。把这条规则刻在脑子里后面遇到任何诡异现象都不慌。另外还要提醒一句技能目录的扫描不是实时的。你在安装完新技能之后通常需要重启会话或者在对话中主动触发一次技能重新加载否则新技能不会被识别。这个“不实时”的坑我后面专门会讲。2.3 安装方式怎么选手动克隆还是自动安装superpowers 的安装方式并不是唯一。我在实际使用中接触到的就有两种常见路径一种是直接把仓库克隆到技能目录另一种是通过宿主的插件安装机制来安装。从我自己的经验看第一种更透明、更好控制也更容易排查问题。我的选择逻辑很简单技能包本身是纯文本文件本质上没有编译期概念所以“安装”的核心动作就是把它放到正确的位置。用 git clone 的方式你可以随时查看技能文件的原貌也能在出问题时快速回溯版本。自动安装方式虽然省事但隐藏了文件路径和结构细节一旦需要调试你就得自己去翻插件的安装记录反而浪费时间。多说一句项目版本的问题。superpowers 仓库的更新节奏不算慢而且技能文件的格式偶尔会跟着宿主工具的版本走。所以我的习惯是每次升级 Claude Code 之后顺手重新拉一次技能仓库的更新。这个小习惯帮我避开了不少“版本不匹配导致技能失效”的坑。3. 从安装到跑通完整走一遍实操链路3.1 克隆仓库到技能目录整个安装过程最核心的动作就是把 superpowers 仓库的内容放进宿主工具可识别的技能目录。我当时的操作记录大致如下你可以直接参考cd ~/.claude/skills git clone https://github.com/obra/superpowers.git superpowers克隆完成后先检查一下目录结构是否正常。一个关键检查点是SKILL.md文件必须直接出现在技能的根目录下而不是被套在某个嵌套的子目录里否则宿主工具扫描时会漏掉它。我见过不少人安装完技能没生效最后发现是仓库目录层级比自己预期多了一层技能文件被埋在了深处。检查命令很简单find ~/.claude/skills/superpowers -name SKILL.md如果这个命令能列出多个 SKILL.md 文件的路径说明仓库结构完整。接下来重启会话让宿主工具重新扫描技能目录。3.2 如何确认技能已经被加载安装完最容易产生的疑问就是我怎么知道它到底生效没有这里分享一个我实测有效的验证思路不需要去看什么深层日志直接通过对话行为来判断。重启会话后故意抛出一个符合技能定位的任务。比如我想验证调试类技能是否生效就故意让 AI 帮我分析一段有明显逻辑错误的代码。如果技能生效你会观察到回答流程出现明显变化——AI 不再急着给结论而是会先提出一些确认性问题或者按照技能文件里的步骤逐项推进比如“先复现问题”“检查输入边界”“验证假设”这类结构化输出。我的经验是这种验证方式比查看内部状态可靠得多。因为技能加载成功后它的“存在感”体现在行为模式上而非输出一段特定的声明文字。如果连续试了几个典型场景AI 的行为都没有变化那再进入排查流程。3.3 用一个小场景验证整个链路为了让你更直观地感受技能带来的差异我把第一次实测的场景完整还原一遍。我准备了一段简单的 Python 代码函数逻辑是统计列表中的偶数个数但我故意隐藏了一个边界条件 bug。没装技能之前AI 的典型反应是直接指出“漏掉了空列表判断”然后给你补一行代码。装好 superpowers 之后再试观察到的行为完全不一样。AI 先复述了我需要它做的事然后列出它要执行的检查步骤读取完整代码、确认输入类型、用一组输入样例做模拟执行、定位可能的异常点、再给修复建议。整个过程像极了一名谨慎的初级工程师在被要求评审代码时的表现。这组对照实验让我立刻理解了技能包的运作方式它不是在教 AI 更多知识而是在教它“按什么顺序想问题”。这个体验上的差异比任何性能数字都更能说明问题。4. 默认技能包里到底藏了哪些“超能力”逐个拆解装好 superpowers 之后你会发现它并不是“一个技能”而是一整套技能集合。不同版本包含的技能清单会有些出入我这里只挑几个我反复用到的、并且确认稳定的核心技能来拆解。我用一张表格先做个总览再逐个说明使用场景。技能方向核心作用典型触发场景我的一句话评价调试分析按“复现-定位-验证”流程处理 bug代码报错、逻辑异常、偶发问题最实用直接改变 AI 的修 bug 习惯测试先行先写失败测试再写实现新功能开发、重构旧代码对团队质量规范帮助最大提交规范生成符合约定的提交信息准备 git commit 时省去逐字打磨提交信息的功夫问题拆解把大任务分解成可执行子任务复杂需求落地时避免 AI 一股脑把代码堆出来代码走查按检查清单审查代码质量合并请求前自查相当于给代码加了一道流程闸门4.1 调试分析把“修 bug”变成一套纪律这套技能是我日常使用频率最高的。它的核心约束是禁止在复现问题之前给出修复结论。如果你观察 AI 的输出会看到它先要求你提供完整的复现环境、错误日志、输入样本然后建立一个可验证的“假设-验证”循环。我记忆最深刻的一次实战是排查一个诡异的数据错乱问题。当时问题的表象是间歇性的没有稳定的复现路径。换在以前AI 大概率会开始猜“是不是缓存导致的”“是不是并发写导致的”。但启用了调试技能之后它第一步竟然是在帮助我梳理“哪些输入可以缩小复现范围”通过排除法把问题空间逐步压缩最终锁定了是某个极端输入导致的状态残留。如果你觉得这听起来就像“一个懂行的同事在旁边监督 AI”那就对了。要的就是这个效果。4.2 测试先行从源头强制质量意识E测试先行技能对我的工作方式改变很大。用过 TDD 的人都知道先写一个会失败的测试再写让它通过的实现是一个反人性的过程对 AI 来说尤其如此——因为它天生倾向于“最快给出看起来正确的答案”。这套技能会强制 AI 在动手写实现代码之前先提交一个预期失败的测试用例并明确说明它预期的行为。我刚开始觉得这样很拖沓直到有一次重构一个历史遗留模块AI 按照这个流程先列出了几十个行为断言然后才开始改代码。重构完成后跑测试几乎所有断言一次通过连回归风险都大幅下降。它的价值不在于“测试”本身而在于它提前逼出了需求边界。不知道“正确行为是什么”就让 AI 先写下对正确行为的定义再开工实现这个习惯帮我提前暴露了很多隐含需求。4.3 提交规范与问题拆解流程感带来的隐性收益提交规范技能比较轻量它的作用是在你执行 git commit 时让 AI 严格按照“类型-范围-摘要”的格式生成提交信息并且会要求你看一遍确认。这个技能单独看平平无奇但放在团队协作里非常有用因为它消除了提交信息风格不一致的烦恼。问题拆解技能则完全不同它的作用更像是“项目经理附体”。当你要 AI 实现一个横跨多个模块的功能时它会先把任务拆成若干有依赖关系的子任务标注清楚哪些可以并行、哪些必须串行然后按顺序推进。我以前让 AI 做大型需求总是提心吊胆怕它顾此失彼。启用这个技能后至少它给你的是一个可控的推进计划而不是一把梭。5. 实测踩过的坑从现象到根因的完整排查链路5.1 技能完全没生效最隐蔽的目录层级问题第一次安装完我遇到的第一个问题就是技能完全没生效。当时我直接克隆到~/.claude/skills/superpowers目录结构看着没问题但 ai 的行为没有任何变化。开始怀疑是不是版本兼容问题反复重装了两次无果兜了一大圈才发现真相仓库根目录下并不是技能文件而是skills/这层子目录里才是真正的技能集合。原来的目录结构是这样的~/.claude/skills/superpowers/ ├── skills/ │ ├── some-skill/ │ │ └── SKILL.md │ └── another-skill/ │ └── SKILL.md └── README.md宿主工具只扫描技能目录的一级结构每个子目录必须以技能名命名且直接包含 SKILL.md。这下层级全乱了技能自然一个都识别不了。解决方法很直接不克隆到子目录而是把仓库内层 skills 目录里的所有技能子目录直接平铺到~/.claude/skills/下。这次踩坑给我的教训很深刻安装完不要急着用先花 30 秒查看目录结构是否符合识别规则。这个简单的习惯能排掉大半的“技能不生效”问题。5.2 技能之间互相干扰元信息描述写得太宽泛用了一段时间后我遇到了一个新的问题AI 做代码走查的时候行为里混进了测试先行技能的要求一会儿让我先写测试一会儿又要走查逻辑整个回答变得混乱不堪。我花了一些时间排查最后定位到是技能元信息里的“触发条件”互相重叠了。代码走查技能的描述里写了“适用于代码质量分析”测试先行技能的描述里也写了“适用于代码质量分析”。对宿主工具来说两个技能看起来高度相似于是两个技能文件都被加载进了上下文。解决方案很直接修改技能文件的元信息让每个技能的“适用场景”更窄、更明确。比如测试先行技能改成“适用于新功能开发或重构场景要求在编写实现代码前先定义测试用例”代码走查技能改成“适用于合并请求前的代码审查重点检查可读性、边界条件、代码复杂度”。改完之后技能匹配的准确率明显提升混用的问题基本消失了。这个坑值得特别留意。技能包用得越久你往里加的自定义技能越多描述冲突的概率就越大。给自己的技能写清楚边界不是文档洁癖而是保证 AI 行为可控的关键。5.3 升级宿主工具后技能集体失效版本耦合的现实还有一个坑出现得比较隐蔽。某次宿主工具发布大版本更新我像往常一样继续使用会话结果发现 AI 完全不读技能文件了仿佛技能包被一键删除。排查了一圈才发现新版本对技能文件的元信息字段做了更严格的校验我本地那些旧版本技能文件里几个自定义字段格式不符合要求被直接忽略。这种问题排查起来最费时间因为它不是“某一个技能坏了”而是所有技能一起失灵。我的排查路径是先随便改一个技能文件的描述字段保存后重启会话看行为有没有变化。没有变化就说明是加载链路出了问题进一步检查宿主工具版本更新日志最终锁定到字段兼容性。这类问题没有一劳永逸的解决办法只能养成升级后立即做冒烟测试的习惯。我的做法是准备一组简单的验证任务每次升级宿主工具或技能包后跑一遍确保核心技能都被正常加载。花不了十分钟但能避免关键时刻掉链子。5.4 排错思路总结一套可复用的定位框架踩过这些坑之后我给自己总结了一套排查技能类问题的思路分享出来供你参考。不管现象多诡异按这个顺序走大部分问题都能定位到根因。首先确认目录结构是否符合识别规则这是最高频的根因其次确认 SKILL.md 的元信息格式是否完整注意大小写和字段类型然后检查技能描述是否与你的问题场景匹配避免触发条件没覆盖接着确认是否需要重启会话以触发重新加载最后再查宿主工具版本与技能文件格式的兼容性。这套框架帮我快速定位过不少问题也让我意识到技能系统的所有问题本质上都是“文件位置”“文件格式”“描述匹配”这三类问题的排列组合。想明白了这一点排错就不再是玄学。6. 进阶玩法从“用别人的技能”到“写自己的技能”6.1 SKILL.md 的结构拆解一份技能就是一份标准作业流程当你用熟了超级技能包之后很大概率会冒出“我自己也想写个技能”的念头。这个需求非常自然因为项目的痛点往往是定制的。好在 SKILL.md 的编写门槛真不高核心就是要掌握它的三个组成部分。第一部分是元信息用 YAML 写在文件开头至少包含name、description、when_to_use这几个字段。description要写清楚这个技能做什么when_to_use要尽量精确地定义触发条件。第二部分是执行步骤用 Markdown 写清楚 AI 应该按什么顺序做什么尽量步骤化、可验证。第三部分是注意事项写清楚哪些事情不能做、哪些边界要守住。给我的感受是一个写得好用的技能本质上就是一份“标准作业流程文档”。你平时在团队里怎么培训新人的技能文件就是这么写出来的。6.2 实战案例我写的一个日志分析技能为了让你更直观地理解怎么写我分享一个自己写的小技能专门用于分析应用日志中的错误堆积问题。它的触发条件是“用户提供日志片段或要求进行日志分析”执行步骤是先识别日志中重复出现的错误特征再按时间线聚合错误频率然后定位错误之间的依赖关系最后给出排查建议。写法上我把每个步骤都定义得非常具体。比如“识别重复错误特征”这一步我要求 AI 先做日志聚合统计而不是一句“请分析日志”就打发了。实际用下来这个技能让 AI 在日志分析场景的表现从“给出泛泛解释”变成了“输出可操作的排查线索”效果非常明显。写完后把它放进~/.claude/skills/log-analyzer/重启会话再用一个预置的日志样例测试确认 AI 遵循了技能里的步骤就算完成了。整个过程不到半小时。6.3 写技能的几个推荐原则写了几个自定义技能并实际用了一段时间后我总结出了几条实用的编写原则。第一条步骤必须写得足够具体越具体越好因为 AI 的强项是执行指令弱项是脑补你没写明的意图。第二条触发条件宁可窄也不可宽过宽的触发条件容易和别的技能抢上下文。第三条每一项步骤都要有明确的完成标志让 AI 能判断自己是否完成了这一步。还有一个非常重要的细节技能的步骤不要贪多。一个技能的最佳粒度是解决一个具体问题步骤控制在五到八步之间。一旦步骤太多AI 在长上下文里容易“忘记”前面的流程表现反而下降。如果一个流程过于复杂拆成两个技能会比硬塞进一个技能高效得多。按这四个原则来写即使你从没写过技能文件也能很快产出能用的自定义技能。我自己的感受是写技能的过程其实就是把你对“AI 应该如何干活”的期望具象化地表达出来。想清楚你期望什么技能就能帮你实现什么。最后分享一个我个人的操作习惯我会把写好的每一个自定义技能放到独立的 git 仓库里管理版本更新、回滚都很方便。技能文件本身就是文本天然适合用版本管理来跟踪。数不清这个习惯帮我避免了多少次误改导致的问题回退。如果你也准备深度使用这套体系强烈建议从第一天开始就做好技能的版本管理。