最近好几个技术群和私信里都在同时刷一个关键词superpowers。有人问superpowers安装有人问superpowers使用指南还有人连续追问“它能不能搭配Codex用”“Java项目里到底怎么用”。我先给一个明确结论这里说的superpowers本质不是某个官方工具的名字而是一套开源社区里给AI编程代理准备的“技能库”体系。它通过预置一批带明确操作步骤、输入输出规范和自查清单的能力文件让Claude Code、Codex这类代理在干活时不再靠临场发挥而是严格按照一套可复用的SOP执行。这篇文章我不打算复述官方README而是结合我自己实际配置和使用的经验把superpowers从“它到底解决什么问题”讲到“怎么装、怎么用、怎么调”再附上我在Java项目、Codex联动、文字处理类任务里踩过的坑和总结出来的排查方法。无论你是刚听说这个项目的新手还是已经在用但被某些细节卡住的老手这篇文章应该都能让你少走不少弯路。1. 项目核心思路拆解为什么AI编程代理需要“技能库”1.1 从“提示工程”到“技能工程”以前大家调AI写代码习惯把精力花在写提示词上给一段上下文加一句“请用Java实现”然后期待模型输出正确代码。但等你真正在一个中型项目里跑上几天就会发现这种“一次性提示”的方式非常不稳定。模型经常改着改着就忘了约束条件或者换一种说法就产生完全不同的行为更不用说多步骤任务中间一旦断掉整个流程就从“自动化”退化成“手把手教”。superpowers这个体系解决的核心问题就是把“提示工程”往“技能工程”推进一大步。它的思路是与其每次对话都重新告诉AI该怎么做不如把一类操作封装成一个“技能文件”。这个文件里不只是写一句描述而是把触发条件、执行步骤、决策规则、完成标准全部固化下来。AI一旦识别到任务属于某个技能就按照清单一步步执行而不是自由发挥。打个比方你带实习生如果每次都不一样说一遍流程他总会漏步骤。但如果你把一套操作写成SOP规定他每一步做什么、每完成一项打一个勾最后再对照检查表验收出错的概率就会大幅下降。superpowers就是给AI代理准备的这套SOP。1.2 为什么大家的关注点会集中在“安装”上热搜词里高频出现superpowers安装、superpowers使用教程其实很能说明问题。这个项目不是一个图形界面的应用它不提供安装包也没有一键启动的客户端。它的交付物是一组markdown文件需要放进对应AI代理的配置目录里再由代理在每次启动时扫描加载。很多人第一次接触到“安装”这个词时会习惯性地去找安装向导结果发现找不到就开始到处问。所以要理解安装核心是先弄懂它运行的载体到底是什么。superpowers技能库最常见的运行载体是Claude Code这类支持插件和技能机制的AI编码代理其次是一些能自定义工作流的Codex客户端和命令行工具。这类代理启动后会读取固定目录下的技能文件。文件本身是纯文本结构上包含name、description、steps、checklist这样的字段。代理在对话中判断用户请求是否匹配某个技能的description匹配上了就加载对应的步骤列表然后按步骤执行。这整套机制并不依赖特定厂商所以社区里才有了“codex superpowers”这类组合玩法。1.3 一个技能文件里到底装了什么东西我直接把一个典型技能文件的目录结构拆给你看。假设你有一个名为skill-unittest的技能skills/ └── skill-unittest/ ├── SKILL.md ├── steps/ │ ├── 01-scan-test-framework.md │ └── 02-write-targeted-tests.md └── checks/ └── pre-commit-checklist.mdSKILL.md是入口负责描述这个技能什么时候适用并规定代理必须读取哪些步骤文件。steps目录下是按顺序编号的说明每个文件里包含具体指令、输入输出要求有时还夹带代码示例。checks目录则是验收清单用于执行完成后逐项确认。这个结构最大的价值是“隔离”。不同技能之间互不干扰一个技能内部的文件也各自独立代理只会按需读取。等于说你不用把所有规则塞进系统提示词里也不用每次对话都重复一遍需求。1.4 技能库与普通插件的区别很多人会把superpowers和插件混为一谈。二者确实有交集但出发点不一样。普通插件通常是一个固定功能的程序比如“格式化代码”“运行测试”它本身知道怎么执行。技能文件更侧重“让AI知道该按什么顺序调用什么工具、决策时遵循什么原则”。换句话说插件像是给AI装上了一双手技能则是给这双手配上操作规程。superpowers技能库里很多步骤最终还是要调用现有命令行工具和编辑器功能但它真正牛的地方在于把“怎么调用”“什么时候调用”“调用到什么程度算完成”给定义清楚。这也解释了为什么很多用了默认配置的Claude Code再做测试、重构、提交这类高重复度任务时输出质量会明显提升。不是底层模型变了而是原本靠临场发挥的步骤现在有了固定流程。2. 安装与前置准备从零开始把一个技能库跑起来2.1 环境依赖清单先说清楚安装superpowers的前提是你已经装好了支持技能扫描的AI编码代理。以最常见的Claude Code为例我得先确认命令行环境里能正常执行claude命令。你可以用下面这条命令快速验证claude --version如果提示找不到命令就先安装Claude Code官方脚本一般一行命令就能搞定。另外还需要确认你本地的Node.js版本够新因为Claude Code早期版本对Node版本有要求版本太老会出现各种诡异问题。我在CentOS机器上就遇到过Node 14导致的加载异常升级到18之后才稳定下来。如果你用的是Codex类工具情况稍微不一样。部分Codex客户端支持类似技能目录的机制有的则要借助第三方框架去加载。动手前先查一下你那个客户端是否已经有skills目录的约定。这一步差之毫厘谬以千里因为网上很多教程默认你用的是同一个主流客户端但实际上各家机制并不兼容。2.2 获取superpowers技能库的两种方式获取技能库源码有两条路我建议优先用git clonegit clone https://github.com/你的技能库地址/superpowers.git不过superpowers在社区里有多个fork和变体有的叫“superpowers”有的叫“superpowers-skills”授权协议和技能内容也有些差别。如果你只是想跑通流程随便取一个星标较高的版本即可。等熟悉了结构再按自己的需求增删修改。另一种方式是手动下载压缩包解压到目标目录。这种方式在你没有办法访问git服务时会派上用场。对于后续维护而言我更推荐git clone因为技能库更新比较快用git pull能直接同步上游修正不用再重新下载覆盖。拿到源码后先别急着复制。先看一下仓库里的README和目录结构确认它要求的安装路径是什么。因为不同变体会规定技能文件放进哪个目录有的叫skills有的叫plugins有的需要在配置文件中显式声明路径。2.3 在Claude Code中的配置步骤以Claude Code为例完整配置过程分三步。第一步进入你希望存放技能的目录比如mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/你的技能库地址/superpowers.git第二步确认Claude Code会扫描这个目录。Claude Code默认会读取用户目录下的.claude文件夹但不同版本对skills子目录的支持程度不一样。较新的版本会自动扫描老版本需要在配置文件里加上类似这样的字段{ skills: [ { name: superpowers, path: ~/.claude/skills/superpowers } ] }第三步重启会话。让Claude Code重新加载配置然后在对话里输入“我有哪些技能”或者在交互界面里找一下技能列表入口。能列出superpowers及其子技能就说明加载成功。2.4 安装完成后第一件事跑一次内置演示很多人的习惯是装完就开一个大项目去测结果某一步出错了也不知道是技能没生效还是指令写错了。我的建议是先跑一个自带的最小示例。超级技能库里一般会有类似“做一个示例任务”的技能你在一个空目录里触发生成看它是否按预定步骤创建文件、执行命令并输出完成说明。我第一次跑的时候卡在了命令执行权限上技能要求调用git但代理的运行用户配置不对git命令直接拒绝执行。后来我把运行目录的属主改对并把技能要求依赖的命令逐个列出来本地验证问题马上解决。先小范围验证再上真实项目能帮你在最短时间内判断“技能是否生效”这一层问题。3. 核心技能解析与实操要点3.1 高频技能都有哪些不同版本的superpowers技能库略有差异但有几个核心技能基本是标配。下面这张表列的是我在实际使用中觉得最常用的几个以及它们各自解决的问题域技能名称适用场景核心价值status技能项目中期开发先梳理当前代码库状态、未提交变更、测试情况再决定下一步动作test-driven技能需要新增或修改功能强制先写测试再写实现最后跑回归git工作流技能提交、分支、合并规范提交信息检查暂存区避免把调试代码提交进去depth-first技能复杂功能探索沿着一个任务路径深入展开不中途被无关信息带偏review技能代码审查按设计规范、安全隐患、性能问题逐条核查你可能会发现这些技能并没有发明新工具它们只是把优秀工程师的日常工作方式固化成了步骤。重要点在于它们让AI代理“想起”在这个过程中应该怎么做从而避免遗漏关键动作。3.2 触发机制的细节不要靠“猜”技能库的触发通常有两种方式。一种是显式触发比如你直接输入“请使用test-driven技能来完成这个功能”代理会毫不犹豫地加载对应技能。另一种是隐式触发代理根据你请求的内容自动匹配技能描述。日常使用中我强烈建议关键任务使用显式触发。因为隐式触发依赖模型对description与用户意图相似度的判断模型判断有偏差就可能选了错误的技能。例如“帮我改一下登录逻辑”这句话既可能匹配到重构技能也可能匹配到测试驱动技能还可能匹配到bug修复技能。一旦选错整个流程方向就偏了。所以我在团队内部定了一个小规矩任何超过10分钟的开发任务必须在开头明确指定使用哪个技能不允许纯靠AI自己判断。底下同学实践下来步骤漏跑的情况少了非常多。3.3 Java项目里的典型用法热词里出现superpowers java说明Java用户已经注意到这个技能库的价值但Java项目有自己的一些特殊性。第一个特殊点在于构建工具。Java项目可能是Maven、Gradle也可能是一个老旧仓库里还在用Ant。技能里的统一命令如果写的是mvn test就直接不适合Gradle项目。所以使用前要调整技能文件里的命令模板把测试命令改成与项目一致。第二个特殊点是Java的测试框架选择。JUnit 4、JUnit 5、TestNG、Spock各有各的写法。superpowers的测试驱动技能默认输出的是通用步骤不会替你写JUnit 5新特性。你需要在步骤文件里补充本团队的测试约定比如断言库用AssertJ还是HamcrestMockito的版本规则等。第三个特殊点是Java项目的构建时间。大型Java项目一次全量编译可能就要几分钟技能如果设计成每步都跑完整测试效率会非常低。我在实操里会把技能流程改成“增量编译→只跑受影响模块的测试→最后跑全局回归”并把这一步明确写进技能文件的决策规则里。3.4 如何改出一个属于自己的技能文件官方技能库不可能覆盖所有场景真正让superpowers发挥威力的是你自己动手定制技能。定制技能不需要会写代码只需要掌握Markdown的基本结构。先复制一个现有技能目录改名然后编辑SKILL.md。SKILL.md里最重要的字段是description因为它是代理做隐式匹配时的依据。我写description的一个技巧是用“当用户需要...时使用此技能”句式把可能的触发场景都写进去。如果一个触发词都不在description里代理基本就不会选它。步骤文件要写得具体包括操作顺序、输入来源、输出标准。我在自己团队里做代码规范检查技能时会把检查项直接并列成数字编号列表并且明确要求最后输出一个检查报告。这样代理执行完以后输出格式稳定下游评审环节也更容易对接。4. 实操过程实录从配置到跑通一个真实任务4.1 跑任务前必做的三件事每次拿superpowers跑真实任务前我都会强制自己做三件准备。第一件确认所在git分支是干净的或者至少知道本地有多少未提交改动。有未提交的改动时跑自动修改类的技能非常危险因为无法判断哪一行是AI改的、哪一行是你自己改的。第二件把任务范围写清楚。包括涉及的文件路径、期望的行为变化、允许修改的范围、禁止触碰的模块这能大幅减少AI在无关代码上操作的可能。第三件确认工作目录里的测试命令能独立运行成功。不要低估这三件事的作用。我见过大量案例表面上是“技能执行失败”实际上是准备工作没做好。比如代理在步骤里运行测试结果因为本地环境缺少依赖而失败它就自己判断“测试不通过继续改代码”然后越改越乱。如果一开始就验证基础测试是过的问题就只会在修改后的代码上出现。4.2 用test-driven技能新增一个Java接口的完整流程我拿一个实际场景举例项目里要给订单模块新增一个查询接口。我先显式触发技能输入请使用test-driven技能开发订单模块的查询接口要求参数包含订单号和用户ID返回值包含订单状态和创建时间。代理读取技能后第一步不是写接口而是先分析现有测试框架。我在技能文件里放了一个扫描步骤让它自动查找pom.xml或build.gradle里的测试依赖并识别当前用的JUnit版本。这一步在实际执行时很关键因为它避免了生成完全不兼容的测试代码。第二步是写第一个失败测试。技能强调必须先看到失败因为只有看到失败才能证明测试是真正在验证你要的功能。代理会创建订单查询服务的测试类写一个基本场景传入存在的订单号和用户ID断言返回状态正确。然后运行mvn test预期抛出编译错误或断言失败。第三步是实现最小代码使测试通过。代理会在测试的驱动下添加新方法并且只添加满足现有测试的代码不做多余实现。这一步执行完后再次运行测试确认全绿。第四步是跑全量回归。技能文件的最后一步会要求执行整个模块的测试套件并检查是否有其他用例因为本次改动而失败。整个流程跑完代理会输出一个简短报告列出测试用例数量、失败数以及修改文件清单。整个过程我几乎不需要介入。但有一点要提醒代理在识别测试框架时偶尔会出错如果你发现它生成了JUnit 5风格的注解但项目还在用JUnit 4就及时打断它把技术栈信息直接补充进对话。4.3 让技能与Codex生态配合使用为什么会有人搜codex superpowers是因为不少开发环境里Claude Code和Codex会并存而superpowers主要活在Claude Code体系内。那Codex用户是不是就没法享受这套东西了并不是。关键在于Codex是否能读取同样的技能文件。一种做法是采用支持技能目录的Codex客户端。我可以把一个技能文件目录配置到Codex的读取路径里让Codex在回答代码问题时也能参考技能文件的规定。实际操作中我会在Codex的配置里增加一个自定义指令让其优先加载skills目录下的重点技能内容。这种方式没办法完整复现Claude Code的步骤编排但对于“规范测试流程”“规范提交信息”这类轻量约束效果非常明显。另一种做法是让Claude Code和Codex分工。Claude Code跑完整流程级的任务比如“按test-driven技能完成接口开发”Codex负责更轻量的“帮我查一个API参数”“快速生成一段样板代码”。这样两边的角色清晰也不互相打架。我比较反对的是在两个环境里同时跑同一个复杂任务因为没有统一的状态管理容易出现把同一个文件反复改写的情况。给工具明确边界比你想象的要重要得多。4.4 非代码场景的扩展用法热词里还有一个我比较在意的问题worbuddy怎么用superpowers。我猜测提问者是想在文字处理类工具里引入类似技能库的机制让AI按一套流程处理文档。其实这个方向完全可行因为superpowers底层解耦了“技能文件格式”和“代理执行器”。只要某个工具允许加载外部指令集理论上都能用。我自己试过在文档批处理场景里定义技能给定一批原始素材先统一格式再做敏感词过滤然后按模板生成摘要最后归档到指定目录。每一个步骤都写成技能文件里的一个checklist每完成一项确认一次。执行下来虽然不可能达到代码项目那种精确度但比我以前用一段超长提示词去控制AI要稳定得多。如果你要做这个方向记住一个原则不要追求“一个技能搞定所有”。文字处理任务千差万别一个技能内部步骤越短越不容易出错。宁可拆成五个小技能也别写成一个庞大而模糊的技能。5. 高频问题与排坑实录5.1 问题速查表下面这张表是我从自己踩坑经验和社区高频问答里整理出来的问题清单按“现象→原因→解法”三列展开现象常见原因解决办法输入“使用superpowers”但代理毫无反应技能目录路径不被代理扫描检查配置文件里的skills路径确认目录存在且权限正确技能加载了但执行到一半跳过步骤SKILL.md里的步骤编号不规范代理没读全重写步骤文件去掉非必要内容保持步骤编号清晰代理生成了错误的测试框架代码技能里没有规定识别依赖的步骤在步骤开头加入“先扫描构建文件确认框架版本”的指令运行测试命令报权限错误代理执行环境用户与项目属主不一致统一运行用户或调整项目目录属主多个技能同时匹配行为混乱description写得过于泛化精简description使用更精确的任务关键词安装其他插件后技能突然失效插件优先级覆盖了技能目录检查插件加载顺序恢复技能目录读取配置这张表不能覆盖所有情况但你可以把它当作排查起点。大多数问题都不是模型不行而是“代理没有读到该读的文件”或者“多个约束之间打架”。5.2 三个我踩过最深的坑第一个坑是直接把技能库放在项目仓库根目录下。短期看着没什么问题但技能文件会随着项目变动出现在代码审查里团队成员还得反复处理这些无关改动。后来我把技能统一放到了用户目录所有项目共享一份问题一次性解决。如果你希望某个技能只对当前项目生效再考虑放进项目内部并且记得把它加入.gitignore。第二个坑是技能步骤文件里写入了过时的命令。比如老版本技能库里的测试命令是mvn test -DskipITs但项目后来已经切换到Gradle这条命令就失效了。代理每次执行到这一步就报错又没法自己判断是命令问题还是项目问题会不停尝试别的猜测性修复。现在我每次更新技能库都会顺手跑一遍关键命令确认和当前项目兼容。第三个坑是过度依赖技能库的“默认编排”。superpowers默认设置有时候会把任务拆得很长每一步都要求确认结果完成一个小功能需要十几轮交互。这种体验非常磨人。后来我学会了给技能增加一个“快速模式”分支如果任务风险低就跳过部分检查项直接按精简流程执行。这个优化把完成时间缩短了将近一半。5.3 让技能稳定生效的四个小习惯第一描述任务时尽量包含结构化信息。比如把需求拆成“背景、目标、约束、完成标准”四段代理在加载技能后能直接套用这些信息而不是再从模糊对话里提取。第二技能文件里多用显式指令少用“合适的话可以XX”这类模糊说法。代理对委婉表达的理解很不稳定写“必须在步骤完成后输出检查结果”一定比“可以考虑输出一下”更可靠。第三重要项目里给技能步骤设定“检查点”。我会在容易出问题的步骤之间要求代理暂停等确认无误后再继续。虽然会多花一些交互时间但失败回滚的成本要高昂得多。第四定期清理不再使用的技能目录。我见过有人把十多个技能全部堆在同一个目录里导致代理在选择技能时频繁匹配错误。留下三个真正高频使用的技能比堆二十个花哨技能有效得多。5.4 排一个真实案例技能加载了但测试一直失败有次我在一个Spring Boot项目里跑测试驱动技能代理已经正确创建了测试类但运行mvn test时报错提示找不到测试类。我首先确认测试目录结构是src/test/java没写错。又检查了pom.xml发现项目里配置了maven-surefire-plugin的includes节点它只扫描以ControllerTest结尾的测试类而我生成的是OrderQueryTest所以被过滤掉了。这个案例很有代表性因为所有步骤都是按技能设计执行的问题出在项目本身的构建配置上。这类问题靠改流程没用需要把项目的特殊规则补充到技能文件里。我随手在技能目录下加了一个notes文件记录Spring Boot项目常见的surefire配置异常之后再次跑技能时代理会先读取这个notes文件再决定生成测试类的命名策略。这个经验给我提了个醒技能库不是一次配置永久有效的项目一多样就得持续往里补上下文。最后再分享一个个人习惯。我每次使用superpowers之前都会先做一次“技能文件自检”对着清单确认目录结构、命令路径和描述精确度。这个习惯看起来笨但它帮我避开了绝大多数“装了没生效”的尴尬。如果你准备把superpowers引入日常工作流不妨从一个小任务开始先跑通再放大。等技能真正稳定运转起来你会明显感觉到AI编程代理从一个“偶尔聪明但经常跑偏”的助手变成了一个“每一步都有章法”的合作伙伴。