superpowers 这个名字很容易让人以为是某种夸张的 AI 增强插件但实际接触这类项目你会发现它给 AI 编程助手带来的不是变魔术而是把一套可复用的工作流程固化下来。简单说当你在 Codex 这类命令行编程助手里安装 superpowers 插件后AI 就不再只是零散地回答你的问题而是会按技能文件定义的步骤去完成任务先拆需求、再写测试、然后实现、最后做变更总结。它适合天天用 AI 写代码、但又经常觉得 AI 改完代码没有章法的人。下面我会按照实际安装和使用顺序把这个项目常见的目录结构、安装方法、技能调用方式和排查思路拆开讲一遍。1. superpowers 解决的不只是“多几个提示词”而是让 AI 按流程干活先说一个很多人会误解的点superpowers 这类“技能插件”并不是给 AI 额外装一个能联网、能读心、能自动升级的模块。它更像是一套给 AI 编程助手看的“操作手册”。1.1 普通会话式编程和技能化编程的差别普通用法下你在 Codex 里输入一句话AI 就按这句话直接写代码。比如你对它说“帮我把用户列表接口加上分页”它可能立刻开始改文件也可能先问你觉得改成什么风格整个过程依赖你当时 prompt 写得多清楚。同一个需求今天问和明天问AI 的处理顺序可能完全不同出来的代码风格也不稳定。技能化之后AI 的行为被约束在一条明确的流程里。比如 TDD 技能打开后它会先理解需求再写失败测试运行测试确认然后写最简实现最后再跑一遍全部测试。这个顺序不是靠你在每个任务里重复提醒而是技能文件里已经规定好、每次都能被加载的内容。所以 superpowers 真正的价值是一致性、可复用、可版本管理。技能文件是文本你可以把不同项目的规范写成不同技能可以提交到 Git 里和团队共享也可以观察 AI 在执行过程哪里容易出错再回头改技能描述。1.2 这类项目最常见的组织方式如果你打开一个这类技能的 GitHub 仓库通常会看到类似这样的目录结构superpowers/ README.md skills/ code-review/ SKILL.md test-driven-development/ SKILL.md examples/ git-workflow/ SKILL.md scripts/ task-breakdown/ SKILL.md install.sh核心是skills/目录下面每个子目录代表一个技能。每个技能目录里通常有一个SKILL.md文件它就是给 AI 看的说明书里面会写这个技能适用什么场景、执行步骤是什么、输出格式是什么。有些项目还会带install.sh或安装脚本作用是帮你自动把这些文件复制到 AI 编程助手的配置目录里。安装过程本质上就是“放文件”不是执行什么黑魔法。所以遇到安装失败不要先怀疑项目不行多半是目录放错了、文件没权限、或者助手版本不读这个目录。2. 安装前先确认环境、版本和目录否则后面全是怪问题把技能文件装进 Codex听起来很简单实际操作时最麻烦的一步反而是确认环境。我见过很多安装失败的案例最后查下来都不是项目的问题而是工具的配置目录和安装预期不一致。2.1 先判断你的 AI 编程助手支持哪种扩展方式不同编程助手的扩展机制不一样。“插件”这个词在不同工具里含义不同。一些工具支持 marketplace 式的插件市场你输入一个插件名就能安装另一些工具则只支持从配置文件里引用技能目录还有一类工具更简单约定好把技能文件夹放到指定路径下就会自动读取。到底属于哪一种要以你正在用的工具官方文档、以及 superpowers 仓库 README 为准。对于 Codex 这类命令行工具常见做法是有一个用户级配置目录比如~/.codex。技能文件、插件配置、历史会话可能都放在里面。你只需要把 superpowers 里的技能目录复制到对应位置再重开会话让工具重新加载配置就行。2.2 环境清单和安装前检查项这里给一个通用检查清单适用于大多数本地命令行编程助手检查项建议状态说明操作系统Windows / macOS / Linux 均可不同系统配置路径不一样先确认你的平台命令行工具已正确安装并能在终端启动确保codex这类命令能正常返回版本信息用户目录权限可读写技能文件要复制进配置目录权限不足会失败依赖运行时按项目 README 准备如果技能里有辅助脚本可能要求 Node、Python 等网络可访问仓库或下载页面获取项目文件阶段需要网络配置文件保留原样不要乱改安装前最好备份原有配置方便回滚实测里最容易忽略的是版本。 Codex 这类工具迭代很快今天支持的配置字段下周可能就改了。所以你在搜索“superpowers 安装”时如果看到别人的配置结构先对比自己的工具版本不要直接抄。注意安装前可以先跑一句 “请列出你现在加载了哪些技能”。能列出来说明技能加载机制正常后面装 superpowers 只是加文件如果列不出来说明你的环境和别人写教程时的环境可能不一样需要先解决基础加载问题。3. 给 Codex 安装 superpowers 插件的通用流程下面这套流程不针对某个特定版本而是这类项目最常见的安装路径。你实际操作时以项目仓库 README 为准。3.1 第一步获取项目文件第一种方式是通过 Git 克隆仓库git clone https://github.com/obra/superpowers.git如果你不方便用 Git也可以直接下载项目压缩包解压到本地临时目录。这一步不复杂重点是你后面要知道文件被放到了哪个路径。我一般会先在终端里切到项目目录用ls看一眼确认里面确实有skills或类似目录再继续下一步。有些用户会遇到“下载很慢”或“仓库访问不了”的情况。先看网络和代理配置是否正常再看项目是否已经迁移到新的地址。很多时候不是项目没了而是你拿到的旧链接已经失效。3.2 第二步按工具要求的目录放置技能文件这步是核心也最容易出错。不同工具的技能目录可能叫skills、plugins、commands路径也可能在用户目录、项目目录或工具自己的安装目录。以“把 skills 放到 Codex 用户配置目录”为例常见的命令形如mkdir -p ~/.codex/skills cp -r superpowers/skills/* ~/.codex/skills/注意这段命令只是示例。如果你的工具版本已经改成从~/.codex/plugins.json里读取插件或者要求把技能目录放在某个项目的.codex/skills下那上面的复制方式就不适用。更稳妥的做法是先查看目标目录里是否已经存在同类型文件。如果有打开一个看看格式如果没有也不要强行创建而是先确认工具是否支持这个路径。3.3 第三步验证加载是否成功复制完成之后不要急着开始写代码。先重启命令行会话然后让 AI 输出当前技能列表。如果列表里能看到类似test-driven-development、git-workflow这样的名字说明加载成功。如果你的工具不提供技能列表命令还有一个土办法直接打开一个任务在 prompt 里点名让 AI 使用某个技能。比如“请使用 TDD 技能完成这个函数”。如果 AI 开始按技能的步骤执行说明技能文件已经被读取到了。如果没生效不要反复重启。先检查你复制的文件路径、目录名大小写、文件扩展名再看工具日志。多数情况下问题出在这里。4. 常用技能的实际用法TDD、Git 工作流、任务拆解superpowers 这类项目真正有意思的地方不是装完那一刻而是你开始在日常任务里调用这些技能的时候。这里挑三个最常见的技能来说。4.1 测试驱动开发技能怎么落地TDD 技能会让 AI 在写实现代码之前先写测试。一个典型的技能文件会这样约束 AI# 技能名称test-driven-development ## 适用场景 新功能开发、Bug 修复、行为变更。 ## 执行步骤 1. 阅读需求列出最小验收条件。 2. 为验收条件编写失败测试。 3. 运行测试确认失败原因符合预期。 4. 编写最简实现代码。 5. 再次运行全部测试确认通过。注意我没有说所有 AI 编程助手都自带这套流程但如果你把这段内容作为技能描述提供给 Codex它能明显改变行为。实测中你会看到AI 不再一上来就大段生成业务代码而是先问你“预期输入输出是什么”再生成测试然后再填空似的补实现。很多人不适应这个流程觉得多了一步。但如果你在维护一个核心模块AI 直接生成 200 行没有测试的代码你根本不敢合。有了测试打底后面做重构、改参数、换依赖都更安心。4.2 Git 工作流技能的价值另一个高频技能是 Git Workflow。它主要解决 AI 改完代码后“提交动作太乱”的问题。常见场景是你让 AI 修一个 Bug它一口气改了 8 个文件里面有格式化调整、有逻辑修复还顺手改了两个配置。然后 AI 把这些全塞进一个 commit。代码确实能跑但 review 时很难受。Git 工作流技能会让 AI 在改动前先判断这次任务的最小范围中途拆分 commit并给每个 commit 写清晰的描述。比如分析需求列出会改动的文件。小步改动每完成一个独立逻辑就提交一次。提交信息写明“为什么改”而不是“修改代码”。这个技能特别适合有多人协作的项目。我自己的习惯是只有当我明确要让 AI 处理跨文件、多步骤的任务时才会点名使用这个技能。平时小改动用默认模式就够了否则反而会觉得 AI 太啰嗦。4.3 任务拆解和编码规范任务拆解技能适合复杂需求。你丢给它一个问题“把一个旧模块从单线程改成异步任务队列”它不会立刻改代码而是先产出计划现状评估边界条件梳理改动清单实施顺序验证方案这一步非常关键。AI 直接改复杂模块时最危险的是它理解错了目标最后生成一套看似完整、其实方向完全错误的代码。任务拆解可以把这种风险前置。编码规范技能则可以按项目定制。比如你们团队要求函数要写 docstring、行宽不超过 100、禁止引入新的全局状态这些都可以写进一个规范技能里。安装 superpowers 之后你可以根据团队需要自建技能这也是这类项目另一个价值不只能下载别人写好的还能自己补充。5. 怎么验证技能真的生效而不是装了个寂寞安装完成后我建议不要直接上大型任务而是先用一个很小的样例验证效果。5.1 先跑一个最小的端到端样例找一个不到 50 行的练习任务比如“写一个判断闰年的函数”。在 prompt 里明确要求使用 TDD 技能请使用 TDD 技能为我实现一个判断闰年的函数编程语言用 Python。成功时的行为应该是AI 先列出测试用例比如 2000 年是闰年1900 年不是。生成测试文件并运行测试。测试失败输出失败信息。再写实现代码。再次运行测试全部通过。如果你看到这个顺序说明技能读取成功了。如果 AI 直接给你一个函数就完事说明技能大概率没被加载或者当前工具没有在后台自动调用技能。5.2 观察 AI 的思考路径和输出差异现在很多 AI 编程工具会显示中间步骤。你要看的不是它说了什么漂亮话而是它有没有按照技能的步骤来。比如调用 Git 工作流技能时AI 是否在改动文件之前先做了影响面分析调用任务拆解技能时它是否先输出 checklist 再写代码。如果工具不显示中间步骤也可以通过生成结果反推。比如你要求“小步提交”结果它还是只产生一次大提交那就是没生效。这个时候不要反复在对话里强调“你要按我说的做”而是去查技能文件是否被正确加载。5.3 从耗时、成功率和结果一致性来判断判断技能是否值得长期使用我可以给你几个更客观的指标指标怎么看单任务耗时技能会引入额外步骤耗时增加不一定是坏事首次成功率代码一次跑通的概率有没有提升结果一致性同样的需求分两次问行为顺序是否接近可读性commit 信息、测试命名、代码结构是否更清晰回滚成本出问题时是否更容易定位是哪一步引入的我建议跑 5 个左右的真实小任务再做判断。前 2 个任务可能觉得麻烦第 3 个开始你会慢慢建立起“AI 会先做什么、再做什么”的预期。如果到第 5 个任务你还是觉得它只是多了几段废话那就可以考虑调整技能描述而不是干脆放弃。6. 常见问题和排查顺序这部分我按实际踩坑频率来写。很多问题看着像项目不支持实际都是运行环境或使用方式的问题。6.1 装完不生效先看这些如果技能没有生效按这个顺序排查先确认文件是否在正确目录。跑一下ls查看实际路径不要凭印象。再确认目录层级是否多套了一层。很多人把superpowers/skills/test-driven-development复制成了skills/superpowers/skills/test-driven-development工具读不到。检查文件名大小写。Linux 系统对大小写敏感Skill.md和skill.md可能是两个文件。检查配置目录权限。目录不可读、不可写也会导致加载失败。重启会话。很多工具只在启动时读取技能配置中途添加文件不会自动生效。看工具日志。日志里的信息量通常比错误提示大得多。如果以上都没问题再考虑是不是工具版本太老不支持动态技能目录。6.2 代码风格混乱问题可能出在技能冲突装了多个技能之后AI 可能同时触发好几个行为反而变得混乱。比如 TDD 技能要求先写测试任务拆解技能又要求先做计划两个一叠加AI 可能在计划阶段就开始生成测试步骤来回跳。解决办法不是删掉所有技能而是降低同时启用的数量。很多工具支持在项目目录里放单独的技能配置这样 A 项目只加载 A 需要的技能B 项目只加载 B 需要的技能避免全局加载导致冲突。6.3 我的建议从小技能开始逐步扩展给第一次接触 superpowers 类项目的读者一个建议不要一次把整个技能集装完。先选一个你最痛的问题比如“AI 提交代码太乱”或者“AI 不写测试”只启用对应技能跑一周。确认稳定、有效再添加下一个。因为这个过程本质上是把 AI 的工作方式“调教”成你的开发习惯。如果一次塞给它太多行为约束它要么执行不到位要么频繁打断你的节奏。反而只约束一个点效果最明显。另外时间一长你可能会发现有些技能文件里写的步骤并不完全适合你的项目。这时候可以直接改技能描述文件把“先做什么、再做什么”改成你团队的真实流程。这就是文本化技能的好处不需要重新开发插件改几行说明就行。很多问题其实不是工具能力不够而是前置环境和执行流程没有整理干净。superpowers 这类项目刚好能把你在开发中反复叮嘱 AI 的话沉淀成一份可复用、可修改、可分享的规范文件。