Superpowers 使用指南：Codex 技能扩展从安装到自定义实战

1. 从“superpowers”这个热词说起它到底是什么第一次看到“superpowers”这个词很多人会下意识联想到超级英雄电影里的超能力。但在开发者的语境里它其实指向一个非常具体的东西——一套围绕 AI 编程助手尤其是 Codex 这类工具构建的技能扩展体系。你可以把它理解成给 AI 助手装上一套“外挂技能包”让它在处理具体任务时不再只是泛泛而谈而是能按照预设的专业流程去干活。我最初接触这个概念是因为在几个技术社区里频繁刷到“superpowers 使用指南”“codex superpowers”这类搜索词。当时我的第一反应是这又是一个被炒起来的概念吗但真正上手折腾了一段时间之后我发现它解决的其实是一个很实在的痛点——AI 助手很强但它不知道你的项目里有哪些约定俗成的规矩也不知道你希望它按什么套路来做事。superpowers 就是用来填补这个 gap 的。具体来说superpowers 通常以一组技能文件skill files的形式存在每个技能文件定义了某个特定场景下的工作流程、注意事项和输出规范。当你在 AI 编程助手里触发某个技能时它就会按照那个技能定义的流程来执行任务而不是自由发挥。这听起来简单但实际用起来差别巨大。举个例子你让 AI 帮你写一个数据库迁移脚本没有技能约束的时候它可能给你一个能跑但不符合你项目规范的方案有了对应的技能之后它会先检查你的迁移框架版本、命名约定、回滚策略然后再动手。这篇文章适合几类人看一是已经在用 Codex 或其他 AI 编程助手但觉得输出质量不稳定的开发者二是听说过 superpowers 但不知道从哪下手的新手三是想自己写技能文件来定制 AI 行为的高级用户。我会从安装配置讲到实战使用再到自己写技能的思路尽量把踩过的坑都摊开来说。2. 安装与初始配置别急着上手先把地基打对2.1 安装前的环境确认在动手安装 superpowers 之前有几个前置条件必须先确认清楚。这不是走流程而是我实际踩过坑之后总结出来的血泪教训。首先是AI 编程助手的版本。superpowers 的技能机制依赖于助手本身对技能文件的解析能力不同版本对技能文件格式的支持程度不一样。如果你用的是比较老的版本可能会出现技能加载了但完全不生效的情况。我的建议是先把助手更新到当前稳定版再去折腾 superpowers。其次是Node.js 环境。大部分 superpowers 的安装方式是通过 npm 包管理器来分发的所以你需要一个可用的 Node.js 环境。版本方面我实测下来 Node 18 及以上比较稳妥Node 16 在某些技能文件的依赖解析上会报错。你可以用下面这行命令快速确认node -v npm -v如果版本太低先去 Node 官网下载最新的 LTS 版本装上。这一步看似基础但我见过太多人卡在这里——技能装完了跑不起来排查半天发现是 Node 版本太老。第三是项目目录的权限。superpowers 的技能文件通常会安装在你的项目目录或者全局配置目录下如果你在公司的受限环境里操作可能会遇到写入权限不足的问题。提前确认你对目标目录有读写权限能省掉后面很多麻烦。2.2 安装方式的选择与对比目前 superpowers 的安装主要有两种路径我分别说一下适用场景和实际体验。方式一通过 npm 全局安装。这是最省事的方式一条命令搞定npm install -g superpowers全局安装的好处是技能文件放在统一的位置所有项目都能共享。但缺点也很明显——如果你在不同项目里需要不同版本的技能全局安装就会冲突。而且全局安装的技能文件更新时会影响所有项目有时候你只是想在一个项目里试试新技能结果把其他项目的环境也搞乱了。方式二项目级本地安装。在具体项目的根目录下执行npm install superpowers --save-dev这种方式的好处是技能文件跟着项目走版本可控不会互相干扰。团队协作的时候每个人拉下代码后跑一次安装就能获得一致的技能配置。缺点就是每个新项目都要装一遍稍微麻烦一点。我的建议是如果你只是想在个人项目里体验一下用全局安装快速上手如果是团队项目或者需要长期维护的项目一定用本地安装。这个选择看起来小但后面技能版本升级和团队协作的时候差别会非常明显。安装完成后你可以用下面的命令验证是否安装成功npx superpowers --version如果能看到版本号输出说明基础安装没问题。如果报“command not found”大概率是 npm 的全局 bin 目录没有加到 PATH 里需要手动配置一下。2.3 初始化配置里最容易忽略的三个细节安装只是第一步初始化配置才是决定后面用起来顺不顺手的 key。我总结了三个最容易出问题的地方。第一个是技能目录的路径配置。superpowers 默认会从某个固定目录读取技能文件但不同操作系统和不同安装方式下这个默认路径可能不一样。你需要确认助手实际读取的是哪个目录。最直接的办法是看助手的日志输出通常它会打印出加载技能文件的路径。如果路径不对你写的技能文件放错地方了助手根本读不到。第二个是技能文件的命名规范。技能文件通常有固定的命名格式比如skill-name.skill.md或者类似的约定。命名不规范的文件会被直接忽略而且不会有明显的报错提示。我第一次写自定义技能的时候就犯过这个错——文件内容写得没问题但命名少了个后缀结果助手完全不认排查了快一个小时才发现。第三个是配置文件的编码格式。这个坑比较隐蔽。如果你在 Windows 上用记事本编辑技能文件默认可能会保存成带 BOM 的 UTF-8 格式而某些助手对 BOM 头处理不好会导致技能文件解析失败。建议统一用 VS Code 或者类似的编辑器保存时选择“UTF-8 无 BOM”格式。提示初始化配置完成后先别急着写复杂技能。用一个最简单的测试技能验证整条链路是否通畅——从文件放置、命名、加载到触发全部跑通一遍再去搞复杂的。3. 技能文件的结构与编写逻辑3.1 一个技能文件由哪些部分组成superpowers 的技能文件本质上是一个结构化的 Markdown 文档但它比普通的 Markdown 多了几个关键字段。理解这些字段的作用是写出好用技能的前提。一个典型的技能文件包含以下几个部分元信息区定义技能的名称、描述、触发条件、适用场景等。这部分决定了助手什么时候会调用这个技能。角色定义区告诉助手在执行这个技能时应该扮演什么角色比如“你是一名资深数据库管理员”或者“你是一名前端性能优化专家”。流程说明区这是技能的核心详细描述执行这个任务时的步骤、顺序和每个步骤的注意事项。输出规范区定义助手最终应该输出什么格式的内容包括代码风格、文档结构、注释要求等。边界与禁忌区明确哪些事情不能做哪些情况需要停下来询问用户哪些操作需要额外确认。这五个部分缺一不可。我见过很多人写技能只写了流程说明结果助手执行的时候要么角色定位不对要么输出格式乱七八糟要么在该停下来问的时候自作主张。3.2 触发条件的设计让技能在该出现的时候出现触发条件是技能文件里最需要仔细设计的部分。设计得太宽泛助手会在不相关的场景下乱触发技能设计得太窄该用的时候又用不上。我一般用三个维度来定义触发条件关键词触发当用户的输入中包含特定关键词时触发。比如一个“数据库迁移”技能可以设置当用户提到“migration”“迁移”“schema change”等词时触发。关键词要覆盖常见的表达方式但也不能太泛像“数据库”这种词就太宽了几乎任何数据库相关的对话都会触发。文件类型触发当用户正在操作特定类型的文件时触发。比如一个“React 组件编写”技能可以设置当用户打开或创建.tsx文件时触发。这种方式比关键词更精准因为它结合了上下文。显式调用触发用户通过特定命令或语法主动调用某个技能。比如输入/skill database-migration来手动触发。这种方式最可控适合那些不希望被自动触发的技能。实际使用中我通常会把关键词触发和文件类型触发结合起来用显式调用作为补充。这样既能保证大部分场景下技能自动生效又给了用户手动控制的能力。3.3 流程说明的写法把“老手经验”翻译成步骤流程说明区是技能文件的灵魂。写得好助手就像一个经验丰富的老手在干活写得不好助手就是一个照本宣科的机器人。我的经验是写流程说明的时候要想象你正在带一个刚入行的新人。你会怎么跟他解释这个任务你会先让他做什么再做什么哪些地方你会特别提醒他注意哪些错误你见过太多次一定要提前警告举个例子一个“API 接口编写”技能的流程说明可能是这样的先确认接口的请求方法和路径检查是否与现有接口冲突。定义请求参数和响应结构确保字段命名符合项目的驼峰或下划线约定。编写接口处理逻辑注意错误处理要覆盖参数校验失败、权限不足、资源不存在等常见情况。添加单元测试至少覆盖正常流程和一个异常流程。更新 API 文档确保文档与实际实现一致。每一步都要说清楚“做什么”和“为什么”。比如第 3 步为什么要覆盖那几种错误情况因为这是实际生产环境中最常出现的三类问题提前处理能避免上线后频繁修 bug。3.4 输出规范让每次结果都长一个样输出规范区经常被忽略但它直接决定了助手输出内容的可用性。没有输出规范的技能每次执行结果可能格式都不一样有的用 tab 缩进有的用空格有的写注释有的不写有的把代码放在一个块里有的拆成好几个块。我在输出规范区通常会定义这几样东西代码风格缩进用几个空格、是否使用分号、命名用驼峰还是下划线、注释的语言和格式。文档结构如果需要输出文档定义标题层级、段落长度、是否使用列表、是否使用表格。代码块标注要求助手在输出代码时标注语言类型方便后续处理。长度限制某些场景下需要限制输出长度比如“每个函数的说明不超过三句话”。这些规范看起来琐碎但积累起来对输出质量的提升非常明显。尤其是团队协作的时候统一的输出规范能省掉大量格式调整的时间。4. 在 Codex 中实战使用 superpowers4.1 从零跑通第一个技能理论说了这么多还是得实际跑一遍才有感觉。我拿一个最常用的场景来演示——代码审查技能。假设你已经安装好了 superpowers现在在项目根目录下创建一个技能文件code-review.skill.md。文件内容大致如下--- name: code-review description: 对指定代码进行结构化审查 triggers: - keywords: [review, 审查, 检查代码] - file_types: [.js, .ts, .py, .java] --- # 角色 你是一名有十年经验的资深开发工程师擅长发现代码中的潜在问题。 # 流程 1. 通读代码理解整体逻辑和业务意图。 2. 检查命名规范变量、函数、类名是否清晰且符合项目约定。 3. 检查错误处理是否有未捕获的异常、是否有静默失败的情况。 4. 检查边界条件空值、越界、并发等情况是否处理。 5. 检查性能隐患是否有不必要的循环嵌套、重复计算、内存泄漏风险。 6. 按严重程度分类列出问题阻断性、建议性、参考性。 # 输出规范 - 每个问题标注所在行号。 - 阻断性问题必须给出修复建议。 - 使用 Markdown 表格汇总问题列表。保存文件后在 Codex 里打开一个代码文件输入“帮我审查一下这段代码”助手应该就会自动加载这个技能并按流程执行。如果没触发检查一下技能文件是否放在了正确的目录以及触发关键词是否匹配。第一次跑通的时候我建议你故意在一段代码里埋几个明显的问题——比如一个没处理的空指针、一个命名混乱的变量、一个性能很差的循环——然后看助手能不能全部找出来。这能帮你快速判断技能是否真正生效。4.2 多技能协同让助手按顺序执行多个技能单个技能跑通之后下一步就是让多个技能协同工作。实际开发中一个任务往往需要多个技能配合比如“先审查代码再根据审查结果生成修复方案最后写测试用例”。superpowers 支持技能链的概念你可以在一个技能里引用另一个技能或者通过配置文件定义技能的执行顺序。我通常会在项目根目录下放一个superpowers.config.json里面定义常用技能链{ chains: { full-review: [ code-review, fix-suggestion, test-generation ] } }这样当我说“执行 full-review”的时候助手会依次执行代码审查、修复建议、测试生成三个技能。每个技能的输出会作为下一个技能的输入形成一条完整的工作流。这里有个细节需要注意技能之间的数据传递格式要统一。如果第一个技能输出的是 Markdown 表格第二个技能期望的是 JSON中间就会断掉。我在设计技能链的时候会专门定义一个中间数据格式所有技能都按这个格式输出和解析。4.3 实测中遇到的三个典型问题在实际使用中我遇到过几个比较典型的问题这里分享一下排查思路。问题一技能加载了但不触发。这种情况最常见的原因是触发条件不匹配。排查步骤是先确认技能文件确实被加载了看助手日志然后检查你的输入是否命中了触发关键词或文件类型。有时候是因为关键词写的是英文但你输入的是中文或者反过来。解决办法是在触发条件里同时覆盖中英文表达。问题二技能执行到一半停了。这通常是因为流程说明里某一步的描述不够明确助手不确定该怎么继续。比如你写了“检查代码质量”但没定义“质量”具体指哪些维度助手可能检查了一两项就停了。解决办法是把每一步都拆得足够细细到不需要助手自己做判断。问题三输出格式每次都不一样。这是输出规范区没写清楚导致的。检查你的输出规范是否足够具体——不要写“格式整洁”要写“使用两个空格缩进函数之间空一行每个函数上方写一行注释说明用途”。4.4 性能与效率的实测对比为了直观展示 superpowers 带来的效率提升我拿一个真实项目做了对比测试。任务是给一个已有的 Node.js 项目添加五个新的 API 接口每个接口包含路由、控制器、服务层和测试。对比维度不使用技能使用技能完成时间约 4 小时约 1.5 小时代码规范一致性需要手动调整基本一致测试覆盖率约 60%约 85%返工次数3 次1 次文档同步容易遗漏自动生成这个数据不是精确的 benchmark但趋势很明显。使用技能之后主要节省的时间在格式调整、规范检查和文档编写上。这些工作本身不复杂但很琐碎交给技能去处理之后我可以把精力集中在业务逻辑上。不过也要说清楚superpowers 不是银弹。它擅长的是流程标准化和重复性工作对于需要创造性思考的任务比如架构设计、复杂算法优化技能能提供的帮助有限。你得清楚它的能力边界别指望它什么都能干。5. 自定义技能从使用者变成创造者5.1 什么场景值得写一个自定义技能用了一段时间现成的技能之后你自然会想写自己的技能。但不是什么场景都值得写技能我判断的标准是这个任务是否重复出现且每次的流程基本固定。值得写技能的场景每次新建项目都要做的初始化配置团队约定的代码审查清单特定框架的组件编写规范定期执行的维护任务如依赖更新、日志清理不值得写技能的场景一次性的探索性任务需要大量创造性判断的设计工作流程还在频繁变化、尚未稳定的任务我刚开始的时候犯过一个错——给一个还在频繁调整流程的任务写了技能结果技能文件改得比代码还勤完全得不偿失。后来我学乖了先手动做几次等流程稳定了再固化成技能。5.2 从零写一个技能的完整过程我拿一个实际写过的技能来演示——“新项目初始化”技能。每次启动一个新项目我都要做一系列重复的配置工作正好适合写成技能。第一步梳理流程。我先手动做了三次新项目初始化把每一步都记下来。包括创建目录结构、初始化 package.json、配置 ESLint 和 Prettier、设置 Git hooks、创建基础 README、配置环境变量模板。第二步识别可变部分。有些步骤是固定的比如创建.gitignore有些步骤因项目类型而异比如 React 项目和 Node 后端项目的目录结构不同。可变部分需要用参数来处理。第三步定义参数。我定义了两个参数projectTypereact/node/cli和projectName。技能根据这两个参数决定具体的目录结构和依赖。第四步编写技能文件。把流程翻译成步骤每一步都写清楚“做什么”和“为什么”。比如“创建.gitignore文件排除node_modules、.env、dist目录因为这些是本地环境或构建产物不应该提交到版本库”。第五步测试和迭代。用不同类型的项目跑几遍看技能是否能正确处理各种情况。遇到问题就回去改技能文件直到稳定为止。5.3 技能文件的版本管理与团队共享技能文件写多了之后版本管理就成了问题。我的做法是把技能文件纳入项目的版本控制和代码一起提交。这样有几个好处团队成员拉下代码就自动获得最新的技能配置技能文件的修改有记录可查新成员入职时不需要额外配置。如果是跨项目共享的通用技能我会单独建一个仓库来管理然后通过 npm 包的方式分发。项目里通过npm install your-superpowers-pack来引入更新的时候改一下版本号就行。团队共享技能的时候有个坑要注意不同人的编辑器配置可能不一样。比如有人用两个空格缩进有人用四个。如果技能文件里硬编码了缩进风格在别人那里可能就不适用。解决办法是把这类配置抽成参数或者写清楚“根据项目现有代码风格自动适配”。提示技能文件也要写注释。我见过有人写的技能文件过了一个月自己都看不懂某一步是干什么的。在关键步骤旁边加一行注释说明意图维护成本会低很多。6. 常见误区与进阶思路6.1 把技能当成万能药这是最常见的误区。有些人觉得装了 superpowers 之后AI 助手就应该什么都能干、什么都干得好。实际上技能的作用是约束和引导不是增强能力。助手本身不会因为你写了一个技能就突然变聪明它只是按照你定义的流程去执行而已。如果你的技能流程本身就有问题助手执行出来的结果只会更糟——因为它会严格按照你的错误流程走而且速度更快。所以写技能之前先确保你对这个任务的流程理解是正确的。6.2 技能写得过于复杂另一个极端是把技能写得极其复杂恨不得把整个开发规范都塞进去。结果就是技能文件几百行助手执行的时候经常卡住或者跑偏。我的经验是一个技能只做一件事。如果你发现一个技能需要处理多种差异很大的场景那就拆成多个技能。比如“代码审查”和“代码格式化”应该分开不要写成一个“代码处理”技能。技能的粒度控制在“一个明确的、可独立完成的任务”这个级别比较合适。太粗了不好维护太细了又会导致技能数量爆炸。6.3 忽略技能的维护成本技能文件不是写完就完了它需要维护。项目规范变了、依赖升级了、团队约定调整了技能文件都要跟着改。如果你写了几十个技能但从来不维护它们很快就会变成负担——助手按照过时的流程执行产出反而需要更多时间修正。我的做法是定期审查技能文件大概每个月过一遍把不再适用的删掉把需要更新的改掉。同时给每个技能文件标注最后更新日期和负责人方便追踪。6.4 进阶让技能具备条件分支能力基础的技能是线性的——第一步、第二步、第三步。但实际任务往往需要根据情况走不同的分支。superpowers 支持在技能里写条件判断让助手根据上下文选择不同的执行路径。比如一个“依赖更新”技能可以这样设计先检查当前依赖是否有主版本更新如果有则走“主版本升级流程”包含破坏性变更检查和迁移如果没有则走“常规更新流程”。这样同一个技能就能覆盖不同的情况不需要写两个技能。条件分支的写法通常是在流程说明里用自然语言描述判断条件比如“如果检测到主版本号变化执行以下步骤否则跳过”。助手会根据实际上下文来判断走哪条路。这种写法比硬编码的 if-else 更灵活但也更依赖助手的理解能力需要多测试几遍确保判断准确。6.5 进阶技能与外部工具的联动superpowers 的技能可以调用外部工具和脚本这大大扩展了它的能力边界。比如一个“部署”技能可以在流程中调用构建脚本、运行测试命令、执行部署命令把整个部署流程串起来。实现方式通常是在技能文件里写明需要执行的命令助手会在合适的时机调用。比如# 流程 1. 运行 npm run build 构建生产版本。 2. 运行 npm test 确保所有测试通过。 3. 如果测试失败停止部署并输出失败原因。 4. 运行 npm run deploy 执行部署。这种联动让技能从“建议工具”变成了“执行工具”实用性提升了一个档次。但也要注意安全边界——涉及生产环境操作的技能一定要加上确认步骤避免助手自动执行了不该执行的操作。7. 我个人的一些使用体会折腾 superpowers 这段时间最大的感受是它改变的不是 AI 的能力而是我和 AI 协作的方式。以前我用 AI 助手更像是在“提问-回答”的模式里循环每次都要重新解释背景、重新说明要求。有了技能之后很多重复的解释工作被固化下来了我可以把精力放在真正需要思考的地方。另一个体会是写技能的过程其实是在梳理自己的知识。当你试图把一个任务的流程写清楚的时候你会发现自己对很多细节的理解其实是模糊的。写技能逼着你去把这些模糊的地方搞清楚这个过程本身就很有价值。如果你刚开始接触 superpowers我的建议是从一个小技能开始别一上来就搞大而全的配置。先跑通一个最简单的场景感受一下技能带来的变化然后再逐步扩展。技能文件不用追求完美先能用再用好。最后分享一个我常用的小技巧给每个技能文件加一个“测试用例”部分写清楚在什么输入下应该产生什么输出。这样当你修改技能文件之后可以快速验证改动是否影响了原有行为。这个习惯帮我避免了好几次“改了一个地方坏了另一个地方”的情况。