1. 这个项目究竟在解决什么问题

1.1 从“会用 Codex”到“让 Codex 自动干活”

如果你玩过 Codex CLI，应该有一个很直观的体感：它比在网页对话框里聊天要强，能直接读写你的项目文件，能执行命令，能写 commit。但真拿它做完整功能时，会发现几个特别拧巴的时刻。

比如你让它“给用户模块加一个导出接口”，它会做，但经常只做“最顺手”的那一版：不写单元测试、不补文档、不按你项目里已有的代码风格来。你得多轮追问，它才会把那些你心里早就知道但没说出口的隐性要求补齐。

再比如，团队里的代码规范、目录约定、数据库访问方式、错误码约定，这些知识散布在文档、注释和老同事的脑子里。Codex CLI 能不能用上这些？能，但如果每次开工都靠你把上下文粘进去，不仅累，而且每次都要重新讲一遍。

Superpowers 就是把这些问题摊开来解决的。它不是一个独立的大模型，也不替换 Codex，而是给 Codex CLI 增加了一层“技能 + 插件 + 指令注入”的管理框架。你可以把某个编程任务、某项工程规范、某种代码生成模板写成一个小文件，也就是 SKILL.md，让 Codex 在遇到需要这个技能的场景时自动调用。技能越多，Codex 越像你团队里一位熟悉项目约定的新同事，而不是一个只会答话的终端机器人。

用过这个框架之后，我的使用习惯也被改变了。过去我是“给 Codex 派活”，现在更像是“给 Codex 立规矩、备工具、再让它干活”。不少一起折腾过的朋友也有类似评价：一旦技能体系建立起来，Codex 在完成中大型任务时明显更稳，很少出现“做到一半忘了项目约定”之类的问题。

1.2 为什么我叫它“框架”，不是“插件”

其实你可以简单把 Superpowers 理解成一个“元工具”：它在 Codex CLI 外面套了一层工程方法论。你在项目里安装它，它会扫描项目结构、读取技能文件、生成辅助指令，然后把这些内容整合进 Codex 的启动上下文中。

这句话有两个关键词很关键：

• 扫描：框架会读取你项目根目录下的plugins.txt和 skills 目录，按顺序收集插件路径。
• 整合：加载完后不是直接丢给模型一堆文件，而是生成一份精简的“技能摘要”，让 Codex 知道有哪些技能可用、每个技能的触发条件是什么。

依赖这套机制，Superpowers 做到了普通提示词方案很难做到的三件事：技能可以被复用、可以被版本管理、可以被团队共享。一次写好的技能文件，放到 Git 仓库里，整个团队都能用；换新机器也不需要把一段超长提示重新粘贴一遍。

我用一个类比解释为什么这层封装有价值：直接给 Codex 写提示词就像自己动手做菜，每次口味都随心情走；用技能框架则像把菜谱装订好，放进厨房抽屉，厨师照着翻就行。后者稳定、可传承、可改进，前者一旦菜式多了必然手忙脚乱。

1.3 什么人最该现在上手

这个工具不是只有高级工程师才能用。我实际带过几个不同基础的朋友体验，结论是：只要你能跑通codex命令行，就具备上手 Superpowers 的前提。当然，不同人群的收益点不一样。

• 独立开发者/自由职业者：适合把反复做的“建项目骨架、写 CRUD、写测试”这些事固化成技能，减少重复劳动。
• 中小团队工程师：适合把团队规范装进技能，配合 AI 编码，让 Codex 生成的代码自动符合仓库约定。
• 开源维护者：适合把“提 issue 模板、编译检查、测试命令”这类项目特有流程写成技能，减少与模型来回澄清的时间。
• 编程新手：收益反而最大。新手最怕的是“不知道该怎么给 AI 提要求”。有了技能文件之后，需求被拆成了步骤，AI 按步骤执行，比纯靠对话瞎碰靠谱得多。

我自己日常主要用 Java、TypeScript、Python，在 Java 工程上试了一段时间，后面会专门讲一段实战。你可以把它看作一个“许愿池”，但更准确的说法是：Superpowers 把你在某个技术栈上的一次次成功经验，沉淀成了模型能复用的能力。我愿意把它称为“编程副驾驶的副驾”。

