★ FEATURED ARTICLE 最近AI圈子里有个词出镜率高得吓人——superpowers。别误会这里说的不是超级英雄电影而是一套能让AI助手真正“干活”的技能框架。我自己从Codex CLI刚起步时就在捣鼓终端AI编程短短几个月从只会“你问我答”的聊天助手变成能跨仓库跑测试、做代码审查、写项目文档的“半自动协作者”靠的正是superpowers这套思路。这篇文章不讲虚的就把我实际踩过的坑、验证过的方案以及怎么从零把一个只会写代码片的AI助手养成一个能独立完成多步骤任务的“老员工”完整梳理一遍。无论你是刚接触Codex的新手还是已经在用Claude Code、Cursor的玩家读完大概率都能直接把这一套搬进自己的项目里。全文技术含量不算高贵在每一步都是亲手试过的。1. superpowers到底是个什么东西1.1 先理解普通AI助手的“天花板”我得先说清楚一个很多人容易忽略的问题AI编程助手到底卡在哪里。其实答案很简单它们大多只有一张嘴没有手和记忆。它们能帮你写一个函数、解释一段报错、补一个测试用例但你让它“把这个服务模块从单体里拆出来顺带把相关调用点改一遍、测试补好、文档更新掉”它就懵了。为什么第一它没有状态记忆。上一轮聊了什么下一轮就忘了超过上下文窗口的内容直接蒸发。你让它做跨文件的修改它改到一半自己都不知道自己改到哪儿了。第二它没有持续的工具调用链。虽然现在的模型都支持function calling可以调搜索、跑命令、读写文件但“能调工具”和“知道什么时候调、按什么顺序调、失败了怎么回退”完全是两回事。大模型本质上还是概率生成你指望它每次都在正确时机调取正确的工具链痴人说梦。第三它没有团队经验。你的团队有编码规范、有测试标准、有历史包袱这些东西不在训练数据里模型根本不知道。它给出的建议可能语法完全正确却不符合你们项目的实际约束。这就是superpowers这类工具出现的背景。它不改变模型本身而是改变你组织AI工作流的方式把“怎么做一件事”的完整经验提前写成一份AI可读的说明书。说明书里写清楚触发条件、详细步骤、工具命令和兜底策略。模型遇到相应场景时不再靠猜而是打开说明书照做。1.2 技能不是插件是一份“经验说明书”接着上面的话题superpowers的核心设计非常朴素技能即文件。它不搞复杂的二进制插件体系也没有启动常驻服务。你安装superpowers之后得到的是一个个遵循统一格式的文本文件通常叫SKILL.md。每个文件就是一个完整技能的说明书。这个设计我觉得非常高明。你可以把SKILL.md理解为“给AI看的SOP”。里面记录了这个技能叫什么、什么时候触发它、具体执行哪些步骤、每一步要调用什么命令、最后的输出应该是什么样子。因为技能是纯文本文件它有普通工具插件做不到的几个优势可读性极强。AI执行出错时你打开SKILL.md扫一眼立刻能看出是哪条指令写得有歧义改一行字就完成技能迭代。天然适合版本管理。技能库就是一个git仓库写坏了随时回滚升级了自动同步。复制成本几乎为零。你在一个项目里沉淀出一个好技能想带到另一个项目就是复制一个文件的事。更关键的是这种方法论对模型是通用的。不管底层用的是Codex、Claude还是其他任何支持工具调用的模型只要它读得懂Markdown、能执行终端命令技能体系就能跑起来。这也解释了为什么superpowers能迅速聚集起一批用户——它解决的问题是刚需方法又轻到极致。2. 装好第一套技能从Codex到superpowers2.1 把Codex CLI跑起来当底座superpowers最常见的搭档是OpenAI的Codex CLI。一个原因是Codex本身就在终端里工作和技能体系的“命令行驱动”天然契合另一个原因是Codex对配置文件的扩展性做得比较开放技能路径可以直接挂进去。先装Codex。我实测用的是npm方式npm install -g openai/codex如果你的机器上已经有Homebrew也可以走brew路线二选一brew install codex装完先别急着用确认版本号正常输出codex --version没有报错的话接下来配置API Keyexport OPENAI_API_KEYsk-你的key我建议把这行写进~/.zshrc或~/.bashrc。不然每天打开终端第一次用Codex都得手动export一遍真的很烦。这里有个小坑Codex对API Key的权限要求比较严格如果你的Key绑定的是基础模型权限后面跑技能时报错会非常诡异比如明明能对话但一调工具就静默失败。遇到这种情况先去检查Key的权限范围别急着怀疑superpowers装错了。2.2 三条安装路径怎么选装好Codex之后第二步就是安装superpowers。我试过的方式里比较靠谱的有三条按你的情况选。方式一一键初始化新手无脑走npx superpowerslatest这条命令做的事很直观把技能库从网络拉到你本地、扫描机器上的Codex配置、自动把技能路径写进去。整个过程是交互式的会问你几个问题比如“是否需要网页搜索技能”“是否启用长时记忆”等等。我的建议是第一遍全部选yes先把能力都拉起来后面不需要了再逐个关掉。方式二Git clone手动挂适合二次开发git clone https://github.com/xxx/superpowers.git ~/.superpowers然后打开Codex的配置文件一般在~/.codex/config.toml手动加上技能路径。至于配置项的键名不同版本略有区别最稳妥的做法是先跑codex --help看输出里关于skills的参数叫什么再对着写。这种方式适合想自己魔改技能库的人你可以把整个目录当成自己的私货仓库随意增删。方式三完全自己搭最干净说白了就是创建自己的技能目录在里面按标准的SKILL.md格式写技能再把目录指给Codex。这个方案的好处是完全可控不带任何第三方依赖。坏处是前期得自己积累技能没有内置库可直接用。三种方式选哪种我的判断标准很简单新手选一折腾过一些AI工具的人选二目标明确只想给Codex加三五个专属技能的人选三。装好之后先做一次目录检查ls -la ~/.superpowers/skills能看到一堆SKILL.md文件就说明技能库基本就位了。2.3 安装完必须先做的一次冒烟测试这一步很重要别跳过。很多人在安装完之后直接上大任务结果AI跑得稀里糊涂最后才意识到技能压根没被加载。启动Codexcodex然后直接在会话里问一句你现在有哪些技能如果配置正常它会把你技能库里各个文件的描述信息做个概括哪怕只是简单列举几个名字也是好信号。要是它回答“我没有任何技能”或者表现出完全不知道你在说什么的状态不要卸了重装先按第6章的自查表走一遍。大概率是路径拼写错了、环境变量没刷新或者config文件被别的插件覆盖了。还有一个我自己重复踩过的坑技能是“按需触发”的。你装完技能不代表AI会在每个回答里都自动调用它。模型是根据用户请求和技能的description来判断要不要激活的。所以冒烟测试时如果AI能说出技能名就已经达标了真正要验证技能好不好使得构造一个触发它的具体任务比如直接说“用代码审查技能看看当前分支的改动”。3. 核心机制SKILL.md到底该怎么写3.1 技能文件的基本结构与元数据理解了安装真正的重头戏是理解技能文件的写法。一个标准的SKILL.md由两个部分组成YAML格式的元信息头和Markdown格式的正文指令。拿我常用的“代码审查”技能举例--- name: code-review description: 对当前Git仓库的代码变更做全面审查输出问题清单和修改建议。 --- # 代码审查技能 执行以下步骤 1. 运行 git status 查看当前变更文件 2. 运行 git diff 获取变更内容 3. 逐个检查业务逻辑、异常处理、命名规范、安全风险 4. 输出Markdown格式报告按严重程度排序这里最关键的是description字段。它是模型判断是否触发技能的“引力源”写得越具体、越能覆盖实际使用场景触发就越准确。比如“对当前Git仓库的代码变更做全面审查”这种描述比“代码分析工具”好一百倍。因为你跟AI说“看看这次分支改了什么”如果description太宽泛它可能随便用个通用能力回答不会想到要调技能。正文部分则要遵循“可执行原则”。每一条指令都应该包含足够的信息让AI不需要自己发挥、临场猜步骤。与其写“检查代码质量”不如写清楚查哪些维度、用哪个命令、输出什么格式。AI就像一个新来的实习生你要把步骤讲到它不用思考也能干活的程度。3.2 内置技能逐个拆解哪些真正值得用我装完superpowers之后把内置技能都过了一遍这里说说实际感受。首先是web-search。这个技能等于给AI加了一双“外眼”它可以在你允许的前提下主动上网搜资料。我最常用的场景是查依赖的新版本、确认某个库的最新API、看社区对某个报错的解法的讨论。实测下来它的效果取决于底下的搜索引擎质量偶尔会抓到过时页面。用的时候最好在指令里加限定词比如“只搜最近一年”“优先看官方文档”。然后是memory这个是我认为整套内置技能里最值钱的一个。它能给AI提供跨会话的长时记忆你把项目背景、技术栈、用户偏好、进行中的任务写进本地文件下次新开会话时AI先读一遍就“回忆起”之前聊了什么。这对多轮推进同一个大需求尤其重要。不过memory也有副作用一旦写入策略太宽松AI会把所有对话内容都记下来记忆文件越滚越大最后反而干扰判断。我的处理办法是定期清理只保留真正跨会话有用的项目级信息。project-management技能也不可小觑。它专门干一件事把一个大任务拆成多个阶段维护一个待办列表按顺序执行。我实际用下来的体验是它非常适合那种“涉及十几个文件的重构”。普通对话里AI做着做着就忘记自己做到哪一步了而这个技能能让它每一步先检查待办、更新进度相当于给AI加了一张任务看板。至于secrets类的技能我建议有条件就装上。它的作用是防止AI在处理敏感信息时把密钥明文打印出来。平时可能用不上但一旦踩雷代价很大。我不建议把内置技能当成不可修改的黑箱。这些技能的指令能力有限你完全可以按照自己项目的实际情况去改。改一个技能的成本和改一份文档差不多。3.3 实操演示从零写一个Java测试生成技能光看原理不过瘾我们直接上手写一个技能。目标场景是Java项目为指定类自动生成JUnit 5单元测试用Maven管理依赖。第一步在技能目录下新建文件夹mkdir -p ~/.superpowers/skills/java-unit-test第二步创建SKILL.md--- name: java-unit-test description: 为指定的Java类自动生成JUnit 5单元测试使用Maven作为构建工具测试覆盖主要业务分支。 --- # Java单元测试生成技能 当用户要求为某个Java类编写单元测试时按下面步骤执行 1. 读取目标类的源码确认包名、类名、构造方法和关键业务方法 2. 检查项目根目录是否有 pom.xml确认里面已包含JUnit依赖 3. 如果缺少JUnit依赖先在 pom.xml 中加入以下内容后执行 mvn dependency:resolve xml dependency groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter/artifactId version5.11.4/version scopetest/scope /dependency在src/test/java下对应包路径中新建测试类类名以Test结尾编写测试方法覆盖正常路径、异常路径和边界条件运行mvn -q test -Dtest你要生成的测试类名验证通过如果测试失败读取失败日志并分析原因修改测试代码或被测代码后重跑这个技能写出来已经能处理大部分Java单元测试生成需求。这里有几个我踩过的写技能教训值得说一下 - 指令一定要带上确切的命令和参数。我第一次写的时候只写“运行测试”结果AI自己发挥出了各种奇怪的命令有的在Linux上有效在macOS上直接报错。 - 一定要有“失败后怎么办”的兜底分支。AI是概率模型写单次成功路径不够你得告诉它失败了从哪看日志、怎么定位问题否则它会卡在原地反复试同一个错误命令。 - 不要在技能里写太多和任务无关的上下文。技能文件越聚焦模块触发越精准AI执行起来越不跑偏。 ## 4. 进阶实战Java项目、AI工作流与团队复用 ### 4.1 Java项目里superpowers这样用才不踩坑 搜“superpowers java”的人不少说明大家真想把它用在Java项目里。Java和Python、JavaScript最大的差异在于两点依赖管理和构建周期。一个Java工程从编辑代码到跑通测试中间隔着Maven或者Gradle的编译打包耗时动辄几十秒这对AI执行技能的影响非常大。 我实测下来的解法是围绕Java的构建特点定制技能。比如给AI写一个“Maven依赖审计”技能让它在分析任何代码前先跑 mvn dependency:tree -DoutputFile...把依赖树存到临时文件然后再让代码分析技能只读这个文件减少AI自己解析pom导致的路径错误。 再比如编译期长的问题。技能里应该拆成两步走第一步先 mvn compile 确认编译通过第二步再 mvn test 跑测试。这样如果编译挂了AI能快速定位语法错误而不是傻等一个跑到一半挂掉的测试任务。 Java项目还有一个细节模块化工程里测试类所在的位置、类路径的配置都很有讲究。技能文件里最好写入你的项目约定比如“所有单元测试统一放在 src/test/java 下集成测试放在 src/it/java”AI就不会在乱七八糟的位置乱建文件。 我建议每个Java团队都维护一套自己的Java专用技能包括依赖审查、单元测试生成、JavaDoc补全、增量构建等。这比通用技能实用得多因为通用技能根本不知道你们项目用的是老版本Spring还是新版本虚拟线程。 ### 4.2 把superpowers接进日常AI工作流 很多人搜“worbuddy怎么用superpowers”我猜言下之意是怎么把这套技能嵌入到自己常用的AI工作流或编排工具里。这类工具五花八门有的叫助手有的叫Agent但背后的集成思路大差不差——它们都允许你通过命令行或脚本调用外部工具。 一个通用且稳的用法是用 codex exec 跑非交互任务。假设你想每天自动审查一次当天代码变更可以写这么一段脚本 bash #!/bin/bash cd /your/project codex exec 用code-review技能审查当前分支的变更输出报告到 /tmp/review.md然后把这个脚本挂到cron里每天早上跑一次再把报告推送到团队群。代码审查这件事就自动化了一大部分。这种玩法我实际跑过一段时间发现关键是要先验证codex exec在非交互环境下能正常加载技能有些配置在shell里生效但在cron这种最小环境里会漏掉。如果是更复杂的工作流编排比如你希望“先跑测试再根据结果决定是否生成发布说明”那就更简单了——把Codex的技能调用嵌在自动化流水线的多个节点上。superpowers只负责“让AI有能力做某件事”流水线本身还是用你自己熟悉的那套工具。4.3 团队技能库怎么维护自己用顺了自然想在团队里推广。我的建议是建一个独立的git仓库放技能库团队成员clone到统一路径比如~/.superpowers/skills再在Codex配置里指向这个共享目录。团队维护技能库要注意几件事技能文件要有人负责。每一条技能都是团队AI行为的规则改错一个description影响的是所有人后续的AI输出。版本要绑定项目。团队项目在快速迭代时技能库里的编码规范、目录约定都要跟着项目走。技能库跟代码库同步更新不要一套技能走天下。做一次评审。新增或修改技能应该像改动核心代码一样过一遍Review重点检查指令没有歧义、命令没有过时、兜底分支是否完整。我见过最典型的反面案例某团队把旧的目录结构写死在技能里结果项目重构后AI还按旧路径去找代码给出的建议全不落地。技能库和代码库一样需要人定期维护不能写完就撒手不管。5. 常见问题与排错实录5.1 一张速查表解决80%的安装配置问题我把这几个月遇到的高频问题整理成了一张表基本覆盖了从安装到使用的常见故障现象可能原因解决思路我的备注AI完全不知道有技能存在技能路径未生效或权限不对检查config路径、目录可读性、环境变量是否刷新配置里写绝对路径最省心技能触发太频繁description写得太宽泛收紧描述限定触发场景别写“处理所有问题”这类词技能执行到一半报错指令里的命令与当前系统不兼容手动在终端跑一遍该命令确认先本机验证再交给AIweb-search返回过期资料搜索引擎结果排序问题在技能里限定时间范围和站点关键信息必须加二次验证步骤memory内容越来越乱写入策略太宽松限制写入条件只记项目级信息每周删一次记忆文件毛病少很多AI频繁碰壁不换思路技能缺少兜底分支在技能正文补充“失败时执行什么”这是新手写技能最爱漏的部分这张表里的前四条基本上可以解决我见过的80%的安装配置问题。剩下两条属于使用习惯问题需要你在实际使用中慢慢调整。5.2 从日志定位技能不生效或执行中断排错不要瞎猜先看日志。Codex运行时的详细日志默认在~/.codex/logs/目录下每次会话都有独立日志文件里面记录了每一次工具调用的输入、输出和报错信息。我的排查流程通常是这样的用ls -t ~/.codex/logs/找到最近一次的日志文件在日志里搜索技能名比如搜code-review确认它到底有没有被触发如果没搜到说明模型的调用流程根本就没走进技能体系问题多半出在description写得不够触发条件如果搜到了继续往下看技能读取的是哪个文件、执行了哪些命令找到具体报错行最后手动跑一遍日志里记录的关键命令对比输出到第五步绝大多数问题都能定位。如果手动跑命令成功而AI跑失败那基本是环境变量或当前工作目录的问题可以重点检查cron或自动化场景下的配置如果手动跑也失败那就没什么好说的技能文件里的命令本身就是错的直接改技能。还有一个技巧如果你怀疑某个技能文件没有被正确读取可以故意在该文件的正文第一行写一句“如果你读到这句话请先回答我读到了”然后触发一次技能。这个方法非常直观能快速判断AI到底有没有真正看到这个文件。最后分享一点个人体会。我最初以为superpowers最大的价值是那堆现成的技能用了几个星期之后发现真正值钱的是它把“扩展AI能力”这件事变成了一种可以积累、可以传承、可以Review的工程实践。今天你花十分钟写的一个小技能也许当时看平平无奇但半年之后它可能已经是整个团队AI工作流里最稳定的一块基石。如果你也打算入坑我的建议很简单不要贪多先挑一个你现在最痛的点写一个把它做到极致的技能。比如你每天最烦的就是人工Review别人的Pull Request那就写一个代码审查技能先跑通、跑稳再慢慢添加其他能力。这比一次性装二十个技能、最后哪个都调不准要有效得多。工具的版本更新很快安装方式说变就变但“技能即文件、经验即代码”这个思路是很长时间内都成立的。
阅读完成 · 觉得有帮助？
