如果你最近在折腾 Codex CLI 或者 Claude Code大概率会频繁刷到 superpowers 这个词。它不是什么超级英雄电影也不是某个游戏 Mod而是一套给终端里的 AI 编程助手“叠 buff”的技能库——准确说是一组按特定格式组织的 skills 集合能让 Claude Code、Codex CLI 这类 Coding Agent 在项目里表现出远超默认配置的能力。我第一次看到这个项目时也以为是营销噱头但实际用下来发现它解决的是一个非常真实的痛点默认的代码助手只会“被动回答”而 superpowers 提供了一套机制让它学会“主动干活”——比如批量重构前先做影响面分析、写测试前先列断言清单、修 Bug 前先复现现场。这篇文章我会从项目设计思路、安装配置、与 Codex 的集成实操到自定义技能和 Java 项目里的具体用法完整过一遍。不管你是刚接触 CLI Agent 的新手还是已经在日常开发里深度使用 AI 编程助手的从业者应该都能从这里拿到可以直接抄作业的东西。1. 项目核心思路为什么需要一套“技能库”而不是更好的 Prompt1.1 从“问答式助手”到“流程式协作者”默认情况下你在终端里启动 Codex CLI 或 Claude Code它本质上是一个“高级问答机器人”你给它一个任务它根据上下文生成代码、执行命令、返回结果。听起来很美好但实际用两周就会发现瓶颈——它缺少“工作方法”。举个例子你让它“给这个支付模块补几个边界测试”它会真的去写测试但不会先问你“支付状态机有哪些分支”也不会主动检查覆盖率报告更不会在写完以后跑一遍变异测试。这不是模型能力不行而是它缺少一套“怎么拆解任务、按什么顺序执行、什么时候该停下来问人”的流程约束。superpowers 的核心思路就是把这些“优秀工程师的工作方法”固化成可复用的技能文件。每个技能是一个带结构化元数据的 Markdown 文档告诉模型你是谁、你负责解决哪类问题、你在什么情况下启动、你执行时的标准动作是什么。模型在对话开始时会扫描这些技能清单根据用户请求的意图匹配最合适的技能然后按照技能里写的步骤一步步执行。这就像给一个很有天赋但没什么经验的新人配了一本《团队工作手册》他不需要每次都在脑子里重新发明做事方法直接照着手册执行就行。1.2 为什么选“文本规则 目录约定”而不是插件 SDK市面上也有不少 AI 编程插件走的是“深度集成 IDE API”的路线比如直接注册代码补全事件、读取编译错误流。superpowers 选了一条完全相反的路它只依赖两个基础机制——约定目录和 Markdown 文件。技能就是文档文档就是代码。这样设计的好处极其明显第一跨工具通用。写好的技能文件Claude Code 能读Codex CLI 也能读未来任何支持自定义指令的 Agent 工具大概率都能用同一套格式。你不用为每个工具重写一套技能投资一次长期复用。第二可审阅、可版本管理。技能文件就是纯文本放在 Git 仓库里代码评审时直接看改动就行。团队成员能清清楚楚看到“为什么模型这次表现变好了”因为就是有人给某个技能增加了两个步骤。这比黑盒的插件系统透明得多也更符合工程团队的协作习惯。第三迭代门槛低。改一个技能文件之后重新加载即可不需要编译、不需要重启服务、不需要发布插件包。我经常在项目里临时写一个“针对本项目特殊日志格式的排障流程”技能用两天觉得不好用就直接改或删试错成本几乎为零。1.3 superpowers 的边界它不替代模型而是约束模型这里有个容易误解的点superpowers 不会增强模型的推理能力它改变的是模型的“输出策略”。模型该会的还是会不会的还是不会但它会更规范地调用自己会的东西。比如模型本来就能执行grep、find、git log但没有 superpowers 时它可能跳过排查直接生成猜测性代码有了系统设计System Design技能约束后它会老老实实先做代码定位、再查调用链、然后才改代码。换句话说这套技能库教模型“在动手前先建立上下文在改代码前先写验证计划”。2. 安装配置全解析目录结构、环境和第一跑通2.1 获取项目与一键安装脚本做了什么安装 superpowers 非常简单克隆仓库然后跑安装脚本git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本会做的事主要有三件。第一把技能文件复制或建立软链接到当前用户的家目录下常见位置是~/.claude/skills/和~/.codex/skills/。第二检查当前是否安装了 Claude Code 或 Codex CLI如果缺少会提示你补齐。第三生成一份 README 风格的技能清单索引方便你后续自己查阅。如果你是在团队项目里用不建议直接跑全局安装更推荐把技能库放进项目仓库的.claude/skills/和.codex/skills/目录下。这样所有 clone 这个仓库的成员都能用同一套技能不同项目还能用各自定制的技能集合。我实测下来项目级技能目录的优先级高于全局目录也就是说同一个技能名项目里的版本会覆盖全局版本——这个机制非常适合在不同项目里微调团队规范。2.2 核心目录与文件格式SKILL.md 究竟长什么样技能文件的核心就是一个 Markdown 文件文件名随意但目录名就是技能名文件本身统一叫SKILL.md。目录里还可以放参考资料、模板、脚本等附件模型在执行技能时能按需读取附件内容。一个典型技能目录结构如下~/.claude/skills/ ├── plan-architecture/ │ └── SKILL.md ├── system-design/ │ ├── SKILL.md │ └── templates/ │ └── design-doc.md ├── bug-hunting/ │ ├── SKILL.md │ └── examples/ │ └── regression-analysis.md └── maven-debug/ ├── SKILL.md └── scripts/ └── analyze-build-log.pySKILL.md 的正文必须带 YAML frontmatter至少包含name和description两个字段。name是技能标识description最关键因为模型就是靠读这个字段来判断“当前任务要不要唤起这个技能”的。描述写得越具体、越覆盖触发场景技能被正确唤起的概率就越高。正文部分则是步骤式的工作流可以是“先做 A再做 B最后用 C 验证”也可以直接给模板和检查清单。2.3 第一次实操从加载到确认技能生效安装完以后怎么验证技能真的被模型读到了最简单的方法是在交互式终端里直接问一句“你现在加载了哪些技能”如果模型能列出 skill 清单说明加载正常。如果它只回复“我没找到任何技能”优先检查路径当前版本的工具通常只认~/.claude/skills/、~/.config/claude/skills/、.claude/skills/这几个位置装完以后建议先用ls确认文件确实落到了对的地方。另外一个细节技能文件的目录名建议不要带空格别用中文命名。虽然理论上模型能理解中文目录名但真实测试中我发现带空格或特殊字符的目录名偶尔会导致技能无法被索引到。用kebab-case命名最稳比如system-design、bug-hunting、maven-debug。3. 与 Codex CLI 的组合配置文件、上下文构建与技能唤起机制3.1 Codex 下如何让技能生效AGENTS.md 与技能双通道Codex CLI 与 Claude Code 的技能机制不完全一致。Claude Code 有原生 skills 支持直接在配置里指定即可而 Codex 的较早版本主要依靠AGENTS.md文件来注入项目级指令如果想让技能文件在 Codex 里同样生效最直接的做法是在项目根目录的AGENTS.md中增加一段“技能使用指南”把~/.codex/skills/下有哪些技能、各自用途、何时调用写清楚再附上“开始任何任务前先检索技能列表”的要求。我个人的实际做法是双通道并行技能文件依旧放在skills目录里作为“知识库”AGENTS.md里则只写一段精炼的“工作协议”比如# 工作协议 - 用户在要求“规划”“设计”“重构”“写测试”“排查故障”时优先检索对应技能并按其流程执行。 - 执行涉及多文件修改的任务前先输出影响文件清单。 - 所有代码改动完成后必须运行一次项目现有的测试命令。这样设计的理由很简单技能是“怎么做”的详细手册AGENTS.md是“何时用技能”的触发开关。二者配合Codex 才能在正确的时候把技能文件里的步骤真正执行起来。3.2 技能唤起失败怎么办从描述改写到手动手动指定技能唤起本质上是一个“意图匹配”过程模型会对比用户请求和技能描述的相关度。描述写得太泛比如在“生成测试”的技能描述里只写“处理测试相关任务”模型可能把任何沾边的请求都路由过去造成频繁误触发描述写得太窄模型又可能完全看不见它。理想的 description 应该包含触发动作、目标对象、典型场景、排除条件。如果调了几次描述还是无法稳定唤起还有一个兜底方法在对话里直接指定“请使用 maven-debug 技能来处理这个报错”。如果模型执行力正常它会严格按照该技能的 SKILL.md 逐步执行。这一步在 Codex 里同样适用因为技能本身就是一种可被显式索引的上下文。3.3 实操案例为 Codex 配置一个项目级“代码审查”技能我最近给一个团队项目配置了代码审查技能过程比较有代表性。先新建目录~/.codex/skills/pr-review/然后创建SKILL.mdfrontmatter 里name写pr-reviewdescription写“在用户要求代码评审、检查 Pull Request、审查变更列表时使用重点关注逻辑正确性、边界条件、异常处理和测试覆盖”。正文部分我列出了完整步骤先运行git diff获取变更内容再定位每个变更文件所属的模块上下文然后按列表逐项检查空指针风险、并发安全、资源释放、事务边界最后输出带严重等级的评审意见表。配置完以后实测Codex 在收到“帮我 check 一下这个分支的改动”时就直接按技能执行了评审意见的结构化程度比默认状态高了不止一个档次。4. 实操过程Java 项目里的典型用法与技能定制4.1 从零搭三个 Java 场景构建、单测、排障superpowers 在 Java 项目里能玩出很多花样我先按常见场景拆解。第一个场景是构建你让 Codex“帮我修一下项目构建失败”默认行为往往是它直接去看 pom.xml 猜测问题。有了技能约束后模型会先执行mvn -DskipTests compile复现失败再读取target/surefire-reports或编译日志里的第一个报错然后沿报错栈定位源码文件最后才提出修复建议。第二个场景是单测生成让模型“给某个工具类写完整单测”。默认它可能一口气生成几百行测试里面一半是无效断言。定制技能后模型会先读取该类的方法签名列出需要覆盖的分支和边界值把清单给你确认然后才逐个方法写测试。这样生成的测试覆盖率更扎实也更容易通过评审。第三个场景是故障排查线上日志里抛了一个 NullPointerException默认模型可能直接让你“检查空指针”等于没说。技能约束后模型会先让你提供堆栈、相关日志片段、最近改动记录然后基于堆栈逐步反向推理把可能的原因按概率排序列出来再针对每个原因给出验证方式。这套流程写进技能文件后排查效率提升非常明显。4.2 自制一个实用技能Maven 构建失败分析器自己写技能没有想象中复杂以“Maven 构建失败分析器”为例。新建目录~/.claude/skills/maven-debug/创建SKILL.md--- name: maven-debug description: 当用户报告 Maven 构建失败、编译错误、依赖冲突、测试失败时使用。先复现再分析不给出未经日志验证的结论。 --- # Maven 构建失败分析 ## 触发条件 - 用户提到 mvn 命令执行失败 - 用户贴出 BUILD FAILURE 日志 - 用户说“依赖冲突”“编译错误”“单测挂了” ## 执行步骤 1. 复现构建运行 mvn -DskipTests compile记录完整输出。 2. 定位第一个错误从日志中提取第一个 ERROR 级别信息忽略后续连锁错误。 3. 识别错误类型 - 编译错误定位到出错文件与行号查看相关 import 和泛型签名。 - 依赖冲突运行 mvn dependency:tree查找版本冲突的可传递依赖。 - 测试失败读取 target/surefire-reports/*.txt提取失败断言行。 4. 生成修复建议每条建议必须附带“为什么这样做”的解释不直接改代码。 5. 验证修复若用户同意修改修改后重新运行 mvn -DskipTests compile。 ## 注意事项 - 不要先用“可能是 X 问题”来猜测先看日志再下结论。 - 不要一次性修改多个变量一次只解决一个失败原因。 - 如果修复涉及依赖版本升级提醒用户检查兼容性。这个技能文件总共不到 40 行但实测效果非常明显因为模型每次分析构建失败时都被强制“先复现再分析”杜绝了它凭空臆测的毛病。4.3 技能文件里的“坑”模型会照做的边界写技能容易让模型稳定照做则需要摸清边界。第一步骤要足够原子化每步只做一件事一次性要求模型“分析问题、定位缺陷、修改代码、补测试、跑构建”五连它往往会在中间某个环节偷工减料最常跳过的就是“验证”。所以技能步骤里一定要把验证单独列为必须步骤并明确具体验证命令。第二避免在技能里写互相矛盾的规则。比如前面说“不要直接改代码”后面又说“如果用户要求就直接改”模型会困惑最后表现就是两次执行的结果不稳定。规则之间要层次分明明确“用户明确要求”作为更高优先级。第三技能正文要主动留白不要试图覆盖所有分支。模型在具体执行时会根据上下文填充细节你只需要定义流程骨架和关键checkpoint。我见过有人把技能写成一本书结果模型执行时反而迷失在大量细节里每一步都在犹豫要不要按“特殊情况”走。5. 常见问题与排查技巧实录5.1 技能加载后不生效优先排查这五个地方我踩过的坑不少整理成一张速查表效率最高现象可能原因解决方式模型说不存在任何技能路径不对或目录名含空格确认 SKILL.md 落在正确的 skills 目录目录名统一 kebab-case技能存在但从不主动触发description 写得过泛或过窄重写 description加入触发动作、对象和排除条件技能被频繁错误触发description 场景覆盖太宽增加“不处理 XX 类问题”的排除说明步骤执行时总是跳过验证环节技能正文没把验证列为必做步骤把验证步骤单独成节写明具体验证命令更新技能后行为没变化缓存或上下文过长导致技能被截断新开会话重试或主动要求模型“重新加载技能”5.2 上下文占用与 token 开销控制技能越多每次对话时模型需要扫描的文件就越多token 消耗自然上涨。我实测过加载 10 个技能后基础 token 开销大约增加 20% 左右但这部分成本换来的行为规范是值得的。不过要注意别在全局目录堆几十个技能尤其不要让某个技能的 SKILL.md 里贴一大段完整代码那是灾难。技能文件篇幅控制在 60 行以内附件类参考资料按需单独存放不要全塞进主文件。5.3 Codex 与 Claude Code 行为差异实测同一个技能文件在两种工具里的表现并不完全一致。Claude Code 对技能的执行更“死板”步骤顺序严格照做Codex 则更灵活会自主调整顺序甚至跳过它认为不必要的小步骤。因此如果你在 Codex 里发现某个技能没有被完整执行不要第一时间怀疑技能写错了先看看是不是模型自主决定简化了流程。对策是在步骤里显式声明“这些步骤缺一不可”并且每个步骤写明产出物把流程变成“不完成上一步就无法进入下一步”的链条。6. 扩展经验让技能库活起来的三个进阶玩法6.1 把团队规范直接“翻译”成技能很多团队有详细的编码规范文档但模型往往不会主动翻查。把这些规范浓缩成技能文件后约束效果立竿见影。我接手过一个项目规范文档要求“所有对外接口的异常必须包装成 BizException禁止裸抛 RuntimeException”写成技能后模型新生成的业务代码里就极少再出现裸抛异常。注意这里不是让模型读整个规范文档而是提取其中最硬性的约束转成步骤式检查项放进技能里。6.2 生产环境故障复盘反哺技能库每次线上事故复盘都会产出“下次要提前检查的指标”这些经验最适合沉淀为技能。比如某次生产事故是缓存穿透导致的复盘结论是“发版前要评估热点 key 的并发量”。我把它写进 code-review 技能从此每次代码评审模型都会自动关注缓存穿透风险点。技能库因此变成了团队经验的活体记录价值随使用时长递增。6.3 技能之间互相调用让 Agent 学会“分工协作”高级用法是让一个技能调用另一个技能。比如“大型重构”技能里可以写“在执行步骤一之前调用 system-design 技能生成目标架构方案”。这样模型会把多个技能串成流水线表现更像一个真正的技术负责人。我在实际项目里配合这个机制做过一次模块拆分Agent 先产出架构方案再生成影响面清单再逐步迁移代码最后跑回归测试整个过程的推进节奏比我手动指挥要顺畅得多。我个人在实际操作中的一个体会是superpowers 这类技能库最核心的价值不是“让 AI 变得更聪明”而是“让 AI 的行为变得更可预期”。你不再跟一个每次表现都随机的黑盒打交道而是在跟一套你亲手设计的流程执行器协作。如果你刚装好不知道怎么下手我建议别贪多先挑一个自己最痛的点——比如“代码审查”或“构建排障”——写一个十几行的技能对比一下开启前后的差异你会立刻感受到这套思路的威力。