最近在折腾 Codex CLI 的时候我把一套叫 superpowers 的开源技能包接到了工作流里结果整个项目的推进方式发生了明显变化。以前让 AI 编程代理干活总有一种“碰运气”的感觉——同一个问题它今天这么修明天那么改有时候一次过有时候绕一大圈。装上 superpowers 之后最直观的感受是代理不再靠临场发挥办事而是像团队里一位有章法的工程师按流程拆解任务、按步骤执行、按约定交付。这篇文章就围绕 superpowers 到底是什么、它怎么改变 AI 编程的协作方式、如何在 Codex 环境里安装配置以及 Java 项目里怎么落地这套技能体系展开。不管你是刚接触编程代理的新手还是已经在用 Codex、Claude Code 这类工具的资深开发这篇文章都能给你一套可以直接抄作业的实操路径。1. 为什么 AI 编程代理需要“技能包”而不是靠一次性提示词硬问1.1 一次提示词驱动模式的崩溃现场先说一个真实场景。我之前让 Codex 去“修复某个 Java 模块的编译错误”任务看似简单但它第一次直接打开报错文件改了几行结果引入了新错误第二次它换了一种思路把整个方法重写了虽然能编译但破坏了已有逻辑第三次我不得不把完整的报错日志贴进提示词里它才勉强收敛。问题就在于AI 代理本质上是一个大模型驱动的执行者它的“行为方式”完全取决于当前上下文里装载了什么信息。你在提示词里塞得越多它表现得越好但每次重新对话这些信息几乎都要重来一遍。项目一旦复杂起来靠“一次性填空”式的提示词驱动根本无法保证稳定输出。1.2 技能包的本质像菜谱一样组织代理的做事方法superpowers 解决的就是“稳定复现优秀行为”这件事。它的核心思路特别朴素把代理做某类任务的步骤、约束、检查点沉淀成一份份结构化的 Markdown 文件我习惯叫它们“技能”。每个技能就像一张菜谱——上面写清楚这道菜需要什么食材、什么锅具、先做什么后做什么、出锅前怎么判断熟没熟。代理接到任务后不是凭空发挥而是先去“技能库”里找对应的菜谱然后严格按照菜谱执行。这种方法最大的价值是把“知识”从“上下文”里剥离出来。知识存放在独立文件里不随对话消失不占提示词配额还能被多个任务、多个代理反复引用。你可以在技能库里放一个“修复 Java 编译错误”的技能里面写明先跑 mvn compile 抓取完整错误信息再逐个定位出错文件修改后重新编译确认最后跑一遍相关单元测试。之后你再让代理修复编译问题它就会自动检索并调用这个技能而不是像第一次那样乱撞。1.3 superpowers 的整体定位让代理拥有自学习能力这里要说明一点superpowers 并不只是一个静态的提示词集合它本质上是一套“代理技能框架”。它给代理定义了怎么理解技能文件、怎么匹配技能、怎么按步骤执行、怎么在任务中途发现技能不足时自己补写新技能。这套机制最关键的一点是“代理可以自己创建技能”。举个例子代理在修改某个旧代码时发现项目里有一套特殊的构建流程它可以在完成修改后顺手把这个流程记录成一个新技能下次遇到同类项目就能直接调用。说白了superpowers 不仅给了代理鱼还教会了它怎么结网、怎么保存猎物。1.4 我最终选择这套方案的核心原因市面上类似的方案其实有不少有人喜欢把各种提示词写进系统提示里有人用自定义的 CLI 工具封装固定流程。我最终选择 superpowers 这条路原因是它有几个别人给不了的好处。第一技能文件不占用对话上下文。如果你把一套完整的工作规范塞进 system prompt几十次对话之后上下文窗口大概率会被撑爆。但技能文件是外挂的代理只在需要时读取相关内容日常对话里不需要一直挂在嘴边。第二技能可以版本化管理。一组技能就是一个目录里面全是文本文件天然适合 Git 管理。团队里谁改了技能、改了哪一步、为什么改都能留痕。第三多代理可以共用同一套技能库。Codex、Claude Code 这类工具读的是同一套 Markdown 技能只要格式约定一致理论上你可以在不同工具之间无缝迁移工作习惯不用为每个工具重写一套提示词。2. 核心细节解析与技能文件实操要点2.1 技能库的目录结构到底怎么摆第一次接触 superpowers 的人最容易在目录结构上犯迷糊。这里放一个我实际在用的技能库布局superpowers/ ├── AGENTS.md ├── skills/ │ ├── create-skill.md │ ├── improve-skill.md │ ├── reflect-on-work.md │ ├── java/ │ │ ├── compile-fix.md │ │ ├── test-isolation.md │ │ └── module-scan.md │ └── general/ │ ├── code-review.md │ └── commit-message.md └── plans/ └── current-plan.mdAGENTS.md 是整个技能库的“总入口”代理启动时先读这个文件了解自己拥有的能力和工具skills 目录里按领域分子目录每个技能一个 Markdown 文件plans 目录用来存放当前任务的执行计划代理会在开始工作前先写一份计划然后逐步完成并勾选。这个结构看起来简单但每个部分都有明确的作用。AGENTS.md 文件的内容不需要特别长我一般会写清三件事代理在处理任务时可以使用的“技能索引”、代理在任务开始前需要做什么准备比如先读项目结构、代理在完成每个子任务后应该如何更新计划文件。记住AGENTS.md 是给代理看的导航页不是让代理背下来的规则清单所以内容要精简只写必要的“元信息”。2.2 单个技能文件的骨架与设计原理技能文件是整个体系的细胞它的格式决定了代理能不能准确理解并执行。我比较推荐使用 YAML frontmatter 加正文 Markdown 的结构。举一个我常用的“编译问题修复”技能的例子--- name: java-compile-fix description: 当 Java 项目存在编译错误时使用。适合处理 Maven 或 Gradle 项目的编译失败问题。 when_to_use: 编译失败、类找不到、包不存在、JDK 版本不兼容 steps: 1. 运行 mvn compile 或 gradle compileJava 获取完整错误列表 2. 按错误顺序逐一定位源文件 3. 修改前阅读该文件的类结构和依赖关系 4. 修改后重新运行编译命令确认错误数量减少 5. 编译通过后运行相关单元测试 6. 总结错误原因和经验更新技能文件 ---写技能文件有一个核心原则只写步骤和方法不写具体答案。你不需要告诉代理“遇到这个错误就改成这样”而应该告诉它“遇到这个错误先做 A 再做 B 再验证 C”。答案会因为项目不同而千变万化但方法是可以沉淀复用的。这个文件放在 java 子目录下前台靠 frontmatter 里的 description 字段和 when_to_use 字段来做匹配后面正文则承载详细的执行步骤。2.3 对 Java 项目最有用的技能组合我因为日常主要是写 Java 后端所以在技能库里为 Java 场景单独开了一个子目录沉淀了三类非常常用的技能。第一类是编译修复技能。Java 项目编译失败是家常便饭尤其是多人协作的大项目里依赖冲突、JDK 版本不一致、缺失 import各种问题都有。编译修复技能的核心就是让代理遵循“先拿完整错误列表—逐一定位—修改—再编译验证”的闭环避免它看到一个错误就埋头改改完发现还有十个错误。第二类是测试隔离技能。很多 Java 项目跑全量测试非常慢动辄十几分钟。这个技能会让代理在修改完代码后先用 Maven 的-DtestClassName#methodName方式只跑相关测试类或单测方法确认逻辑没被破坏再决定要不要跑全量。这个细节极大提升了代理的迭代效率也降低了它对 CI 资源的占用。第三类是模块扫描技能。Java 工程往往是一个多模块的 Maven 项目代理如果不先搞清楚模块之间的依赖关系经常会出现“改了 A 模块却不重新构建 B 模块”的情况。模块扫描技能会要求代理先执行mvn dependency:tree读取依赖关系再定位当前修改落入哪个模块、影响哪些下游模块最后在编译和测试阶段一并验证。2.4 实操要点技能粒度越小越好用我在试用过程中踩过最大的坑就是把技能写得太大、太全。一开始我试图把“Java 项目日常开发”整个写成一个技能里面从项目初始化、代码编写、测试到部署全都有。结果代理每次调用这个技能都要看完一整篇几千字的文档执行的时候反而犹豫不决不知道该从哪一步开始。后来我把技能拆成“一个任务一个技能”粒度控制在每次执行不超过六到八个步骤。这样代理匹配得快、理解得准、执行得稳。技能名字和描述也要起得足够明确。description 里要写清楚“什么时候该用、什么时候不该用”代理才能精准调用。比如一个技能描述写成“Java 编译错误修复”就比较模糊写成“当 Maven 项目编译失败时使用适合处理类找不到、包不存在、版本冲突等错误”代理一看就知道该不该调用它。3. 安装配置与 Codex 集成实操过程3.1 前置环境准备在动手之前先把环境列个清单。你需要准备好以下几样东西一个能正常运行的 Codex CLI 环境这个不必多说一个 Git 客户端用来拉取技能库以及目标项目的构建工具比如 Java 项目对应的 Maven 或 Gradle。如果你用的是别的编程语言也同理先把对应语言的工具链准备好。我建议把 superpowers 技能库单独放在一个固定目录比如~/.superpowers然后在不同的项目里通过软链或复制的方式引入。这样技能库可以全局维护任何项目需要时都能快速接入。3.2 安装技能库的完整步骤整个安装过程我把它分成四步走。第一步把技能库拉取到本地。在终端里执行 Git 克隆命令把 superpowers 仓库复制到~/.superpowers目录。这里要说一下这个仓库本身的结构基本不需要改动它的顶层目录就是 AGENTS.md、skills 和 plans 三个部分拉下来就能用。第二步给 Codex 配置技能库路径。Codex 在启动会话时会读取项目根目录或用户配置目录下的 AGENTS.md 文件。你可以在~/.codex/AGENTS.md这个全局配置里加上一行指向技能库的引用让代理知道“我的技能库在哪个位置”。这样所有项目都能共用同一套技能库不需要每个项目重新配置。第三步在目标项目里建立技能库入口。我通常会在项目根目录放一个 AGENTS.md里面写明本项目使用的技术栈、构建命令、测试命令并按需引用全局技能库里对应的子技能。由于 Java 项目的构建命令往往固定这一步能把项目级信息和技能库的通用能力结合起来。第四步验证技能是否被加载。最简单的方式是直接在 Codex 里问一句“你能列出当前可用的技能吗”如果代理能报出技能库里的各个技能名称和适用场景说明加载成功。3.3 Java 项目接入技能库的额外配置Java 项目用的一个是静态语言编译信息是代理最重要的反馈信号。我在项目级 AGENTS.md 里会特意写上这几个信息项目使用的构建工具Maven 还是 Gradle、JDK 版本号、常用的编译命令、测试命令和测试报告输出位置。这些信息看似是项目常识但对代理来说却至关重要。它只有知道了这些基础约束才能在执行“编译修复技能”时选对命令。另外我强烈建议在项目根目录维持一个标准的 Maven 目录结构src/main/java放主代码src/test/java放测试代码根目录放pom.xml。如果你把代码放在非标准目录里代理每次都得先花大量时间探索项目结构技能的效率会大打折扣。保持标准结构代理就能把有限的上下文用在真正重要的逻辑上。3.4 用一次真实对话验证技能生效装完之后怎么确认它真的生效拿一个小任务试一试就知道了。我在一个 Java 工程里故意留下一处编译错误然后在 Codex 里说“当前项目编译失败请使用 java-compile-fix 技能处理。”如果配置成功你会看到代理并没有直接打开文件乱改而是先运行mvn compile拉出错误列表然后逐条分析错误与源文件的对位关系再动手修改修改完重新编译最后还跑了一下相关的单元测试。以上这套流程走下来完全可以确认 superpowers 已经在你的工作流里正常工作了。以后你再遇到编译错误、测试失败、依赖问题不必每次从头给代理解释背景技能库会自动匹配最合适的处理流程。这个收益随着你沉淀的技能数量增加会越来越明显。3.5 配置过程中的常见误区我在配置初期犯过几个错误这里提前帮你排掉。第一个误区是把技能库直接复制到项目里而不是引用。如果你直接把几百个技能文件复制进项目仓库每次修改技能库都要同步到所有项目非常麻烦。正确做法是全局放一份技能库项目里只在 AGENTS.md 里写引用路径。第二个误区是忘记区分“全局技能”和“项目技能”。全局技能应该放那些无论做什么项目都用得上的方法比如代码审查、提交信息规范、错误记录反思项目技能则应该聚焦技术栈和业务特定流程比如“Spring Boot 项目启动失败排查”。两者混在一起会导致代理在无关场景下检索到错误技能反而降低效率。4. 常见问题与排查技巧实录4.1 现象代理说“已了解技能”但执行时并不遵守这是很多人接入 superpowers 后遇见的第一个坑。代理在对话里能复述技能的内容但真正动手时却绕开技能里的步骤凭自己的感觉直接改代码。出现这种情况多半不是代理理解能力的问题而是技能文件里的指令不够强。我的解决办法是在技能文件开头明确写上一句“必须严格按照以下步骤执行”并在 AGENTS.md 里统一约定“在处理匹配技能描述的任务时不得跳过技能中任何步骤”。这句话对代理的约束力远比想象中大。它本身不具备强制力但显式的指令能显著提高代理的遵循率。如果还是不听那就把技能文件的设计改一改把它从“建议怎么做”改成“按照这个顺序做不得跳过”。4.2 现象代理反复犯同一个编译错误Java 项目里最常见的低效行为是代理改了一个文件编译又报错它再去改下一个文件如此循环但你发现它每次都是在同一个错误上打转。这种情况之所以发生是因为代理缺少“全局错误视图”。它只看到了当前这个错误没有意识到整个模块里还有一连串相关的错误。我在技能文件里特意加了“先获取完整错误列表按错误数量排序后再开始修改”这一步骤。实测效果非常好。代理先拉出全部错误然后从第一个错误开始依次处理每处理完一个就重新编译确认错误列表在减少。这样做表面上多跑了几次编译实际上省掉了大量“改了这里、坏了那里”的来回折腾。建议每个 Java 编译修复技能里都加上这么一条它可以靠编译错误数量作为代理的进度条让代理始终清楚自己处于什么位置。4.3 现象对话上下文被技能文件撑爆技能太多、每个技能又写得太长代理在检索完技能后依然会把全文读入上下文占掉了本来可以用于项目代码的窗口空间。做了一段时间后我的技能库膨胀到两百多个文件个别技能几百行最终导致代理论证问题时上下文捉襟见肘。处理办法分三步第一条控制单个技能文件篇幅正文不超过一百五十行超了就拆第二条在技能文件背后放一个“摘要区”只记录关键步骤让代理先读摘要、按需读全文第三条定期清理技能库把长时间没被调用的技能归档到 archived 目录里。这与代码重构的道理是相通的——不是写得越多越好而是保留被频繁使用的高价值技能。4.4 排查速查表问题可能原因解决方案代理不加载任何技能AGENTS.md 路径配置错误检查配置中的技能库路径是否存在技能被加载但不生效技能描述与任务场景不匹配优化 frontmatter 中的 when_to_use 字段代理跳过技能步骤技能指令语气不够强制在技能开头写明必须按步骤执行编译错误反复出现缺少全局错误视图增加先获取完整错误列表的步骤上下文窗口经常溢出技能文件过大、数量过多精简技能、拆分子技能、归档冷技能多个项目技能互相干扰全局技能与项目技能混用分目录管理按项目语境引用4.5 独家避坑技巧最后分享几个常规文档里不太会写的经验。第一技能文件名就用小写加横线的风格例如fix-import-order.md不要用大写或空格这样代理检索时不容易出错。第二在技能文件的 frontmatter 里加一个version字段每次修改技能内容就递增版本号。这不是给代理看的而是给团队协作时追踪技能演进用的。第三每过一两周让代理跑一个“技能库复盘”任务让它扫描所有技能文件的调用率标记出几个月都没用过的技能。这个技巧本质上是让 AI 帮你维护 AI 的技能库长期下来收益很高。5. 实操心得与后续扩展思路5.1 一次真实的 Java 项目修复体验我印象最深的一次是给一个多模块的 Maven 项目修 CI 构建问题。那个项目一共有五个子模块CI 在第三个模块上编译崩溃。以前我让代理直接去处理它打开第三个模块的报错文件就改结果改完之后第四个模块接着报错。反复两轮代理也没什么进展。那次我改用 superpowers 的模块扫描加编译修复组合技能。代理先用mvn dependency:tree把模块依赖关系列出来发现第三个模块是第二个模块的上游它先检查了第二个模块的编译状态果然问题出在公共依赖的类变更上。它先在第二个模块里修好了对应类的 API 变更然后再重新构建第三个模块一次通过。整个过程代理没有乱跳完全是按技能里定义的顺序在推进。这个体验让我彻底信服技能驱动的代理行为质量上限远高于提示词驱动的随机发散。5.2 把技能体系扩展到团队协作superpowers 不只能用于个人工作流它在团队协作里也能发挥价值。我建议团队把这套技能库放进 Git 仓库由团队成员共同维护。新成员入职时不需要读几十页文档只需要让代理读一遍技能库它就能按照团队约定完成常见任务。团队里解决过疑难问题的经验也可以随手抽象成一个新技能沉淀进共享技能库。这样一来团队的知识不再藏在个别资深工程师的脑子里而是逐步转变成一种可检索、可复用、可迭代的资产。5.3 结合 CI 与测试工具做深度联动我现在正在尝试进一步把技能库和 CI 流程联动起来。简单的做法是在 CI 脚本里加一步“预检技能”让代理先跑一遍编译修复技能、代码规范技能再提交代码。更进一步的想法是把 CI 失败日志自动喂给代理让它结合技能库生成修复补丁再由人工审查后合入。这样形成的闭环等于给 CI 系统配了一个会自动诊断和修复常见问题的“虚拟工程师”。虽然还没完全跑通但已经能看到明显收益——重复性故障的修复时间比原来缩短了一倍以上。5.4 给新手的第一个小建议如果你刚开始接触这套玩法不要一上来就想着建一个特别完善的技能库。我的建议是从手头最频繁、最痛苦的一个任务开始比如“修编译错误”或“写单元测试”先写一个最简单的技能花一天时间在真实项目里用起来再根据代理的表现不断迭代它。等这一个技能稳定了再去扩展第二个、第三个。毕竟技能库是一个活的东西它不是一步到位的而是在持续使用中越来越强大。