1.4 横向对比：它和纯提示词、AGENTS.md 有什么不同

这里我多说几句，因为很多人问。直接写一大段系统提示让 Codex 遵守，是最简单的思路，但也是最脆弱的思路。提示词是线性文本，一旦项目规范变化，你往往需要整段重写；而且长提示词会挤占上下文，模型很容易在某个角落出现“理解偏差”。

项目里用 AGENTS.md 这类指令文件也不错，可以让 Codex 按加载规则读取仓库说明。但它是静态的说明文件，缺少“技能索引、懒加载、按需触发”这一套机制。Superpowers 做的事情更接近“给指令文件做了工程化”：入口文件收集技能路径，每个技能独立成册，还支持模板和示例关联。

如果用过 Anthropic 生态里的 Skills 机制，你会很容易理解 Superpowers 的设计哲学：两者都强调把大段经验拆成“可复用、可共享、可评分”的最小技能。只是 Superpowers 面向 Codex CLI，并且通过 npm 包的形式提供一套开箱即用的管理命令，上手门槛比纯手工整理要低。

2. 核心机制拆解：技能、插件和指令注入

2.1 SKILL.md 才是真正的“最小单位”

Superpowers 的管理单元不是“整个项目的提示词”，而是一个个独立的小文档，文件名统一叫SKILL.md。每个技能目录都包含这样一个文件，里面用固定格式描述“这个技能是什么、在什么场景用、具体步骤是什么、有哪些要点”。

示例的目录结构大致是这样：

plugins/ java-testing/ SKILL.md examples/ junit5-demo/ rest-api/ SKILL.md templates/ controller.tpl.java

如果一个技能比较复杂，目录下还可以放templates、examples、scripts等子目录。框架在加载技能时，不只是把SKILL.md文本塞给模型，还会把同目录下的模板文件路径、示例代码路径一并列出来，方便 Codex 直接引用真实代码作为参考。

为什么要用SKILL.md而不是一段随便写的*.md？因为技能文件需要结构化。通常它包含 front matter（YAML 格式的元数据）、正文步骤、常见陷阱和验收标准。模型读到元数据后，可以在恰当的时机“按需触发”技能，而不是每个任务都把所有技能内容读一遍。

用一个我自己的视角来理解：这就像给 Codex 一本查阅型的工具手册。手册不会在每页都写“太阳从东边升起”，而是被问到“怎么测试”时，顺手翻开对应章节。

2.2 插件索引和系统提示摘要

技能文件散落在项目里，框架怎么知道该加载哪些？答案是plugins.txt。这个文件是插件索引，相当于“入口清单”。框架初始化时会在项目里生成一个默认的plugins.txt，里面列明了生效的技能目录或插件包。

实际加载过程大致是：

1. 框架读取plugins.txt
2. 逐一读取列出的插件/技能目录
3. 解析每个目录下的SKILL.md
4. 汇总成一份紧凑的、包含技能名与触发语境的摘要
5. 把摘要并入 Codex CLI 会话的初始上下文

最后一步特别关键。Codex CLI 本身支持通过指令文件的方式附加项目说明，Superpowers 并没有去修改 Codex 的代码逻辑，而是巧妙地利用了“指令注入”这个通道。所以它和各版本 CLI 的兼容性普遍比较好，一般不需要改动 CLI 本体。

不过要提醒一句：并非所有技能都应该默认加载。有的技能适合全局（比如“git 提交规范”），有的只适合某个项目（比如“数据库迁移”）。在plugins.txt里按需取舍，是框架使用中最重要的“瘦身”动作。这一点我们留到常见问题部分详细说。

2.3 工作流包：把“套路”变成固定流程

除了单个技能，Superpowers 还支持“工作流包”，你可以理解成一组技能的有序组合。例如我要做一次“新增功能”的开发，可以定义一个工作流包：先读需求文档，再检查既有代码结构，然后生成实现，接着补测试，最后改文档。每个环节都对应独立的技能，整个流程被编排成一条指令链。

