给AI编程装超能力：Superpowers技能包全解析

最近在开发者圈子里superpowers 这个词的刷屏频率比我预想的高不少。不是美剧也不是什么超能力崇拜而是 Jesse VincentOBRA开源的一套给 AI 编程助手用的 skill 合集最早依托 Claude Code 的技能市场分发现在 Codex CLI、Trae 这些工具也能接入。陆续有朋友在问这东西到底怎么装、装上之后 AI 编程体验能变强多少、以及网上那些给 AI 装超能力的说法是不是营销。我把自己实际安装、试用、踩坑的过程完整梳理了一遍这篇就把从零配置到真实使用的所有细节都写清楚适合正在用 AI 编程工具、但对 skill 体系还比较陌生的开发者。1. 为什么 AI 编程火了半年大家又开始追 superpowers 这个词1.1 它到底是什么一份写给 AI 的工程师工作手册先给一个最朴素的定义Superpowers 不是一个框架不是一个新模型也不绑定任何特定 IDE。它就是一个 GitHub 仓库里面装了十几份 Markdown 文件这些文件按一定的目录结构组织在一个 skills 文件夹下。每份 Markdown 文件其实就是一份给 AI 看的岗位说明书业内把这种文件叫做 SKILL.md。它用 YAML 头信息描述这个技能是干什么的、什么时候触发用正文告诉 AI 具体该怎么一步步做。模型在对话时读到这些文件一旦判断当前任务符合某个技能的描述就会加载对应的完整指令并按步骤执行。作者 Jesse Vincent 是 Perl 社区的老兵维护过 Bugzilla 和 Request Tracker。他在大量使用 Claude Code 之后意识到一件事模型本身的能力上限不低但缺的是工作方法。就像一个天赋很好的新人没人教他需求澄清、写计划、写测试、自查代码他永远只能靠本能写代码。于是他把自己的私人配置整理好开源命名叫 superpowers中文直译就是超能力。这个隐喻其实是准确的技能不是模型自带的是外挂上去的工作习惯。它的作用相当于给 AI 补齐工程师职业素养而不是提升智商。1.2 三个典型场景它到底治好了哪种AI 病我实际用下来觉得它对三类问题改善最明显。第一类是模糊需求处理。默认情况下AI 会把用户一句含糊的话直接当最终需求三秒钟把代码糊到你脸上。Superpowers 会强制它先进入 brainstorming 环节把边界条件、性能指标、异常处理逐项问清楚再动手。第二类是改代码不跑回归。没有任何流程约束时AI 改完一个函数会很自信地告诉你应该没问题。但测试驱动开发TDD技能会强制它先写测试再写实现最后跑一遍验证而不是靠嘴说。第三类是大任务一次性梭哈。让 AI 写一个完整模块它倾向于一次输出几百行代码中间没有任何检查点。executing-plans 技能则强调一个计划执行完一步就要停下来验证结果再走下一步把大任务切成小步快跑。这三类问题本质上都是新手工程师常犯的毛病。所以圈子里有句调侃Superpowers 的核心价值是把 AI 训练成一个守规矩的初级工程师而不是一个聪明的天才写手。仔细想想这恰恰是它最宝贵的地方。1.3 热度背后的三个条件这个仓库发布没多久热度却一路走高不是没有原因的。前提条件之一是 Agent 型编程工具已经成熟。只有 Claude Code、Codex CLI 这种能自主读写文件、执行命令的工具出现skill 机制才有发挥空间。传统补全型 IDE 根本用不上这类技能。第二个条件是 Anthropic 推出的 Agent Skills 规范慢慢成了事实标准用文件夹加 SKILL.md的方式给模型提供可动态加载的指令包。Superpowers 恰好长在这个规范之上传播成本很低。第三个条件是口碑效应。很多开发者在实际对比后发现装不装 skillAI 的行为差异是肉眼可见的。一个工具如果能让人明显感觉到它做事变靠谱了那它在社区里火起来只是时间问题。superpowers 的使用教程、安装命令等相关搜索量飙升也完全符合这个传播规律。提示在理解 skill 机制之前先别急着问怎么装。先想清楚它解决什么问题、工作流长什么样否则装完你也可能觉得好像没什么变化。2. 拆开仓库看结构十几个技能如何编排成一条完整研发流程2.1 最小单位 SKILL.mdAI 技能的标准说明书把仓库 clone 下来之后第一眼看到的结构大致是这样的superpowers/ ├── CLAUDE.md ├── README.md ├── skills/ │ ├── brainstorming/ │ │ └── SKILL.md │ ├── writing-plans/ │ │ └── SKILL.md │ ├── executing-plans/ │ │ └── SKILL.md │ ├── writing-tests/ │ ├── writing-code/ │ ├── implementing-changes/ │ ├── self-critique/ │ ├── test-driven-development/ │ ├── debugging/ │ ├── asking-questions/ │ ├── running-tasks/ │ ├── verifying-work/ │ ├── using-git/ │ └── committing-changes/顶层的 CLAUDE.md 是总入口定义了整个技能包的工作原则。skills 目录下面是十几个独立的技能文件夹每个文件夹里是核心的 SKILL.md有的还附带配套脚本或模板。每一个 SKILL.md 的开头长这样--- name: brainstorming description: 在开始写代码之前用于澄清需求、探索方案、确认边界条件。当用户提出的需求含糊不清、影响范围不明、或存在多种实现方案时应当使用本技能。 ---接下来正文给模型看的则是详细操作步骤和禁止事项。这套格式的精妙之处在于模型先读取 description判断当前对话是否符合技能的使用条件一旦决定调用才加载对应完整指令。也就是说技能是按需加载的而不是把所有说明书一次性塞进上下文。十几个技能的 head 信息加起来并不算太长token 开销完全可控这也是这套方案能真正落地的原因。2.2 技能清单一览从澄清需求到提交代码我把核心技能按研发流程梳理了一遍下面这张表基本可以看到全貌技能触发时机核心作用brainstorming需求不明确、方案有分歧澄清需求、探索候选方案writing-plans需求已对齐、准备实现前把实现拆成可验证的小步骤writing-tests计划完成、动手写代码前先用测试锁定期望行为implementing-changes有测试用例作为保障后写实现代码让测试通过self-critique代码写完后以评审视角主动找 bug 和边界漏洞verifying-work实现完成、准备提交前对照验收标准逐条验证committing-changes全部验证通过后生成规范、可追溯的提交信息debugging测试失败或运行报错系统化定位问题而不是瞎猜asking-questions需求描述有遗漏用引导式提问把隐含条件问全running-tasks需要执行命令、跑脚本时规范模型执行外部命令的方式这个顺序不是随便排的。它是一个有经验的后端工程师在处理中等复杂度需求时几乎每天都会走的完整链路先想清楚、再拆步骤、先写测试、再写代码、然后自查、最后提交。2.3 我把这条流水线理解为工程素养的显式化很多人第一次看到这套流程的反应是这不就是我们平时干活的方式吗有什么稀奇的没错它确实不稀奇。这正是它最大的价值所在。默认的 AI 编程工具是把写代码这个动作单独拎出来放大但忽略了写代码前后那一大堆琐碎但关键的工程活动。而 Superpowers 做的事情就是把这套隐性的工程素养显式化写成模型能照着执行的 checklists。它有点像给 AI 装了一个驾驶辅助系统不替你做决定但会提醒你打灯、看后视镜、保持车距。对于习惯了直接要结果的 AI 用户来说这套流程可能一开始会让你觉得烦但长期来看它省掉的是返工、debug、上线事故这些更大的成本。2.4 asking-questions 和 self-critique 是隐藏 MVP在所有技能里我最想拎出来说的是 asking-questions 和 self-critique。因为这两个最容易被忽略但恰恰又是提升输出质量最明显的。asking-questions 不是简单的要求模型多问问题。它更像一个苏格拉底式的拷问流程会引导模型在需求不清时逐项追问用户没说清楚输入输出边界怎么办是否存在隐含约束性能指标是什么是否需要兼容旧数据它把追问变成一套有结构的提问模板而不是一句空泛的如果有问题请提问。self-critique 则是让模型写完之后切换身份把自己写的代码当成别人的代码来 review主动找出逻辑漏洞、并发问题、资源泄漏风险然后逐个修复。我在多个场景里实测下来这是全包价值最高的一个技能它能把代码看起来能跑、实际一测就挂的尴尬情况减少一大半。3. 安装实录Claude Code / Codex CLI / Trae 三种接入方式3.1 安装前的检查清单在开始安装之前先确认你的运行环境。Superpowers 最早是为 Claude Code 设计的但因为本质上是 Markdown 指令包凡是支持 Agent Skills 规范或者能读取自定义指令文件比如 AGENTS.md的工具理论上都能接入。我建议至少满足以下条件之一Claude Code官方支持插件市场安装最省事Codex CLI通过 AGENTS.md 或新版 skills 目录接入Trae 这类内置技能功能的 AI IDE另外确认你使用的模型版本不要太旧。技能能生效的前提是模型具备较强的指令遵循能力和文件读取能力新版本模型在这方面的表现会稳定得多。3.2 Claude Code一行插件市场命令搞定Claude Code 安装 Superpowers 最省力的方式是用插件市场直接在交互界面里输入/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace装完可以用/plugin查看已安装的插件状态或者用/skills列出当前可用技能。如果~/.claude/skills/目录下能看到 superpowers 相关的文件夹就说明已经生效。如果不想走插件市场也可以直接克隆仓库放到用户级 skills 目录git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers两种方式本质是一样的都是让 Claude Code 在启动时自动发现 skills 目录。按我个人的使用体验插件市场的方式更新更方便仓库方式则更便于直接修改技能文件各有利弊。3.3 Codex CLI用 AGENTS.md 给 AI 指路Codex CLI 早期没有和 Claude Code 一模一样的一键插件市场命令所以社区里最主流的做法是把仓库 clone 下来然后用 AGENTS.md 告诉模型技能放在哪、什么时候该用git clone https://github.com/obra/superpowers.git ~/superpowers然后在项目根目录或用户级的 AGENTS.md 里加一段指令大意是存在一个技能库位于 ~/superpowers/skills。 每个子目录中的 SKILL.md 是给 AI 的指令文档。 当任务符合某个技能的 description 描述时先完整阅读并严格遵循对应的 SKILL.md。这种做法实际上是充分利用了模型的三个能力路径读取能力、指令遵循能力、按需加载能力。不需要任何特殊插件模型只要能读 Markdown 文件指令就能生效。新版 Codex CLI 如果已经支持原生的 skills 目录通常在~/.codex/skills下也可以直接把 skills 文件夹复制过去原理和 Claude Code 一致。3.4 Trae复制 skills 目录到 IDE 配置最近不少人在搜trae work cn 安装 superpowers skill说明 Trae 用户也在尝试这套流程。Trae 这类内置技能机制的 IDE安装方式更接近复制文件夹。常见做法是打开仓库目录进入 skills 文件夹复制你需要的技能子目录粘贴到 Trae 的技能目录可能是项目下的.trae/skills也可能是用户主目录下的 skills 配置目录重启 IDE 让配置生效注意不同版本、不同操作系统的技能目录路径可能不一样。最稳妥的办法是打开设置面板搜索 skills 或 技能看它明确提示的目录在哪里。不要盲目照抄网上的路径这一步是很多人装完不生效的直接原因。3.5 安装结束后的一分钟冒烟测试装完先别急着投入真实项目花一分钟做三个快速测试在对话里问 AI你有哪些技能如果它列出了 brainstorming、writing-plans 这类名字说明技能已被加载到上下文。随便提一个含糊的需求比如帮我优化一下这个函数观察它是停下来问问题还是直接改代码。前者说明技能触发正常。如果模型对技能毫无反应回去检查目录结构SKILL.md 必须在以技能名命名的子目录下frontmatter 里必须有 name 和 description 字段。这两个细节是首次安装时最高频的失误点。4. 同一个需求开不开 Superpowers 的差别有多大4.1 默认状态下的 AI像急着交卷的考生先回顾一下没有 Superpowers 时AI 处理需求的典型表现。我随手举一个很常见的需求给登录接口加一个限流。默认状态下模型会立刻给出类似这样的代码# 这是默认 AI 的典型回应风格 from flask_limiter import Limiter limiter Limiter(app) app.route(/login, methods[POST]) limiter.limit(5 per minute) def login(): # ...看起来挺专业但它完全没有问限流维度是用户 ID、IP还是两者结合5 次每分钟这个阈值是怎么来的生产环境真的合适吗超限之后是返回 429还是排队等待还是静默放行限流状态存哪里Redis 还是进程内如果是进程内多实例部署时怎么办需不需要加白名单需不需要给前端返回重试时间结果就是代码能跑但拿到真实场景里几乎到处都是坑。这就是没有流程约束的 AI 工程师的典型画像代码能力在线工程意识缺失。4.2 开启技能后的 AI会先提问再动手同样的需求放在装有 Superpowers 的 Claude Code 或 Codex CLI 里对话节奏完全不同。AI 在 brainstorming 技能触发之后会先停下来在动手之前我想先确认几个问题限流按用户维度还是 IP 维度阈值大概多少生产环境有没有参考数据超限后的行为是返回 429 还是静默通过限流状态用 Redis 可以吗这个接口目前有没有其他限流逻辑会不会冲突等你回答完它进入 writing-plans 阶段输出一份结构化的实现计划在配置文件中新增限流参数实现基于 Redis 的滑动窗口限流为登录接口挂上限流中间件编写单元测试覆盖正常放行、超限拦截、白名单三种场景运行测试确认全部通过自查代码修复潜在问题接下来才进入代码阶段。而且写代码阶段也不是一口气写完而是按 executing-plans 的要求完成一步验证一步先写测试再写实现最后跑通全部测试再做一轮 self-critique。同样一个需求两种表现高下立判。4.3 一次真实改动导出功能的异步改造我在自己维护的一个内部分支管理工具上做过一次系统性实测需求是给导出功能加异步任务导出完成后通知用户。没开 skill 的对照组直接给出 Celery 任务加邮件通知的实现。代码结构完整看起来没什么毛病但它忽略了任务失败的重试策略、导出文件的过期清理、通知频率限制这几个关键点。开了 skill 的实验组则完全不同。它在动手前先问了导出文件大小上限、是否需要多格式支持、通知渠道是邮件还是站内信、失败重试策略怎么定。最终给出的方案里包含了任务状态表、重试队列、文件保留策略和一整套异常处理逻辑。代码量明显更大但一眼就能看出是能直接上生产的东西。这个对比让我对 skill 的价值有了一个很清晰的结论它并不让 AI 写出更炫的代码而是让 AI 输出的代码更像一个负责任的人写出来的代码。4.4 我的结论它提升的不是智商而是责任心所以如果问我 superpowers 到底带来了什么我的答案是责任心。模型还是那个模型推理能力没有变化但它被流程约束着必须先问清楚需求、先写计划、先写测试、做完自查。这些约束逼着它把本该做而没有做的工程步骤补齐最终产物自然就从能跑的代码升级为能上生产的代码。不过也要泼一盆冷水Superpowers 不会让一个模型突然变聪明。如果模型本身的推理能力有限再多步骤也只是让它在错误方向上更系统地犯错。所以工具选型上尽量用推理能力较强的版本老模型也能走流程但成果质量的上限会明显低一截。5. 装完不等于会用五个常见的坑和我的应对办法5.1 技能不生效按四条链路逐项排查我见过最多的问题就是我明明装了AI 就是不理我。遇到这种情况排查链路基本是固定的按顺序检查即可。第一确认目录结构。技能必须放在以技能名命名的目录下SKILL.md 必须是这个目录的直接子文件。很多人只把 SKILL.md 文件单独拷了出来丢了外层文件夹模型在扫描目录的时候根本认不出来这是最高频的错误。第二确认 frontmatter 完整。SKILL.md 的开头必须是 YAML frontmatter并且包含 name 和 description 两个字段。description 是模型判断何时激活的依据一旦缺失模型就不知道这个技能什么时候该用。第三确认工具启动时确实扫描了对应目录。不同工具对目录名和位置的约定不一样有的要求放到用户级目录有的要求放到项目级目录。路径不对配置就静默失效不会报错所以特别隐蔽。第四确认会话模式。部分工具在 headless 模式或者某些特定终端模式下不会自动加载用户级配置。遇到这种情况重新启动一个正常模式的会话通常就能解决。5.2 流程开销变大了学会让小事绕开流程感知最明显的副作用是这套流程会明显增加对话轮次和输出长度。一个小需求以前一两句话搞定现在 AI 要问好几个问题、写一份计划、再分解执行。好处是质量上去了坏处是 token 消耗上去了而且在琐碎任务上显得小题大做。我的应对经验有两个第一对简单的一次性脚本直接跟 AI 声明这是个小改动不用走完整流程直接做。技能包本身允许用户手动跳过流程属于正常用法。第二如果某个任务经常误触发流程可以直接编辑技能文件里的 description把触发条件写得更苛刻。比如要求仅当需求影响范围超过一个函数或涉及多文件改动时才使用本技能。这样能减少大量无效流程开销。5.3 权限不足导致流程中断在 Codex CLI 和部分终端工具里模型执行技能时经常需要运行测试命令比如pytest、npm test。如果你的运行环境没有给 CLI 足够的执行权限或者测试命令本身依赖特殊环境变量你会看到模型走流程走到一半卡住然后开始假装继续实际上什么都验证不了。建议在项目根目录预先配置好测试命令和运行环境并在 AGENTS.md 或项目说明里明确告诉模型测试命令是什么如果失败就把失败信息贴出来继续修复。这样能减少很多半途中断的尴尬场面。5.4 不同模型对同一份技能的遵循度差异很大这是一个很容易被忽略的点。同样一份 SKILL.md不同模型的遵循程度可以天差地别。推理能力强的模型读一遍 description 就能准确判断什么时候该激活某个技能该走流程时老老实实走流程。能力弱一点的模型可能出现两种极端一种是频繁误触发什么任务都套全流程输出臃肿另一种是把技能文档当背景介绍读完就忘该用的时候完全想不起来。所以如果你装上之后发现效果不明显先别急着怪技能包换个模型试试可能就有完全不同的体验。这也是为什么我一直建议在用 superpowers 这类技能包时尽量搭配你能拿到的最强推理模型。5.5 把技能包当模板改造才是最值的用法最后说一点我自己这段实践里体会最深的东西superpowers 这种开源技能包最好的用法不是当黑盒而是当模板。我最初装完就是直接用后来发现有些技能的执行顺序不完全符合我的项目习惯比如团队要求先写设计文档再写计划技能包里就没有这个步骤。于是我把仓库里的 SKILL.md 逐个打开看了一遍发现它的设计其实非常清晰每个文件的步骤、检查项、措辞都是可以改的。我就复制了一份到自己的技能目录新增了团队规范、去掉了不适用的流程效果反而更好。这大概就是这类开源技能包和付费AI 工作流最大的区别它把方法论摊开给你看允许你按需裁剪。你有自己的团队规范、技术栈和代码风格完全可以把它当成一份草稿改成适配自己团队的样子。我在实际使用中体会很深的一点是真正让 AI 变强的不是多一个技能包这种名词而是你愿意花时间去定义你希望 AI 用什么方式为你工作。superpowers 恰好把这件事的起点画了出来剩下的路得自己走。