如果你已经在用 OpenAI 的 Codex 写代码大概率遇到过这种尴尬单次对话里它很强换个新会话就瞬间“失忆”——上回说好的命名规范、测试要求、目录约定又得从头讲一遍它默认还不联网碰到不熟的库只能凭记忆硬编。superpowers 这个开源项目就是专门补这几块短板的。一句话定位它是一个给 Codex 装“技能包”的框架通过插件机制给 Codex 加上可复用的技能skills、跨会话的长期记忆memory、联网检索与阅读网页的能力。装完之后你可以把团队的工程约定、常用工作流、问题排查清单全部写成 Markdown 技能文件让 Codex 每次开工前自动加载。这篇文章是我从安装、上手到写自定义技能的全过程记录适合正在用 Codex 但觉得它“不够听话”的开发者也适合想把团队编码规范变成 AI 硬约束的工程负责人。哪怕你只是好奇“给大模型配技能”这个思路怎么玩也能从里面捡到点东西。1. Superpowers 到底是什么给 Codex 打工的“技能框架”1.1 先给它定个性不是语言不是 IDE是“插件技能库”很多人第一次听到 superpowers第一反应是“又冒出来一个 AI 编程工具”。真不是。它本身不写代码也不提供编辑界面更不绑定某个特定模型它只是一个跑在 Codex 插件机制上的技能管理框架。那“技能”到底是个什么东西说白了技能就是一个带元信息的 Markdown 文件。文件顶部用 YAML 写清楚这个技能叫什么、干什么用正文写清楚“当这个技能被触发时模型应该按哪些步骤执行、要遵守什么约束”。Codex 启动并加载 superpowers 之后插件会把当前项目里可用的技能清单注入到对话上下文里模型看到你的任务跟某个技能的描述匹配就会按技能里的步骤去执行。这个设计最妙的地方在于技能不是写死的程序逻辑而是“给模型的指令手册”。你不需要会写插件、不需要懂底层实现只要你能把一件事的流程用文字讲清楚你就能定义一个技能。门槛低到任何能写清楚操作文档的人都能上手这也是它能被社区快速接受的原因。1.2 它到底解决了什么痛点先说 Codex 原生最让我难受的短板用四个字概括就是记、查、规、攒。这四个字分别对应四类问题也是我后来决定给 Codex 加装 superpowers 的核心原因。记Codex 没有跨会话记忆。上午跟它约好“日志一律用 SLF4J”下午开新会话它就忘了。所有约定都得靠人肉重复项目一忙就乱有时候连自己都记不清上次到底约定过什么。长期来看这种“每次从零开始”的体验跟“雇了个懂编程但失忆的实习生”没什么两样。查Codex 默认不联网。不认识的库、新出的 API、私有文档它只能靠训练数据里的印象去猜。训练数据是有时间边界的猜错了就是编造。对大项目来说这是致命伤因为一个废弃方法的误导成本往往比从零开始查文档高得多。规每个项目都有自己的约定。包结构、命名规则、异常处理方式、测试风格这些没法塞进一条 Prompt 里塞进去也占上下文而且每次都要重新塞。更有意思的是这些约定往往只有团队里待得久的人才知道新人根本无从下手。攒真正的经验应该越用越多。你今天用 Codex 排查完一个诡异的线上问题这份排查过程有没有沉淀下来原生 Codex 不会帮你沉淀。下次遇到同一个问题它照样从头开始猜你之前踩过的坑它一个都记不住。superpowers 的思路就是把“记、查、规、攒”这四件事分别做成能力模块用技能去承载用记忆去存储用联网去补齐信息最后让所有经验都落到 Markdown 文件里变成可以版本管理、可以复用、可以分享的东西。我在团队里推广后最直观的感受是新会话的 Codex 不再是个“懂编程的陌生人”而是个“读过团队手册的老员工”。1.3 适用人群边界什么人不适合用我先把丑话说在前面。如果你只是偶尔拿 Codex 跑个脚本、写个一次性代码片段superpowers 对你来说太重了装完你大概率觉得“就这”。它的真正价值要在持续进行的项目里才体现得出来。另外如果你所在的公司对第三方插件有严格的合规审查尤其是对数据流向要求不清晰的环境别急着装先让安全团队把插件的行为审一遍。这类框架会往模型上下文里塞额外的提示词、可能在本地读写文件合规红线要先确认。什么人强烈建议试两类。第一类是重度使用 Codex 做真实项目的开发者你已经被“重复交代背景”折磨过装完会有一种“早该如此”的感觉。第二类是带团队的工程负责人你可以把代码规范、评审要求、构建流程全部固化成技能文件放进 Git 仓库团队每个人拉下来就是一套统一的“AI 行为准则”新人也跟着受益。2. 核心设计拆解为什么“技能即 Markdown”这条路走得通2.1 技能的本质给模型一本“操作手册”我们直接看一个技能文件长什么样这是我实际项目里的简化版--- name: maven-build-check description: Use when Maven build fails, to diagnose and fix compilation errors step by step. --- # Maven 构建排查 1. 先运行 mvn -q compile -DskipTests 复现错误。 2. 只看第一处编译错误不要尝试同时修多个问题。 3. 定位到具体文件和行号后先说清楚原因再动手改。 4. 改完重新编译确认通过后再运行相关测试类。 5. 如果连续三次修复失败停下来向用户说明现状并请示。看到没技能文件干的事就是把你平时“希望 AI 按这个套路干活”的话变成一份结构化文档。YAML 里的 name 和 description 是给模型做匹配用的正文才是它真正执行的步骤。这里有几个关键点值得单独说一下。第一description 一定要写成“模型一眼能判断什么时候该用”的句式。模型不会把每个技能全文都读一遍它拿到的是技能清单靠 description 来匹配。你写“关于 Maven 的说明”模型看了也白看你写“Use when Maven build fails”它立刻知道触发条件。第二正文步骤要具体到可执行像“看看哪里错了再改”这种话等于没写。第三技能步骤不要贪多一个技能聚焦一个场景宁可拆成两个技能也不要写成一个大杂烩。2.2 记忆系统让 Codex 不再是金鱼记忆功能我刚上手的时候觉得没啥用了一周才发现是隐藏的重点功能。它的机制分两层短期记忆服务当前会话长期记忆跨会话持久化。长期记忆存储在本地文件里Codex 每次启动时可以读取和更新。实际用法是这样的你在对话里说一句“记住我们项目的数据库表名一律小写下划线禁止驼峰”模型配置正常的话就会调用记忆相关技能把这条规范写进长期记忆文件。下次新会话它读到这条记忆自然就遵守了。我习惯每隔一段时间就翻一下记忆文件清理过期的、合并重复的避免时间长了堆积成垃圾场。需要提醒的是记忆不是自动发生的。模型不会主动把每次对话都存下来它需要被技能指示“什么内容值得记”团队规范、命令习惯、关键决策这些都是值得记的你把“今天午饭吃了啥”告诉它它也会傻乎乎存下来那就纯属浪费上下文。2.3 联网检索从“写代码”到“查资料干活”web-research 是我另一个离不开的技能。它让 Codex 能够根据关键词发起搜索、抓取网页内容、提取正文再把结果作为上下文带给模型分析。对我来说最大的应用场景是让 Codex 去查某个依赖库的最新文档然后按新 API 改代码这比它凭记忆瞎写强太多了。但这里有个使用边界要讲清楚。web-research 能拿到的是公开网页内容内部文档、需要登录的系统、动态渲染的页面它大概率抓不到。所以别拿它去查你们公司的内部 Wiki也别指望它能读某个需要复杂认证的系统。另外搜索到的内容不代表权威模型很容易“看着像就信”你最好在技能里加一条约束“引用外部信息时必须标注来源和日期拿不准就明说不知道”。2.4 功能对比装 superpowers 前后的 Codex 差别有多大我用一张表复盘一下装 superpowers 前后的差异方便你判断值不值得花这半小时能力维度裸奔 Codex加 superpowers 之后跨会话记忆没有完全失忆有长期记忆规范一次写入长期可用自定义流程只能靠每次写提示词技能文件写好即用可复用可分享联网查资料默认不支持可搜索、抓取网页并引用来源团队经验沉淀无经验随会话消失技能和记忆全部落盘进 Git 管理上下文开销每次交代背景占大量上下文技能按需加载记忆按需读取看完这张表你应该能理解我为什么说它“值得半小时”它相当于把原来每次开工前都要做的“背景交代”一次性做成了基础设施。后面所有会话都在吃这套基础设施的红利。3. 安装与初始化从零到能跑通全程实操记录3.1 前置条件Codex CLI 装好没有superpowers 是 Codex 的插件所以前提是本地已经装好 Codex CLI并且能正常对话。装好之后先敲一下命令确认环境codex --version如果这条命令报 not found先去把 Codex CLI 装好再来。不建议在没有确认基础环境的情况下直接装插件否则后面排查问题会多一层干扰。顺便说一句我装的时候用的是较新的 Codex 版本如果你手里的版本比较老插件机制可能不完整建议先升级。3.2 安装插件一条命令的事安装本身很简单codex plugins install superpowerslatest这个命令会把 superpowers 插件拉取并注册到 Codex 的插件体系里。安装过程一般很快如果网络状况不好可能要等一会儿。装完后可以用下面的命令确认它能被识别codex plugins list能看到 superpowers 在列表里就算装上了。这里有个小建议安装前先看一眼官方仓库的 README。这类工具迭代很快今天的命令可能明天就变了以官方文档为准永远是最稳妥的做法。3.3 初始化codex superpowers 干了什么装完插件还不算完还要初始化codex superpowers我第一次跑这个命令的时候它做了几件事创建了技能目录、往我的 Codex 配置目录里写入了一套默认技能、在当前项目目录生成了一个 SUPERPOWERS.md 文件相当于技能索引里面列出当前可用的技能清单和一句话描述还问我要不要修改一些配置项。不同版本的交互细节可能不一样比如中间可能会问你是否要开启某个功能我建议第一次全选默认跑通之后再去调。这里有个容易忽略的点SUPERPOWERS.md 是 Codex 上下文里实际加载的那份清单。每次启动 Codex 时它通过这个文件知道现在有哪些技能可用再按需去读具体技能文件。所以这个文件很重要最好别删也别随手改坏格式。3.4 验证安装是否成功初始化完成后我习惯做三步验证。第一步查看技能目录结构确认内置技能已经落盘ls ~/.codex/skills第二步打开项目目录下的 SUPERPOWERS.md看一眼技能清单是不是完整。第三步启动 Codex直接问一句“你现在有哪些技能可以用分别什么时候用”如果模型能列出 skill-editor、memory、web-research 等技能并说清用途说明 superpowers 已经在上下文中生效了。如果模型一脸茫然多半是初始化没跑完或者你启动 Codex 的目录跟生成 SUPERPOWERS.md 的目录不一致后面排查章节会细说。4. 核心技能逐个拆解与实战用法4.1 skill-editor造技能的技能superpowers 内置了一套“元技能”其中 skill-editor 是我用得最多的。它的作用就是帮你创建、修改、审查技能文件。我一般这么用直接跟 Codex 说“我想写一个技能功能是 XXX帮我按 superpowers 的规范生成一个技能文件”它会自动调起 skill-editor生成带 YAML frontmatter 的 Markdown还会提示我放在哪个目录。生成之后不要直接就用一定要做两步人工检查一是检查 description 的触发条件写得够不够清楚二是检查正文步骤是不是可执行。我自己犯过的错是让 skill-editor 一次帮我写三个技能结果每个都写得很泛后来改成一次只写一个、写完立刻实测质量立刻上来了。记住skill-editor 是提效工具不是免责工具最终质量责任在你。4.2 memory记忆的正确打开方式再说说记忆的正确用法。长期记忆不是让你把整个项目文档都塞进去那就把上下文撑爆了。我的经验是只记四类东西长期有效的项目约定、用户明确说过的偏好、反复出现的技术决策、以及那些“你花半小时才查明白”的关键结论。用的时候也有技巧。想让 Codex 记住一件事说清楚是“长期还是本次会话”“记住长期我们项目禁止使用 System.out.println 打日志”比含糊地说“记住啊”要好得多。查询记忆的时候同样要具体比如“我们之前对数据库迁移是怎么约定的”模型会去检索记忆文件而不是凭空编一个。最后记忆文件要定期清理。我见过有人把记忆当垃圾桶堆了几百条结果每次会话都要读一堆无用内容反而拖慢了响应。4.3 web-research联网查资料的正确姿势web-research 适合干的事我排个优先级查库的最新文档、查某个 API 的用法示例、确认某个技术方案是否可行、调研同类项目的做法。不适合干的事查内部系统资料、抓需要登录才能看的内容、看动态渲染的复杂页面。在使用上我有一条硬性要求写进了项目技能里“所有来自网页的信息必须给出来源 URL如果网页内容与已有知识冲突以网页为准但要说明差异。”这么做的好处是 Codex 就算引用错了我也能顺着来源去核不会把错误信息一路带进代码里。4.4 其他基础技能plan、git-workflow、thinking 要不要装superpowers 还附带了一些基础技能比如 plan先做计划再执行、thinking复杂问题先展开思考再回答、git-workflow按规范流程操作 Git。我的观点是不要全装按需启用。这些技能本身不是越多越好每多一个清单就长一分匹配的干扰也大一分。我当时先留了 skill-editor、memory、web-research 三个外加自己写的两个项目技能。跑了两三个真实任务之后才决定要不要加 plan 这类流程型技能。这种“最小可用”的启动方式能帮你更快看清 superpowers 到底解决了什么问题而不是被一堆功能淹没。5. 把 Superpowers 用在 Java 项目里一个完整的实战案例5.1 为什么单独聊 Java搜索热词里“superpowers java”热度不低说明很多人在意它跟 Java 生态怎么配合。这并不奇怪——Java 项目恰恰是最适合技能化的一类项目约定多包结构、分层、命名、样板多POJO、Mapper、DTO、构建链路繁琐Maven/Gradle、测试、打包。如果你让裸奔的 Codex 去改一个 Spring Boot 项目它大概率会给你写出“能用但不像团队风格”的代码。有了技能就不一样了你等于把团队的《开发规范手册》直接放进模型的脑子里。5.2 场景设定一个需要约束的 Spring Boot 项目假设我们接手的项目有这些约定很典型包结构以 com.example 开头分层严格——Controller 只做参数校验和路由Service 层写业务逻辑数据访问走 Mapper使用 Lombok 减少样板代码测试用 JUnit 5 加 AssertJ构建用 Maven提交前必须编译且测试全绿。在没有技能的时候我让 Codex 加一个接口它可能直接在 Controller 里写业务逻辑、手动写 getter/setter、测试风格跟项目里旧的测试对不上。每次都要我在 Review 阶段反复纠正非常烦。这个场景就是写技能的完美动机。5.3 动手写两个 Java 项目技能我先写一个规范类技能 java-spring-conventions内容大概是这样的--- name: java-spring-conventions description: Use when writing or modifying Java code in this Spring Boot project. Enforces layering, naming, Lombok usage and exception handling conventions. --- # 项目 Java 编码约定 - 包名前缀统一为 com.example新增类必须先放在正确的子包下。 - Controller 只做参数校验、路由和响应封装业务逻辑一律在 Service 层。 - Service 接口定义方法Impl 类实现禁止在 Controller 里直接操作 Repository。 - 使用 Lombok 的 Data / Builder / Slf4j禁止手写 getter/setter。 - 日志使用 Slf4j 的 log禁止 System.out.println。 - 异常业务异常抛自定义 BizException禁止裸抛 RuntimeException。 - 方法命名查询用 get/find 开头新增用 create/add修改用 update删除用 delete。然后是构建与测试流程技能 maven-safe-build--- name: maven-safe-build description: Use after modifying Java code to verify the build and relevant tests. Run compile first, then targeted tests, then full build if time permits. --- # Maven 构建与测试流程 1. 运行 mvn -q compile -DskipTests确保编译通过。 2. 针对改动的类运行相关测试mvn -q test -DtestXXXTest。 3. 若失败先阅读第一处失败信息定位原因后再修复禁止盲目反复重跑。 4. 相关测试通过后如果改动涉及公共层再跑 mvn -q test 全量回归。 5. 任何一步失败都要停下来向用户说明失败原因而不是绕过测试。这两个技能文件就是团队的硬约束。放在项目的技能目录里All 就绪。5.4 实测过程让 Codex 按技能干活技能文件放好后我重启 Codex确保新技能被加载给了一个真实任务“在 UserService 里增加一个根据邮箱查询用户的方法并补一个测试。”然后观察它的行为。没加技能之前它可能会在 Controller 里顺手写查询逻辑、用 JPA 的 findByEmail 直接在接口里定义、测试类里用 System.out 打印结果。加了技能之后它明显先检索了 java-spring-conventions然后给出的代码Controller 只暴露端点、Service 接口加方法、Impl 里实现、用 Optional 处理查不到的情况、测试用 AssertJ 断言、日志用 Slf4j。代码风格跟项目完全一致我 Review 起来几乎不用改。这个对比让我很受触动不是 Codex 写不了符合规范的代码是你没给它规范。superpowers 的价值就是让规范的传递不再是每次对话前的一段临时提示词而是项目的一部分。5.5 把技能沉淀为团队资产技能文件是可以进 Git 的。我把这两个技能文件放到一个 skills 目录并在项目的 README 里写了说明“用 Codex 干活前先确认技能已安装。”新同事拉到项目初始化一下 Codex就自动获得整套团队 AI 行为准则。后面再有人发现 Codex“不听话”第一反应不是改提示词而是看技能哪里写得没覆盖到然后更新技能所有人同步受益。这个过程其实就是在把“隐性经验”变成“显性资产”。你可以把它类比成原来团队里的《开发规范文档》只不过这份规范不是给人看的是给 AI 看的而且 AI 真的会执行。6. 常见问题、避坑指南与排查思路6.1 安装与初始化问题速查我整理了一张表覆盖我见到过的大部分问题常见问题可能原因处理方式codex plugins 命令报错Codex 版本过旧老版本没有插件机制先升级 Codex CLI 再装装完没有生成 SUPERPOWERS.md只装插件没跑初始化执行codex superpowers完成初始化模型不认技能清单启动目录跟生成索引的目录不一致在项目根目录启动确认 SUPERPOWERS.md 存在新写的技能不生效技能文件没放在正确目录或格式错误检查 YAML frontmatter 是否完整重启会话上下文异常变大技能或者记忆文件写太多精简技能描述定期清理记忆插件更新后行为变化版本迭代改了交互看官方更新日志必要时重新初始化6.2 运行时的典型翻车现场翻车现场一技能加载了但模型不按技能走。我遇到过 Codex 明明看到技能清单还是自顾自地回答。后来发现原因是我把技能描述写得太泛任务描述又多又乱模型选择了自由发挥。解决办法任务描述写清楚点或者在对话里直接指定“按 xxx 技能执行”。翻车现场二记忆写崩了。有一次我让 Codex 记住的东西太多包括一些临时任务结果后面每次对话它都要读一堆没用的长期记忆响应又慢又容易跑偏。后来我养成习惯每周日花十分钟清理记忆文件把过期的、临时的、已经失效的条目删掉。翻车现场三联网查出来的资料是过时的。web-research 搜到一个博客讲的是旧版 APICodex 信了写出来的代码用到已废弃的方法。这就是为什么我坚持在上面提到的技能里加“必须标注来源和日期”。信息带来源你才能核、才能纠。6.3 这个月踩过的坑希望你别再踩最后说几个最有代表性的坑。第一个是“技能描述用词太文艺”。我最早写的一个技能描述是“帮助处理项目中遇到的常见问题”结果模型根本不知道什么时候该触发改成“Use when the user reports a build failure or test failure in the Maven project”之后立刻精准命中。触发条件要写场景不要写能力。第二个坑是“一个技能塞了太多东西”。我试图写一个“全流程开发技能”从建表到部署全在里面结果模型执行到第三步就忘了后面内容。拆成独立技能之后每个都短小聚焦执行完整度大幅提升。第三个坑是在团队里直接全量推没给过渡期。有人新装的 Codex 突然“变得不听话”其实是技能和记忆还没跟他本人磨合好。后来我调整了策略新成员先装基础技能用一周顺手了再根据自己的工作流逐步加新技能。superpowers 这东西适合渐进式引入不适合一步到位。我个人在实际操作里的体会是superpowers 最值钱的地方不是某一个技能而是它逼你把“想让 AI 怎么干活”这件事想清楚了。技能写得越具体Codex 干活越可靠。如果你还在观望我建议先花二十分钟装起来写一个你最头疼场景的小技能跑完一个真实任务再下结论。这个投入大概率不会亏。
如果你已经在用 OpenAI 的 Codex 写代码大概率遇到过这种尴尬单次对话里它很强换个新会话就瞬间“失忆”——上回说好的命名规范、测试要求、目录约定又得从头讲一遍它默认还不联网碰到不熟的库只能凭记忆硬编。superpowers 这个开源项目就是专门补这几块短板的。一句话定位它是一个给 Codex 装“技能包”的框架通过插件机制给 Codex 加上可复用的技能skills、跨会话的长期记忆memory、联网检索与阅读网页的能力。装完之后你可以把团队的工程约定、常用工作流、问题排查清单全部写成 Markdown 技能文件让 Codex 每次开工前自动加载。这篇文章是我从安装、上手到写自定义技能的全过程记录适合正在用 Codex 但觉得它“不够听话”的开发者也适合想把团队编码规范变成 AI 硬约束的工程负责人。哪怕你只是好奇“给大模型配技能”这个思路怎么玩也能从里面捡到点东西。1. Superpowers 到底是什么给 Codex 打工的“技能框架”1.1 先给它定个性不是语言不是 IDE是“插件技能库”很多人第一次听到 superpowers第一反应是“又冒出来一个 AI 编程工具”。真不是。它本身不写代码也不提供编辑界面更不绑定某个特定模型它只是一个跑在 Codex 插件机制上的技能管理框架。那“技能”到底是个什么东西说白了技能就是一个带元信息的 Markdown 文件。文件顶部用 YAML 写清楚这个技能叫什么、干什么用正文写清楚“当这个技能被触发时模型应该按哪些步骤执行、要遵守什么约束”。Codex 启动并加载 superpowers 之后插件会把当前项目里可用的技能清单注入到对话上下文里模型看到你的任务跟某个技能的描述匹配就会按技能里的步骤去执行。这个设计最妙的地方在于技能不是写死的程序逻辑而是“给模型的指令手册”。你不需要会写插件、不需要懂底层实现只要你能把一件事的流程用文字讲清楚你就能定义一个技能。门槛低到任何能写清楚操作文档的人都能上手这也是它能被社区快速接受的原因。1.2 它到底解决了什么痛点先说 Codex 原生最让我难受的短板用四个字概括就是记、查、规、攒。这四个字分别对应四类问题也是我后来决定给 Codex 加装 superpowers 的核心原因。记Codex 没有跨会话记忆。上午跟它约好“日志一律用 SLF4J”下午开新会话它就忘了。所有约定都得靠人肉重复项目一忙就乱有时候连自己都记不清上次到底约定过什么。长期来看这种“每次从零开始”的体验跟“雇了个懂编程但失忆的实习生”没什么两样。查Codex 默认不联网。不认识的库、新出的 API、私有文档它只能靠训练数据里的印象去猜。训练数据是有时间边界的猜错了就是编造。对大项目来说这是致命伤因为一个废弃方法的误导成本往往比从零开始查文档高得多。规每个项目都有自己的约定。包结构、命名规则、异常处理方式、测试风格这些没法塞进一条 Prompt 里塞进去也占上下文而且每次都要重新塞。更有意思的是这些约定往往只有团队里待得久的人才知道新人根本无从下手。攒真正的经验应该越用越多。你今天用 Codex 排查完一个诡异的线上问题这份排查过程有没有沉淀下来原生 Codex 不会帮你沉淀。下次遇到同一个问题它照样从头开始猜你之前踩过的坑它一个都记不住。superpowers 的思路就是把“记、查、规、攒”这四件事分别做成能力模块用技能去承载用记忆去存储用联网去补齐信息最后让所有经验都落到 Markdown 文件里变成可以版本管理、可以复用、可以分享的东西。我在团队里推广后最直观的感受是新会话的 Codex 不再是个“懂编程的陌生人”而是个“读过团队手册的老员工”。1.3 适用人群边界什么人不适合用我先把丑话说在前面。如果你只是偶尔拿 Codex 跑个脚本、写个一次性代码片段superpowers 对你来说太重了装完你大概率觉得“就这”。它的真正价值要在持续进行的项目里才体现得出来。另外如果你所在的公司对第三方插件有严格的合规审查尤其是对数据流向要求不清晰的环境别急着装先让安全团队把插件的行为审一遍。这类框架会往模型上下文里塞额外的提示词、可能在本地读写文件合规红线要先确认。什么人强烈建议试两类。第一类是重度使用 Codex 做真实项目的开发者你已经被“重复交代背景”折磨过装完会有一种“早该如此”的感觉。第二类是带团队的工程负责人你可以把代码规范、评审要求、构建流程全部固化成技能文件放进 Git 仓库团队每个人拉下来就是一套统一的“AI 行为准则”新人也跟着受益。2. 核心设计拆解为什么“技能即 Markdown”这条路走得通2.1 技能的本质给模型一本“操作手册”我们直接看一个技能文件长什么样这是我实际项目里的简化版--- name: maven-build-check description: Use when Maven build fails, to diagnose and fix compilation errors step by step. --- # Maven 构建排查 1. 先运行 mvn -q compile -DskipTests 复现错误。 2. 只看第一处编译错误不要尝试同时修多个问题。 3. 定位到具体文件和行号后先说清楚原因再动手改。 4. 改完重新编译确认通过后再运行相关测试类。 5. 如果连续三次修复失败停下来向用户说明现状并请示。看到没技能文件干的事就是把你平时“希望 AI 按这个套路干活”的话变成一份结构化文档。YAML 里的 name 和 description 是给模型做匹配用的正文才是它真正执行的步骤。这里有几个关键点值得单独说一下。第一description 一定要写成“模型一眼能判断什么时候该用”的句式。模型不会把每个技能全文都读一遍它拿到的是技能清单靠 description 来匹配。你写“关于 Maven 的说明”模型看了也白看你写“Use when Maven build fails”它立刻知道触发条件。第二正文步骤要具体到可执行像“看看哪里错了再改”这种话等于没写。第三技能步骤不要贪多一个技能聚焦一个场景宁可拆成两个技能也不要写成一个大杂烩。2.2 记忆系统让 Codex 不再是金鱼记忆功能我刚上手的时候觉得没啥用了一周才发现是隐藏的重点功能。它的机制分两层短期记忆服务当前会话长期记忆跨会话持久化。长期记忆存储在本地文件里Codex 每次启动时可以读取和更新。实际用法是这样的你在对话里说一句“记住我们项目的数据库表名一律小写下划线禁止驼峰”模型配置正常的话就会调用记忆相关技能把这条规范写进长期记忆文件。下次新会话它读到这条记忆自然就遵守了。我习惯每隔一段时间就翻一下记忆文件清理过期的、合并重复的避免时间长了堆积成垃圾场。需要提醒的是记忆不是自动发生的。模型不会主动把每次对话都存下来它需要被技能指示“什么内容值得记”团队规范、命令习惯、关键决策这些都是值得记的你把“今天午饭吃了啥”告诉它它也会傻乎乎存下来那就纯属浪费上下文。2.3 联网检索从“写代码”到“查资料干活”web-research 是我另一个离不开的技能。它让 Codex 能够根据关键词发起搜索、抓取网页内容、提取正文再把结果作为上下文带给模型分析。对我来说最大的应用场景是让 Codex 去查某个依赖库的最新文档然后按新 API 改代码这比它凭记忆瞎写强太多了。但这里有个使用边界要讲清楚。web-research 能拿到的是公开网页内容内部文档、需要登录的系统、动态渲染的页面它大概率抓不到。所以别拿它去查你们公司的内部 Wiki也别指望它能读某个需要复杂认证的系统。另外搜索到的内容不代表权威模型很容易“看着像就信”你最好在技能里加一条约束“引用外部信息时必须标注来源和日期拿不准就明说不知道”。2.4 功能对比装 superpowers 前后的 Codex 差别有多大我用一张表复盘一下装 superpowers 前后的差异方便你判断值不值得花这半小时能力维度裸奔 Codex加 superpowers 之后跨会话记忆没有完全失忆有长期记忆规范一次写入长期可用自定义流程只能靠每次写提示词技能文件写好即用可复用可分享联网查资料默认不支持可搜索、抓取网页并引用来源团队经验沉淀无经验随会话消失技能和记忆全部落盘进 Git 管理上下文开销每次交代背景占大量上下文技能按需加载记忆按需读取看完这张表你应该能理解我为什么说它“值得半小时”它相当于把原来每次开工前都要做的“背景交代”一次性做成了基础设施。后面所有会话都在吃这套基础设施的红利。3. 安装与初始化从零到能跑通全程实操记录3.1 前置条件Codex CLI 装好没有superpowers 是 Codex 的插件所以前提是本地已经装好 Codex CLI并且能正常对话。装好之后先敲一下命令确认环境codex --version如果这条命令报 not found先去把 Codex CLI 装好再来。不建议在没有确认基础环境的情况下直接装插件否则后面排查问题会多一层干扰。顺便说一句我装的时候用的是较新的 Codex 版本如果你手里的版本比较老插件机制可能不完整建议先升级。3.2 安装插件一条命令的事安装本身很简单codex plugins install superpowerslatest这个命令会把 superpowers 插件拉取并注册到 Codex 的插件体系里。安装过程一般很快如果网络状况不好可能要等一会儿。装完后可以用下面的命令确认它能被识别codex plugins list能看到 superpowers 在列表里就算装上了。这里有个小建议安装前先看一眼官方仓库的 README。这类工具迭代很快今天的命令可能明天就变了以官方文档为准永远是最稳妥的做法。3.3 初始化codex superpowers 干了什么装完插件还不算完还要初始化codex superpowers我第一次跑这个命令的时候它做了几件事创建了技能目录、往我的 Codex 配置目录里写入了一套默认技能、在当前项目目录生成了一个 SUPERPOWERS.md 文件相当于技能索引里面列出当前可用的技能清单和一句话描述还问我要不要修改一些配置项。不同版本的交互细节可能不一样比如中间可能会问你是否要开启某个功能我建议第一次全选默认跑通之后再去调。这里有个容易忽略的点SUPERPOWERS.md 是 Codex 上下文里实际加载的那份清单。每次启动 Codex 时它通过这个文件知道现在有哪些技能可用再按需去读具体技能文件。所以这个文件很重要最好别删也别随手改坏格式。3.4 验证安装是否成功初始化完成后我习惯做三步验证。第一步查看技能目录结构确认内置技能已经落盘ls ~/.codex/skills第二步打开项目目录下的 SUPERPOWERS.md看一眼技能清单是不是完整。第三步启动 Codex直接问一句“你现在有哪些技能可以用分别什么时候用”如果模型能列出 skill-editor、memory、web-research 等技能并说清用途说明 superpowers 已经在上下文中生效了。如果模型一脸茫然多半是初始化没跑完或者你启动 Codex 的目录跟生成 SUPERPOWERS.md 的目录不一致后面排查章节会细说。4. 核心技能逐个拆解与实战用法4.1 skill-editor造技能的技能superpowers 内置了一套“元技能”其中 skill-editor 是我用得最多的。它的作用就是帮你创建、修改、审查技能文件。我一般这么用直接跟 Codex 说“我想写一个技能功能是 XXX帮我按 superpowers 的规范生成一个技能文件”它会自动调起 skill-editor生成带 YAML frontmatter 的 Markdown还会提示我放在哪个目录。生成之后不要直接就用一定要做两步人工检查一是检查 description 的触发条件写得够不够清楚二是检查正文步骤是不是可执行。我自己犯过的错是让 skill-editor 一次帮我写三个技能结果每个都写得很泛后来改成一次只写一个、写完立刻实测质量立刻上来了。记住skill-editor 是提效工具不是免责工具最终质量责任在你。4.2 memory记忆的正确打开方式再说说记忆的正确用法。长期记忆不是让你把整个项目文档都塞进去那就把上下文撑爆了。我的经验是只记四类东西长期有效的项目约定、用户明确说过的偏好、反复出现的技术决策、以及那些“你花半小时才查明白”的关键结论。用的时候也有技巧。想让 Codex 记住一件事说清楚是“长期还是本次会话”“记住长期我们项目禁止使用 System.out.println 打日志”比含糊地说“记住啊”要好得多。查询记忆的时候同样要具体比如“我们之前对数据库迁移是怎么约定的”模型会去检索记忆文件而不是凭空编一个。最后记忆文件要定期清理。我见过有人把记忆当垃圾桶堆了几百条结果每次会话都要读一堆无用内容反而拖慢了响应。4.3 web-research联网查资料的正确姿势web-research 适合干的事我排个优先级查库的最新文档、查某个 API 的用法示例、确认某个技术方案是否可行、调研同类项目的做法。不适合干的事查内部系统资料、抓需要登录才能看的内容、看动态渲染的复杂页面。在使用上我有一条硬性要求写进了项目技能里“所有来自网页的信息必须给出来源 URL如果网页内容与已有知识冲突以网页为准但要说明差异。”这么做的好处是 Codex 就算引用错了我也能顺着来源去核不会把错误信息一路带进代码里。4.4 其他基础技能plan、git-workflow、thinking 要不要装superpowers 还附带了一些基础技能比如 plan先做计划再执行、thinking复杂问题先展开思考再回答、git-workflow按规范流程操作 Git。我的观点是不要全装按需启用。这些技能本身不是越多越好每多一个清单就长一分匹配的干扰也大一分。我当时先留了 skill-editor、memory、web-research 三个外加自己写的两个项目技能。跑了两三个真实任务之后才决定要不要加 plan 这类流程型技能。这种“最小可用”的启动方式能帮你更快看清 superpowers 到底解决了什么问题而不是被一堆功能淹没。5. 把 Superpowers 用在 Java 项目里一个完整的实战案例5.1 为什么单独聊 Java搜索热词里“superpowers java”热度不低说明很多人在意它跟 Java 生态怎么配合。这并不奇怪——Java 项目恰恰是最适合技能化的一类项目约定多包结构、分层、命名、样板多POJO、Mapper、DTO、构建链路繁琐Maven/Gradle、测试、打包。如果你让裸奔的 Codex 去改一个 Spring Boot 项目它大概率会给你写出“能用但不像团队风格”的代码。有了技能就不一样了你等于把团队的《开发规范手册》直接放进模型的脑子里。5.2 场景设定一个需要约束的 Spring Boot 项目假设我们接手的项目有这些约定很典型包结构以 com.example 开头分层严格——Controller 只做参数校验和路由Service 层写业务逻辑数据访问走 Mapper使用 Lombok 减少样板代码测试用 JUnit 5 加 AssertJ构建用 Maven提交前必须编译且测试全绿。在没有技能的时候我让 Codex 加一个接口它可能直接在 Controller 里写业务逻辑、手动写 getter/setter、测试风格跟项目里旧的测试对不上。每次都要我在 Review 阶段反复纠正非常烦。这个场景就是写技能的完美动机。5.3 动手写两个 Java 项目技能我先写一个规范类技能 java-spring-conventions内容大概是这样的--- name: java-spring-conventions description: Use when writing or modifying Java code in this Spring Boot project. Enforces layering, naming, Lombok usage and exception handling conventions. --- # 项目 Java 编码约定 - 包名前缀统一为 com.example新增类必须先放在正确的子包下。 - Controller 只做参数校验、路由和响应封装业务逻辑一律在 Service 层。 - Service 接口定义方法Impl 类实现禁止在 Controller 里直接操作 Repository。 - 使用 Lombok 的 Data / Builder / Slf4j禁止手写 getter/setter。 - 日志使用 Slf4j 的 log禁止 System.out.println。 - 异常业务异常抛自定义 BizException禁止裸抛 RuntimeException。 - 方法命名查询用 get/find 开头新增用 create/add修改用 update删除用 delete。然后是构建与测试流程技能 maven-safe-build--- name: maven-safe-build description: Use after modifying Java code to verify the build and relevant tests. Run compile first, then targeted tests, then full build if time permits. --- # Maven 构建与测试流程 1. 运行 mvn -q compile -DskipTests确保编译通过。 2. 针对改动的类运行相关测试mvn -q test -DtestXXXTest。 3. 若失败先阅读第一处失败信息定位原因后再修复禁止盲目反复重跑。 4. 相关测试通过后如果改动涉及公共层再跑 mvn -q test 全量回归。 5. 任何一步失败都要停下来向用户说明失败原因而不是绕过测试。这两个技能文件就是团队的硬约束。放在项目的技能目录里All 就绪。5.4 实测过程让 Codex 按技能干活技能文件放好后我重启 Codex确保新技能被加载给了一个真实任务“在 UserService 里增加一个根据邮箱查询用户的方法并补一个测试。”然后观察它的行为。没加技能之前它可能会在 Controller 里顺手写查询逻辑、用 JPA 的 findByEmail 直接在接口里定义、测试类里用 System.out 打印结果。加了技能之后它明显先检索了 java-spring-conventions然后给出的代码Controller 只暴露端点、Service 接口加方法、Impl 里实现、用 Optional 处理查不到的情况、测试用 AssertJ 断言、日志用 Slf4j。代码风格跟项目完全一致我 Review 起来几乎不用改。这个对比让我很受触动不是 Codex 写不了符合规范的代码是你没给它规范。superpowers 的价值就是让规范的传递不再是每次对话前的一段临时提示词而是项目的一部分。5.5 把技能沉淀为团队资产技能文件是可以进 Git 的。我把这两个技能文件放到一个 skills 目录并在项目的 README 里写了说明“用 Codex 干活前先确认技能已安装。”新同事拉到项目初始化一下 Codex就自动获得整套团队 AI 行为准则。后面再有人发现 Codex“不听话”第一反应不是改提示词而是看技能哪里写得没覆盖到然后更新技能所有人同步受益。这个过程其实就是在把“隐性经验”变成“显性资产”。你可以把它类比成原来团队里的《开发规范文档》只不过这份规范不是给人看的是给 AI 看的而且 AI 真的会执行。6. 常见问题、避坑指南与排查思路6.1 安装与初始化问题速查我整理了一张表覆盖我见到过的大部分问题常见问题可能原因处理方式codex plugins 命令报错Codex 版本过旧老版本没有插件机制先升级 Codex CLI 再装装完没有生成 SUPERPOWERS.md只装插件没跑初始化执行codex superpowers完成初始化模型不认技能清单启动目录跟生成索引的目录不一致在项目根目录启动确认 SUPERPOWERS.md 存在新写的技能不生效技能文件没放在正确目录或格式错误检查 YAML frontmatter 是否完整重启会话上下文异常变大技能或者记忆文件写太多精简技能描述定期清理记忆插件更新后行为变化版本迭代改了交互看官方更新日志必要时重新初始化6.2 运行时的典型翻车现场翻车现场一技能加载了但模型不按技能走。我遇到过 Codex 明明看到技能清单还是自顾自地回答。后来发现原因是我把技能描述写得太泛任务描述又多又乱模型选择了自由发挥。解决办法任务描述写清楚点或者在对话里直接指定“按 xxx 技能执行”。翻车现场二记忆写崩了。有一次我让 Codex 记住的东西太多包括一些临时任务结果后面每次对话它都要读一堆没用的长期记忆响应又慢又容易跑偏。后来我养成习惯每周日花十分钟清理记忆文件把过期的、临时的、已经失效的条目删掉。翻车现场三联网查出来的资料是过时的。web-research 搜到一个博客讲的是旧版 APICodex 信了写出来的代码用到已废弃的方法。这就是为什么我坚持在上面提到的技能里加“必须标注来源和日期”。信息带来源你才能核、才能纠。6.3 这个月踩过的坑希望你别再踩最后说几个最有代表性的坑。第一个是“技能描述用词太文艺”。我最早写的一个技能描述是“帮助处理项目中遇到的常见问题”结果模型根本不知道什么时候该触发改成“Use when the user reports a build failure or test failure in the Maven project”之后立刻精准命中。触发条件要写场景不要写能力。第二个坑是“一个技能塞了太多东西”。我试图写一个“全流程开发技能”从建表到部署全在里面结果模型执行到第三步就忘了后面内容。拆成独立技能之后每个都短小聚焦执行完整度大幅提升。第三个坑是在团队里直接全量推没给过渡期。有人新装的 Codex 突然“变得不听话”其实是技能和记忆还没跟他本人磨合好。后来我调整了策略新成员先装基础技能用一周顺手了再根据自己的工作流逐步加新技能。superpowers 这东西适合渐进式引入不适合一步到位。我个人在实际操作里的体会是superpowers 最值钱的地方不是某一个技能而是它逼你把“想让 AI 怎么干活”这件事想清楚了。技能写得越具体Codex 干活越可靠。如果你还在观望我建议先花二十分钟装起来写一个你最头疼场景的小技能跑完一个真实任务再下结论。这个投入大概率不会亏。
