这阵子我把 Codex CLI 从一个“会在终端里帮你写代码的助手”升级成了“自带全套项目流程的结对同事”关键一步就是给装上社区里很火的那个 superpowers 技能包项目。它不是一个新框架也不是另一个 CLI而是一套打包好的技能文件集合作用相当于给 Codex 预装各种开发场景下的“肌肉记忆”从初始化工程、按团队规范落地代码、跑测试到定位 bug 时先查什么都有现成的流程可循。对开发者来说最直接的收益是你不再需要每次重复交代“我们项目是 Java 17 MavenController 不直接操作仓储层Service 要加事务单测放 src/test”Codex 会在任务命中技能描述时自动把这套约定翻出来照着做。这篇文章我不打算复读 README而是把安装方式、目录规范、Skill 文件原理以及我拿一个真实 Java 项目跑通全流程的完整链路拆开讲一遍。适合刚听说 superpowers、想马上上手的人也适合已经在用、但一直没搞明白“为什么技能时灵时不灵”的人。1. superpowers 到底是什么一套技能包不是另一个 CLI1.1 从“智能聊天”到“自带流程”技能系统解决的核心痛点坦白说Codex CLI 本身的写码能力已经很强了我第一周用下来的最大感受是它像极了一个聪明但没人带过的实习生。你问它什么它都能答但如果没人告诉它“我们项目的 Controller 层不直接操作仓库要经过 Service测试要写在 src/test 下异常要统一包装”它每次都有可能给你生成风格完全不一致的代码。这个问题不是模型能力不够而是上下文工程没做到位。普通交互里项目的隐性约定全都靠用户在每次对话中临时口述一旦需求跨文件、跨服务这些约定很快就会在长对话里被稀释输出质量自然往下掉。superpowers 这类技能包项目的核心思路就是把“老工程师脑子里那套做事步骤”写成结构化的技能文件放到 Codex 能读到的地方。当任务匹配到某个技能的描述时模型会主动把该技能内容读进上下文按照里面定义的流程执行。跟普通 prompt 最大的区别在于技能是可沉淀、可复用、可分享的资产而不是每次临场发挥的一段话。1.2 一个类比它像给 AI 配了一本“项目 SOP 手册”我常用一个整理仓库的类比来解释这件事。假设你要请一个临时工帮你整理仓库你当然可以每次都口头交代“先看货架上哪些箱子过期过期的搬到退货区没过期的按日期排序。”但如果这个临时工手里有一本写好的《仓库整理 SOP》每次开工前自己翻一遍你的效率会高很多出错率也会低很多。技能系统就是这本 SOP 手册。它把高频动作固化成“先做什么、再做什么、遇到什么情况怎么处理”的流程。Codex 面对一个任务时先匹配技能描述命中后读取技能正文再开始干活。这样一来只要技能写得好输出质量就基本稳定不再依赖你每次提问时能不能把话说全。1.3 适合谁用以及不适用边界从我的经验看superpowers 最适合三类场景一是团队技术栈相对固定的项目比如后端就是 Spring Boot MyBatis你可以把分层规范和代码风格固化成技能二是个人长期维护的项目把自己的常用命令、测试习惯、部署流程写进技能省得每次从零解释三是需要 Codex 产出可交付代码的场景技能里的检查清单能明显减少返工。但它也不是万能药。如果是完全一次性的问答比如“这段 SQL 为什么报错”技能反而多余如果项目有大量私有业务上下文但没有沉淀成任何文档那技能也救不了因为技能只是个模板不是业务知识库还有一个比较隐蔽的问题如果技能没人维护随着项目演进过时的技能反而会误导 Codex。所以我的原则是技能数量宁少勿多每一条指令都要对得上当前项目的真实情况。2. 安装与初始化把 superpowers 装进 Codex CLI 的正确姿势2.1 安装前置条件确认 CLI 版本与环境动手之前先把基础环境确认一遍。因为我见过不少朋友一上来就 clone 仓库结果放错目录折腾了半天还不知道问题出在哪。这里有几个前置检查项Codex CLI 能正常运行输入codex --version能看到版本号系统里有 git并且能正常 clone 公开仓库按你实际要跑的场景准备好运行时比如后面要跑 Java 实战至少得有 JDK 和 Maven终端所在的用户目录有写入权限因为默认技能目录会放到家目录下。如果你是先装好了 Codex但之前没接触过技能类项目建议先随便跑一次正常对话确认模型调用没问题再引入技能这样后续排查时能少一个变量。2.2 获取技能包clone 还是下载 zip在 GitHub 上搜superpowers codex能找到对应的技能包仓库。通常有两种拿法直接git clone到本地或者下载 zip 再解压。我个人更喜欢 clone因为后续拉新版本只要git pull就行。命令大概是git clone 你找到的仓库地址 ~/superpowers-src注意我现在故意不把路径直接指到最终的技能目录而是先放到一个临时位置。因为你想装的可能不是整个包的根目录而是里面按领域拆好的多个技能目录。不同版本的 superpowers 仓库结构会不一样常见的是仓库里直接有skills/目录里面放着java-backend/、frontend-react/、testing/这类子目录也有些仓库把技能分散在顶层各目录里。这一步没有标准答案一定要以你拿到的仓库 README 为准。我踩过最蠢的坑是把整个仓库文件夹直接当成一个技能塞进~/.codex/skills结果 Codex 一直说找不到技能后来才发现里面真正的技能实体是下一级目录。2.3 目录放对才算装好全局与项目两级目录技能目录最关键的一点是位置。社区实践里普遍约定的结构是~/.codex/skills/ # 全局技能 java-backend/ SKILL.md frontend-react/ SKILL.md以及项目内的局部技能你的项目/ .codex/ skills/ project-specific/ SKILL.md全局技能适合放那种跨项目通用的能力比如“Java 后端规范”“编写单元测试”“日志排查套路”项目内的.codex/skills适合放团队私有约定比如“订单模块的错误码规范”“这个仓库的发布流程”。两者可以共存而且项目内技能会覆盖全局同名技能这一点后面在常见问题里还会细说。把目录放对之后技能文件本身也要注意命名格式。技能目录名一般用全小写加连字符比如java-backend不要用空格、大写或者中文。SKILL.md 这个文件名也是约定俗成的有些版本也支持PROMPT.md之类但为了兼容性和可预期我建议一律用 SKILL.md。2.4 验证安装怎么知道技能真的被读到了装完想立刻确认有没有生效我通常会按顺序做三件事。先直接问 Codex“你会哪些技能”如果它能列出你刚放进目录里的技能名说明技能目录扫描没问题。这一步在不同实现里表现不一样有的版本会明确列出有的只会说“我可以在需要时参考技能”但至少能看出它有没有感知到技能的存在。再看有没有自动触发。比如你在对话里描述一个“帮我给订单接口加分页和缓存”的需求这正好命中java-backend技能描述里的触发词那么在输出计划时模型应该会引用技能里的步骤而不是自己重新编一套流程。如果前两步都不满意就用显式引用的方式测试在提示里直接写java-backend或者“请先阅读技能 java-backend 再开始”。大多数支持技能的系统都会响应这种显式调用。这一步能确认技能文件本身没坏只是触发机制可能需要调 description。3. 核心机制拆解Skill 文件是怎么被 Codex 调用的3.1 一个技能就是一个文件夹SKILL.md 与配套文件很多人第一次看技能包会觉得奇怪为什么不是一个.json或者.yaml配置文件而是一个文件夹加一个 Markdown实际上这正是技能系统最聪明的地方。SKILL.md 是给模型读的指令文件而同一个技能目录下可以放模板、示例代码、检查清单等附属资源让技能不只是“一段提示词”而是一个完整的能力单元。一个典型的技能目录长这样java-backend/ SKILL.md templates/ controller-template.java examples/ service-layer-example.java checklists/ code-review-checklist.mdSKILL.md 是整个技能的主入口它有一个固定的 YAML 头后面跟着正文指令。正文可以用 Markdown 引用同目录下的其他资源比如“Controller 层写法参考 templates/controller-template.java”。这样设计的好处是模型需要模板时可以直接把文件内容读出来而不是靠记忆里不稳定的知识硬编。3.2 frontmatter 里的 name 和 description 决定了“激活率”我在实战里发现影响技能到底灵不灵的最大因素不是正文写得有多详细而是文件头那几行 frontmatter 写得好不好。一个标准的 frontmatter 大概是这样的--- name: java-backend description: 当需要开发或修改 Java Spring Boot 后端接口时使用。包含分层规范、事务处理、统一异常、单元测试要求。若涉及订单模块请额外参考项目内技能 order-rules。 ---这段 description 最关键的是开头 200 个字符左右。为什么因为匹配机制基本上就是把用户的请求和所有技能的 description 做相似度匹配开头内容越能覆盖高频触发场景命中率越高。反面典型是只写“用于 Java 开发”这种描述太宽泛几乎没有任何区分度模型在多个技能之间不知道怎么选结果就是你的技能被视而不见。我写 description 的经验是先写“什么时候用”再写“用了之后要遵守什么”。比如上面那个例子“当需要开发或修改 Java Spring Boot 后端接口时使用”是触发条件“包含分层规范、事务处理、统一异常、单元测试要求”是能力摘要。如果还有跨技能的强制依赖也可以像例子那样补一句但这句要克制别写太多否则匹配时反而分散注意力。3.3 技能分层与互相引用别把所有内容塞进一个文件刚开始接触技能系统的人容易犯一个毛病想把整个项目规范塞进一个 SKILL.md结果文件比需求文档还长。这是走不通的因为 Codex 读技能文件跟人看文档一样越短越容易抓住重点而且模型上下文窗口有限长技能会占用大量推理空间反而降低代码质量。正确的做法是分层。用一个主技能做“流程编排”再拆成几个子技能做“具体执行”。比如java-backend主技能里写流程执行本技能时按以下顺序读取并应用子技能 1. 先读取 sub/understand-project/SKILL.md了解项目结构和依赖 2. 编码阶段读取 sub/write-service/SKILL.md 3. 提交前读取 sub/test-checklist/SKILL.md按清单检查。这样每个子技能文件都短小聚焦模型只在需要的时候读给对应阶段用既节省上下文又容易维护。我在实际项目里就是把“理解项目”“写代码”“补测试”拆成三个子技能即便某个子技能更新也不会牵连主技能的流程。3.4 上下文工程为什么技能要短、聚焦、可裁剪说穿了技能系统的本质就是上下文工程。模型再强也是在有限的上下文窗口里做推理的。你塞给它 500 行规则它可能记住前 100 行后面就慢慢跑偏了。所以技能正文里的每一行都应该是可执行的动作比如“读取 pom.xml 确认 Spring Boot 版本”“先写测试用例再实现”“异常统一由 GlobalExceptionHandler 处理”。“请尽量高质量”“注意代码规范”这种话就是纯废话它没有提供任何可执行的信息模型看了也不知道该具体做什么。一个可裁剪的技能应该是这样的指令之间有明确顺序每一条都能对应到一个文件、目录或者动作这样模型读到后面就算上下文被压缩也至少能保留住高优先级的检查项。另一个小技巧是当技能需要跟其他技能联动时用相对路径引用子技能或资源文件而不是写绝对路径。绝对路径换台机器就废了相对引用才能让技能包保持可移植性。4. 实战复盘用 superpowers 带 Codex 跑一个 Java 需求4.1 场景设定一个真实的遗留 Java 项目改动这里我拿一个自己跑过的场景复盘一个 Spring Boot 项目需要给订单查询接口加“分页 缓存”并且要补齐单元测试。项目本身有历史包袱Java 17 MavenController 层很薄Service 里直接写查询逻辑团队规范是 Service 方法上加事务注解测试统一放src/test/java下。这种需求看起来很常规但没有技能的情况下Codex 经常会在细节上翻车比如不加事务、缓存注解用错位置、测试只覆盖正常路径。引入 superpowers 之后我做的是在项目里配置了java-backend主技能并把“订单模块错误码规范”等团队特有内容放进了项目级技能。4.2 开场指令怎么写让技能自动被召唤技能能不能被自动触发很大程度取决于你开场指令里的“触发词”能不能跟技能 description 中的场景对齐。我当时是这样写的在 order-service 模块里改造 GET /api/orders 接口按团队规范加分页和本地缓存并补单测。请先参考 java-backend 技能中的规范按里面的流程执行。这里有两个关键动作。第一需求描述里出现了“Spring Boot 接口”“加分页和缓存”“补单测”它们正好命中java-backend和testing类技能的典型场景第二我加了“请先参考 java-backend 技能中的规范”这句显式指引相当于告诉模型去读技能而不是全靠它自己悟。如果只写“给接口加分页”模型可能压根不知道要遵守分层规范也可能自作主张把缓存直接写在 Controller 层。触发词不是魔法本质上是在帮匹配机制缩小范围。4.3 过程中 Codex 执行了哪些技能序列我观察到的执行流程大概是这样的正好对应技能文件里的层级结构。先进入理解项目阶段Codex 自己读了pom.xml确认 Spring Boot 版本和依赖又扫了一遍 controller 和 service 的目录结构才输出实施计划。这一步对应的是子技能sub/understand-project/SKILL.md它让模型在动代码前先建立项目背景认知而不是上来就生成一坨代码。进入编码阶段后它按java-backend主技能里的规范把分页参数封装成 PageRequest在 Service 层通过 Spring Cache 注解做缓存事务注解按团队习惯加在公开方法上。Controller 层保持很薄只负责参数校验和返回包装。这个过程我让技能里写了一条硬性要求不允许在 Controller 里直接调用 Repository模型确实遵守了。最后是测试阶段它先列了一个测试用例清单包括正常分页、缓存命中、缓存失效以及参数非法场景然后再写 JUnit 代码。这个“先列用例再写测试”的习惯就是技能正文里强调的流程效果非常明显测试覆盖面比之前无技能时的随机发挥要稳定得多。4.4 同需求无技能对比差距在细节为了验证是不是 superpowers 的功劳我后来故意在另一个分支上不带任何技能重新跑了一遍同样的需求。结果是代码能跑但细节问题不少。Controller 直接用了仓库层返回的实体没有做 DTO 转换缓存注解加在了私有方法上Spring 代理根本不会生效测试只写了正常路径非法参数和缓存失效都没覆盖。不是说 Codex 没能力写对而是它没有“必须这么做”的强约束。技能的价值就在这里它在模型自由发挥的边界上划了一条线把团队规范、易错点、检查清单直接焊死在执行流程里。对个人开发者来说这可能只是省心对团队来说这意味着不同成员用 Codex 的产出风格能拉齐到同一水平线。5. 常见问题与排查技巧实录5.1 技能说找不到/没被触发怎么办这个问题我遇到至少三次最后整理出一个排查顺序。先看目录结构确认技能是放在~/.codex/skills/技能名/SKILL.md而不是放错成~/.codex/skills/SKILL.md这种扁平结构再看技能目录名是否含空格或大写字符命名不规范确实会导致扫描失败。如果结构没问题就看 description 的触发词跟你的提问是否对得上。最常见的情况是用户问得很宽泛比如“帮我优化代码”而技能描述明确写的是“当需要修改 Spring Boot 后端接口时使用”匹配不上自然就不会触发。最优解是把提问写具体或者干脆显式写java-backend来强制调用。5.2 技能内容太长被截断当技能文件超长时模型可能只读到前半部分导致后面的检查项全部失效。我一般建议单个 SKILL.md 控制在 200 行以内超过就拆子技能。如果你发现技能里的检查清单时灵时不灵多半不是模型偷懒而是清单位于文件后部上下文被压缩掉了。我自己的做法是把最重要的硬性规范放在前面检查清单这种可以后置。另外把描述里的“必须遵守的顺序”放在技能正文的开头这样即使后面被截断核心流程也不容易丢。5.3 技能与项目指令 AGENTS.md 冲突Codex 支持项目级指令文件 AGENTS.md当它跟技能里的规则冲突时你会发现模型一会儿按技能走一会儿按 AGENTS.md 走行为很不稳定。比如 AGENTS.md 规定接口返回直接用实体而技能要求一律走 DTO模型就会很拧巴。解决方法是明确优先级。我通常在技能最前面写一行“本技能若无特殊声明应当服从项目级 AGENTS.md 中的强制要求。”这样等于给了模型一个冲突解决原则避免它在两套规范之间摇摆。反过来如果你希望技能规则优先也要写清楚总之不能留白。5.4 多套技能混用时的优先级困惑装了一堆技能之后你会发现模型有时候会同时触发多个技能然后行为变得混乱。比如既有java-backend技能要求写单测又有fast-prototype技能要求快速出代码别写测试两者一起被召唤模型就会精神分裂。我的建议是一个需求主用一套技能其他技能当作资源按需读取。在 description 里明确“本技能用于需要完整交付的场景若用户明确要求快速原型则忽略测试相关步骤”可以把潜在冲突的责任推到提问信息上。另外别在同一个项目里同时启用两个定位重叠的大技能这是最省心的办法。下面把我会遇到的几个问题整理成一个速查表方便之后对照现象可能原因解决思路技能完全不被读到技能目录结构不对确认~/.codex/skills/name/SKILL.md路径技能平时不触发description 太宽泛或触发词不匹配把提问写具体或显式引用技能名技能只执行前半段单个技能文件过长拆成子技能主技能只做流程编排行为在规范和技能之间摇摆与 AGENTS.md 冲突在技能里声明冲突解决时的优先级多个技能同时触发互相打架定位重叠精简技能数量一场景一主技能收个尾我踩过几次坑之后的几点心得用了这段时间 superpowers最大的体会是技能不是越多越好而是越准越好。一个写得精准、聚焦场景、能稳定触发的 Java 后端技能远比堆二十个宽泛的“开发规范”技能有用。你看社区里吐槽“技能没用”的人绝大多数问题出在 description 写得像散文或者目录里塞了几十个同名鸡肋技能。还有一个小建议别指望技能一次就能写好。它跟代码一样需要迭代。我第一次写的 java-backend 技能太啰嗦模型老是抓不住重点后来把正文砍掉一半再把最关键的规范提到最前面触发率和执行质量都明显提升了。技能系统是个好东西但它终究是工程问题不是装个包就一劳永逸的买卖。