工作流包的价值不在于“多一个自动化脚本”，而在于让 Codex 从“走一步看一步”变成“按清单推进”。日常用 Codex 最常犯的错是什么？是它拿到需求就开始写代码，把分析和确认省了。如果技能里明确要求“先列实现计划再动手”，会让产出质量上一个台阶。

实现上，工作流包通常也是以配置文件或技能清单的形式存在。你可以把它放在项目仓库里，跟着分支一起演进。有些团队干脆把工作流包命名为backend-task、frontend-task，让每个人工智能会话都从固定流程开始。

2.4 为什么不干脆去改 Codex 的提示词

每次讲到这里，总有朋友说：我自己写一段很长的提示词，放进指令文件里不行吗？为什么还要装个框架？

我的观点是：当然行，但维护性差很多。

你自己的提示词是“一段”文本，包含的是你此刻能想到的所有经验。等到你发现某个经验不准确、需要修改某个环节，你是在编辑一大段文本，风险很高。技能框架则把这段文本拆成一件件“可独立替换”的零件。你想调整测试规范，就去改java-testing/SKILL.md，不会影响“生成 REST API”这个技能。

另一个原因是“按需加载”。大的系统提示会挤占上下文窗口，而技能框架里的元数据设计，是为了让模型不必每件事都读全量技能，只要知道“存在这个技能、何时触发”即可。没触发之前不展开，触发后再读取对应细节。这种懒加载策略是我认为它优于长提示词方案的核心原因。

2.5 一个容易被忽略的细节：触发条件怎么写

写技能时，很多人只关注步骤写得全不全，却忽略trigger字段。其实触发条件是“技能会不会被梦见”的关键。写得太泛，比如“当我需要写代码时”，那等于没写，所有场景都可能触发，反而让模型拿不准。写得太窄，比如“当用户输入 gerrit 评论链接时触发”，又很难遇到。

一个比较通用的策略是：把触发条件挂在“名词 + 动作”上。生成接口、写单元测试、做数据库迁移、压缩图片、更新依赖版本，都比“开发”“测试”这类词触发更精准。如果你希望技能在特定目录下才生效，可以把路径约束写进去，框架加载时会做一步判断。

我自己的一个技能project-introspection，触发条件写的是“当用户要求开始开发新功能，或要求分析项目结构时”。实际上它只负责读关键配置文件并把约定总结出来，不会继续写业务代码。这个边界划分很重要，否则技能之间容易打架。

3. 安装与初始化：从零跑通，别跳步

3.1 先确认三样东西

在开始安装 Superpowers 之前，我建议先检查环境。别急着复制命令，少一步都可能让你在排查上多花半小时。

• Node.js：Superpowers 基于 Node.js 编写，需要较新版本的 Node，命令行执行node -v确认。
• Codex CLI：它是一层封装，所以底层得有可用的 Codex CLI。用codex --version确认能正常运行。
• Git：不是强制依赖，但技能文件、插件目录都建议用 Git 管理，方便回溯。有git --version最稳妥。

我曾经在 Windows 上帮朋友安装，卡了很久，最后发现是 PowerShell 执行策略限制了npx。如果你在 Windows 上遇到类似问题，可以用终端把执行策略改成 RemoteSigned 试试（仅限你自己信任脚本的情况）。当然，最省心的方案还是直接用 WSL 或 macOS/Linux 环境。

3.2 装包和初始化的标准动作

典型的安装入口是 npm 包。以我记忆中的使用体验为例，大概是这样的步骤：

# 第一步：全局安装 superpowers 命令行工具 npm install -g superpowers # 第二步：在目标项目目录里执行初始化 cd your-project npx superpowers init

初始化命令会在项目里创建一个superpowers/目录，并生成一个plugins.txt索引文件。有些版本还提供了交互式问答，问你“要默认加载哪些初始化技能”，类似脚手架。

我不能保证每个版本的命令完全一致，因为这类工具迭代非常快。更稳妥的做法是：安装后先执行superpowers --help，看当前版本支持的子命令；如果init命令名变了，以帮助信息为准。以前我就在版本升级后照着旧教程敲过别的命令，结果被提示“没有这个子命令”。

3.3 初始化后目录长什么样

初始化完成后，你大概率会得到类似这样的目录结构：

