之前给 Codex CLI 做能力扩展时最常遇到的问题不是模型不够强而是每次换项目、换技术栈都要在提示词里反复交代背景和规范。后来接触到 superpowers 这类技能包项目后我发现真正值得沉淀的并不是某一个现成技能而是一套“把任务标准化、把经验变成文件”的方法。这篇文章就围绕 obra / superpowers 项目整理一份从安装到自定义技能的完整实操指南覆盖环境准备、核心概念、安装配置、排错清单和工程建议。适合正在折腾 Codex CLI 的开发者也适合想建立个人 AI 工作流的同学。1. 背景为什么需要 superpowers 这类技能包1.1 从 AI 编码助手说起Codex CLI 是 OpenAI 推出的命令行编程助手开发者可以直接在终端里通过对话让模型完成代码编写、文件修改、命令执行等任务。相比在网页端提问CLI 的优势在于它天然贴近本地开发环境能读取项目文件、能执行测试、能结合 Git 状态理解当前进度体验上更像是“团队里多了一个能操作终端的协作者”。但随之而来的问题也很明显模型每次对话都是“无状态”的它只看到当前上下文窗口里的内容。如果你希望它按照团队规范写代码、按照指定流程做重构、按照固定模板生成接口就需要在每一次对话里重新解释规则。对于长期维护的项目来说这种重复沟通成本非常高。superpowers 这一类技能包项目就是为了解决这个问题而出现的。1.2 “obra / superpowers” 到底是什么从项目命名来看obra / superpowers 是一个社区维护的 AI 技能包集合。它做的事情可以通俗地理解为把一套经过验证的工作流、提示词、操作步骤和约束条件打包成结构化文件让 Codex CLI 在开始干活之前先加载这些文件从而把“临时提需求”变成“按标准流程执行”。很多开发者把它称为“插件”但从技术实现上看它更接近“技能包skill pack”。它通常由若干 Markdown 文件组成每个文件描述一个具体能力比如代码审查、测试生成、依赖升级、文档撰写、架构分析。Codex CLI 读取这些文件后会按照文件里定义的步骤去执行任务。这里要提醒一点由于“superpowers”这个名字在 AI 编码社区里出现过多个版本网上能搜到不同作者的实现。有些是专门为 Claude Code 设计的有些是兼容多款编程助手的。本文讨论的是如何在 Codex CLI 环境下安装和配置这一类技能包具体仓库以你搜索到的最新版本为准。1.3 适用人群与使用场景如果你属于下面这几类人那这个概念值得你花时间了解长期使用 Codex CLI 或类似工具完成编码任务的开发者。团队里希望统一 AI 编码规范、减少人工提示词维护成本的技术负责人。对“提示词工程”感兴趣想把自己的工作方法沉淀成可复用资产的效率爱好者。正在评估 AI 编程助手落地方式的架构师。典型场景包括新成员加入项目时让 AI 自动遵循团队的代码风格每次发版前自动执行一遍安全检查把“如何新增一个 API 接口”这类重复性任务固化成标准流程让模型按流程执行而不是自由发挥。2. 环境准备与版本说明2.1 基础运行环境在动手之前先确认你的本机环境满足以下条件操作系统macOS、Linux、Windows建议优先使用 macOS 或 LinuxWindows 下需要额外的终端兼容性检查如 Git Bash 或 WSL。运行时由于 Codex CLI 通常基于 Node.js 分发建议提前安装 Node.js 18 或更高版本。如果你不确定自己是否安装了 Node.js可以在终端里执行node -v查看。命令行工具Git用于拉取技能包仓库以及一个你习惯使用的终端模拟器。Codex CLI需要先能正常在终端中运行codex命令。版本方面有一个现实情况这类工具迭代很快不同版本对技能目录的约定可能有差异。本文示例以常见环境为例重点演示配置思路。如果你遇到“配置了但没有生效”的情况优先查阅你当前版本的官方文档不要盲目照搬旧教程。2.2 安装 Codex CLICodex CLI 的安装方式以官方 README 为准。这里给出一种常见的 npm 安装思路具体包名请以最新文档为准# 方式一常见 npm 包名安装 npm install -g codex # 方式二部分版本使用 openai 作用域 # npm install -g openai/codex # 安装后验证 codex --version如果你是用 Homebrew 安装的也可以使用类似命令brew install codex安装完成后先跑一次简单的对话确认 CLI 可以正常连接模型服务codex 请输出 hello world为什么要先做这一步因为后续安装 superpowers 技能包之前我们必须确保基础链路是通的。如果基础命令都无法运行后面排查起来会混入很多无关因素。2.3 准备项目目录技能包的加载通常是以“项目目录”为边界的。每个项目可以在自己的目录下维护一套技能配置避免跨项目污染。我建议按下面的结构规划my-project/ ├── .codex/ │ └── skills/ # 技能目录 │ └── superpowers/ │ ├── SKILL.md │ └── references/ │ └── workflow.md ├── src/ ├── tests/ └── AGENTS.md # 项目指令文件用于告知 Codex 技能目录位置这里需要注意.codex目录是存放 Codex 配置的地方skills子目录用于存放技能包。AGENTS.md是目前很多 CLI 编程工具都会读取的项目指令文件作用是告诉模型“在这个项目里该怎么工作”。不同版本的 Codex CLI 对指令文件的命名可能不一样常见的有AGENTS.md也有一些项目使用.codex/instructions.md。建议以官方文档为准。3. 核心概念拆解superpowers skill 是如何工作的3.1 技能包的本质是“结构化任务说明书”很多人第一次看到技能包时会以为里面是代码插件或二进制程序。其实不是。大部分技能包的核心就是一个或多个结构化的 Markdown 文件它们的作用是给模型提供“如何完成某类任务”的详细说明。你可以把技能包理解为一份写给 AI 看的 SOP标准作业程序。它包含的不只是“做什么”更重要的是“按什么顺序做”“做到什么标准算完成”“遇到异常该怎么处理”。比如一个“Python 代码审查”技能包它可能会规定审查开始前先读取项目中的README.md和pyproject.toml。检查代码时优先关注数据流和错误处理而不是代码格式。每个问题必须标注文件路径和行号。最后按“严重问题 / 建议优化 / 风格提醒”三个级别输出报告。这些规则如果靠每次对话临时输入既容易遗漏又不稳定。把它放进技能包文件后模型每次被触发该技能时都会自动读取并遵守。3.2 一个技能包常见的文件结构不同作者维护的技能包结构会有差异但通常遵循一个通用模式superpowers/ ├── SKILL.md # 技能主入口定义名称、描述、执行步骤 ├── references/ # 参考资料目录存放补充说明 │ ├── workflow.md # 详细工作流说明 │ ├── examples.md # 输入输出示例 │ └── troubleshooting.md # 常见问题处理策略 ├── scripts/ # 可选目录存放辅助脚本 │ └── precheck.py └── assets/ # 可选目录存放模板、图片等资源其中SKILL.md是最核心的文件。模型通常会先读取这个文件判断当前请求是否命中该技能然后按照文件里的步骤执行。一个典型的SKILL.md包含以下部分name技能名称用于识别。description技能描述说明这个技能适合处理什么类型的任务。模型会根据描述判断是否启用。steps具体的执行步骤建议按顺序编号。constraints约束条件比如“禁止修改测试文件”“必须使用绝对路径”等。output_format输出格式要求比如“先给结论再给分析”。3.3 技能加载与执行流程虽然不同工具在底层实现上有区别但一次技能调用大致遵循下面的链路用户向 Codex CLI 发起请求比如“用 superpowers 完成一次依赖安全审查”。模型读取项目指令文件如AGENTS.md发现skills目录中有可用技能包。模型根据请求语义在技能目录中寻找匹配的SKILL.md。如果匹配成功模型会完整读取SKILL.md并将其中的步骤、约束、输出要求作为本次任务的额外上下文。模型按照技能定义逐步执行过程中可以调用终端命令、读取文件、修改文件。执行结束后按技能要求的格式返回结果。这个流程的价值在于技能包相当于给模型加了一层“方法论约束”。没有技能包时模型可能会自由发挥有技能包时模型的工作路径是确定的、可预期的。4. 实战为 Codex CLI 安装 superpowers 插件4.1 获取项目代码既然技能包以文件形式存在第一步自然是把仓库拉取到本地。这里假设你要使用的项目地址是一个 GitHub 仓库具体地址请以你搜索到的最新版本为准。# 进入你的项目目录 cd my-project # 拉取技能包仓库示例地址请替换为实际仓库 git clone https://github.com/obra/superpowers.git .codex/skills/superpowers执行后你的项目目录下会出现完整的技能包文件。先确认关键文件是否存在ls -la .codex/skills/superpowers/正常情况下你应该能看到SKILL.md以及若干子目录。如果你的网络环境无法直接访问 GitHub也可以选择手动下载压缩包解压后移动到相同位置。这一步不涉及复杂逻辑核心目标只有一个把技能文件放到 Codex 能读取的目录下。4.2 将技能目录接入 Codex CLI下载好技能包只是第一步还要让 Codex CLI 知道“这个项目里有技能包可用”。常见做法是在项目根目录创建或修改AGENTS.md文件。下面是一个最小示例# AGENTS.md 本项目使用 Codex CLI 辅助开发。在开始任务前请先检查 .codex/skills/ 目录下的技能包。 - 如果用户请求与 superpowers 相关请先阅读 .codex/skills/superpowers/SKILL.md。 - 严格按照技能文件中定义的步骤执行任务。 - 遇到技能文件中未覆盖的场景请先向用户说明而不是自行猜测。如果你使用的 Codex 版本支持在config.toml中配置额外指令也可以在~/.codex/config.toml中加入类似的引用但更推荐把指令放在项目内这样团队成员拉到代码后也能自动生效。4.3 在会话中验证技能配置完成后启动 Codex CLI试着触发一次技能调用codex 请使用 superpowers 技能检查当前项目的依赖安全性如果技能包加载成功你会看到模型的回答风格明显不同它不再直接给一个笼统结论而是会先描述工作流比如“我将按照依赖审查技能的流程先读取依赖清单再检查已知漏洞库最后输出报告”随后按步骤执行。你也可以直接询问模型当前有哪些可用技能codex 请列出 .codex/skills 目录下所有可用技能并说明每个技能的用途这是一个非常好的验证手段。如果模型能准确列出技能名称和用途说明目录配置已经生效。4.4 查看输出与后续调整技能首次执行完成后不要急着把它当成“配置完事”。你需要检查两件事第一模型是否严格按照技能文件中的步骤执行。如果它跳过了某些关键步骤可能是技能文件的描述不够明确也可能是当前模型版本对长指令的理解能力有限。这时可以简化步骤数量或者把复杂的步骤拆分成多个技能。第二技能的产出是否满足你的预期。比如技能要求“输出至少包含风险等级和修复建议”但实际输出只有风险等级那就说明SKILL.md中的输出格式部分需要写得更具体。技能包不是一锤子买卖它需要在使用中持续迭代。5. 进阶自定义一个自己的 skill5.1 场景与需求安装现成技能包只是开始。真正让 Codex CLI 变得顺手的关键是把你团队里重复性强的任务固化成自己的技能。这里举一个实战例子假设你经常需要新增一个 Python 命令行工具的子命令每次都要经历“创建入口函数、注册参数、写测试、更新 README”这四个步骤。你就可以为这个任务写一个技能包。5.2 编写 SKILL.md 文件首先创建目录结构mkdir -p .codex/skills/python-subcommand/references然后编写SKILL.md--- name: python-subcommand description: 为 Python CLI 工具新增一个子命令的标准流程适用于 argparse / click 风格项目。 --- # 技能目标 在项目中新增一个可用的子命令并保证测试和文档同步更新。 # 执行步骤 1. 读取项目根目录下的入口文件通常为 cli.py 或 main.py理解现有命令注册方式。 2. 根据用户提供的命令名称和参数说明新增子命令函数。 3. 如果项目使用 argparse遵循现有的 add_parser 模式如果使用 click遵循 click.command 装饰器风格。 4. 为新增子命令编写至少两个测试用例覆盖正常调用和参数校验失败场景。 5. 更新 README 中的命令列表补充新命令的用途和示例。 # 约束条件 - 不要修改与本次任务无关的模块。 - 所有新增代码必须遵循项目已有的日志风格。 - 测试文件必须放在 tests 目录下命名以 test_ 开头。 # 输出格式 完成后按以下格式输出 - 新增文件列表 - 修改文件列表 - 测试运行结果 - 使用示例这段配置里最重要的是description字段。模型会通过它判断当前请求是否应该启用该技能所以描述要具体最好包含场景关键词。5.3 引用技能并实测在AGENTS.md中补充一行- 如果用户请求新增子命令请先读取 .codex/skills/python-subcommand/SKILL.md。然后重启 Codex CLI执行codex 给这个 CLI 工具添加一个 status 子命令用来显示当前配置状态观察模型行为。如果技能正常生效你会看到它先读取入口文件再按步骤操作最后输出完整报告。如果它没有按照技能文件流程执行可以尝试在请求中显式提到技能名codex 使用 python-subcommand 技能给这个 CLI 工具添加一个 status 子命令显式指定技能名能大幅提高触发准确率。5.4 迭代思路技能包写完之后建议至少连续使用一周记录以下问题哪些步骤是模型经常忽略的哪些步骤其实不需要写进技能里模型自己就能做哪些环节的输出格式还需要优化根据这些反馈逐步调整技能文件。一个好的技能包应该让模型“照着做就能达到 80 分”而不是“提供了思路但还需要大量人工修正”。6. 常见问题与排查思路6.1 技能没被加载这是最常遇到的问题。表现是模型回复内容很泛完全没有参考技能文件中的步骤。排查思路确认技能文件路径是否正确项目根目录是否在.codex/skills/下。确认AGENTS.md中的引用语句是否明确是否提到了具体的技能文件名。重启 Codex CLI 之后再试因为有些配置读取发生在启动阶段。用“列出可用技能”的方式看模型能不能发现技能包。6.2 安装后提示找不到命令如果你在技能包的scripts/目录里放了辅助脚本但运行时提示找不到命令通常是依赖没有安装或路径问题。解决方案# 给脚本添加执行权限 chmod x .codex/skills/superpowers/scripts/*.py # 或使用绝对路径调用 python3 .codex/skills/superpowers/scripts/precheck.py在技能文件中建议明确写出脚本的启动方式不要只写文件名避免模型默认使用./执行。6.3 生成结果不符合预期如果技能被加载了但输出结果与预期有偏差常见原因是技能文件里的规则不够具体。例如“最后按清单格式输出”就不如“最后输出一个 Markdown 表格包含风险等级、问题描述、文件位置、修复建议”清晰。模型是靠字面含义理解规则的写得越具体执行越稳定。6.4 版本升级后行为变化Codex CLI 或技能包本身升级后可能出现之前可用的技能突然失效。这通常是两类原因指令文件格式变化或者技能文件中引用的 API 接口、命令格式过期。遇到这种情况优先查看官方更新日志同时检查技能文件里是否引用了外部工具链。建议把技能包固定在项目目录内而不是放在全局目录这样版本变更的影响范围可控。下面是一个常见的排查对照表问题现象常见原因解决思路模型无视技能步骤指令文件没有生效检查 AGENTS.md 路径和引用方式技能目录不存在clone 命令未执行成功检查网络与仓库地址脚本无法执行缺少依赖或权限不足安装依赖并添加执行权限输出格式与预期不符技能文件描述不具体细化输出格式要求升级后技能失效接口或配置格式变化查阅更新日志并同步调整7. 最佳实践与工程建议7.1 把高频任务沉淀为技能使用技能包最大的收益不是“让模型多干活”而是“让模型稳定地按你的方式干活”。建议每次发现模型在某类任务上表现不错时把当时的对话、步骤、输出格式整理成一份技能文件保存下来。这个习惯坚持两个月你就会拥有一套个人工作流资产。换项目、换团队时这套资产可以直接复用。7.2 技能文件要保持“小而专”一个常见的误区是把所有规则写进一个巨大的SKILL.md。这样做的后果是模型在处理具体任务时要阅读大量无关内容反而降低执行准确性。更好的做法是一个技能文件只解决一类问题。比如“数据库迁移审查”和“API 生成”分开写而不是放在同一个技能工程下。每个技能文件的步骤尽量控制在 3 到 8 步之间多出来的细节放进references/目录按需读取。7.3 与项目规范绑定而不是全局滥用有些开发者喜欢把技能包装到全局目录这样所有项目都能用。但实际项目中不同项目的技术栈、编码规范、发布流程差异很大全局技能包容易造成“上下文污染”。更稳妥的方案是把技能包放在项目根目录的.codex/skills/下让技能与项目一起版本管理。团队成员拉取代码后自动获得相同的 AI 操作规范。7.4 注意安全与权限边界技能包本质上是给模型提供可执行的指令这就意味着它会影响模型对本地文件系统的操作。使用第三方技能包时先通读一遍SKILL.md和scripts/目录确认没有可疑操作再接入项目。另外在技能文件中可以增加约束比如“禁止删除未纳入版本控制的文件”“禁止直接执行 git push 到远程分支”“所有危险写操作前必须向用户确认”。这些限制能显著降低误操作风险。对于涉及生产环境的任务例如发布、迁移、批量修改务必先在测试环境验证流程并确保技能文件中有回滚策略说明。宁可多一步检查也不要让模型在未确认的情况下执行高风险操作。7.5 持续维护技能版本技能包不是写一次就结束的静态文件。随着项目演进技能中的步骤可能需要调整。建议把技能包纳入 Git 版本管理并提交清晰的 commit message。当模型执行效果出现波动时可以通过 git diff 定位是哪一次改动引起的。8. 总结与实践建议本文围绕 obra / superpowers 这个项目梳理了技能包的核心概念、安装方式、运行原理和自定义方法。你可以把它看作一份“在 Codex CLI 里安装和使用 superpowers 插件”的操作地图也可以把它当成一套“如何为 AI 编码助手沉淀技能”的方法论。很多人在安装完 superpowers 后觉得效果不够惊艳根本原因往往不是技能包本身不行而是没有结合自己的项目做定制。如果你已经装好了技能包我的建议是先不要贪多。选一个最近两周重复出现三次以上的任务类型把它固化成一条技能让 Codex 按你的标准流程执行。技能包的价值不在数量而在于每一次调用都能产出可预期、可验收的结果。下一步你可以研究如何把技能包分享给团队成员以及如何在 CI/CD 流程中复用这些技能文件。把 AI 编码助手从一个“问答工具”变成“懂你规范的工作流引擎”这才是 superpowers 这类项目最有价值的地方。