用了几个月 Codex CLI 之后我最大的感受是AI 编程助手在一对一对话里确实很强但你每次打开一个新会话它对你的项目、你的偏好、你踩过的坑一无所知。同样的技术方案、同样的代码规范、同样的排查路径你都得重新描述一遍。后来我找到了 Superpowers 这个项目用了一段时间之后基本上把这个问题解决了。这篇文章就围绕 Superpowers 的完整思路、安装方式、工作原理和实际玩法做个拆解希望能帮到正在被“每次从头教 AI”折磨的人。Superpowers 是 Codex CLI 生态里的技能扩展框架。什么叫“技能”说白了就是把 AI 执行任务时需要的工作流、约束条件、示例和检查清单固化成一个可复用的文件。你可以把它理解成给 AI 装了一个“岗位说明书”它按照说明书一步步干活而不是每次凭感觉自由发挥。这个东西尤其适合两类人一类是重度使用 AI 做代码开发的工程师另一类是想把团队经验沉淀成标准化流程的团队负责人。前者能省掉大量重复沟通时间后者能把隐形的经验显性化。这篇文章不会只停留在“推荐你装个工具”的层面我会从为什么需要技能化、怎么安装、技能目录和文件结构长什么样、到如何写一个自己的技能、以及实际使用中遇到的坑一次性讲透。1. 思路拆解Superpowers 到底做对了什么1.1 从“每次重新解释”到“一次定义到处复用”先用一个场景来感受一下痛点。你在项目里有一套自己的代码风格接口返回用统一包装类、异常必须抛业务异常、数据库操作全部走 Repository 层。代码评审的时候你每次都要跟 AI 说明这些规则AI 也每次都要现学现卖。最难受的是如果某次对话里 AI 没理解透它会写出风格完全不一致的代码你又得花时间去改。Superpowers 的思路就是把这类“背景知识”抽出来。你只需要在一次对话里完整地教 AI 一遍然后把教的内容落盘成技能文件之后每个新会话都能自动加载。这个思路其实和人类带新人很像正常团队不会让每个新人都重新发明一套编码规范而是给他一份文档、让他照着执行。Superpowers 就是给 AI 准备的那份文档。1.2 和“Prompt 模板”的本质差异有人可能会说这不就是 Prompt 模板吗我提前准备一段很长的 Prompt每次复制进去不也一样理念上有相似点但实现机制差别很大。Prompt 模板的问题是它完全依赖你把内容贴进上下文里。你贴得越多上下文窗口被占得越满真正重要的代码内容反而被挤到后面。而且模板一旦超过一定长度模型对细节的遵循度会显著下降。Superpowers 的做法则不同它不是把技能文件一股脑塞进对话而是通过对当前任务的自动匹配只把“和当前任务相关”的技能内容加载进来。相当于你先建了一个技能库AI 判断什么时候该用哪条技能再把自己需要的部分拿出来看。这就带来了两个好处。第一上下文使用效率高不会为了一个无关紧要的规范浪费大量 token。第二技能的覆盖面可以非常大你甚至可以同时存在几十个技能文件AI 不会因为文件太多而“记不住”。它还支持技能之间的依赖和复用这部分后面细讲。1.3 一个容易理解的生活化类比如果不用开发术语可以把 Superpowers 理解成“菜谱 厨师”。没有菜谱的时候你每次跟厨师说“做一道拿手的鱼”全凭厨师当时的临场发挥有了菜谱之后厨师严格按照材料清单、腌制时间、火候要求来做味道稳定而且你可以同时准备十几道菜的菜谱厨师会自己判断今晚该做哪道。日常沟通时你永远不会把菜谱全文背给厨师听你只需要说“今晚做鱼”厨师自己去翻菜谱。Superpowers 就是那本菜谱Codex CLI 就是那个厨师。这个类比基本和它的工作方式一一对应。2. 安装与上手30 分钟跑通第一个技能2.1 前置条件先装好 Codex CLI 环境Superpowers 不是独立运行的命令行工具它本质上是一个作用于 Codex CLI 的扩展。所以第一步必须是先把 Codex CLI 装好并且能正常使用。如果你已经装了可以跳过这一小节。安装 Codex CLI 非常简单macOS 或者 Linux 环境下我推荐直接用 npm 全局安装npm install -g openai/codex装完以后在终端输入codex --version验证一下。如果能看到版本号说明基本环境已经就绪。接着用codex login完成身份认证这一步会要求在浏览器里确认一次授权整个过程很快。Windows 环境我建议优先考虑 WSL因为很多技能里的 shell 操作在 WSL 里跑得更顺。直接在 PowerShell 里跑会出现各种路径分隔符和权限上的小问题不是不可以但体验确实不如 Unix 环境。2.2 获取 Superpowers 本体获取方式要看你用的 Codex CLI 版本。比较新的版本支持插件机制可以通过命令直接安装codex plugins install superpowers如果你用的是较早的版本或者命令执行失败那大概率是插件机制还没开。备选办法是把仓库克隆到本地再在 Codex 的配置文件里声明路径。以最常见的路径为例git clone https://github.com/obra/superpowers.git ~/.codex/plugins/superpowers克隆完成之后编辑 Codex 的配置文件通常在~/.codex/config.toml把插件目录加进去。不同版本配置项的名字略有区别常见的是plugin或者plugin_path。我自己在实操中遇到过明明克隆了但 Codex 没加载的情况最后发现就是配置文件的路径写错了细节。建议加完配置之后先跑一条最简单的命令试一下codex skills list如果这条命令能列出技能列表说明加载成功。执行之前记得先codex login因为大部分功能都要求先完成认证。2.3 验证技能是否生效装好之后建议先验证一个内置功能最快的方式是建一个临时测试文件夹在里面丢一个小需求进去mkdir /tmp/superpowers-test cd /tmp/superpowers-test echo 请实现一个计算斐波那契数列的 Python 函数并附带简单的单元测试 task.txt codex task.txt跑完之后观察 Codex 的思考过程。如果它自动引用了某个技能比如列出了# Reading skill X这类日志就说明技能加载链路是通的。我第一次跑的时候没有任何技能加载日志后来排查发现是本地 Codex 版本太老不支持技能协议升级之后才恢复正常。2.4 内置技能的初步体验Superpowers 自带了一批开箱即用的技能强烈建议每个都翻一遍。举几个我实际用下来觉得价值很高的code-review规范代码审查流程列检查清单按严重程度分级输出问题。project-bootstrap从零搭项目结构时用能自动生成目录布局、基础配置、README 框架。technical-spec把模糊需求变成技术方案文档包含上下文分析、方案比较、风险点。write-python-module/write-react-component按团队既定模式生成模块代码。建议的第一个动作不是急着写技能而是先把内置技能都过一遍了解它能干什么不能干什么。这样你在规划自己的技能体系时能做到不重复建设。3. 工作原理技能文件到底是怎么被“执行”的3.1 技能的目录结构Superpowers 的所有技能都以文件夹形式组织。在技能仓库根目录下通常能看到这种布局skills/ code-review/ SKILL.md scripts/ analyze.sh examples/ review-sample.md write-react-component/ SKILL.md templates/ component.tsx.tpl每个技能文件夹里SKILL.md是核心入口它告诉 Codex 这个技能是干什么的、什么时候该用、具体怎么执行。剩下的子目录用于存放辅助资源比如脚本、模板、示例输出。注意技能目录名必须是英文小写加连字符的格式不要用中文或空格否则自动匹配阶段可能出问题。3.2 SKILL.md 的内容规范SKILL.md本质上是一个 Markdown 文件但它的头部有一段 YAML 元信息这段信息是 Codex 做技能匹配的关键依据。一个精简但完整的示例--- name: code-review description: 对代码变更进行系统性审查输出结构化问题清单和修改建议。 when_to_use: 在获取到 diff 或需要审查 pull request 时使用。 --- # Code Review 技能 ## 执行流程 1. 先通读全部变更识别改动范围和核心意图。 2. 检查命名、结构、异常处理是否符合项目规范。 3. 识别潜在性能问题和安全隐患。 4. 输出结构化报告包含问题等级、影响范围、修改建议。 ## 输出格式 - 按 Critical / Major / Minor 三级分类。 - 每条问题附代码位置和修改建议。 - 报告末尾附整体评估意见。 ## 禁忌 - 不要只罗列问题必须给出可操作的修复建议。 - 不要在未确认项目规范的情况下断言“不符合规范”。这里的description和when_to_use是自动匹配的关键。Codex 会在每轮任务开始时比对当前需求与所有技能的元信息挑出匹配度最高的一项或几项。所以这两段的写法非常讲究要写清楚“什么时候用”而不是写一堆“它能做什么”。同一件事用两种说法匹配效果差异很大。3.3 技能的执行编排当一个技能被选中后Codex 并不是把整个 SKILL.md 丢进上下文然后期待模型照着做。它的实际行为更像是一个指令序列——模型读取流程步骤然后逐步执行。步骤里可以引用脚本、读取模板、或者标注一些需要向用户确认的检查点。某些复杂技能还会依赖其他技能例如一个“发布上线”技能里包含“跑测试”和“写变更记录”两个子技能这种依赖关系在文件头部声明即可。这种编排方式的优势在复杂任务里体现得特别明显。比如用technical-spec技能写技术方案它会先用inspect-project检查现有目录结构再用generate-report生成方案骨架最后要求你确认几个关键决策点。整个过程像流水线而不是让 AI 一口气输出——中间任何一步跑偏都很容易纠正。3.4 写一个最简技能的全过程写技能比大多数人想象中简单。我自己写的第一个技能是“生成 git commit message”大约花了十几分钟。步骤大概是这样先建目录和文件mkdir -p ~/.codex/skills/write-commit-message touch ~/.codex/skills/write-commit-message/SKILL.md然后编辑 SKILL.md--- name: write-commit-message description: 根据 git diff 生成符合 Conventional Commits 规范的提交信息。 when_to_use: 当用户要求生成 commit message 或者代码提交信息时。 --- # Commit Message 生成 ## 规则 1. 先运行 git diff --staged 获取待提交内容。 2. 按 Conventional Commits 格式生成消息。 3. 类型说明必须具体不要使用模糊的 update/fix 类表述。 ## 示例 - feat: 新增项目成员列表接口 - fix: 修复订单金额计算精度丢失问题 ## 注意事项 - 如果变更涉及破坏性修改在 commit message 中标注 BREAKING CHANGE。写好之后在当前项目里让 Codex 帮忙提交一次代码如果消息格式符合预期说明技能生效了。整个过程不需要懂编程只要会写 Markdown 就能上手。4. 实战案例三个我每天都在用的技能方案4.1 团队项目中的代码风格守门员这个技能解决的是“AI 写的代码风格不一致”的问题。把团队的编码规范固化成技能之后AI 生成的代码天然符合团队风格代码评审阶段省了大量口水。我通常这样设计--- name: team-csharp-style description: 生成符合团队 C# 编码规范的代码。 when_to_use: 当需要编写或修改 C# 代码时。 --- # 团队编码规范 - 类型命名使用 PascalCase。 - 私有字段使用 _camelCase 前缀。 - 异步方法使用 Async 后缀且必须返回 Task 或 TaskT。 - 禁止使用 var 声明具体返回值类型。 - 构造函数中禁止包含业务逻辑。 - 所有对外公开的方法必须包含 XML 文档注释。实测效果很稳定。团队里不同成员用 Codex 写出的代码风格上不会出现“一眼看出不是同一个人写的”情况。这里需要给一个提醒技能文件描述越具体越容易执行如果你只说“代码风格整洁”AI 依然会乱来。把规则一条条列出来效果立竿见影。4.2 需求到技术方案的自动拆解我还写了一个“需求澄清”技能专门应对那种“给了个模糊需求让 AI 直接写代码”的场景。以前我直接说“帮我做一个用户登录功能”AI 会立刻开写写出来的东西往往跑偏。现在技能会先进入澄清阶段要求你选场景、定技术栈、列边界条件。技能设计成多轮对话的形式核心思路是--- name: requirement-clarify description: 把模糊需求逐步拆解成可执行的任务列表。 when_to_use: 用户提出需求但缺乏关键约束信息时。 --- # 需求澄清流程 1. 向用户确认技术栈和运行环境。 2. 询问核心功能边界明确哪些功能不做。 3. 识别异常流程和边界条件输出风险点。 4. 将需求拆解为任务列表标注依赖关系。 5. 用户确认后按任务列表逐步实现。这个技能的执行结果不只是一段代码而是一个完整的计划。因为有边界确认环节AI 踩空预期的情况大幅减少。尤其适合那种项目需求天然模糊、需要逐步访谈澄清的中小型团队。4.3 让 AI 按规范做单元测试单元测试生成是很多人觉得“鸡肋”的场景——AI 生成的测试要么测不到关键逻辑要么全是 Mock 堆砌。把这个过程技能化之后质量改善非常明显。我的技能文件里明确要求先找到被测函数的源码读懂实现逻辑。列出已有依赖找出必须 Mock 的边界。先写正常路径测试再写边界测试和异常路径测试。每个测试用例必须断言真实行为不能只断言 Mock 被调用。这里可以分享一下我在实操中发现的规律技能执行效果的好坏和你写的检查顺序有强关联。如果你让 AI 先写测试再看代码它按错误前提写出来的测试通常废掉大半。我调整成“先读实现再列场景最后写测试”之后生成用例的有效率显著上升。5. 常见问题与排查指南5.1 你可能遇到的几个典型故障技能机制用起来不难但细节问题确实不少。把我自己踩过的坑整理成一张速查表现象可能原因解决办法Codex 完全没加载技能插件路径配置错误或版本过旧升级 Codex检查config.toml里的路径技能列表能看但从不自动触发description写得太虚匹配不上改写when_to_use加入动词和场景词技能加载了但步骤执行不完整SKILL.md 里流程太长上下文被挤掉拆成多个小技能或把细节放到引用文件里技能修改后行为没变化Codex 缓存了旧技能内容重启会话或清理缓存目录技能之间互相干扰多个技能被同时激活规则冲突在when_to_use中限定互斥条件某些技能在 Windows 上失败脚本使用了 Unix 专属命令改用 WSL或为脚本提供兼容层5.2 调试技能的关键方法看日志如果发现技能没生效或者行为诡异第一件事不是重写文件而是看 Codex 的调试日志。大部分版本支持这个参数启动codex --debug在调试模式下你能看到技能匹配的过程、加载了哪些文件、最终采用了哪些指令。这个信息至关重要。我遇到过一种情况技能文件本身写得很完整但在日志中发现 Codex 把它判断为“不相关”连加载都没加载。问题就出在description字段的关键词匹配上。调整描述之后立刻就能解决。5.3 技能设计的上限与边界有一点必须提醒技能不是魔法它不能超出模型本身的能力上限。如果你的技能要求 AI“理解所有业务遗留代码后重构为微服务架构”它做不到就是做不到这不是技能的问题。技能的价值在于让 AI在有能力执行的任务上执行得更稳定、更规范而不是凭空提升它的推理能力。另外技能文件并不是越多越好。技能库超过一两百个之后自动匹配的准确率会下降因为候选太多选择的噪音变大。这时候宁可把相近的技能合并或者给技能分目录、增加更多触发约束条件。我现在的习惯是同类技能只保留一个最优版本定期清理不再使用的旧技能。5.4 避免编写“伪技能”最常见的误区见过不少朋友第一次写技能时写得跟博客文章一样大段的背景介绍、愿景描述、技术选型理由。这种文件对 Codex 没有意义。技能文件必须是可执行、可验证的指令集合。每个步骤最好对应一种可观察的输出每个输出最好有检查标准。写技能的本质是写一个单元测试——你要能明确判断“这个技能是否被正确执行了”。判断一个技能写得好不好我一般会用三个标准快速自测第一一个完全不熟悉该领域的人或 AI能否照着执行第二能否在 15 分钟内验证一次输出效果第三如果错过了某个步骤结果是否可感知。三条都满足技能的可用性基本就没问题了。我个人在使用了很长一段时间后的体会是Superpowers 最大的价值不是某一个技能写得多漂亮而是它改变了人和 AI 协作的方式。过去我们把 AI 当一个懂很多但“没记性”的工具每次都从头对齐上下文现在更像是给团队里的新成员准备了一本详细的工作手册它按手册执行你只负责审核结果和修订规则。顺着这个思路技能库会随项目演进慢慢长成团队知识库沉淀下来的每条规则都是实际踩过坑后提炼出来的。如果你已经重度依赖 Codex CLI这个项目值得花一个下午认真试一遍。