“Superpowers”这个词最近在我常混的几个技术社群里出现频率高得吓人。结合热搜词里那一串 codex superpowers、superpowers java、superpowers 安装、superpowers 使用教程我心里基本有数了大家讨论的不是什么超级英雄电影而是给 AI 编程代理agent用的那套“技能包”系统。我花了两周时间把整套东西装进自己的开发流里从 Codex 到 Java 工程都试了一遍今天把从理解到落地的完整过程写下来给正在折腾这条路的朋友一份可以照着抄的实操笔记。这套东西解决的是一个特别具体的问题AI 编程工具已经很强了但它们常常“不会干活”——比如拿到一个需求上来就写代码不拆解、不查上下文、不写测试像个急脾气的实习生。Superpowers 做的就是给这些 AI 助手装上“职业素养”一套用 Markdown 写成的技能文件教会它们先规划、再编码、最后验证的完整工作流。适合谁看正在用 Codex、Claude Code 或类似工具做日常开发的人以及想在团队里统一 AI 协作规范的工程负责人。下面全程按我的实操顺序来不绕弯子。1. 先说清楚Superpowers 到底是什么1.1 它不是一款软件而是一套“职业素养包”很多第一次听说 Superpowers 的朋友都会问它是个 IDE 插件吗是个命令行工具吗还是一个新的模型都不是。它本质上是一个技能集合仓库里面装满了各种“作业指导书”。每份指导书是一个.md文件文件名就叫SKILL.md放在对应的技能目录里。比如你想让 AI 学会“做计划”就给它加载planning技能想让它学会“严格代码审查”就加载code-review技能。这套系统的核心思想我非常认同大型语言模型本身掌握的知识足够广但缺少结构化的工作方法——它们在训练时见过海量代码却没见过“一个工程师接到任务后应该按什么顺序动作”。Superpowers 用文本把后者补上了。你把任务交出去AI 会先自动读取相关技能文件然后按照里面写的步骤一步步完成工作而不是天马行空地发挥。我用一个比喻帮助团队理解模型是一个刚毕业的高材生知识底子扎实但没经过岗前培训Superpowers 就是那套“新员工手册”告诉他们需求评审怎么开、代码怎么分层、测试怎么补、线上问题怎么排查。手册本身不是业务知识但它定义了怎样用你的能力去做事这就是“超能力”的来源。1.2 为什么 AI 编程工具用起来总差口气过去一年我几乎试用过市面上所有主流的 AI 编程方式从普通的对话补全到嵌入 IDE 的自动编码再到可以多文件操作的 agent 模式感触最深的一点是工具能力提升很快但产出质量的方差极大。同一个需求有时候 AI 能一次写对更多时候它先给你一个能用但很烂的方案比如把全部逻辑塞进一个两三百行的函数里。问题出在“语境缺失”和“流程缺失”两个环节。语境缺失是指 AI 对项目的技术栈、目录约定、历史决策一无所知只能凭通用经验猜流程缺失是指 AI 没有被要求先思考“怎么做再做”。Superpowers 恰好同时补这两块它的技能库既是“上下文增强器”也是“流程控制器”。拿我用 Codex 的体验来说没有接入 Superpowers 之前我发一句“帮我写个用户注册接口”它可能直接哐哐生成一堆代码看着分析得头头是道拼进项目里就处处不对劲。接入之后同样的请求会触发一系列技能先读取项目的AGENTS.md了解约定再调用planning技能拆解任务然后按implementing技能的规范写代码最后甚至会自动补一轮测试。整体体验从“跟一个聪明但毛躁的助手共事”变成了“跟一个靠谱的初级工程师结对编程”。2. 核心机制拆解SKILL.md 是如何给 Agent 加技能的2.1 技能文件的三个组成部分我克隆完仓库后第一件事就是把技能文件逐个打开看了一遍。一个标准的SKILL.md结构非常清晰由三部分组成frontmatter 元信息、技能描述、操作说明正文。frontmatter 是文件开头的 YAML 区块通常包含技能的name和description这部分的作用是让 AI 在决定“要不要用这个技能”时有依据。操作说明正文则是一段自由的 Markdown作者会写清这个技能适用的场景、前置条件、需要完成的步骤以及强制要求和推荐实践。我把其中一个技能文件简化给你看感受一下它长什么样--- name: planning description: 在动手写代码之前先分析需求并制定分步实施计划。适用于较大或模糊的任务。 --- # 计划技能 在开始实现任何功能之前你必须先完成以下步骤 1. 重新表述需求确认你理解正确。 2. 列出所有涉及的文件和依赖。 3. 将任务拆分为不超过 30 分钟的原子步骤。 4. 输出计划等待用户确认后再动手。注意一个细节正文里用的是“你必须”而不是“建议你”。Superpowers 的技能语言设计得相当有讲究它对 AI 的指令强度远超普通对话提示词。后来我明白了这正是它能稳定发挥作用的原因——大模型对语气强度极其敏感“你考虑一下”和“你必须做”产生的执行概率天差地别。2.2 技能是怎么被“触发”的了解文件结构之后我更好奇的是触发机制。技能放在那里是一堆文本什么时候会被 AI 用到根据我读项目源码和文档的经验触发路径主要有三条第一条是命令式触发。在支持 slash command 的工具里用户直接输入/planningagent 就会读取并执行这个技能。最直接适合用户明确知道自己要什么的时候。第二条是描述匹配触发。当用户没有主动指定技能时agent 会阅读所有可用技能的description根据当前任务内容判断该加载哪个。这依赖模型自身的判断力触发效果会有一定随机性但对用户来说最省心。我实测下来Codex 里描述匹配的准确率在七八成左右被归为模糊任务时命中planning的概率很高。第三条是流程链式触发。这也是我觉得最妙的一个技能执行完会在它的正文中明确指定下一个要调用的技能。比如implementing技能写完代码后会建议调用testing技能来补充测试然后调用code-review来做自查。这样 AI 不是孤立地执行用户的一句话而是走完一整条工程流水线。2.3 为什么是 Markdown 而不是代码这个设计决策我琢磨了好几天越想越觉得合理。用 Markdown 而不是 Python 或 JavaScript 来定义技能至少有四个显然的好处第一零门槛可读。任何开发者在编辑器里打开技能文件都能看懂不需要学习一套新 DSL领域专用语言。团队要自定义技能复制一份 Markdown 改一改就行不用编译、不用发布。第二天然适配 LLM 的输入方式。模型训练时见过的 Markdown 文本量极大对这种格式的理解能力远强于自定义脚本。技能的指令本质是“给模型的自然语言消息”Markdown 恰好就是最好的载体。第三易于版本管理。技能文件就是纯文本用 Git 管理、做 diff、走 Code Review 都顺理成章。我把它理解成“可版本化的团队规范”每次更新了流程团队里所有人的 AI 立刻同步。第四没有执行环境依赖。技能不需要被“运行”它只需要被“阅读并遵守”。这意味着无论你用的是 Codex、Claude Code、Cursor 还是别的 agent只要它能读文件就能获得这些能力跨工具复用极其方便。提示想自定义技能时最简单的方法是把现有技能文件复制一份改名、改描述、改正文你就会立刻得到一个只属于自己的专属技能。3. 从零到一Superpowers 安装与接入 Codex 实录3.1 安装技能库的两种方式我把安装过程分成两条路一条是“省心自动派”另一条是“手动硬核派”。两条我都试过各有优劣看你是哪种使用习惯。省心自动派官方提供的安装升级工具一条命令把整个仓库拉到本地并配置好路径。我最初就是用的这种方式胜在一键搞定后续升级技能库也是同一个命令。缺点是工具本身占一点磁盘空间而且日志有点啰嗦。手动硬核派直接把仓库 clone 到本地的技能目录比如~/.claude/skills或~/skills。这种方式的好处是你能完全掌控文件的存放位置自定义目录结构更方便比如我想把团队内部的私有技能和公共技能分开管理手动克隆后创建软链接是最好的方案。如果你用的是 Codex我个人建议手动克隆为主。因为 Codex 的项目上下文文件AGENTS.md里可以直接写“去某个路径加载技能”路径由自己控制灵活度更高。我的做法是建了一个~/skills目录把公共技能克隆进去然后在每个项目里通过AGENTS.md按需引用。安装完之后检查一下技能文件是否就位ls ~/skills/ # 你会看到类似这样的技能目录列表 # brainstorming/ code-review/ implementing/ planning/ testing/ ... ls ~/skills/planning/SKILL.md看到SKILL.md文件正常出现说明基础安装就已经完成了。这时候你可以先不用接任何工具直接用编辑器打开这些文件读一遍就当是阅读一套行业最佳实践文档也会有不少收获。3.2 让 Codex 认识技能AGENTS.md 与 CLAUDE.md装好技能库只是第一步难点在于让 agent 工具“知道”这些技能存在并主动使用。Codex 和 Claude Code 这类 agent 工具启动时都会读取一个项目说明文件Codex 认的是AGENTS.mdClaude Code 认的是CLAUDE.md。Superpowers 的思路就是在这个文件里告诉 agent技能库在哪、什么场景下去读哪个技能。我的操作流程是这样的。先在仓库根目录创建AGENTS.md写入最少必要信息# 项目编码规范 - 本项目使用 Java 17 Spring Boot 3。 - 所有新增接口必须遵循现有 Controller-Service-Repository 分层。 - 开始工作前先阅读计划技能文件再进行实现。 ## 技能库 - 计划技能: ~/skills/planning/SKILL.md - 实现技能: ~/skills/implementing/SKILL.md - 测试技能: ~/skills/testing/SKILL.md - 代码审查技能: ~/skills/code-review/SKILL.md写完这份文件后我启动了 Codex做了一次最简单的验证让它“给现有用户模块加一个修改手机号的功能”。它先读取了AGENTS.md然后开始找技能文件。我全程盯着日志发现它在动手前真的先调用了planning技能输出了一份结构化计划确认后才开始动手写代码。那一刻有被震到因为我之前试过各种花哨的系统提示词都没能让它这么“听话”。这里有一个关键诀窍不要一次性引用太多技能。我第一次图省事把仓库里十几个技能全列在了AGENTS.md里结果 Codex 光是读文件就花了不少时间执行时还经常在几个技能之间反复横跳反而拖慢了速度。后来我精简到只引用当前项目真正用得上的三四个技能效果立刻好了很多。按需引用宁可少不要多。3.3 一次完整的技能调用现场为了让过程更直观我把一次完整的调用现场记录在这里。任务是“修复登录接口的一个并发 bug”我并没有指定技能完全让它自动匹配。第一步Codex 读取AGENTS.md结合仓库结构初步判断这是一个“需要先排查再修复”的任务。它在上下文里匹配到了debugging技能因为技能描述中出现了“意外行为、性能问题、并发场景”等关键词与当前任务的重合度最高。第二步debugging技能引导它先复现问题、定位根因再输出修复方案。我当时观察到一个特别有价值的行为技能让它先搜索项目中所有相关的日志代码而不是直冲业务逻辑区改代码这是经验丰富的老工程师才会有的动作。第三步修复完成后debugging技能的正文又链式指向了testing技能Codex 随即提出要补充一个并发回归测试。整条链路走下来它就像真切完了一个工程病例观察症状、定位病灶、手术修复、术后复查一气呵成。我强烈建议你第一次接入后刻意做一次类似演练盯住模型调用了哪些技能、技能之间如何串联。这一步能帮你建立对整套系统的“手感”之后排查问题时效率会高得多。4. Java 项目里怎么用 Superpowers4.1 Java 场景下的接入与配置在国内的很多落地场景里Java 依然是绝对的主力语言。我试着把 Superpowers 完整接入到一个中等规模的 Spring Boot 项目中整个过程没有遇到想象中的困难但有一些 Java 特有的配置细节需要单独处理。最关键的一点是技能文件本身是语言无关的planning、review、testing这些技能描述的都是通用工程流程不需要为 Java 改写。真正需要适配的是项目上下文信息也就是AGENTS.md里写给 AI 看的“项目百科”。Java 项目结构相对复杂依赖体系庞大这部分信息写得好不好直接决定技能发挥的效果。我的 Java 项目AGENTS.md写得更细把 Maven 坐标、模块划分、关键技术栈版本、数据库访问方式都写进去了# 电商中台后端规范 ## 技术栈 - JDK 17Maven 多模块结构Spring Boot 3.2。 - 持久层使用 MyBatis-Plus数据库为 MySQL 8。 - 模块划分: gateway / order / user / product / common。 ## 编码要求 - Service 层必须面向接口编程禁止在 Controller 中直接操作 Mapper。 - 所有对外接口返回值统一使用 ResultT 包装。 - 新功能必须提供单元测试测试类放在对应模块的 test 目录。 ## 技能使用 - 开工前~/skills/planning/SKILL.md - 写码时~/skills/implementing/SKILL.md - 提交前~/skills/code-review/SKILL.md - 出问题时~/skills/debugging/SKILL.md写完后我重点验证了一个行为让它开发一个新接口时会不会遵守“Controller 不直接操作 Mapper”这条项目强约束。实测中它先规划出了 Controller、Service 接口、ServiceImpl、Mapper 四层结构实现过程中始终遵循现有分层。对 Java 这种重规范、重结构的生态来说这套组合拳的价值比在偏自由的 Python 项目里更大。4.2 技能在 Java 工程里的实际分工接入一段时间后我给团队做了一个分享把技能在 Java 工程里的分工方式总结成了一张表这比零散演示直观得多技能典型触发场景在 Java 工程中的实际效果planning接到新需求、重构公告输出模块拆分方案避免直接开写implementing编写功能代码严格遵循分层约束生成接口与实现分离的代码testing写完代码后自动补 JUnit 单元测试与 Mock 数据code-review提交前自查检查空指针风险、事务边界、命名规范debugging线上问题复现先查日志与调用链再定位可疑代码段这张表目前焊在我团队的 Wiki 里每次新人入职我都会先让他们按表跑一遍。一个特别值得说的场景是Java 老项目经常有一段无人敢动的“祖传代码”以前让 AI 改这类代码它容易直接重写导致回归。但接入code-review技能后模型会先读测试覆盖情况再决定改动策略——这个行为我看过很多次安全感大大提升。另外多说一句Java 项目的构建时间较长如果你用的 agent 会自动跑 Maven 命令建议在AGENTS.md里明确告诉它“跳过完整构建使用增量编译”之类的策略否则技能流程走到验证环节时会拖得异常漫长。这是我连续踩了两天坑才总结出来的经验。注意技能不是银弹。如果项目本身连基本的分层规范都没有技能文件会把问题暴露得更明显而不是自动变好。先立好工程红线再上技能系统顺序不要反。5. 老司机踩坑实录常见问题与排查清单5.1 典型问题速查表用这套系统半个多月我在社区里也看了大量讨论把高频问题整理成一张速查表按“现象 → 原因 → 解决”排列照着查就行现象核心原因解决办法Agent 完全无视技能文件AGENTS.md路径写错或技能描述过于模糊检查路径简化技能描述用一句话说清适用场景执行时在多个技能间反复横跳引用的技能太多上下文混乱精简技能列表项目只保留 3-4 个核心技能技能执行了但产出质量没提升技能正文被截断或与项目约束冲突确认技能文件里没有“覆盖项目规范”的矛盾指令升级技能库后行为突变新版本技能步骤变化用 Git 查看技能文件 diff回滚到稳定版本自定义技能几乎不被调用frontmatter 里的 description 写得像废话按“场景 任务 结果”结构重写描述增加触发命中率多语言混用项目里技能乱触发项目语境信息不足在AGENTS.md中显式声明各目录对应的语言与技术栈这个表格我打印出来贴在工位上遇到 AI 行为诡异的时候先对一遍省去了很多瞎猜精力。绝大多数问题都不是玄学而是信息传递链条上某个环节断了。5.2 我踩过的三个大坑最后分享三个我实际踩过、而且花了很长时间才爬出来的坑希望你看完能直接绕开。第一个坑是“贪多求全”。刚开始接入时我一股脑给项目引了十多个技能结果模型每次启动都要读几百行技能说明上下文窗口被占掉一大块真正处理任务时反而“变笨”了。后来我悟出一个原则按项目阶段只留最核心的三板斧——planning、implementing、code-review出问题时再临时调用 debugging。精简之后模型响应速度和产出质量双双提升。第二个坑是“技能与项目规范打架”。我在一个用 Lombok 的项目里引用了默认的implementing技能技能正文里有一句“必须显式编写 getter/setter”直接导致模型疯狂生成重复代码。解决办法很直接把技能文件里冲突的部分删掉或者复制一份做项目定制版。技能是死的项目是活的一定不要让技能凌驾于项目现实之上。第三个坑是“只顾功能不看成本”。Superpowers 在执行时确实会引入更多轮次的思考和技能调用每次迭代的 token 消耗比我裸用 Codex 时高了 30%-50%。第一次看到账单时我肉疼了一下。后来我摸索出两个省钱办法大任务拆小不在一次会话里塞太多步骤简单任务不触发 planning直接快速实现。这样既保住了质量费用也回到了可接受范围。最后的一点体会折腾完这套东西我得说一句可能让很多人意外的话Superpowers 最打动我的不是它让 AI 写代码更厉害而是它把“隐性工程经验”变成了显性文本。以前我带新人靠口口相传写代码前先想五分钟、提交前做一次自查——这些习惯很难固化下来现在我把同样的事写成技能文件不仅人能看到AI 也能执行。最后再分享一个很实用的小技巧你把常用的、经过验证的技能文件进行版本化管理之后完全可以把它扩展到非编程场景。比如我身边已有朋友把planning技能用于产品需求拆解把code-review技能用于合同审核。一技通吃这不是玩笑话。我的建议很简单找一个你最头疼的开发流程去技能库里找到一个对应的技能先跑通再谈改造你会打开一扇新的大门。