如果你最近在折腾 Codex CLI多半会碰到一个让人上火的场景这个号称能独立写代码的智能代理每开一个新会话就瞬间失忆。你上周花一整天教给它的项目结构、接口规范、测试习惯它一个都不记得。于是你跟我一样开始在搜索框里敲codex superpowerssuperpowers 安装superpowers 使用教程这些词。我最初也以为 superpowers 是什么玄学配置装完才发现它解决的就是这个最痛的痛点给失忆的 Codex 配上一套职业技能库让它像一位有工龄的老工程师一样干活。这篇不打算写成官方文档的复述。我会把 superpowers 是什么、怎么装、技能系统怎么运作、怎么在 Java 项目里用起来、以及和其他工具怎么配合全部按我实际操作下来的顺序讲一遍。你照着做大概率能在一个小时内跑通第一个自建技能。1. superpowers 不是模型也不是客户端它是一套工作制度1.1 为什么纯靠 Prompt 会那么累Codex 这类 AI 编程代理最大的优点是单次会话里理解能力强最大的缺点恰恰是它的无状态。每次新会话它只知道系统提示、当前目录和你的输入。你项目里的隐性知识——构建命令、代码风格、目录约定、上个月刚踩过的坑——它一概不知道只能靠你反复粘贴。我算过一笔账一个中型项目的废话上下文大概有 2000 到 3000 字。每开一次会话就粘一遍浪费 token 不说还会稀释真正要改的代码。更麻烦的是不同项目之间的约定还不一样A 项目用 Maven 多模块B 项目是 Gradle 单模块同一个 Codex 分身乏术只会拿最近一次对话的习惯去套所有项目。superpowers 的思路就是把这类散落在人脑里的项目知识抽出来变成 Codex 可以按需加载的工具卡。它不是提示词技巧而是一套让 Codex 具备长期工作记忆和行为规范的结构化框架。这也是它和单纯写一个 system prompt 的本质区别知识被拆成了独立的、可维护的模块。1.2 核心组成技能、记忆、子代理、检查点组件作用生活类比技能Skills把高频任务的执行步骤写成结构化 Markdown 文件Codex 按需加载执行老师傅的操作手册记忆Memory跨会话沉淀项目约定、结论和偏好新会话自动读取工作笔记子代理Subagents并行拆分复杂任务让多个 Codex 实例各管一段拆小组分头干活检查点Checkpoint每次关键操作前自动做本地快照出问题能回滚游戏存档点这四个组件里最核心也最值得花时间研究的是技能系统。记忆是它的基础设施子代理和检查点是增强项。我后面会分别拆开讲但请你记住一个总原则superpowers 的价值不取决于装没装上而取决于你的技能库有没有内容、内容够不够贴近真实工作流。1.3 适合谁用先说清楚它不是什么。superpowers 不能替代 Codex也不改变 API 调用方式。它适合的是下面几种人已经装了 Codex CLI但觉得每次都要教它项目背景、效率上不去的人同时维护多个项目、每个项目约定都不一样的开发想让 AI 干活风格更可控、输出更稳定而不是每次随缘的团队以及愿意花一点时间打磨模板、而不是只想装完就自动变强的人。如果你是第一次听说 Codex纯新手我的建议是先正常跑通一次 Codex 基础会话再装 superpowers。否则出了问题你很难判断是模型问题、网络问题还是技能配置问题。工具是好工具但排查成本也得算进去。2. 从零装到能用安装流程与验证方法2.1 前置条件检查安装 superpowers 之前请先确认三件事。第一Node.js 版本在 18 以上很多插件脚本依赖较新的运行时特性第二Codex CLI 已经装好并且能正常跑通一次对话执行codex --version能看到版本号第三本机装了 git因为检查点功能要依赖本地 git 仓库做快照。还想多说一句别跳过基础验证。我见过太多人装完 superpowers 后发现 Codex 本身就没配好结果把所有问题都归到插件头上。先跑通基础链路再谈增强排查会省力很多。2.2 安装步骤我安装的时候走的是 npm 全局安装加初始化脚本的路线。执行下面两条命令npm install -g superpowers superpowers initinit会在你的用户目录下创建 superpowers 需要的目录结构包括技能目录、记忆目录和配置文件模板。如果你更喜欢源码方式也可以把官方仓库 clone 到本地再执行 make install。不同版本对安装路径的细节要求可能不一样强烈建议以当前官方 README 为准。装完之后要让 Codex 加载插件。以我当时用的版本为例需要在~/.codex/config.toml里追加这样一段配置[plugin] enabled true然后重启 Codex 会话让配置生效。如果你的 Codex 版本较新配置文件位置可能从~/.codex迁移到了~/.config/codex路径以你本机实际输出为准。这不是含糊而是这类插件工具的常态主程序一升级路径就变。注意不同版本的配置路径可能从~/.codex迁到~/.config/codex以你本机的实际输出为准。插件没加载时先查路径不要急着改技能内容。2.3 怎么确认装好了验证安装不需要看日志直接在 Codex 会话里做三件事。第一输入/plugins之类的管理命令看有没有 superpowers 的条目第二直接问一句你现在加载了哪些技能看它能不能列出技能清单第三让 Codex 执行一次最简单的技能动作比如让它列出可用的技能。三件事都能正常回应基本就是装好了。我自己的习惯是再额外测试一下记忆目录有没有生成。装完跑了几轮对话之后去用户目录下看一眼 memory 文件夹里面如果开始出现 markdown 文件就说明记忆链路也通了。2.4 安装过程中最常见的三个报错报错现象可能原因处理办法找不到 superpowers 命令npm 全局目录没进 PATH重装 npm 包或把 npm 全局 bin 目录手动加入 PATH插件配置不生效Codex 版本太旧或不支持插件字段升级 Codex按官方 README 重新执行 init技能装了但会话里没有插件加载失败但没有明显报错打开 Codex 日志文件搜索 superpowers 相关关键字这三个坑我一个不落全踩过。尤其是第三个它最阴的地方在于表面静默你以为技能没写好实际上插件压根没加载。所以排查前先确认加载再动技能内容。3. 核心机制拆解技能、记忆、子代理和检查点各管什么3.1 技能是怎么被命中的整个技能系统的核心是 Markdown 文件加一个索引。启动时Codex 读取技能目录里的所有技能文件生成一份目录这份目录通常叫 SKILLS.md。用户提问后模型根据每个技能文件里的描述信息判断当前需求要不要调用技能一旦命中就读取那个技能文件全文严格按里面的步骤执行。所以技能文件里最关键的部分不是正文而是开头那段 YAML 元信息尤其是description和when_to_use两个字段。写得太宽泛模型会在不该用的时候乱用写得太窄该用的时候又完全想不起来。我的经验是把用户可能使用的自然说法直接列进when_to_use比如代码乱了review 一下这个 PR 有问题比写一句抽象的当用户要求代码审查时管用得多。3.2 记忆机制解决AI 失忆的地基记忆目录本质上是一个 markdown 知识库。Codex 在会话中会把重要结论、用户的偏好、项目的特殊约定按规则沉淀成带日期或带主题的文件新会话启动时再自动加载。你可以把它理解成给 Codex 配了一本自动更新的工作笔记。但记忆不是越多越好。我见过有人开了记忆功能之后brain 文件里什么都有包括今天天气不错这类废话结果模型读取时反而被噪音干扰。记忆的价值在于结论不在于过程。项目里真正稳定的约定、踩过坑之后得出的规则才值得写进去。提示记忆的价值在于结论不在于过程。只让模型沉淀稳定的事实别让它记录聊天细节。3.3 子代理和检查点规模化和兜底子代理的设计思路是把一个大任务拆给多个 Codex 实例并行去做各自跑各自的 context再把结果汇总回来。适合代码审查、多文件重构这类天然可以分块的任务。当然并行也带来资源占用翻倍的问题所以别什么事都开子代理。检查点则是另一个方向的兜底在每次关键工具调用之前superpowers 会在本地仓库创建一个快照提交。这样如果 AI 中途把代码改乱了你随时可以回退到操作前状态。注意它是本地提交不会推到远程不影响同事的 git 历史。这一点我特别喜欢等于给每次 AI 操作都配了后悔药。4. 手写第一个技能一个代码审查技能从零到跑通4.1 先选一个高频场景写技能别从看起来很酷开始要从你每周都在重复的事开始。对我来说最典型的高频场景是代码审查。每次要 review 分支改动我都要重新告诉 Codex先看哪些文件、重点检查什么、输出什么格式。这些话说了无数遍写成一个技能一劳永逸。4.2 技能文件长什么样--- name: code-review description: 对当前分支的代码改动做一次系统检查输出风险清单和修改建议 when_to_use: 当用户要求审查代码、检查 PR、评估 diff 改动质量时 version: 1.0.0 --- # 执行步骤 1. 先运行 git diff HEAD --stat 了解改动范围 2. 按文件逐个阅读 diff不要跳过大文件 3. 对照下面的检查清单逐项排查 - [ ] 是否引入新的外部依赖 - [ ] 异常吞掉后是否有日志 - [ ] 是否有明显的性能风险点 - [ ] 改动是否覆盖了边界条件 # 输出格式 输出三部分改动概览、风险清单按风险从高到低、建议的下一步操作。把文件存到 superpowers 的技能目录下init 时会生成一个 custom_skills 之类的目录文件名最好和技能名一致方便检索。光给出文件还不够我有必要解释一下为什么这么写。4.3 每个字段为什么重要description是模型的广告位。它决定了用户在说什么样的话时模型会想起这个技能。所以要把用户可能的表达都写进去。when_to_use更具体一些相当于触发条件的集合。version不是摆设技能的策略会迭代版本号能让你在出问题时快速回溯。正文部分更像给员工下的工作指令而不是科普文档。你要明确写出先做什么、再做什么、每步产出什么、用什么格式输出。模型不会自动补全你省略的细节你写得越具体执行越稳定。4.4 注册、触发和调试技能文件放好后重启 Codex 会话或者执行技能重载命令让索引更新。然后用一句自然的话触发用 code-review 技能看一下当前分支改动。如果它正确地输出了改动概览和风险清单说明链路通了。如果没触发最常见的两个原因一是技能目录结构不对索引没扫到文件二是when_to_use写得和你的触发语句对不上。调试技巧是在正文最后加一步结束时说明本次调用了哪个技能这样你能立刻确认它是否真的读了技能文件而不是凭感觉乱答。提示如果技能没触发先确认索引到底有没有扫到文件再检查触发条件写法。这两个原因占了九成。5. Java 项目里的实战沉淀把 Maven、JUnit 和异常排查变成技能5.1 Java 场景为什么值得单独做技能Java 项目的复杂度往往不在语言本身而在工具链Maven 多模块、Gradle 多仓库、依赖冲突、Surefire 测试报告每一层都有自己的一套规则。Codex 虽然懂这些概念但每次都要在上下文里重新拼装一次效率和稳定性都很差。更现实的问题是Java 项目的异常堆栈信息噪音太大。一个线上报错能有一两百行堆栈外层全是框架包装真正的业务根因藏在某一处 Caused by 里。如果每次都要临时指导 Codex 怎么剥洋葱不如直接把这个过程写成技能。5.2 一个可复用的 Java 异常排查技能--- name: java-stacktrace-triage description: 分析 Java 异常堆栈并定位根因给出可执行的修复建议 when_to_use: 用户贴出 Java 异常堆栈、报错日志或询问线上故障原因时 version: 1.1.0 --- # 工作流程 1. 从堆栈底部向上找第一处 Caused by不要被外层包装异常误导 2. 过滤 JDK 内部方法重点看业务包名下出现频率最高的类 3. 按异常类型分流处理 - NullPointerException沿调用链找最可能为 null 的对象 - ClassNotFoundException执行 mvn dependency:tree -Dverbose 查依赖冲突 - SQLException检查连接池配置和事务边界区分数据库与业务层问题 4. 给出修复建议时必须附上对应的代码位置和改动思路 # 输出格式 根因一句话概括、完整调用链摘要、按可能性排序的修复建议。我在实际使用中给这个技能升过两次版本。第一次是加上了mvn dependency:tree -Dverbose这个排查依赖冲突的具体命令第二次是要求它区分数据库层和业务层的问题避免每次都在错误的方向上浪费两轮对话。版本迭代的记录全写在 frontmatter 里回头看非常清晰。5.3 Java 技能的调优经验第一技能里可以直接写命令让 Codex 自己执行。比如依赖冲突排查与其让它猜不如直接告诉它跑哪条 Maven 命令、看输出哪一段。第二不要做一个Java 万能技能要拆成 build-fix、test-write、stacktrace-triage 这样粒度更小的技能每个只解决一类问题。技能颗粒度越细命中率越高内容也越好维护。第三如果团队项目里有自定义的代码规范一定要单独开一个技能记录规范原文和检查方式这比在系统提示里塞一大段话有效得多。6. 和其他工具协同worbuddy 这一类场景怎么接6.1 为什么总有人问worbuddy 怎么用 superpowers我在开发者社区里没少看到 worbuddy 怎么用 superpowers 这个问题搜索热度还不低。稍微拆一下就知道问这种问题的人多半不是从原生 Codex CLI 入手的而是用某个封装好的图形化工具或对话外壳。工具不同但问题本质是一样的我这边已经有一套 Agent 工作流了superpowers 这套技能体系能不能也在这里面生效。6.2 接入的通用原则superpowers 的插件机制不是跟某一个客户端绑死的它生效的前提是两条底层跑的是 Codex 的 agent 引擎并且引擎能读取你本地的 Codex 配置和插件目录。只要这两条满足无论你是用官方命令行、IDE 里的 Codex 面板还是 worbuddy 这类第三方封装工具技能和记忆都能生效只是外壳不同。反过来如果某个封装工具自带独立的会话隔离不读本机~/.codex的配置那 superpowers 对它就是透明的技能自然不会被触发。这种情况的处理办法不是硬改工具而是在那个工具里找有没有加载外部配置或自定义配置文件的入口让它指向同一份配置。我不具体评价任何一款产品但这个接入原理对绝大多数工具都适用。6.3 我推荐的三种协同姿势第一种重活交给原生 CLI。需要跑技能高频的场景直接开官方 Codex 会话技能体系最完整。第二种日常轻量对话留在封装工具里查资料、解释概念这种不需要项目上下文的活随便哪个外壳都行。真遇到用 code-review 技能审查当前改动这类需求再切回 CLI。第三种把 superpowers 接进脚本和 CI用类似codex exec 用 code-review 技能审查当前改动的方式在流水线里批量执行技能。这样技能不只服务于交互式对话还能变成整个研发流程的一部分。7. 我踩过的坑和我现在离不开的几个效率习惯7.1 高频坑清单现象原因解决办法技能永远不触发when_to_use写得太抽象把用户可能说的原话直接列进触发条件多个技能互相冲突不同技能覆盖同一任务合并成一个技能保留唯一入口记忆文件越来越乱brain 里什么细节都记按项目或月份建子目录只记稳定结论检查点把 git 历史搞乱快照提交进了正常分支确认检查点提交有专属标识必要时忽略对应目录升级 Codex 后技能失效插件路径或配置字段变化重新执行 init按新 README 迁移配置这些坑我在前文里其实都零散提过这里集中列出来是因为它们最常被归错因。尤其是最后一个Codex 一升级插件就失效的情况我遇过不止一次。遇到先别怀疑自己写错了技能先查加载。7.2 我现在离不开的几个效率习惯第一新项目落地第一件事就是建一个项目级记忆目录和三个基础技能构建技能、测试技能、规范技能。花二十分钟建好后面几百次会话都在受益。第二每周翻一次 brain 文件删掉过时结论。AI 不会自己整理记忆这件事必须人来做否则知识库会像无人打理的 wiki 一样慢慢废掉。第三技能升级时把变更原因写进 frontmatter比如加一个changelog字段记一行v1.1.0 增加依赖冲突排查命令。这不是仪式感是几个月后你自己回看时唯一能依赖的线索。第四给高频技能准备一个固定测试输入每次改完技能就用同一段话触发一遍对比输出是否稳定。这一步能帮你快速抓住改坏了哪里而不是在真实需求里试错。最后再说一个我自己的习惯。每次新建仓库我都会先把 .gitignore、依赖安装命令、测试命令这些最基础最容易让 Codex 犯错的常识写成三个平平无奇的技能。名字一点都不炫但正是这三个技能让 Codex 从每次都要重新解释一遍变成了上手就能干活。superpowers 不是什么魔术它更像一套手工打磨的流程。你花在技能上的每一分钟都会在之后无数次的会话里翻倍捞回来。照着这篇文章把它跑通之后剩下的版本迭代就该是你自己的故事了。
如果你最近在折腾 Codex CLI多半会碰到一个让人上火的场景这个号称能独立写代码的智能代理每开一个新会话就瞬间失忆。你上周花一整天教给它的项目结构、接口规范、测试习惯它一个都不记得。于是你跟我一样开始在搜索框里敲codex superpowerssuperpowers 安装superpowers 使用教程这些词。我最初也以为 superpowers 是什么玄学配置装完才发现它解决的就是这个最痛的痛点给失忆的 Codex 配上一套职业技能库让它像一位有工龄的老工程师一样干活。这篇不打算写成官方文档的复述。我会把 superpowers 是什么、怎么装、技能系统怎么运作、怎么在 Java 项目里用起来、以及和其他工具怎么配合全部按我实际操作下来的顺序讲一遍。你照着做大概率能在一个小时内跑通第一个自建技能。1. superpowers 不是模型也不是客户端它是一套工作制度1.1 为什么纯靠 Prompt 会那么累Codex 这类 AI 编程代理最大的优点是单次会话里理解能力强最大的缺点恰恰是它的无状态。每次新会话它只知道系统提示、当前目录和你的输入。你项目里的隐性知识——构建命令、代码风格、目录约定、上个月刚踩过的坑——它一概不知道只能靠你反复粘贴。我算过一笔账一个中型项目的废话上下文大概有 2000 到 3000 字。每开一次会话就粘一遍浪费 token 不说还会稀释真正要改的代码。更麻烦的是不同项目之间的约定还不一样A 项目用 Maven 多模块B 项目是 Gradle 单模块同一个 Codex 分身乏术只会拿最近一次对话的习惯去套所有项目。superpowers 的思路就是把这类散落在人脑里的项目知识抽出来变成 Codex 可以按需加载的工具卡。它不是提示词技巧而是一套让 Codex 具备长期工作记忆和行为规范的结构化框架。这也是它和单纯写一个 system prompt 的本质区别知识被拆成了独立的、可维护的模块。1.2 核心组成技能、记忆、子代理、检查点组件作用生活类比技能Skills把高频任务的执行步骤写成结构化 Markdown 文件Codex 按需加载执行老师傅的操作手册记忆Memory跨会话沉淀项目约定、结论和偏好新会话自动读取工作笔记子代理Subagents并行拆分复杂任务让多个 Codex 实例各管一段拆小组分头干活检查点Checkpoint每次关键操作前自动做本地快照出问题能回滚游戏存档点这四个组件里最核心也最值得花时间研究的是技能系统。记忆是它的基础设施子代理和检查点是增强项。我后面会分别拆开讲但请你记住一个总原则superpowers 的价值不取决于装没装上而取决于你的技能库有没有内容、内容够不够贴近真实工作流。1.3 适合谁用先说清楚它不是什么。superpowers 不能替代 Codex也不改变 API 调用方式。它适合的是下面几种人已经装了 Codex CLI但觉得每次都要教它项目背景、效率上不去的人同时维护多个项目、每个项目约定都不一样的开发想让 AI 干活风格更可控、输出更稳定而不是每次随缘的团队以及愿意花一点时间打磨模板、而不是只想装完就自动变强的人。如果你是第一次听说 Codex纯新手我的建议是先正常跑通一次 Codex 基础会话再装 superpowers。否则出了问题你很难判断是模型问题、网络问题还是技能配置问题。工具是好工具但排查成本也得算进去。2. 从零装到能用安装流程与验证方法2.1 前置条件检查安装 superpowers 之前请先确认三件事。第一Node.js 版本在 18 以上很多插件脚本依赖较新的运行时特性第二Codex CLI 已经装好并且能正常跑通一次对话执行codex --version能看到版本号第三本机装了 git因为检查点功能要依赖本地 git 仓库做快照。还想多说一句别跳过基础验证。我见过太多人装完 superpowers 后发现 Codex 本身就没配好结果把所有问题都归到插件头上。先跑通基础链路再谈增强排查会省力很多。2.2 安装步骤我安装的时候走的是 npm 全局安装加初始化脚本的路线。执行下面两条命令npm install -g superpowers superpowers initinit会在你的用户目录下创建 superpowers 需要的目录结构包括技能目录、记忆目录和配置文件模板。如果你更喜欢源码方式也可以把官方仓库 clone 到本地再执行 make install。不同版本对安装路径的细节要求可能不一样强烈建议以当前官方 README 为准。装完之后要让 Codex 加载插件。以我当时用的版本为例需要在~/.codex/config.toml里追加这样一段配置[plugin] enabled true然后重启 Codex 会话让配置生效。如果你的 Codex 版本较新配置文件位置可能从~/.codex迁移到了~/.config/codex路径以你本机实际输出为准。这不是含糊而是这类插件工具的常态主程序一升级路径就变。注意不同版本的配置路径可能从~/.codex迁到~/.config/codex以你本机的实际输出为准。插件没加载时先查路径不要急着改技能内容。2.3 怎么确认装好了验证安装不需要看日志直接在 Codex 会话里做三件事。第一输入/plugins之类的管理命令看有没有 superpowers 的条目第二直接问一句你现在加载了哪些技能看它能不能列出技能清单第三让 Codex 执行一次最简单的技能动作比如让它列出可用的技能。三件事都能正常回应基本就是装好了。我自己的习惯是再额外测试一下记忆目录有没有生成。装完跑了几轮对话之后去用户目录下看一眼 memory 文件夹里面如果开始出现 markdown 文件就说明记忆链路也通了。2.4 安装过程中最常见的三个报错报错现象可能原因处理办法找不到 superpowers 命令npm 全局目录没进 PATH重装 npm 包或把 npm 全局 bin 目录手动加入 PATH插件配置不生效Codex 版本太旧或不支持插件字段升级 Codex按官方 README 重新执行 init技能装了但会话里没有插件加载失败但没有明显报错打开 Codex 日志文件搜索 superpowers 相关关键字这三个坑我一个不落全踩过。尤其是第三个它最阴的地方在于表面静默你以为技能没写好实际上插件压根没加载。所以排查前先确认加载再动技能内容。3. 核心机制拆解技能、记忆、子代理和检查点各管什么3.1 技能是怎么被命中的整个技能系统的核心是 Markdown 文件加一个索引。启动时Codex 读取技能目录里的所有技能文件生成一份目录这份目录通常叫 SKILLS.md。用户提问后模型根据每个技能文件里的描述信息判断当前需求要不要调用技能一旦命中就读取那个技能文件全文严格按里面的步骤执行。所以技能文件里最关键的部分不是正文而是开头那段 YAML 元信息尤其是description和when_to_use两个字段。写得太宽泛模型会在不该用的时候乱用写得太窄该用的时候又完全想不起来。我的经验是把用户可能使用的自然说法直接列进when_to_use比如代码乱了review 一下这个 PR 有问题比写一句抽象的当用户要求代码审查时管用得多。3.2 记忆机制解决AI 失忆的地基记忆目录本质上是一个 markdown 知识库。Codex 在会话中会把重要结论、用户的偏好、项目的特殊约定按规则沉淀成带日期或带主题的文件新会话启动时再自动加载。你可以把它理解成给 Codex 配了一本自动更新的工作笔记。但记忆不是越多越好。我见过有人开了记忆功能之后brain 文件里什么都有包括今天天气不错这类废话结果模型读取时反而被噪音干扰。记忆的价值在于结论不在于过程。项目里真正稳定的约定、踩过坑之后得出的规则才值得写进去。提示记忆的价值在于结论不在于过程。只让模型沉淀稳定的事实别让它记录聊天细节。3.3 子代理和检查点规模化和兜底子代理的设计思路是把一个大任务拆给多个 Codex 实例并行去做各自跑各自的 context再把结果汇总回来。适合代码审查、多文件重构这类天然可以分块的任务。当然并行也带来资源占用翻倍的问题所以别什么事都开子代理。检查点则是另一个方向的兜底在每次关键工具调用之前superpowers 会在本地仓库创建一个快照提交。这样如果 AI 中途把代码改乱了你随时可以回退到操作前状态。注意它是本地提交不会推到远程不影响同事的 git 历史。这一点我特别喜欢等于给每次 AI 操作都配了后悔药。4. 手写第一个技能一个代码审查技能从零到跑通4.1 先选一个高频场景写技能别从看起来很酷开始要从你每周都在重复的事开始。对我来说最典型的高频场景是代码审查。每次要 review 分支改动我都要重新告诉 Codex先看哪些文件、重点检查什么、输出什么格式。这些话说了无数遍写成一个技能一劳永逸。4.2 技能文件长什么样--- name: code-review description: 对当前分支的代码改动做一次系统检查输出风险清单和修改建议 when_to_use: 当用户要求审查代码、检查 PR、评估 diff 改动质量时 version: 1.0.0 --- # 执行步骤 1. 先运行 git diff HEAD --stat 了解改动范围 2. 按文件逐个阅读 diff不要跳过大文件 3. 对照下面的检查清单逐项排查 - [ ] 是否引入新的外部依赖 - [ ] 异常吞掉后是否有日志 - [ ] 是否有明显的性能风险点 - [ ] 改动是否覆盖了边界条件 # 输出格式 输出三部分改动概览、风险清单按风险从高到低、建议的下一步操作。把文件存到 superpowers 的技能目录下init 时会生成一个 custom_skills 之类的目录文件名最好和技能名一致方便检索。光给出文件还不够我有必要解释一下为什么这么写。4.3 每个字段为什么重要description是模型的广告位。它决定了用户在说什么样的话时模型会想起这个技能。所以要把用户可能的表达都写进去。when_to_use更具体一些相当于触发条件的集合。version不是摆设技能的策略会迭代版本号能让你在出问题时快速回溯。正文部分更像给员工下的工作指令而不是科普文档。你要明确写出先做什么、再做什么、每步产出什么、用什么格式输出。模型不会自动补全你省略的细节你写得越具体执行越稳定。4.4 注册、触发和调试技能文件放好后重启 Codex 会话或者执行技能重载命令让索引更新。然后用一句自然的话触发用 code-review 技能看一下当前分支改动。如果它正确地输出了改动概览和风险清单说明链路通了。如果没触发最常见的两个原因一是技能目录结构不对索引没扫到文件二是when_to_use写得和你的触发语句对不上。调试技巧是在正文最后加一步结束时说明本次调用了哪个技能这样你能立刻确认它是否真的读了技能文件而不是凭感觉乱答。提示如果技能没触发先确认索引到底有没有扫到文件再检查触发条件写法。这两个原因占了九成。5. Java 项目里的实战沉淀把 Maven、JUnit 和异常排查变成技能5.1 Java 场景为什么值得单独做技能Java 项目的复杂度往往不在语言本身而在工具链Maven 多模块、Gradle 多仓库、依赖冲突、Surefire 测试报告每一层都有自己的一套规则。Codex 虽然懂这些概念但每次都要在上下文里重新拼装一次效率和稳定性都很差。更现实的问题是Java 项目的异常堆栈信息噪音太大。一个线上报错能有一两百行堆栈外层全是框架包装真正的业务根因藏在某一处 Caused by 里。如果每次都要临时指导 Codex 怎么剥洋葱不如直接把这个过程写成技能。5.2 一个可复用的 Java 异常排查技能--- name: java-stacktrace-triage description: 分析 Java 异常堆栈并定位根因给出可执行的修复建议 when_to_use: 用户贴出 Java 异常堆栈、报错日志或询问线上故障原因时 version: 1.1.0 --- # 工作流程 1. 从堆栈底部向上找第一处 Caused by不要被外层包装异常误导 2. 过滤 JDK 内部方法重点看业务包名下出现频率最高的类 3. 按异常类型分流处理 - NullPointerException沿调用链找最可能为 null 的对象 - ClassNotFoundException执行 mvn dependency:tree -Dverbose 查依赖冲突 - SQLException检查连接池配置和事务边界区分数据库与业务层问题 4. 给出修复建议时必须附上对应的代码位置和改动思路 # 输出格式 根因一句话概括、完整调用链摘要、按可能性排序的修复建议。我在实际使用中给这个技能升过两次版本。第一次是加上了mvn dependency:tree -Dverbose这个排查依赖冲突的具体命令第二次是要求它区分数据库层和业务层的问题避免每次都在错误的方向上浪费两轮对话。版本迭代的记录全写在 frontmatter 里回头看非常清晰。5.3 Java 技能的调优经验第一技能里可以直接写命令让 Codex 自己执行。比如依赖冲突排查与其让它猜不如直接告诉它跑哪条 Maven 命令、看输出哪一段。第二不要做一个Java 万能技能要拆成 build-fix、test-write、stacktrace-triage 这样粒度更小的技能每个只解决一类问题。技能颗粒度越细命中率越高内容也越好维护。第三如果团队项目里有自定义的代码规范一定要单独开一个技能记录规范原文和检查方式这比在系统提示里塞一大段话有效得多。6. 和其他工具协同worbuddy 这一类场景怎么接6.1 为什么总有人问worbuddy 怎么用 superpowers我在开发者社区里没少看到 worbuddy 怎么用 superpowers 这个问题搜索热度还不低。稍微拆一下就知道问这种问题的人多半不是从原生 Codex CLI 入手的而是用某个封装好的图形化工具或对话外壳。工具不同但问题本质是一样的我这边已经有一套 Agent 工作流了superpowers 这套技能体系能不能也在这里面生效。6.2 接入的通用原则superpowers 的插件机制不是跟某一个客户端绑死的它生效的前提是两条底层跑的是 Codex 的 agent 引擎并且引擎能读取你本地的 Codex 配置和插件目录。只要这两条满足无论你是用官方命令行、IDE 里的 Codex 面板还是 worbuddy 这类第三方封装工具技能和记忆都能生效只是外壳不同。反过来如果某个封装工具自带独立的会话隔离不读本机~/.codex的配置那 superpowers 对它就是透明的技能自然不会被触发。这种情况的处理办法不是硬改工具而是在那个工具里找有没有加载外部配置或自定义配置文件的入口让它指向同一份配置。我不具体评价任何一款产品但这个接入原理对绝大多数工具都适用。6.3 我推荐的三种协同姿势第一种重活交给原生 CLI。需要跑技能高频的场景直接开官方 Codex 会话技能体系最完整。第二种日常轻量对话留在封装工具里查资料、解释概念这种不需要项目上下文的活随便哪个外壳都行。真遇到用 code-review 技能审查当前改动这类需求再切回 CLI。第三种把 superpowers 接进脚本和 CI用类似codex exec 用 code-review 技能审查当前改动的方式在流水线里批量执行技能。这样技能不只服务于交互式对话还能变成整个研发流程的一部分。7. 我踩过的坑和我现在离不开的几个效率习惯7.1 高频坑清单现象原因解决办法技能永远不触发when_to_use写得太抽象把用户可能说的原话直接列进触发条件多个技能互相冲突不同技能覆盖同一任务合并成一个技能保留唯一入口记忆文件越来越乱brain 里什么细节都记按项目或月份建子目录只记稳定结论检查点把 git 历史搞乱快照提交进了正常分支确认检查点提交有专属标识必要时忽略对应目录升级 Codex 后技能失效插件路径或配置字段变化重新执行 init按新 README 迁移配置这些坑我在前文里其实都零散提过这里集中列出来是因为它们最常被归错因。尤其是最后一个Codex 一升级插件就失效的情况我遇过不止一次。遇到先别怀疑自己写错了技能先查加载。7.2 我现在离不开的几个效率习惯第一新项目落地第一件事就是建一个项目级记忆目录和三个基础技能构建技能、测试技能、规范技能。花二十分钟建好后面几百次会话都在受益。第二每周翻一次 brain 文件删掉过时结论。AI 不会自己整理记忆这件事必须人来做否则知识库会像无人打理的 wiki 一样慢慢废掉。第三技能升级时把变更原因写进 frontmatter比如加一个changelog字段记一行v1.1.0 增加依赖冲突排查命令。这不是仪式感是几个月后你自己回看时唯一能依赖的线索。第四给高频技能准备一个固定测试输入每次改完技能就用同一段话触发一遍对比输出是否稳定。这一步能帮你快速抓住改坏了哪里而不是在真实需求里试错。最后再说一个我自己的习惯。每次新建仓库我都会先把 .gitignore、依赖安装命令、测试命令这些最基础最容易让 Codex 犯错的常识写成三个平平无奇的技能。名字一点都不炫但正是这三个技能让 Codex 从每次都要重新解释一遍变成了上手就能干活。superpowers 不是什么魔术它更像一套手工打磨的流程。你花在技能上的每一分钟都会在之后无数次的会话里翻倍捞回来。照着这篇文章把它跑通之后剩下的版本迭代就该是你自己的故事了。
