尧图网页设计 
我研究了一阵子名为 superpowers 的开源项目又结合 Java 开发日常里 Codex 这类终端 AI 辅助编码工具的实际用法来回试了几轮想清楚了一件事superpowers 解决的根本不是“多了一个 AI 插件”的问题而是“怎么让 AI 在终端里干活更像一个靠谱工程师”的问题。它本身是一个配套 Codex CLI 使用的技能包管理工具用 TypeScript 写成通过 npm 分发。核心思路是给终端里的 AI 编码代理叠一层“工作方法层”——先思考、再提问、后规划、拆任务、写约束最后才动手改代码。对于被“AI 直接一顿输出、改完跑不起来、上下文一长就跑偏”折磨过的人来说这层薄薄的 Markdown 技能包价值比再换一个更强的新模型要大得多。这篇文章我会从项目定位、安装配置、技能包架构、完整实操流程到问题排查把这套东西彻底拆开。不管你是刚接触终端 AI 编程的新手还是已经在用 Codex CLI 但觉得它“不够听话”的老手都能从里面找到可以直接抄作业的东西。1. superpowers 项目定位与核心思路拆解1.1 superpowers 到底是什么先直接说结论superpowers 是一套基于 Codex CLI 的技能包体系。它不替代 Codex CLI也不替代任何大模型它的工作在更上面一层——负责“教”AI 编码代理按照一套可靠的工作流程来做事。你通过 npm 全局安装 superpowers 命令之后运行它会得到一个交互式引导流程。引导程序做的事情主要有两件把一系列 Markdown 格式的技能包下载到本地的 Codex 技能目录默认是~/.codex/skills修改 Codex 的配置文件config.toml在instructions里指向额外的约束文档比如AGENTS.md让 Codex 每次启动时都先读到这些“工作守则”。顺着热搜词里出现的 “superpowers java”“codex superpowers” 去实测你会发现它在 Java 项目里的表现尤其有意思技能包里的 “brainstorming”“writing-plans”“creating-task-lists” 都是语言无关的做法但是一旦配合AGENTS.md里写的“先确认构建工具、再明确 Java 版本、改完必须跑测试”这类约束Codex 在 Maven/Gradle 项目里的行为会比裸用稳非常多。1.2 为什么需要一层“工作方法”很多人第一次用 Codex CLI 的体验是在终端里扔一句“给这个项目加个用户登录功能”它噼里啪啦改了一堆文件然后告诉你“完成了”。你跑测试立刻报错你追问它又改了几处再跑下一个错。几个来回之后你已经不确定它到底动了哪些文件也说不清现在的代码是不是比刚才更烂。这不是模型能力不够而是缺少过程约束。就像你让一个很有天赋但没有项目经验的实习生独立干活他确实能写代码但不会先问清楚需求边界、不会列改动清单、不会在动手前确认约束条件、也不会在改完后主动验证。superpowers 的整套设计就是在给这个“实习生”建立一套工作 SOP。它的每个技能包都是一份非常具体的 Markdown 指令告诉 AI 在特定场景下必须按什么顺序思考、必须问哪些问题、必须产出什么中间产物。这套东西不看模型版本的脸色只要你用的模型遵循系统提示词它就能被“约束”住。1.3 核心组件与技术选型解析从代码结构和运行机制上看superpowers 有四个核心组成部分CLI 安装器帮助你完成技能下载、路径配置、config 修改整个过程是交互式的。它考虑到了不同操作系统的默认 shell 差异实测在 zsh 和 bash 下都能正确写入配置。技能包集合每个技能是一个子目录里面有SKILL.md主文件。SKILL.md有 YAML frontmatter名称、描述正文部分用“必须/禁止/建议”这类强指令描述工作流。约束规则文档AGENTS.md这类文件被配置为 Codex 的全局指令规定 AI 的总体行为准则比如“不要不懂装懂”“不要跳过测试”“在不确定时主动提问”。目录约定技能包统一放在 Codex 的 skills 路径下目录名即技能名Codex 启动时会按需加载和匹配相关技能。选型上项目用 Markdown 做技能载体而不是写死在代码里是个很聪明的决定。Markdown 既是人能读懂的文档也是模型最擅长解析的格式。改技能等于改文档不涉及重新编译这让整个系统的可扩展性变得极强。普通开发者完全可以自己写一个“代码审查技能包”或者“数据库迁移技能包”丢进 skills 目录就能生效。2. 环境准备与安装配置实战2.1 前置环境要求在动手安装 superpowers 之前先把环境准备好。这一步踩坑的人不少绝大多数不是因为步骤复杂而是版本没对齐。Node.js 与 npmsuperpowers 是通过 npm 发布的全局命令行工具建议 Node.js 18 以上。我用的是 Node 22 LTS没碰到任何兼容性问题如果还在用 Node 16建议先升级。Codex CLI需要先安装并完成基础配置。Codex CLI 是 OpenAI 开源的终端编码代理npm 安装命令是npm install -g openai/codex。安装后需要配置认证支持 OpenAI API key 或者 ChatGPT 登录两种方式。Git技能下载本质上是把远程仓库 clone 到本地所以 Git 必须可用。这一步容易被忽略有些精简环境里没有装 Git会导致安装器静默失败。2.2 安装 superpowers环境就绪后安装 superpowers 本身非常简单就是在终端里执行一条命令npm install -g superpowers装完后可以确认一下版本和入口superpowers --version正常情况下会输出版本号。如果你在安装过程中看到权限报错说明你的 npm 全局目录需要 sudo 权限或者你的 Node 安装方式有问题。个人建议不要直接sudo npm install -g而是用 nvm 管理 Node这样全局包会安装在当前用户目录下干净又省心。安装完成后在终端里直接运行superpowers它会启动一个交互式指引问你是否要为 Codex CLI 安装技能包集合。选择“是”之后安装器会自动完成三件事在~/.codex/skills目录下创建技能目录结构从远端仓库拉取默认的技能包修改~/.codex/config.toml在instructions部分追加指向AGENTS.md等约束文件的路径。实测下来这个过程的体验相当顺畅整个过程不超过两分钟。唯一需要留意的是如果你的config.toml里已经写了一堆自定义 instructions安装器不是覆盖而是追加这一点做得比较稳妥。2.3 配置文件与技能目录结构安装完之后你一定要自己去看一眼配置文件和技能目录别装完就完事。理解这两处后面的使用逻辑才算真正打通。先看配置文件# ~/.codex/config.toml model gpt-5-codex instructions [ ~/.codex/skills/AGENTS.md, ]instructions数组里指向的AGENTS.md是每次 Codex CLI 启动时都会读取的全局约束文件。它的作用有点像给 AI 在开工前开一次简短会议把“我希望你做事的总体原则”一次性说清楚。再看技能目录~/.codex/skills/ ├── AGENTS.md ├── brainstorming/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md └── creating-task-lists/ └── SKILL.md每个技能包目录下都有SKILL.md。这就是技能的完整定义。Codex 在对话过程中会根据内容匹配到相关技能然后读取对应的SKILL.md来调整自身行为。2.4 验证安装是否真的生效装完配置完别急着直接扔大需求。先做一次快速验证直接在终端启动codex进入交互模式输入一句简单的话“列出当前项目的目录结构并说明你读取了哪些指令文件”观察它是否会提到AGENTS.md和 skills 目录。如果它准确说出了技能包的存在说明配置已经生效。如果它完全没提就要检查config.toml里的instructions路径是否写对、~/.codex目录是否存在。这里有个小技巧Codex CLI 正常启动时如果配置了额外的 instructions 文件它会在启动信息里带出相关行。我遇到过一次配置路径写错的情况——路径里多了一个波浪号没被展开导致文件读取失败Codex 直接忽略了它。解决办法是写绝对路径或者确认 shell 会正确展开~。3. 技能包架构与核心机制详解3.1 SKILL.md 的文件结构与编写规范技能包的核心文件是SKILL.md。我在本地实际打开看过几个内置技能包它的结构非常有代表性几乎每个技能都遵循同一套骨架--- name: brainstorming description: 在动手实现之前通过提问和讨论来澄清需求边界与实现路径 --- # 头脑风暴技能 ## 使用条件 当用户提出一个较复杂的功能需求且需求中存在明显的不确定信息时必须使用本技能。 ## 工作流程 1. 不要直接开始写代码。 2. 先列出你不确定的点逐一向用户提问。 3. 根据用户回答整理出需求描述。 4. 输出一份简短的方案摘要等待用户确认。 ## 禁止事项 - 禁止在信息不足时直接猜测实现细节。 - 禁止在未获得用户确认前修改任何代码文件。看到没有这部分内容是完全可编辑的。frontmatter 里的name和description是给模型做技能匹配用的正文部分则是真正的行为指令。用词都是“必须”“禁止”“禁止”这种强约束表述这是故意的——研究表明明确的禁止性指令比模糊的建议性能更有效地约束模型行为。3.2 内置核心技能逐个拆解3.3 “先问再答”的约束为什么有效 superpowers 技能包：让 Codex CLI 在终端里像靠谱工程师一样干活
我研究了一阵子名为 superpowers 的开源项目又结合 Java 开发日常里 Codex 这类终端 AI 辅助编码工具的实际用法来回试了几轮想清楚了一件事superpowers 解决的根本不是“多了一个 AI 插件”的问题而是“怎么让 AI 在终端里干活更像一个靠谱工程师”的问题。它本身是一个配套 Codex CLI 使用的技能包管理工具用 TypeScript 写成通过 npm 分发。核心思路是给终端里的 AI 编码代理叠一层“工作方法层”——先思考、再提问、后规划、拆任务、写约束最后才动手改代码。对于被“AI 直接一顿输出、改完跑不起来、上下文一长就跑偏”折磨过的人来说这层薄薄的 Markdown 技能包价值比再换一个更强的新模型要大得多。这篇文章我会从项目定位、安装配置、技能包架构、完整实操流程到问题排查把这套东西彻底拆开。不管你是刚接触终端 AI 编程的新手还是已经在用 Codex CLI 但觉得它“不够听话”的老手都能从里面找到可以直接抄作业的东西。1. superpowers 项目定位与核心思路拆解1.1 superpowers 到底是什么先直接说结论superpowers 是一套基于 Codex CLI 的技能包体系。它不替代 Codex CLI也不替代任何大模型它的工作在更上面一层——负责“教”AI 编码代理按照一套可靠的工作流程来做事。你通过 npm 全局安装 superpowers 命令之后运行它会得到一个交互式引导流程。引导程序做的事情主要有两件把一系列 Markdown 格式的技能包下载到本地的 Codex 技能目录默认是~/.codex/skills修改 Codex 的配置文件config.toml在instructions里指向额外的约束文档比如AGENTS.md让 Codex 每次启动时都先读到这些“工作守则”。顺着热搜词里出现的 “superpowers java”“codex superpowers” 去实测你会发现它在 Java 项目里的表现尤其有意思技能包里的 “brainstorming”“writing-plans”“creating-task-lists” 都是语言无关的做法但是一旦配合AGENTS.md里写的“先确认构建工具、再明确 Java 版本、改完必须跑测试”这类约束Codex 在 Maven/Gradle 项目里的行为会比裸用稳非常多。1.2 为什么需要一层“工作方法”很多人第一次用 Codex CLI 的体验是在终端里扔一句“给这个项目加个用户登录功能”它噼里啪啦改了一堆文件然后告诉你“完成了”。你跑测试立刻报错你追问它又改了几处再跑下一个错。几个来回之后你已经不确定它到底动了哪些文件也说不清现在的代码是不是比刚才更烂。这不是模型能力不够而是缺少过程约束。就像你让一个很有天赋但没有项目经验的实习生独立干活他确实能写代码但不会先问清楚需求边界、不会列改动清单、不会在动手前确认约束条件、也不会在改完后主动验证。superpowers 的整套设计就是在给这个“实习生”建立一套工作 SOP。它的每个技能包都是一份非常具体的 Markdown 指令告诉 AI 在特定场景下必须按什么顺序思考、必须问哪些问题、必须产出什么中间产物。这套东西不看模型版本的脸色只要你用的模型遵循系统提示词它就能被“约束”住。1.3 核心组件与技术选型解析从代码结构和运行机制上看superpowers 有四个核心组成部分CLI 安装器帮助你完成技能下载、路径配置、config 修改整个过程是交互式的。它考虑到了不同操作系统的默认 shell 差异实测在 zsh 和 bash 下都能正确写入配置。技能包集合每个技能是一个子目录里面有SKILL.md主文件。SKILL.md有 YAML frontmatter名称、描述正文部分用“必须/禁止/建议”这类强指令描述工作流。约束规则文档AGENTS.md这类文件被配置为 Codex 的全局指令规定 AI 的总体行为准则比如“不要不懂装懂”“不要跳过测试”“在不确定时主动提问”。目录约定技能包统一放在 Codex 的 skills 路径下目录名即技能名Codex 启动时会按需加载和匹配相关技能。选型上项目用 Markdown 做技能载体而不是写死在代码里是个很聪明的决定。Markdown 既是人能读懂的文档也是模型最擅长解析的格式。改技能等于改文档不涉及重新编译这让整个系统的可扩展性变得极强。普通开发者完全可以自己写一个“代码审查技能包”或者“数据库迁移技能包”丢进 skills 目录就能生效。2. 环境准备与安装配置实战2.1 前置环境要求在动手安装 superpowers 之前先把环境准备好。这一步踩坑的人不少绝大多数不是因为步骤复杂而是版本没对齐。Node.js 与 npmsuperpowers 是通过 npm 发布的全局命令行工具建议 Node.js 18 以上。我用的是 Node 22 LTS没碰到任何兼容性问题如果还在用 Node 16建议先升级。Codex CLI需要先安装并完成基础配置。Codex CLI 是 OpenAI 开源的终端编码代理npm 安装命令是npm install -g openai/codex。安装后需要配置认证支持 OpenAI API key 或者 ChatGPT 登录两种方式。Git技能下载本质上是把远程仓库 clone 到本地所以 Git 必须可用。这一步容易被忽略有些精简环境里没有装 Git会导致安装器静默失败。2.2 安装 superpowers环境就绪后安装 superpowers 本身非常简单就是在终端里执行一条命令npm install -g superpowers装完后可以确认一下版本和入口superpowers --version正常情况下会输出版本号。如果你在安装过程中看到权限报错说明你的 npm 全局目录需要 sudo 权限或者你的 Node 安装方式有问题。个人建议不要直接sudo npm install -g而是用 nvm 管理 Node这样全局包会安装在当前用户目录下干净又省心。安装完成后在终端里直接运行superpowers它会启动一个交互式指引问你是否要为 Codex CLI 安装技能包集合。选择“是”之后安装器会自动完成三件事在~/.codex/skills目录下创建技能目录结构从远端仓库拉取默认的技能包修改~/.codex/config.toml在instructions部分追加指向AGENTS.md等约束文件的路径。实测下来这个过程的体验相当顺畅整个过程不超过两分钟。唯一需要留意的是如果你的config.toml里已经写了一堆自定义 instructions安装器不是覆盖而是追加这一点做得比较稳妥。2.3 配置文件与技能目录结构安装完之后你一定要自己去看一眼配置文件和技能目录别装完就完事。理解这两处后面的使用逻辑才算真正打通。先看配置文件# ~/.codex/config.toml model gpt-5-codex instructions [ ~/.codex/skills/AGENTS.md, ]instructions数组里指向的AGENTS.md是每次 Codex CLI 启动时都会读取的全局约束文件。它的作用有点像给 AI 在开工前开一次简短会议把“我希望你做事的总体原则”一次性说清楚。再看技能目录~/.codex/skills/ ├── AGENTS.md ├── brainstorming/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md └── creating-task-lists/ └── SKILL.md每个技能包目录下都有SKILL.md。这就是技能的完整定义。Codex 在对话过程中会根据内容匹配到相关技能然后读取对应的SKILL.md来调整自身行为。2.4 验证安装是否真的生效装完配置完别急着直接扔大需求。先做一次快速验证直接在终端启动codex进入交互模式输入一句简单的话“列出当前项目的目录结构并说明你读取了哪些指令文件”观察它是否会提到AGENTS.md和 skills 目录。如果它准确说出了技能包的存在说明配置已经生效。如果它完全没提就要检查config.toml里的instructions路径是否写对、~/.codex目录是否存在。这里有个小技巧Codex CLI 正常启动时如果配置了额外的 instructions 文件它会在启动信息里带出相关行。我遇到过一次配置路径写错的情况——路径里多了一个波浪号没被展开导致文件读取失败Codex 直接忽略了它。解决办法是写绝对路径或者确认 shell 会正确展开~。3. 技能包架构与核心机制详解3.1 SKILL.md 的文件结构与编写规范技能包的核心文件是SKILL.md。我在本地实际打开看过几个内置技能包它的结构非常有代表性几乎每个技能都遵循同一套骨架--- name: brainstorming description: 在动手实现之前通过提问和讨论来澄清需求边界与实现路径 --- # 头脑风暴技能 ## 使用条件 当用户提出一个较复杂的功能需求且需求中存在明显的不确定信息时必须使用本技能。 ## 工作流程 1. 不要直接开始写代码。 2. 先列出你不确定的点逐一向用户提问。 3. 根据用户回答整理出需求描述。 4. 输出一份简短的方案摘要等待用户确认。 ## 禁止事项 - 禁止在信息不足时直接猜测实现细节。 - 禁止在未获得用户确认前修改任何代码文件。看到没有这部分内容是完全可编辑的。frontmatter 里的name和description是给模型做技能匹配用的正文部分则是真正的行为指令。用词都是“必须”“禁止”“禁止”这种强约束表述这是故意的——研究表明明确的禁止性指令比模糊的建议性能更有效地约束模型行为。3.2 内置核心技能逐个拆解3.3 “先问再答”的约束为什么有效