“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 的工具里，用户直接输入/planning，agent 就会读取并执行这个技能。最直接，适合用户明确知道自己要什么的时候。

第二条是描述匹配触发。当用户没有主动指定技能时，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.md，Claude 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 项目里怎么用 Superpowers

4.1 Java 场景下的接入与配置

在国内的很多落地场景里，Java 依然是绝对的主力语言。我试着把 Superpowers 完整接入到一个中等规模的 Spring Boot 项目中，整个过程没有遇到想象中的困难，但有一些 Java 特有的配置细节需要单独处理。

最关键的一点是：技能文件本身是语言无关的，planning、review、testing这些技能描述的都是通用工程流程，不需要为 Java 改写。真正需要适配的是项目上下文信息，也就是AGENTS.md里写给 AI 看的“项目百科”。Java 项目结构相对复杂，依赖体系庞大，这部分信息写得好不好，直接决定技能发挥的效果。

我的 Java 项目AGENTS.md写得更细，把 Maven 坐标、模块划分、关键技术栈版本、数据库访问方式都写进去了：

# 电商中台后端规范 ## 技术栈 - JDK 17，Maven 多模块结构，Spring Boot 3.2。 - 持久层使用 MyBatis-Plus，数据库为 MySQL 8。 - 模块划分: gateway / order / user / product / common。 ## 编码要求 - Service 层必须面向接口编程，禁止在 Controller 中直接操作 Mapper。 - 所有对外接口返回值统一使用 Result<T> 包装。 - 新功能必须提供单元测试，测试类放在对应模块的 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 工程里的分工方式总结成了一张表，这比零散演示直观得多：

这张表目前焊在我团队的 Wiki 里，每次新人入职我都会先让他们按表跑一遍。一个特别值得说的场景是：Java 老项目经常有一段无人敢动的“祖传代码”，以前让 AI 改这类代码，它容易直接重写，导致回归。但接入code-review技能后，模型会先读测试覆盖情况，再决定改动策略——这个行为我看过很多次，安全感大大提升。

另外多说一句，Java 项目的构建时间较长，如果你用的 agent 会自动跑 Maven 命令，建议在AGENTS.md里明确告诉它“跳过完整构建，使用增量编译”之类的策略，否则技能流程走到验证环节时会拖得异常漫长。这是我连续踩了两天坑才总结出来的经验。

注意：技能不是银弹。如果项目本身连基本的分层规范都没有，技能文件会把问题暴露得更明显，而不是自动变好。先立好工程红线，再上技能系统，顺序不要反。

5. 老司机踩坑实录：常见问题与排查清单

5.1 典型问题速查表

用这套系统半个多月，我在社区里也看了大量讨论，把高频问题整理成一张速查表，按“现象 → 原因 → 解决”排列，照着查就行：

这个表格我打印出来贴在工位上，遇到 AI 行为诡异的时候先对一遍，省去了很多瞎猜精力。绝大多数问题都不是玄学，而是信息传递链条上某个环节断了。

5.2 我踩过的三个大坑

最后分享三个我实际踩过、而且花了很长时间才爬出来的坑，希望你看完能直接绕开。

第一个坑是“贪多求全”。刚开始接入时，我一股脑给项目引了十多个技能，结果模型每次启动都要读几百行技能说明，上下文窗口被占掉一大块，真正处理任务时反而“变笨”了。后来我悟出一个原则：按项目阶段只留最核心的三板斧——planning、implementing、code-review，出问题时再临时调用 debugging。精简之后，模型响应速度和产出质量双双提升。

第二个坑是“技能与项目规范打架”。我在一个用 Lombok 的项目里引用了默认的implementing技能，技能正文里有一句“必须显式编写 getter/setter”，直接导致模型疯狂生成重复代码。解决办法很直接：把技能文件里冲突的部分删掉，或者复制一份做项目定制版。技能是死的，项目是活的，一定不要让技能凌驾于项目现实之上。

第三个坑是“只顾功能，不看成本”。Superpowers 在执行时确实会引入更多轮次的思考和技能调用，每次迭代的 token 消耗比我裸用 Codex 时高了 30%-50%。第一次看到账单时我肉疼了一下。后来我摸索出两个省钱办法：大任务拆小，不在一次会话里塞太多步骤；简单任务不触发 planning，直接快速实现。这样既保住了质量，费用也回到了可接受范围。

最后的一点体会

折腾完这套东西，我得说一句可能让很多人意外的话：Superpowers 最打动我的，不是它让 AI 写代码更厉害，而是它把“隐性工程经验”变成了显性文本。以前我带新人靠口口相传，写代码前先想五分钟、提交前做一次自查——这些习惯很难固化下来；现在我把同样的事写成技能文件，不仅人能看到，AI 也能执行。

最后再分享一个很实用的小技巧：你把常用的、经过验证的技能文件进行版本化管理之后，完全可以把它扩展到非编程场景。比如我身边已有朋友把planning技能用于产品需求拆解，把code-review技能用于合同审核。一技通吃，这不是玩笑话。我的建议很简单：找一个你最头疼的开发流程，去技能库里找到一个对应的技能，先跑通，再谈改造，你会打开一扇新的大门。