1. 为什么 AI 编程助手需要一套"技能扩展"体系
先说结论：Superpowers 不是某个单一功能的插件，而是一套给 AI 编程代理（Agent）加装"技能"的扩展层。很多人第一次听到这个名字，以为它是一个像 Copilot 那样的补全工具，其实完全不是。它更像一个"技能市场 + 技能管理器"，让你用的 Codex CLI、Claude Code 这类终端里的 AI 助手，不再只会机械地"你问我答"，而是能按一套成熟的工程方法论去处理任务。
用过 Codex CLI 的人应该都有这种体验：原始版本的 Agent 确实能读代码、改代码、跑测试，但它做事的风格非常依赖你的提示词。你提示词写得好，它就像个资深工程师；提示词写得糙，它就给你一顿瞎改，改了还理直气壮。问题不在于模型能力不够，而在于它缺少一套"该以什么顺序思考、该先做什么后做什么、遇到什么情况要停下来问"的行为框架。
Superpowers 做的就是这件事。它把那些资深工程师解决问题时用的方法论沉淀成了一个个"技能"（skills），比如先头脑风暴再动手、先红后绿的 TDD 流程、深挖根因的调试术、安全审查清单。Agent 在执行任务时会自动加载相关的技能，按技能定义的步骤推进。简单说，普通 Agent 是"你说一句它做一步"，挂上 Superpowers 之后，它变成"你说一个目标，它走一套流程"。
这套东西最初在 Claude Code 社区里火起来，后来逐步扩展支持了 OpenAI Codex CLI 等更多终端 Agent。热词里出现"codex superpowers"一点也不奇怪，因为很多人装它就是为了给 Codex 补上规划、调试、审查这一类工程能力。我自己是从 Claude Code 版本开始用的，后来 Codex 有了插件机制之后，也在同一个工作流里验证过，整体逻辑一致，只是安装入口和存储目录有差别。
这篇内容适合谁？两类人最值得看：一类是已经在用 Codex 或 Claude Code 写代码、但对产出质量不稳定感到头疼的人；另一类是刚听说 Superpowers、想弄清楚它到底能做啥、值不值得装的观望者。我会把安装、初始化、技能机制、真实任务实测和踩坑经验全部过一遍。
2. 装之前先理清两件事：它支持哪些 Agent，装到哪个目录
2.1 前置条件与版本选择
安装 Superpowers 之前，请先确认你的环境里已经有可用的 Agent 终端工具。这里有一个很容易被忽略的点：Superpowers 本身不是独立程序，它是寄生在 Agent 工作流里的插件层，所以你电脑里必须先装好 Codex CLI 或者 Claude Code，它才有地方挂载。
版本选择上，我的建议是装最新发布版，不要因为保守去装很早期的 tag。原因很简单：这个项目迭代非常快，早期版本对技能市场的协议、自动触发机制、缓存目录定义都和现在差别很大。网上很多老教程讲的命令，拿到现在跑会直接报错或不生效。我最初就是顺手装了个半年前的版本，结果技能列表都拉不全，排查了半天才发现是版本太老、接口对不上。
2.2 安装方式和目录约定
安装方式分两条路径，取决于你主力用的 Agent：
如果你用的是 Claude Code，社区最常见的做法是直接跑仓库里的安装脚本，脚本会把 Superpowers 作为插件写进 Claude 的配置文件，同时创建插件市场入口。如果你用的是 Codex CLI，做法类似，只是最终的目录会落到 Codex 的配置目录下。核心思路都是：克隆项目到本地，然后用 agent 的插件命令去加载它。
以 Codex 为例，大致是这几步（不同版本命令略有差异，以官方 README 为准）：
# 克隆项目 git clone https://github.com/obra/superpowers.git cd superpowers # 运行安装脚本，脚本会自动检测你机器上装了哪些 agent ./install.sh跑完之后，脚本会输出一段说明，告诉你已经注册了 marketplace 入口，并要求在新的会话里输入对应的插件命令来确认。这里我要特别强调一个操作习惯：安装脚本提示你"需要重启会话"的时候，一定要老实照做。这个插件是在 Agent 启动时扫描并加载技能清单的，你现有的那个会话并不会热加载，我见过不少人在旧会话里敲命令没反应，以为装坏了，其实只是没开新会话。
2.3 配置目录与运行时目录的区分
装完之后，你会在用户目录下看到两类不同的内容，很多人分不清：
一类是安装目录，也就是你 clone 下来的那个项目目录，它相当于"技能仓库本体"，包含技能模板、默认脚本和版本信息。另一类是运行时目录，通常叫.superpowers或者以插件名命名的子目录，Agent 每次会话会从这里读取已安装的技能缓存、会话记录和技能执行日志。
理解这个区分非常重要，因为你之后如果手动改技能、加自定义 skill，改的是运行时目录里的对应文件；而你升级 Superpowers 本体时，更新的是 clone 下来的项目目录。两者别搞混，否则你花半天改好的自定义技能，一次升级可能就找不到了。
3. 第一次初始化：从空会话到跑通一个技能
3.1 初始化会话的正确姿势
安装完成后，打开一个新的 Agent 会话，在对话里输入插件面板命令（不同 Agent 的命令前缀不同，Codex 系一般是/plugin，Claude Code 系一般也是类似结构）。如果安装成功，你会看到当前会话里出现了 Superpowers 的主面板，里面通常包含技能浏览、技能市场管理、当前会话的上下文配置等几块内容。
我第一次跑的时候，面板里密密麻麻列了几十个技能，一时间根本不知道怎么下手。这里给你一个保守的启动方式：先不要急着一口气启用所有技能，先看面板里那几个核心技能，比如 brainstorming（头脑风暴）、planning（规划）、debugging（调试）、TDD（测试驱动开发）、code review（代码审查）这几个。它们是这个项目里打磨得最久、社区反馈最好的一组，也是日常编码需求量最大的。
3.2 技能浏览、订阅与启用
技能市场的工作方式跟手机应用市场有点像，但维度上多了一个"订阅"的概念。你可以浏览市场里有哪些技能，然后用订阅命令把某个技能"拉"到本地缓存里，之后在任何会话里都能使用。有一部分技能是安装时默认就有的，有一部分需要手动订阅。
实际操作时，你要区分两个状态：订阅（subscribe）和启用（enable）。订阅表示"这个技能已经下载到本地了"，启用表示"在当前会话里允许它参与执行"。有些技能默认是禁用的，原因很务实——它们要么是重型工具（比如需要启动额外服务），要么是有一定风险的操作（比如大范围重构）。Agent 在执行过程中碰到一个已订阅但未启用的技能时，会先询问你，而不是默默启用。这个设计我刚开始觉得烦，后来发现它救过我很多次：有些重型技能一旦触发，会真的改动你仓库里几十个文件，给它加个确认闸门是合理的。
3.3 跑通第一个技能的最小验证
初始化完成后，我建议你做一个最小验证，别一上来就丢一个巨大的重构任务。我当时的做法是这样的：打开一个临时测试仓库，新建一个简单的 Python 脚本文件，故意在文件里留一个明显的 bug，然后用对话让 Agent 去修复它，同时明确要求走调试流程。
你会看到 Agent 的输出方式跟没装插件时有明显变化：它不再是直接甩给你一段修补代码，而是先输出一个分析步骤，再检查文件结构，复述问题定位，最后才给出修复方案。这其实就是一个叫"debugging"的技能在起作用：它让 Agent 按照"复现 -> 定位 -> 根因 -> 修复 -> 回归"的路径走，而不是跳步猜答案。
这一步跑通之后，你对整个系统就有感觉了。剩下的技能树，可以按需在真实任务里慢慢点亮。
4. 技能机制拆解：它到底是怎么给 Agent 注入"超能力"的
4.1 技能的文件构成
很多人用了一两周 Superpowers，仍然以为它是靠某种魔法在起作用。其实不是，它的机制非常朴素，核心就是一个叫SKILL.md的 Markdown 文件，外加可选的脚本目录。
每个技能在运行时目录里对应一个子文件夹，里面至少有一个SKILL.md。这个文件用结构化文本定义了技能的名称、描述、适用场景、执行步骤、输入输出格式，以及更重要的——"触发条件"。Agent 在执行时，会先扫描当前任务描述，通过语义匹配决定要不要加载某个技能。一旦判定命中了，它就会把SKILL.md里的内容当成"系统提示词"注入到本次执行的上下文中。
你可以把SKILL.md理解为给 Agent 的一本"操作手册"。手册写得越具体，Agent 的执行就越稳定。这和普通提示词工程本质上是一回事，只不过 Superpowers 把它标准化了，让每一本"手册"都有固定的结构、更新机制和分发渠道。
4.2 技能与 Agent 的协作流程
Superpowers 的另一个核心设计是"技能之间的编排"。单一技能往往只解决一个步骤，比如"写测试""跑审查"，但一个完整任务往往需要多个步骤配合。
这里就体现出这套系统的聪明之处：一个技能里可以显式调用另一个技能。比如brainstorming技能内部会引导 Agent 调用planning技能去整理头脑风暴的结果；debugging技能在找到根因后，可能会调用TDD技能来写一个回归测试，防止问题复发。它们之间的关系就像工序表，Agent 顺着技能链一步步走。
这种设计带来一个好处：你不必自己用一个巨型提示词去把整个流程讲清楚。Agent 会在执行时按需拉取相关技能文档，每次只需要读它当前那一步需要的内容。我实测下来，同样的任务，用技能编排的方式比单一提示词方式不仅产出质量更高，而且更省对话上下文。
4.3 自定义技能：把它变成你的团队规范
如果你只是用现成技能，Superpowers 的价值已经很高，但真正让它"超值"的是自定义技能。你完全可以在运行时目录下新建一个技能文件夹，写一个SKILL.md，定义一套适用于你自己团队的规范，然后 Agent 在对应场景就会自动遵守。
举个例子，很多团队要求 Python 代码必须通过ruff check和mypy --strict才算完成。你可以写一个名为project-lint的技能，在SKILL.md里写明"任何涉及 Python 文件变更的任务，必须在完成修改后运行上述两个命令，并将结果作为任务的最终输出之一"。之后 Agent 每次完成 Python 文件改动，都会自动执行这套校验流程，不需要你每次重复叮嘱。
自定义技能是让这套系统从"通用工具"变成"团队基础设施"的分水岭。我的建议是刚开始不要追求面面俱到，选定一个你团队里每天都会重复的检查动作，先做成一个技能，跑顺了再扩展其他流程。
5. 实测场景：用 Superpowers 走完一个带调试的编码任务
5.1 场景设计与触发条件
为了把那套抽象机制讲得具体一点，我把一次真实跑过的任务还原出来。仓库是一个 Node.js 编写的内部命令行工具，功能是从配置文件里读取数据源列表，然后并发拉取数据并汇总。这个工具在某次新增配置项之后，运行时会偶发出现"某个数据源超时导致整个任务失败"的问题，已经影响了线上定时任务。
我把这个任务交给挂载了 Superpowers 的 Codex，原话大概是："帮我看一下这个工具为什么一个数据源失败会导致整个任务失败，我需要它失败一个不影响其他数据源。先定位问题，再给出修复方案。"
正常情况下，Codex 接到这种开放式的排查任务，输出方向很难稳定，可能直接开始改代码，改完也不告诉你为什么要这样改。但挂载 Superpowers 之后，我观察到它在正式动手之前，输出了一段"我要先做的事情"清单：复现问题、查看定时任务入口、检查并发控制代码、确认失败处理逻辑。
5.2 实际执行过程
Agent 先读取了主入口文件，发现并发控制的实现是简单的Promise.all，任何一个请求被 reject，整个任务就立刻抛错退出。这个根因定位很准确，也正是我预期中的问题常见形态。
接下来的过程让我觉得物有所值。它没有直接改成Promise.allSettled然后交差，而是先引用了 debugging 技能里关于"根因和症状区分"的检查清单，确认这只是表层的失败传播问题，而不是更深层的资源泄漏问题。随后它又拉出了 TDD 技能，写了一个小型的回归测试，模拟一个数据源超时、其他数据源正常返回的场景，验证修复确实让失败不再扩散。
最终给出的修复是在入口处增加一个并发收口模块，用settled语义处理每一路结果，同时把失败的数据源记录进日志，并保留整体任务的成功状态。这个修复方案没有引入额外的库，改动面也控制在一个文件里，跑了全部测试之后确认通过。
5.3 与裸用 Agent 的对比
说句实话，这种修复如果提示词写得够详细，裸版 Codex 也大概率能完成。真正拉开差距的不在于"能不能修"，而在于过程的规范性和结果的确定性。
裸版 Agent 在长任务里很容易飘，尤其当任务包含分析、实现、验证多个阶段时，它可能做着做着就把早期得出的结论忘掉了。Superpowers 的技能链相当于一道护栏：每一步都有当前技能的规则在约束它。比如 debugging 技能要求它必须陈述根因再写修复方案，这个规则始终停留在上下文中，即便对话已经推进了几十轮，它也不太会跳步。
另一个实际差异是回归测试。裸版 Agent 在完成任务后，经常默认"运行冒烟测试"即可，不会主动为一个 bug 写一个专门的回归测试。Superpowers 的 TDD 技能把"红-绿-重构"的循环写进了它的行为逻辑，所以在很多场景它会自动补上这一步，这对长期维护价值很大。
6. 我从实践中总结的避坑经验与注意事项
6.1 权限确认不是形式主义
Superpowers 在执行技能脚本时，会请求权限确认，很多人习惯性地一路Allow always。我的建议是：对于像 brainstorming、planning 这类纯文本分析型技能，可以放开权限；但对于 debugging、refactor 这类可能大规模改动文件的技能，请务必看清楚它要执行的是什么命令再做决定。
有一个很典型的风险场景：refactor 类技能在执行时，会调用它脚本目录里的批量替换逻辑。如果技能版本和你仓库当前的代码风格不匹配，它可能做出一堆"无害但错误"的替换。我吃过一次亏，技能把几个注释里的功能名词替换成了新名词，看起来内容更一致了，但实际上那些注释指向的是历史版本里的过时信息，等到后人看代码时产生了误导。这不是 Superpowers 的错，是"盲目信任自动化"的错。
6.2 缓存目录和网络问题
技能市场本身依赖 Git 仓库作为分发源。如果你的网络环境访问仓库不稳定，订阅技能时可能会超时。这时不要反复重试同一命令，先看一下运行时目录下是否残留了半下载的状态，残留下一次会被当作"已订阅"处理，但实际上内容不全。
处理方法是手动删除对应技能的缓存目录，重新订阅。这个场景在换机或断网重试时很常见，也是社区里提问率最高的问题之一。没有太多技术含量，但遇到了会让人困惑很久。
6.3 与本地自定义提示词/技能的关系
很多团队在 Agent 配置里已经定义了自己的AGENTS.md或CLAUDE.md这类项目规则文件。这里要特别注意：Superpowers 的技能指令和项目规则文件是并存的，并不是互相覆盖。
实际效果是：项目规则定义"你这个项目里要遵守的约束"（比如数据库只能用 A 方案），而技能定义"处理某种任务要走的流程"（比如改数据库结构前必须做迁移兼容检查）。两者理论上互补，但在少数场景会有重叠甚至冲突。我的经验是：遇到冲突时，以项目规则文件为准。Superpowers 本身也遵循这个层级，它的设计初衷是补齐方法论，不是越过项目约束。
6.4 不要一次开太多技能
最后一条建议最朴素，但也最重要：不要像囤电子书一样囤技能，启用的技能越多，Agent 在每次任务里做语义匹配的负担就越重，偶尔还会出现多个技能抢同一类任务的情况。
什么叫抢任务？比如你同时启用了autonomous-coding和TDD两个技能，Agent 对"写一段代码"这个动作可能同时命中两套流程，输出的行为就会出现不可预测的混合。我的做法是保持一个固定组合：分析类技能留两到三个，实施类技能留三到四个，其余全部保持订阅但禁用状态。需要哪种能力，再在当前会话里单独启用。
6.5 关于升级与备份
Superpowers 迭代快，升级是常态。升级之前，请养成备份运行时目录的习惯。尤其是你自己写过的自定义技能和那些手动调整过的技能配置文件，它们不在 clone 的项目目录里，升级操作往往不会覆盖它们，但保险起见，复制一份到旁边目录只需要几秒钟。
真正容易丢的是会话记录。如果你依赖 Superpowers 的会话管理能力，升级前务必看一下版本说明里有没有关于会话存储格式变更的提示。这类不兼容变更在快速迭代的项目里并不罕见，提前备份能省去很多后悔的时间。
用下来我的整体感受是：Superpowers 不是一个让你"多了一样工具"的插件，而是改变了你和 Agent 协作方式的插件。它把很多本来要靠人反复叮嘱的工程流程，变成了 Agent 默认的行为模式。如果你已经受够了和裸版 Agent 来回拉扯、不断补充提示词的体验，花一个下午装好它、配上核心技能，绝对值回时间。