your-project/ plugins.txt superpowers/ installed/ my-skills/ generated-skill-templates/

• installed/：放第三方安装的技能和插件。
• my-skills/：给你自己写自定义技能的地方。
• generated-skill-templates/：框架在创建新技能时自动生成的模板文件。

如果plugins.txt里默认带了一些通用技能，比如 “code-review”、“unit-testing” 之类，先不要急着全删。留一两周，观察哪些真正被 Codex 用到，再决定去留。删太早不利于理解框架的用法，留太久又会把每次会话挤得又长又慢。

提示：不要把整个superpowers/目录无脑提交进 Git。技能本身值得提交，但有些版本会在目录里生成本地缓存文件，建议看下.gitignore是否把缓存排除了。

3.4 验证是否生效

验证这一步不要跳过。最简单的办法是直接在项目里问 Codex CLI 一句话：

codex "用一句话列出你现在可用的技能"

如果系统正确加载，它通常会罗列几个技能名，并按技能描述的触发语境回答。如果你发现它完全不知道技能存在，那就是注入环节出问题了。优先检查plugins.txt内容、路径大小写、以及SKILL.md是否放在了正确位置。

这类工具的版本迭代很快，“安装三步曲”很可能一年里变好几次。写这篇时我只记录通用的动作方法和验证思路，具体命令请以官方仓库 README 为准。理解原理比背命令重要得多——你只要能说出“索引文件、技能目录、注入摘要”这三样东西，换个版本也能自己摸索出来。

3.5 初始化失败时的恢复路径

有时候init执行到一半会因为网络、权限或者旧配置冲突中断。这时候不要慌，更不要反复重跑同一个命令排队确认。通常做法是：先备份现有plugins.txt和superpowers/目录到临时文件夹，再删除项目内生成的superpowers/目录，最后重新执行init。

如果重装后某些技能不生效，多半是旧的本地缓存目录还留在原处。某些版本会把技能缓存写进~/.cache或~/.superpowers这类全局目录，单纯删项目内的superpowers/并不彻底。遇到诡异问题，可以先查全局目录，再决定要不要清理。

这一节的内容虽然零碎，但踩坑现场往往就差这些。安装类工具最怕的不是“装不上”，而是“装上了但不知什么版本、不知改过什么、不知带了多少旧配置”。只要养成“先备份、再看帮助、再验证”的习惯，大多数安装问题都能在十分钟内定位。

4. 实战操作：从写第一个技能到 Java 工程落地

4.1 五分钟写一个“最小技能”

空谈半天不如直接上手。假设你希望 Codex 以后写 Java 接口时，默认都先按你团队的规范来。一个最简技能可以长这样：

--- name: java-rest-controller description: 用于生成符合团队规范的 Spring Boot REST Controller。 trigger: 当用户要求新增 REST 接口或 Controller 时自动触发。 --- ## 步骤 1. 检查 `src/main/java` 里现有 Controller 的包名和命名风格。 2. 使用 `@RestController` 和 `@RequestMapping("/api/v1/<模块名>")`。 3. 返回统一响应体 `ApiResponse<T>`，不要直接返回裸对象。 4. 参数校验用 Jakarta Validation 注解。 ## 常见错误 - 不要使用 `@GetMapping` 处理写操作。 - 不要自定义异常处理散落在各 Controller。 ## 验收标准 - 编译通过。 - 用 `mvn test` 能跑通依赖该接口的集成测试。

把这个文件放到superpowers/my-skills/java-rest-controller/SKILL.md，然后在plugins.txt里追加一行该目录的路径。以后你再让 Codex 生成接口，它有很大概率在动手前先读这个技能。就这一点，已经能让产出风格稳定不少。

我第一次写这种技能时犯过一个错：把步骤写得太详细，足足写了两千字，导致 Codex 在任务里反复引用技能本身，而不是专注去写代码。后来我改成“检查风格、固定写法、验收标准”三点式，效果反而好很多。技能是指导书，不是百科全书。

4.2 Java 项目里的典型使用流程

搜索热词里“superpowers java”排得很靠前，我重点讲讲 Java 场景。常见组合是 Maven 或 Gradle 项目，配 JUnit 5、Spring Boot、MyBatis 或 JPA。

