最近只要聊到 AI 辅助编程就很难绕开 superpowers 这个词。我第一次看到的时候也愣了一下这到底是个框架、一个插件还是一套提示词后来把仓库翻完、又在真实项目里跑了几轮才确认它本质上是一套给 AI 助手用的技能库目的就是让模型执行复杂任务时不再靠自由发挥而是按标准化流程走。默认状态下的 AI 编程助手很像一个能力很强但没经历过系统培训的新人你让它画个架构图它可能直接开始写接口你让它重构代码它顺手把业务逻辑也改了。Superpowers 做的就是把这些容易出错的环节拆成一个个可复用的技能比如任务拆解、代码审查、测试生成AI 看到任务后会先匹配技能再按技能文档里的步骤执行。这篇文章我会从安装、引入、具体使用一路讲到排坑适合已经在用 AI 编程工具、想让代码产出更稳定的开发者参考。不用把这个项目想得多神秘。你真正需要理解的只有三件事技能目录怎么放、SKILL.md 怎么读、触发机制怎么生效。剩下的都是在这三个基础上的应用扩展。1. 先搞清楚 Superpowers 到底解决什么问题1.1 别把 Superpowers 理解成“又一个插件”很多人第一次听到 superpowers会下意识把它归类为 IDE 插件或者代码补全工具这个理解偏差挺大。它既不是 LSP也不会接管你的编译过程本质上是一套基于自然语言代理的“工作手册集”。每一个技能就是一个目录里面一般放着一份 SKILL.md这份文档写清楚了这个技能在什么场景下使用、执行步骤是什么、有哪些禁忌。模型本身是通用的但 skills 让它在特定场景知道该按什么顺序做什么。我习惯用新人的培训手册来类比。一个实习生再聪明你也不会直接把他丢到核心项目里自由发挥你要先给他一本 SOP告诉他接到需求先确认边界再拆任务写代码之前先想测试。Superpowers 就是给 AI 助手发的这本 SOP。它不改变模型底层的推理能力而是改变模型使用能力的方式让每次输出都有流程兜底。还有一点需要明确superpowers 这个名字虽然听起来像“外挂”但它不是魔法。装上之后 AI 不会突然变得无所不知而是变得更可控、更稳定。它的价值在于把那些“靠提示词碰运气”的操作变成了有明确输入输出和步骤的固定动作。1.2 一个典型的工作流对比没有 Skills 的 AI 助手 vs 有 Skills 的 AI 助手我拿一个很常见的需求来对比比如给库存管理模块加一个“导出 Excel”的功能。没有技能时你大概率会把需求直接丢给 AI它一次性生成一大坨代码包括数据查询、文件写入、前端下载按钮甚至还会顺手帮你改掉几个无关方法。第一版看着很完整但跑起来可能边界条件没处理文件路径写死测试也没补。有 Superpowers 之后同样的需求会走完全不同的路线。AI 会先调用 planning 技能把任务拆成“确认数据模型、实现导出接口、加前端入口、补测试用例”四步然后按顺序执行每一步做完都会停顿下来等确认最后还会用 code-review 技能做一个自查检查有没有明显问题。对比维度没有 Skills 的默认状态有 Superpowers 的状态接到任务后的第一反应直接生成代码先拆解任务、确认边界测试环节经常省略需要你反复提醒由技能流程强制驱动上下文管理一次对话越滚越长容易前后矛盾分多轮小步执行状态可控产出稳定性凭模型手感时好时坏靠流程兜底结果可预期你可能会觉得这不就是把一个需求拆成几步吗我自己手动在提示词里写不就行了。原理上是这样但难点在于一致性。手动写的提示词每次都不一样有时候记得加测试有时候就忘了技能则把流程固化下来只要触发条件匹配就会按文档里的步骤走。这种“流程带来的稳定性”才是 superpowers 这类技能库的核心卖点。2. 安装 Superpowers 前的环境准备与版本辨析2.1 核心依赖支持 Skills 的 AI 编程终端与目录结构在安装之前先确认你手上的工具真的支持 skills 机制。现在市面上不少 AI 编程终端都能读取外部技能目录比如 Claude Code 这类工具安装时会自动创建~/.claude/skills/这样的目录你只需要把技能文件夹放进去启动时工具就会扫描每个技能目录里的 SKILL.md把元信息注入上下文。不同工具的目录不一定是同一个。有些放在~/.claude/skills/有些放在~/.config/xxx/skills/还有的允许你在项目里维护一份.claude/skills/做到团队共享。我在第一次安装时就因为没搞清楚路径把技能放错了位置折腾了大半天才发现工具根本没扫那个目录。建议先做一件事打开你的工具文档搜“skills directory”或者“技能目录”把实际路径确定下来再开始动手。除了路径还要检查工具版本。skills 机制是近一年才普及的功能老版本可能压根不支持或者只支持部分字段。如果你用的是长期没升级的版本先升到最新稳定版再说。模型方面尽量选择能读懂较长 Markdown 文档的新模型这直接影响技能文档能不能被有效理解。2.2 不同安装路径该怎么选Superpowers 的安装方式没有特别统一的标准因为项目本身也在快速迭代。我见过的主要有三种直接从仓库 clone 到技能目录、通过包管理器安装、手动下载 release 压缩包解压。三种方式各有适用场景不用盲目追求某一种。安装方式适合人群优点需要注意的点Git clone 仓库后复制技能目录想改技能、排查问题的开发者能看到源码排错直观仓库更新需要自己拉取包管理器安装喜欢统一管理工具链的人更新方便版本管理清晰依赖项目维护者的发布节奏下载 release 手动解压只想开箱即用的用户快速、轻量无法直接看到中间过程我自己更推荐第一种尤其是新手。原因很简单技能这种文件形式最好能随时打开看一眼。当你发现某个技能行为不对时能直接定位到是 SKILL.md 里的哪条指令引起的这是排错能力的基础。用包管理器装的话文件分散在安装目录里反而不直观。不过无论选哪种都要注意版本问题。技能库更新频率通常很快但并不是每次更新都是平滑的。作者可能会调整技能名称、改变触发描述、改动步骤结构这些都可能影响你现有的工作流。所以安装完成之后最好记下版本号或者直接用 tag 固定版本别一路追最新。3. 一步步安装并引入 Superpowers 技能3.1 从仓库拉取到本地 Skills 目录假设你已经确认工具支持 skills并且知道了技能根目录。以~/.claude/skills/为例第一步是创建目录然后把仓库 clone 下来。下面的命令里的地址只是示意实际请以项目仓库页为准。mkdir -p ~/.claude/skills git clone https://github.com/example/superpowers.git ~/.claude/skills/superpowers但这里有一个很关键的坑不是所有仓库 clone 下来就能直接用。很多技能库是 monorepo 结构里面有一个skills/目录存放着多个技能子目录如果你直接把整个仓库放到~/.claude/skills/superpowers那技能根目录就变成~/.claude/skills/superpowers/skills/skill-name多套了一层工具很可能扫描不到。正确的做法是clone 到一个临时位置然后把里面的 skills 内容复制到真正的技能根目录。我常用的命令是这样的mkdir -p ~/.claude/skills git clone https://github.com/example/superpowers.git /tmp/superpowers cp -r /tmp/superpowers/skills/* ~/.claude/skills/ rm -rf /tmp/superpowers复制完以后检查一下目录结构。正确的形式是~/.claude/skills/skill-name/SKILL.md而不是~/.claude/skills/superpowers/skill-name/SKILL.md。这个细节决定了工具能不能认出技能我见过很多人卡在这一步。3.2 最小可用配置让 AI 助手识别到技能文件放好之后还需要确认工具的配置是否正确。有些工具支持自动扫描默认技能目录不需要额外配置但如果你使用的是自定义路径通常需要在配置文件里指定。以 JSON 配置文件为例最小化的配置大概是这样的{ skills: { enabled: true, paths: [/home/username/.claude/skills] } }注意这里配置的一定是“技能根目录”也就是直接存放各个技能子目录的那一层不能把路径指到某个具体技能里面。另外很多配置文件不处理~这种波浪号展开建议直接写绝对路径避免启动时找不到目录。不同工具对这个配置项的命名可能不一样有的叫skills有的叫additional_skills_path还有的直接通过环境变量指定。最稳妥的办法是先去工具配置界面看一眼 schema再决定字段名。不要直接复制网上的配置版本不同很容易踩坑。如果工具支持项目级配置我会优先用项目级配置。比如在仓库里维护.claude/skills目录然后提交到 Git团队每个人 clone 项目后技能自动生效比各人手动配置全局目录省心得多。3.3 快速验证技能到底加载了没有装完配置完别急着开始写需求先花一分钟验证技能有没有真正被加载。验证方式有三种我按效率从高到低排列。第一种直接在对话里问 AI“你现在加载了哪些技能把技能名和用途列出来。”如果 superpowers 里的技能名称能出现在回复里说明扫描成功如果它只说了一些通用能力说明技能大概率没被读到。第二种如果你的工具支持调试模式启动时看日志。日志里一般会输出“scanning skills directory”之类的信息后面跟着扫描到的技能列表。找不到技能时日志里通常也会有 warning能直接定位目录路径问题。第三种实际触发一个技能。比如让 AI“使用 code-review 技能检查当前目录下代码”然后观察它的行为。如果它的回复明显是在按 SKILL.md 里的步骤走说明加载成功如果它只是按照一般常识给建议那就要回到目录结构排查。我把验证过程当成安装的一部分因为它能在最早的时间点暴露问题。很多时候你以为自己装好了实际上技能目录路径写错、文件名大小写不对、frontmatter 格式坏了这些小问题在正式使用时才暴露会严重干扰对技能本身的判断。4. Superpowers 到底有哪些 Skills 值得重点用4.1 按使用频率划分的技能清单具体技能清单会因仓库版本不同而变化我不建议照搬任何旧版本的目录结构但有一类技能是几乎所有技能库都会覆盖的也是我在项目里最常用的。这里按使用频率整理一份参考你可以在自己安装的 superpowers 里对照查找。技能名使用场景典型产出planning接到复杂需求需要先拆解任务拆分清单、风险点提示implementation按计划实现功能分步生成的代码同步更新测试testing补测试用例或跑测试可执行的测试代码与运行结果code-review代码合并前自查按可维护性、边界、性能输出的问题清单debugging排查线上或本地故障日志分析、假设验证过程documentation写 README、接口文档结构化的说明文档这六个技能里planning 和 code-review 是我个人认为最可能改变工作习惯的。planning 强制 AI 在写代码前先想清楚这能很大程度避免“需求理解偏差”code-review 则让 AI 对自己的产出做一次结构化检查相当于给代码加了第二道质量闸门。但要注意技能不是越多越好。技能库装得太多系统提示会被撑大模型在每一个具体任务上反而可能犹豫不决。我见过有人把几十个技能全部塞进去结果 AI 在一个简单问题上都要翻半天“该用哪个技能”效率明显下降。先装核心技能跑熟了再扩展。4.2 技能如何被触发元信息与调用流程技能能被触发靠的是 SKILL.md 文件头部的元信息也就是 frontmatter。这个机制理解起来不难但很多人忽略它的作用。下面是一个简化版的 SKILL.md 示例--- name: code-review description: 用于对代码变更做结构化审查检查可维护性、边界条件、性能隐患。当用户要求 review 代码或合并前检查时使用。 --- # Code Review 技能 ## 执行步骤 1. 列出本次变更涉及的文件 2. 按可维护性、边界条件、性能三个维度逐项检查 3. 输出问题清单并标注建议优先级模型选择技能的核心依据是 description 字段。它读取这个描述后会和当前任务做语义匹配判断“现在的场景是不是该调用这个技能”。所以 description 一定要写得具体、有触发场景不然模型很容易忽略它。触发方式有两种。一种是用户主动点名比如“请使用 code-review 技能检查这段代码”另一种是模型自动触发这完全依赖 description 的质量。如果你发现某个技能经常不被激活优先检查 description 是不是写得太泛了。像“这是一个代码审查技能”这种描述基本等于没写改成“当用户要求 review 代码或合并前检查时使用”就好很多。4.3 自定义技能从一份 SKILL.md 开始用到一定阶段你会发现内置技能总有不顺手的地方这时候就该自己写了。Superpowers 这类技能库最大的优点在于它鼓励你把“自己项目中反复出现的任务”固化成技能文件而不是每次手动敲提示词。我以“数据库迁移”为例演示怎么自定义一个技能。先在技能根目录下建个子目录mkdir -p ~/.claude/skills/db-migration然后在里面创建 SKILL.md。内容不要写长篇大论要把自己当成在给另一个工程师写交接文档。重点写清楚什么场景用、按什么步骤做、有什么禁止事项。这是我自己常用的模板结构--- name: db-migration description: 用于生成数据库迁移脚本并检查迁移顺序。当用户提到要改表结构、加字段、建索引时使用。 --- # 数据库迁移技能 ## 步骤 1. 先列出当前迁移文件目录确认最新版本号 2. 按照项目命名规范生成新迁移文件 3. 迁移内容只包含结构性变更不混入数据修复逻辑 ## 注意事项 - 禁止直接修改历史迁移文件 - 如果变更涉及回滚需要在迁移脚本内提供 down 方法自己写技能时最容易犯的错是试图把所有情况都写进去。实际上技能文档越聚焦越好一个技能只解决一个高频场景。写得太宽泛模型反而不知道什么时候该触发写得步骤太多执行时也容易在中间环节偏离。5. Superpowers 实际项目中的使用技巧5.1 把大任务拆成“技能小步走”的执行序列很多人在实际项目中用不好技能不是因为安装有问题而是用法太粗暴。最典型的场景是让 AI“一次性用所有技能完成一个功能”。这其实违背了技能设计的初衷。技能是提供流程约束的如果把它当成超级提示词一样一次触发效果反而不好。我现在遇到复杂需求会刻意把过程拆成五个小步骤。第一步让 AI 使用 planning 技能输出任务拆解第二步我确认拆解结果再让它进入下一个阶段第三步用 implementation 技能实现具体功能第四步用 testing 技能补充测试并运行第五步用 code-review 技能做输出前检查。这里要注意每一步之间最好显式断开让 AI 停下来等我指令。比如开头就说“不要直接写代码。先用 planning 技能把这个需求拆成步骤输出后等我确认。”这样每个阶段的状态是可控的也方便我在中间介入纠偏。小步走的好处不止是更稳还能减轻上下文负担。一次对话里塞太多任务描述模型越到后面越容易忽略最早的约束拆成几次调用每次聚焦一个目标模型的注意力会集中很多。这也是我认为 superpowers 真正能提高产出质量的原因。5.2 用生成目录与复盘日志管理上下文技能执行过程中会产生很多中间信息如果全部靠对话记住很容易把上下文窗口撑爆。我的办法是让技能在输出内容的同时把关键结果写入项目里的文件之后的新会话直接读文件而不是依赖对话记忆。举个例子planning 技能输出任务拆解后我会让它把结果写进docs/plan.md。后面开新对话、或者上下文被截断只需要告诉 AI“先读一下 docs/plan.md”它就能快速恢复对任务的理解。这个习惯听着简单但我在实际项目中试过比任何上下文压缩工具都管用。类似地code-review 技能产生的检查结果我也会让它输出到docs/review.md。这个文件不仅能辅助当前任务还能成为团队 review 的记录方便之后追溯。关键是这也让技能的产出变得可复用而不是只存在于一次性的对话流里。如果你用的技能支持输出文件路径尽量在 SKILL.md 里固定下来。每个技能写清楚“输出应该落在哪里”执行时会少很多不确定尤其是在多轮对话、多人协作的场景里这个约定非常有价值。5.3 团队协作时如何同步技能库当团队里多个人都在用技能库时最大的问题不是安装而是版本不一致。你这边升级了新技能同事那边还是旧版行为表现就不一样问题排查会变得很麻烦。我建议直接把技能库作为 Git 仓库管理通过 submodule 方式引入项目。git submodule add https://github.com/example/superpowers.git .claude/skills/superpowers git commit -m Add superpowers as project skills这样每个 clone 项目的人只要执行git submodule update --init就能拿到统一版本的技能。需要注意submodule 默认记录的是 commit 引用不要随意更新。在新功能验证稳定之前建议固定到某个 tag 或已知稳定的 commit 上。cd .claude/skills/superpowers git checkout v1.2.0 cd ../.. git commit -m Pin superpowers to v1.2.0这个做法的背后逻辑是技能库更新可能引入破坏性变化而团队协作场景没有试错的余地。固定版本虽然看起来保守但能保证每个人行为一致。等新版本在个人项目里验证充分了再统一升级。6. Superpowers 常见问题与排查实录6.1 技能没有被识别从路径到格式逐项排查技能装好后完全不生效这是最常遇到的问题。我见过的情况里绝大多数不是工具坏了而是细节没到位。排错的时候按照下面这个顺序逐项检查能省很多时间。症状可能原因处理方式对话里问技能列表为空技能根目录配置错误检查配置文件里 paths 是否指向根目录不要指向技能子目录日志显示没有扫描到 SKILL.md目录结构多套了一层确认每个技能目录下直接就是 SKILL.md不要有中间层扫描到了但技能不触发description 写得太笼统重写 description明确“什么场景下使用”扫描报 YAML 解析错误frontmatter 缺少结尾分隔符检查 SKILL.md 是否以---开头和结尾最容易被忽略的是目录层级问题。工具通常只扫描根目录下的直接子目录如果技能被放在skills/superpowers/skills/xxx这种嵌套结构里它大概率会因为层级太深而找不到。遇到这类问题先在文件管理器里把目录结构完整截图看一眼比自己瞎猜快得多。另外文件名大小写也要留意。Linux 和 macOS 的默认文件系统是区分大小写的如果技能目录是CodeReview配置文件里却写了codereview也会导致扫描失败。优先保持所有名称一致都用同一种大小写规则。6.2 技能执行时的路径与权限问题技能能被加载不代表它能顺利执行。有些技能文档里包含 shell 命令或者需要读写文件这时候最容易出现路径和权限问题。我在一次日志分析任务里遇到过很典型的情况技能脚本尝试直接读取/var/log下的系统日志文件结果被沙箱权限拒绝整个过程卡在第一步。后来我把项目日志输出到工作目录下再让技能读取项目内文件问题就解决了。这里的经验是尽量让技能只访问当前工作目录内的内容不要依赖系统目录或全局路径。权限问题还有一种表现是“command not found”。技能文档里写了某个命令但执行环境里没装这个依赖。解决办法不是让 AI 硬试而是在技能文档里明确写出前置依赖比如“此技能需要安装 jq”然后提前装好再执行技能。我建议不要用给系统目录放开权限的方式解决问题风险太大。优先调整技能的执行范围把需要读写的文件放进项目目录里这样既安全也稳定。如果你改了一个技能脚本记得重新触发一次确认没有因为路径问题引入新的错误。6.3 版本升级后行为突变怎么处理AI 编程工具和技能库都在快速迭代版本升级引起的行为变化几乎不可避免。我自己就遇到过工具升级到新版本后某个技能突然不触发了查了很久才发现是新版对 description 的解析格式更严格旧写法不再被识别。遇到这种情况第一步是备份当前技能目录然后查看升级前后的 changelog。第二步重新跑一遍之前的验证流程看技能是否还能被正常加载。第三步如果问题依旧对比升级前后 SKILL.md 文件里的 frontmatter 写法通常问题就在格式上。如果技能库本身也更新了但它依赖的工具版本还没跟上可能会反过来出现不兼容。这时候选择就很简单升级技能库或者回退工具版本选一个更可控的方向。我的习惯是“固定一边”工具版本固定或者技能库版本固定尽量不同时两边都升级。现在每次升级前我都会先去技能仓库的 release 页面看一眼确认没有 breaking change再决定要不要动。这个习惯帮我省了不少排错时间也让我对技能行为有了更稳定的预期。最后说一点我自己的体会。superpowers 这类技能库的价值不在于它内置了多少个技能而在于它让你重新审视“如何与 AI 协作”这件事。你不需要记下每一个技能的具体命令只要理解了技能目录结构、SKILL.md 的写法、以及触发机制剩下的完全可以自己做扩展。与其等作者更新不如把它当成模板往里面填自己项目里的高频任务。这个思路用熟之后你会发现自己对 AI 产出的可控性提升了一个档次代码质量的波动也会明显变小。