superpowers 这个名字第一次看到时我以为是某个效率玄学工具直到在 Codex 工作流里真正连续用了一周才确认它并不是包装出来的概念而是真的能把 AI 编程 Agent 的产出质量往前推一截的东西。它不是脚手架也不是一键生成项目的代码生成器而是一套面向 AI 编程 Agent 的技能包。技能两个字不是比喻是字面意义上的文件一个文件夹、一个 SKILL.md、若干辅助脚本和示例组合成一件可复用的行为协议。如果你已经在用 Codex CLI、Claude Code或者任何兼容 skills 目录的 AI 编程工具这篇就是给你写的。我会把 superpowers 的使用指南、安装过程、核心原理、Java 项目接入经验一次讲完也会把我在真实开发里踩过的坑直接摊开。后面你搜superpowers 安装superpowers 使用教程codex superpowers之类关键词时看到的基本就是这套东西落地后的实际状态。1. 先搞清楚superpowers 是给谁用的技能包1.1 它的核心单元是 SKILL.md很多人在第一次接触 superpowers 时会有一个错觉觉得它是一个大而全的框架装完以后 Agent 就自动变强。这种理解基本是反的。superpowers 放在你项目里的是一堆技能目录每个技能目录里最关键的文件是 SKILL.md里面用 Markdown 写清楚了这件事的触发条件、执行步骤、验收清单和禁止事项。用我自己熟悉的目录结构举例skills/ plan/ SKILL.md examples/ review/ SKILL.md scripts/ test/ SKILL.md refactor/ SKILL.mdAgent 在执行任务时会先看用户是否提到某个技能名或技能触发词。一旦命中它就会把对应目录里的 SKILL.md 作为一段强上下文读进当前会话然后按照里面写的步骤走。表面上看技能像是命令本质上它是一种动态提示词注入你平时写在对话里重复叮嘱的内容被固化成了文件。这也是为什么 superpowers 能解决同样的要求每次都要重新说一遍的痛点。比如代码审查这件事如果没有技能文件Agent 可能看到代码就直接改改完你才发现它没有看边界条件。有了 review 技能它会先扫描文件、列出风险点、输出审查结论最后才动手修改而且这一步是写在技能流程里的不是靠你碰运气。1.2 为什么只靠提示词撑不住大部分团队让 AI 编程 Agent 干活的方式是这样的在项目根目录放一个 AGENTS.md把编码规范、常用命令、禁用事项写在里面然后就开始对话。这种做法不是没用但它有个天然上限一份全局说明只能描述大部分场景很难把不同任务的工作流拆细。你今天让 Agent 做新功能明天让它修 bug后天让它做重构任务类型完全不同。如果用一份 AGENTS.md 强行覆盖所有情况要么写得特别长导致 Agent 抓不住重点要么写得特别短导致每次执行质量全看运气。superpowers 的应对思路很直白把任务类型的差异拆成独立技能用目录结构做隔离通过触发词做路由。这有点像一个团队不能只靠一本员工手册运转还得有评审流程、测试流程、发布流程。每套流程单独成文需要时再拿出来而不是让所有人把全书背下来。superpowers 就是把评审流程、测试流程、重构流程单独成文Agent 按需加载。1.3 谁适合用谁不适合我用了几天之后对适用人群有了一个比较清楚的判断。它适合两类人一类是已经在用 Codex CLI 这类工具、但对输出质量不太满意的开发者另一类是带小团队、想让 AI 成员按统一工作流干活的技术负责人。因为它本质上是把流程写成文件组里每个人都能看到、都能改也都能审。反过来如果你是刚接触 AI 编程的纯新手连项目里生成了什么文件都还没搞清楚我建议先别急着上 superpowers。它假设你已经对基础命令和项目结构有基本概念它的价值是约束和增强而不是替代基础能力。把基础对话磨明白再回来你会更容易体会到它好在哪。2. 从零开始安装 superpowers 的 15 分钟实操2.1 装之前要准备什么安装前你先确认两件事第一你已经有一个能正常发起 AI 编程会话的工具常见的就是 Codex CLI开源生态里也有不少支持 skills 目录的同类产品第二你了解这个工具读取项目配置和工作目录的基本方式至少要知道它是在哪个目录下启动的。前置工具这一块要看具体仓库的要求不同版本差别比较大。我倾向于不在博客里写死某个运行时版本因为项目更新得很快写死了隔两个月就误导别人。你只需要在安装后跑一次冒烟测试能触发第一个技能就说明当前环境是兼容的。另外想提醒一点如果你的项目代码比较多最好在本地新建一个临时目录来练习安装不要一上来就把技能包直接塞进生产项目。我第一次就是这么干的结果技能路径跟项目配置纠缠在一起排查了半天才弄清楚是加载顺序的问题。2.2 标准安装流程克隆、放目录、指路径第一步是把技能源码拿到本地。打开终端创建一个专门放技能的目录然后克隆仓库。我习惯放在用户目录下而不是项目目录里这样多个项目可以共用而不会因为某个项目删了影响全局。mkdir -p ~/.superpowers cd ~/.superpowers git clone superpowers仓库地址仓库地址以项目主页为准我不在这里贴写死的链接避免传着传着就变成非官方镜像。你自己搜索superpowers skills agent就能找到官方入口克隆后先看一眼 README再动手。第二步是让 Agent 能看到这些技能。不同工具提供的方式不一样最常见的两种是在项目根目录的配置里声明 skills 根路径在会话开场时主动说明skills 目录在哪。我自己的经验是能写进配置就写进配置不要靠每次手输。因为你会忘。把路径写死在项目配置中等于每次会话自动加载省心很多。# 以常见配置示例表示具体字段名以你使用的工具为准 skills_path ~/.superpowers/superpowers/skills2.3 安装后必做的冒烟测试装完别急着丢大任务进去。先做一次两分钟冒烟测试确认技能真的被加载了。具体做法是随便选一个你知道肯定存在的技能例如review然后给 Agent 发一条简短指令使用 review 技能对当前项目 README 做一次结构审查。正常情况下Agent 会回一段结构化的审查结论而不是上来就大改文件。如果它完全无视技能名直接输出一段通用回答那说明技能没有被正确加载。这个时候去检查两件事路径有没有写对以及当前工作目录是不是 Agent 实际读取的那个目录。我见过最多的坑是路径看起来没问题、实际差了层级。你写的是相对路径但 Agent 从另一个目录启动技能就扑空了。解决方法是统一用绝对路径或者写一个启动脚本把工作目录固定住。2.4 版本迭代带来的安装差异superpowers 这个项目的迭代速度不算慢不同版本之间可能会有目录结构变动。比如早期版本把技能集中放在根目录后面对应不同 Agent 体系拆分成了多个子目录。遇到这种变化不用慌还是以 README 为准。我的建议是把 README 当作安装指南的第一手资料而不是只看网上的教程。网上教程适合帮你建立概念真正装的时候照着官方目录结构来少踩很多坑。你在搜索时看到的所有superpowers 安装文章本质上都是某次迭代的切片不保证现在仍然适用。3. 核心技能拆解这些超能力到底给了 Agent 什么3.1 先从一张常用技能表说起不同版本的 superpowers 会自带或社区提供大量技能你完全不用全装。下面这张表是我实际使用频率最高的几个技能以及它们适用的场景技能名触发场景核心作用plan新需求、不确定时先拆解任务、列出约束、输出执行计划review已完成代码、合并前扫描风险点、检查边界输出审查结论test需要验证行为时阅读现有测试、规划用例、执行测试命令refactor感觉代码混乱时先分析依赖和影响范围再分步重构root-causebug 反复出现时不急着修复先定位根本原因每个技能目录里都有具体的步骤说明内容比我这里列的自然要细得多。重点不在于你记住这些名字而在于理解它们的共性所有技能都会在动手之前增加一个分析环节。3.2 为什么用 Markdown 而不是 JSON 配置我第一次打开技能文件时愣了一下这项目居然用 Markdown 描述行为协议而不是用 JSON 或者 YAML。后来想明白了这是有意为之。Agent 本身就是用自然语言训练的Markdown 对它来说是一种非常自然的指令载体几乎不需要额外解析。用 JSON 写规则优点是机器可读但缺点是你得维护一套 schema声明条件、步骤、例外情况这套东西写出来很像编程。用 Markdown 写规则优点是不需要编译不需要复杂格式校验谁打开都能改。你甚至可以让 Agent 自己根据新经验更新技能文件。这就像一个团队的流程手册用 Word 写还是用纯文本写纯文本显然更适合文档的持续演化。superpowers 选 Markdown本质上是把给机器看的格式降级成给人写的文本换取更高的可维护性。3.3 动手写一个最小技能示例与其只讲概念不如直接给你看一个我能跑通的最小技能文件。假设你经常需要 Agent 做空指针风险审查你可以自己建一个技能--- name: null-check description: 当用户要求检查空指针风险时使用 --- ## 执行步骤 1. 先扫描目标文件的方法签名列出所有外部输入。 2. 标记可能为 null 的变量、参数、返回值。 3. 输出风险清单逐个说明触发条件和影响。 4. 在你的风险清单得到用户确认前不要修改任何代码。 ## 验收标准 - 每个风险点都有代码位置 - 每个风险点都有触发前提 - 没有跳过声明文件只检查业务代码的情况这个技能很简单但在真实会话里非常有用。你把文件放到技能目录后Agent 一看到空指针风险这个描述就会加载它。你会发现它不再直接改代码而是先输出清单你再决定哪些要修。这个模式的威力在于它把沉默的代码改动变成了透明的决策过程。3.4 多个技能之间怎么串起来superpowers 的进阶用法不是单个技能单打独斗而是让技能之间形成流水线。比如 Agent 接到一个新功能需求时可以先加载 plan 技能拆分任务拆完以后用 review 技能审查当前代码基础再用 test 技能确认预期行为最后才是写实现代码。实际操作中你不需要手动切换Agent 会根据上下文自动连续调用多个技能前提是技能描述写得足够清晰。我见过比较麻烦的情况是技能描述写得太宽泛Agent 一个任务里加载了七八个技能上下文被塞满反而输出了一些无关内容。后来我把技能描述改成仅在……时使用情况好了很多。做技能配置时触发条件越收窄路由越准确。4. 在 Java 项目里用 superpowers 的实操记录4.1 Java 项目为什么更吃这一套Java 项目和那种几十行的脚本项目不太一样它的结构性更强从包名、注解、依赖管理到测试框架都有既定惯例。AI 编程 Agent 在 Java 项目里的最大问题不是不会写代码而是经常忽略项目约束写出了风格完全不一致、甚至编译不过的东西。superpowers 对这种场景的约束价值特别大。以 Spring Boot 项目为例一个处理订单的 Service 类Agent 如果直接上手改很容易忽略事务边界、忽略 null 校验、忽略已有测试。但如果你让它先调用 review 技能它会先分析出方法签名里的空值风险再决定要不要动。我在一个多模块 Maven 项目里做过一次测试让 Agent 给订单模块新增分页查询接口同时要求它使用 review 技能先排查当前实现。它第一轮没有直接生成代码而是先输出了一份风险清单里面准确提到了分页参数可能为 null、当前没有统一异常处理、以及查询超时时间没配置。我对这种输出并不意外因为技能文件里就写了这些检查步骤。但它确实比以往的直接生成干净得多。4.2 实操过程从需求到技能调用的完整链路我记录了一次实际会话过程大致是这样的第一步我给 Agent 下了一段指令使用 plan 技能拆分这个需求再调用 review 技能检查订单模块现有代码我确认后你才写实现。注意这一步的要点是提前说清楚技能顺序和确认节点。第二步Agent 先加载 plan 技能输出了一个四步计划梳理现有接口、明确分页参数、检查事务边界、补充测试。计划之后它又调用 review 技能把目标文件里所有可能引发空指针的地方列成了表格。第三步我看了表格确认了两项修改建议才告诉它可以动手。最终 Agent 生成的改动和计划完全一致没有超出我批准的范围。整个过程像带了一个非常谨慎的初级开发而不是一个想到哪写到哪的自动生成器。这就是技能驱动的意义每一步都有产出物每一段产出物都能被人类审查。4.3 Maven 多模块项目最容易踩的坑Java 项目里最常见的报错不是代码问题而是命令执行位置不对。Maven 多模块项目里Agent 很容易在根目录直接跑mvn test结果某个子模块起不来或者跑了一堆无关模块的测试。解决思路不是让 Agent 猜而是在技能文件里写清楚项目结构和命令模板。以 Maven 为例你可以让技能在执行测试前先读取根pom.xml的modules列表然后使用-pl和-am参数指定模块范围。mvn -pl order-service -am test这个命令的意思是只构建 order-service 模块同时构建它所依赖的其他模块。如果你发现 Agent 在 Java 项目里反复跑错命令先别急着换工具先检查是不是技能文件里缺少了识别模块结构这一步骤。这是我在实战里最有体感的一条经验。4.4 在WorkBuddy 怎么用 superpowers这类问题上的统一回应很多人在搜索时用worbuddy 怎么用 superpowers其实问的是其他桌面端 AI 编程工具能不能接入技能包。统一答案是能但入口位置不一样。Codex CLI 这类纯命令行工具靠配置文件和启动参数桌面端工具多半靠设置面板里的技能根目录或指令文件路径选项。你只需要抓住一个核心原则Agent 必须从某个路径读到技能文件。至于这个路径是写在配置里、填在对话框里、还是设定在面板上都是同一件事的不同实现。如果某个工具界面里找不到技能配置入口你就手动把技能目录放进项目根目录然后在会话开头明确写一句技能目录在 ./skills需要时请加载对应技能。这招在绝大多数 GUI 工具里都有效。5. 常见问题与排查技巧实录5.1 一张拿来即用的问题速查表下面这些是我和群里朋友实战中遇到过的典型问题整理成速查表症状最常见原因解决动作Agent 完全不理会技能名技能路径没被读取改用绝对路径检查启动目录技能加载了但执行到一半中断技能步骤太长上下文被占满拆小技能一个技能只做一件事输出内容天马行空技能里只有步骤没有禁止项写在确认前不要修改代码这类硬约束Maven 多模块命令失败在错误目录执行命令在技能里写死-pl和-am参数多个技能互相干扰技能描述触发条件太宽泛收窄 description限定具体场景这五个问题覆盖了我见到的大部分使用事故。你会发现大多数根因不是 Agent 笨而是技能文件的设计不够明确。5.2 实操排查法用三分法定位问题当技能没按预期生效时我有一套固定的排查思路把它叫三分法先分离变量、再定位环节、最后重放最小用例。分离变量指的是你一次只改一个东西不要同时改技能内容和 Agent 配置。很多人一着急就把好几个地方都改了结果问题看起来消失了但不知道是谁修好的。定位环节指的是判断问题是出在加载、读取还是执行加载环节看技能目录结构是否正确读取环节看技能描述是否触发执行环节看 SKILL.md 里的步骤是否矛盾。重放最小用例是我最常用的收尾验证。我建一个空目录只放一个简单技能和一份测试代码跑一次完整流程。如果最小用例能跑通再逐步加入项目内容很快就能定位到是项目里什么东西把 Agent 弄晕了。这套办法跟查网络问题差不多都是从最小单元开始复现。5.3 一条反直觉的避坑建议有一个建议看起来反直觉但很有用不要一次性导入太多技能。技能不是越多越好每个技能在加载时都会占用上下文窗口技能数量一旦上去Agent 在每次任务里都可能自我诊断出多个匹配项反而把该干的事挤掉了。我实验过 20 个技能和 5 个核心技能的差别。后者在 Java 项目里的表现明显更集中、更可控。你完全可以保留整个技能库但只在项目配置里启用当前项目真正用得上的那几个。这样既保留了扩展性又不会把 Agent 变成什么都懂、什么都不精的状态。5.4 日志是最好的老师如果你用的工具支持输出调试日志或会话记录遇到问题时请第一时间翻日志。日志能看到 Agent 到底是加载了技能还是没加载是加载失败还是读取不到文件这比让它自己解释原因可靠得多。我遇到过一次奇怪问题技能文件在路径也对但 Agent 就是不触发。翻日志才发现它读取的是项目里另一个同名目录根本不是我以为的那个路径。这种问题在文件系统层级复杂时特别容易发生。别相信你在文件管理器里看到的路径要让 Agent 自己说出它读取的路径或者直接从日志里找证据。6. 几个真正改变我使用习惯的体会6.1 先写验收标准再谈技能我把 superpowers 用顺手之后回头总结出一条判断标准技能文件前面几行可以是做什么但真正起约束作用的是最后的验收标准。没有验收标准的技能Agent 很容易出现一种情况——流程走得很完整结果却完全偏离目标。你在设计技能时要把怎么算做完写清楚。这不是小事是整个技能是否能落地的关键。6.2 Agent 是执行流程的人你是定流程的人和它配合几周后我最大的心态变化是不再期待 Agent 替我做决策而是把它当成一个严格执行流程的人。它最大的价值是稳定不是创意。你负责把流程定清楚它负责每一步都按流程走。superpowers 恰好提供了一种更舒服的方式让你把流程写成文件而不是写进对话。6.3 最后分享一个小技巧如果你不知道从哪里开始就先拿一个最让你头疼的场景写技能。不要追求全只写一个能在下一次会话里直接验证的小技能。我自己的第一个技能就是空指针检查写了不到 30 行效果立竿见影。后面每一次碰到新问题就往技能库里补一条规则就像是给自己的 AI 同事做持续培训。这套模式用久了你会发现真正沉淀下来的不只是代码还有你对开发这件事的理解。