我把一个典型流程拆成三个动作。

动作一：让 Codex 先读懂现有工程

Java 工程结构比脚本项目复杂，模块多、包多、依赖关系隐形。启动会话时，我通常先让 Codex 扫一遍关键文件：

codex "先浏览项目里的 pom.xml、application.yml、entity 和 repository 包，告诉我这个项目的分层约定和数据库访问方式，再开始干活。"

有了 Superpowers 之后，这个动作可以沉淀成一个技能project-introspection，里面写明要读取哪些文件、要关注哪些约定。省得每次对话都重新敲一遍。

动作二：生成 Java 代码时，让技能接管规范

比如我要生成一个用户查询接口，会让 Codex 执行：

codex "用 java-rest-controller 技能新增 GET /api/v1/users/{id} 接口"

实际体验是：它能主动去匹配 Controller 命名风格、返回ApiResponse、给 DTO 加校验注解，甚至会在 repository 层按你团队习惯的方法名生成查询。比技能时代节省了两三轮迭代。

动作三：测试先行，不要事后补

Java 工程里测试很重要，但手工让 Codex 写测试往往写得“很个性”。我会做一个unit-test-junit5技能，里面固定了 JUnit 5 的依赖版本、测试类命名、断言风格。这样生成出来的测试代码在仓库里看起来是“一家人”。

还有个小技巧是让技能里写上“用 Maven/Gradle 测试命令验证”。Java 编译期类型检查能挡掉很多肉眼看不出的错误，让 Codex 每生成一组代码后跑一次测试，能大幅减少垃圾代码和幻觉。

codex "按 unit-test-junit5 技能为 UserService 写单元测试，并执行 mvn -q test 验证全部通过"

4.3 自定义技能的迭代原则

技能不是一次写好的，它会跟着你的项目一起演化。我建议每两周回看一次自己常用的技能文件，问三个问题：

1. 这个技能最近被 Codex 触发过吗？触发频率是多少？
2. 它描述的规范还符合项目现状吗？
3. 有没有因为该技能导致任务跑偏的例子？

如果有技能长期未触发，说明场景不存在，可以删掉或归档。如果技能描述与现实不符，Codex 会被误导，纠错的成本比没有技能还高。技能库和依赖库一样，也是要还技术债的。

4.4 把技能变成团队资产

Superpowers 真正值钱的地方在于共享。你把superpowers/目录提交进项目的 Git 仓库后，团队所有人执行一次同步，就能获得同一套技能。

有些团队还会做更细的事：把“如何提交 bug 单”“如何写变更日志”“前端组件规范”都写成技能。这等于把多年积累的隐性知识，翻译成了模型能读的标准格式。新人加入时，与其看一堆文档，不如让 Codex 在编码过程中自然遵循团队规范。这是我觉得最有长期价值的使用场景。

4.5 一次翻车案例：过度设计技能的代价

给你讲个我真实的翻车经历。有一段时间我在做 Spring Boot 服务，觉得“代码都应该自动生成”，于是写了一个超大的spring-boot-service技能，内含 20 多个步骤，从 Maven 坐标写到 DTO 再到 Dockerfile。结果 Codex 每次生成 service 都要花很长时间“按步骤走”，中间一旦哪一步和现有代码冲突，它就卡在技能里出不来。

后来我把这个庞然大物拆成四个独立技能：gen-controller、gen-service、gen-repository、gen-dockerfile。只有用户明确提到要哪个层，技能才触发。效果立竿见影，生成速度快了，可维护性也高了。

这个案例给我的教训是：技能设计的边界应该对齐“人类工程师用一次操作能完成的粒度”。让 Codex 同时完成十个子任务，不如让它一个接一个地完成三个子任务。技能之间可以有工作流编排，但单个技能要保持专注。

5. 常见问题与避坑实录

5.1 安装和加载问题排查表

我用一张很朴素的表，把遇到的问题、可能原因、处理方式列出来。你可以把它当作排查起点。

遇到“不确定技能有没有被加载”的场合，我会先用一条小请求让 Codex “列出技能名字”，而不是直接上一个复杂的开发任务。这一步很快，能有效区分“框架问题”还是“任务问题”。

5.2 最容易踩的坑：技能写成案例大全

很多朋友说某段技能没用，拿过来一看，写得跟论文似的：背景、原理、N 个示例、十几种边界情况。问题是 Codex 不是人，它读上下文时会试图把每个细节都“合理解释”，技能太长反而容易带偏。

最佳实践是控制每个SKILL.md在几十到一百行以内。把核心步骤放在最前面，把示例压缩成关键代码片段，把“常见错误”用两三行写完。如果某个技能确实复杂，就拆成多个技能，在工作流包层面串起来。

5.3 版本更新带来的破坏性变更

Superpowers 迭代快，升级 npm 包之后，原有配置可能不兼容：比如某个插件目录名改了、某个字段失效了。解决办法其实就三条：

1. 升级前先备份plugins.txt和整个superpowers/目录。
2. 升级后用superpowers --help对比新命令。
3. 如果升级后初始化出问题，别犹豫，回滚到上一个版本先干活。

我见过太多人升级翻车后继续硬撑，浪费一上午。工具是拿来用的，不是拿来追新的。稳定比新鲜重要。

5.4 上下文窗口的用量控制

Codex CLI 在单次会话里能容纳很多内容，但上下文并不是免费的。技能摘要、项目扫描结果、代码历史都会挤占空间。常用做法是只加载与当前任务相关的技能：做后端任务，就不加载前端技能；做数据迁移，就先把“代码审查”技能摘除。

另一个技巧是给技能设置精准的触发条件。只有当触发词出现在需求里时，模型才会去读取技能的完整内容，否则它只知道“有这个技能”。触发词要写得具体一些，比如“补测试”优于“测试”，“生成接口”优于“开发”。这样既能享受技能的好处，又能避免每次都全文加载。

5.5 团队协作时怎么避免技能互踩

团队一旦共享技能库，就会出现“你的规范”和“我的规范”打架的情况。比如有人写了一条“生成 Controller 用 Lombok”，另一个人写了一条“避免使用 Lombok”。Codex 读到两个冲突技能时，行为就会变得不可预测。

我的建议是：技能文件里加一栏“适用范围”，明确写清楚“仅用于 xxx 模块”或“仅用于 xxx 分支”。还可以指定优先级字段。更重要的是，团队把技能库当成普通代码库来评审，谁来合并、谁负责清理废弃技能，都要有明确归属。没人维护的技能库，过三个月就会变成一锅粥。

6. 一点个人实操心得与扩展方向

最后再分享几个我自己的判断，供你参考。

先说结论：合理利用 Superpowers，不用一上来就把一百个技能装齐。我见过一个朋友第一天就把官方技能库装了大半，结果 Codex 每次回答都像在背技能清单，好几回偏离正题。正确姿势是先从自己最难受的那两三个重复场景入手，运行一周，把技能从“能用”调到“好用”，再慢慢扩展。我自己的技能库到现在也就十几个，其中高频使用的可能不到五个，但已经覆盖了大部分日常编码场景。

在 Java 工程上，这些技能叠加的效果比较明显。因为 Java 代码风格更容易标准化，团队约定也多，模型一旦掌握了约定，生成质量会稳定许多。相比之下，在自由风格的脚本项目里，技能的收益更多体现在“别忘测试和文档”这种过程性约束上。

我一直觉得 Superpowers 最有潜力的方向不是“让 AI 更聪明”，而是“让团队的共同经验进入 AI 的默认行为”。你可以把一个格式化工具、一段领域建模规范、一套测试覆盖要求都变成技能。AI 越能理解你的上下文，就越能成为真正意义上的团队一员。

如果你刚接触这个工具，我建议在下一个项目里挑一个最简单的任务，比如“生成一个符合项目风格的 Controller”或“按固定模板画一个 issue”，写出第一个技能，然后让 Codex 试跑。跑通之后，你会发现自己对“给工具引入一套使用框架”这件事的理解，彻底不一样了。它的价值不在“魔法”，而在把经验结构化的过程里。这个动作本身，就是你和 AI 协作方式的一次升级。