最近AI编程工具圈里superpowers这个技能包热度很高不少人在问同一件事Codex CLI、WorkBuddy、Trae Work CN里到底怎么把这个skill装好、跑起来。我前后折腾了一个多星期在几个主流工具上都试了一圈踩了不少坑今天把完整的从零到上手的过程整理出来方便想装的人少走弯路。superpowers是什么一句话说清楚它是给AI编程助手准备的技能包。默认状态下Codex、Claude Code这类Agent工具虽然能写代码但在复杂任务面前经常出现高估自己、上来就写、写一半发现方向错了的情况。superpowers做的事就是把软件工程里先规划、再执行、边做边验证、最后审查重构这套成熟玩法变成AI能够稳定加载并执行的技能。适合谁如果你已经在用AI编程工具但觉得产出质量不稳定、经常要返工或者你想让工具在你离开时也能按规范推进任务那这个技能包值得拿出半天时间装上、跑通、调顺。1. superpowers核心思路为什么一个技能包能解决问题1.1 技能包到底在干什么先别急着敲安装命令我得说清楚superpowers这套东西解决的根本问题是什么。大家用AI编程助手时间长了大概都有同感让AI写个函数、改个bug它很利索但让它完成一个跨文件、多模块、带约束条件的任务它就开始自由发挥经常是把代码糊出来了架构却没想明白改完一个地方又弄坏另一个地方。原因在于默认状态下AI只被训练了如何回答没有被系统性地训练如何像有经验的工程师一样推进工作。它知道编程语言的语法知道常用框架的API但它不知道项目动工前要先做需求拆解不知道改共享模块时要去排查所有调用方不知道测试通过不等于质量过关。这些工程常识对人是靠多年经验沉淀出来的对AI则需要显式地告诉它。superpowers这类技能包本质上是一组经过精心设计的指令文件和规范文档打包成技能形式放进AI工具能读取的目录里。它给AI补上的正是上面说的工程常识接到任务后先分析需求和约束拆解成可执行的子任务明确每一步的验收标准执行过程中每完成一步就自查一次确认没有引入新问题再进入下一步全部做完后还要做代码审查、补测试、优化结构。这套流程放在人身上叫职业素养放在AI身上就成了超能力。1.2 和普通提示词、普通插件有什么区别有朋友和我说我直接在系统提示词里把你要先规划再写代码写进去不就行了我一开始也是这么想的试过之后发现真不行原因有三点第一系统提示词有长度上限。你把完整工作流塞进去留给代码和上下文的窗口就被挤占了大项目里本来就紧张你还要拿珍贵的上下文去装行为规范不划算。第二提示词是一次性加载的。对话一长、任务一多模型很容易把靠后的指令忘掉。我实测过会话进行到一半AI完全可能把先分析再动手这件事抛到脑后直接进入写码模式。第三普通提示词是线性叙述AI不知道在什么节点该引用哪段规范。技能包则是按需加载的结构平时占用极小空间一旦任务进入某个环节AI能通过工具调用机制主动读取对应技能文件拿到针对当前步骤的详细指导。普通插件比如各类VS Code扩展解决的是工具链集成问题帮你方便地调用API、跑命令、看结果superpowers解决的是行为模式问题它不新增工具能力而是重新组织AI的工作方式。两者可以共存并不矛盾——实际项目里superpowers的工作流经常会调用插件暴露的命令和接口来完成任务。1.3 理解两个关键机制Skills与Agent要顺利安装和使用你需要先理解两个底层机制Skills和Agent。Skills是一种标准化的技能定义方式可以理解为一套按目录组织的、带额外元数据的提示词文件集合。每个技能有一个名字、一段描述、若干具体操作指令存放路径通常遵循约定比如用户目录下的skills文件夹或项目内的.skills目录。AI工具启动时或运行过程中能够感知这些技能的存在并根据任务需要加载对应内容。superpowers就是这样一个包含多技能、多文件的技能包集合。Agent则是执行主体。在Codex CLI、WorkBuddy、Trae Work这类工具里Agent是驱动整个编码过程的大脑它接收用户指令决定调用哪些工具、读取哪些文件、执行什么命令。superpowers的种种技能最终要作用在Agent身上才有意义。理解这一点很重要安装superpowers的过程本质是让Agent在运行时有途径找到并使用这些技能所以无论你用的是哪款工具核心逻辑都是一致的——把技能文件放进Agent能检索到的位置再通过对话或配置让它按需加载。2. 安装前的准备版本、环境与目录结构2.1 几款主流工具的定位差异网上搜索到的安装教程往往针对不同工具如果不加分辨直接照抄很容易装完发现不生效。先说清楚这三款主流工具的定位差别Codex CLI是OpenAI出品的开源命令行编码代理最大的特点是极简、纯命令行交互强调和终端工作流的融合。它适合习惯在终端里解决一切的开发者对技能包的加载比较直接目录结构约定清晰适合从零开始理解superpowers的原理。WorkBuddy是在部分开发者社区里流行起来的一款Agent工作台工具它的特色是把技能作为一类一等公民来管理内置了技能市场、可视化配置面板安装superpowers的体验更接近在应用商店装一个应用。它的特点是门槛低适合不想折腾命令行的朋友。Trae Work是字节跳动旗下AI IDE Trae里的Agent工作流能力Trae Work CN是面向国内用户的版本。它本质上是IDE Agent的组合技能包安装和使用方式介于命令行和可视化之间核心是让AI在编辑器上下文里完成端到端的开发任务。需要特别注意Trae Work CN这类中间态工具对技能格式的兼容性偶有问题安装时优先使用官方推荐的版本格式。一句话总结Codex CLI适合折腾派、WorkBuddy适合省心派、Trae Work适合想要IDE体验派。工具没有绝对好坏选和你日常开发习惯最匹配的就行。2.2 安装前必须确认的四件事动手安装前我强烈建议先花十分钟检查环境避免装到一半才发现基础条件不满足。第一确认工具版本。superpowers对较老的工具版本支持不好很多安装后不生效的问题根源其实是工具版本太低根本读不到新格式的技能文件。建议把Codex CLI、WorkBuddy、Trae Work都升级到当前最新稳定版再去安装技能包。第二确认Node.js或运行时环境。Codex CLI以及不少技能包内部会调用外部脚本Node.js 18以上是常规要求部分新技能甚至要求20。用一个简单的node -v命令确认版本低于18的建议先升级。第三检查磁盘写入权限。技能包装到用户目录通常不需要sudo但如果你用公司电脑用户配置目录可能被安全策略锁住技能文件写不进去。这种情况可以先在项目目录下建一个技能文件夹用项目级配置绕过全局目录的限制。第四确认Git可用。superpowers的安装方式通常是git clone技能仓库到本地或者手动下载压缩包解压。Git版本太老可能导致拉取失败或文件不完整装完技能缺胳膊少腿。2.3 技能目录与加载机制几乎所有支持技能的AI编码工具都遵循一个共同逻辑技能文件放对位置Agent才能发现它。位置上通常有两种模式用户级目录放在当前操作系统的用户主目录下比如~/.codex/skills、~/.workbuddy/skills或~/.trae/skills。这种模式的好处是全局生效打开任何文件夹工具都能找到技能包。项目级目录放在当前项目根目录里比如your-project/.codex/skills、your-project/.workbuddy/skills。这种模式适合把技能和团队共享配合配置文件一起提交到代码仓库新成员克隆项目后开箱即用。选择哪种模式我个人的倾向是如果你只需要自己用装在用户级如果要在团队里推广或者不同项目可能需要不同版本的技能用项目级。多说一句如果两者同时存在具体某一工具优先加载哪个要看它的实现大多数是项目级覆盖用户级。你可以在项目里放一份特调配置用户目录放一份通用配置灵活度会更高。2.4 配置文件的身份与作用技能目录旁边通常会有一个配置文件名字一般叫config、config.json或settings。它负责登记两件事哪些技能被启用以及技能在运行时的一些默认参数。比如superpowers里可能有一个关于规划深度的配置你可以在配置里指定它平衡速度和完整性还有是否在每次任务前强制生成计划清单等开关也由配置文件控制。这部分经常被新手忽略以为技能包clone下来就算装好了结果Agent运行起来时没有应用超人行为就是因为配置里根本没声明启用。所以第3章的安装步骤里我会把配置文件的修改单独拉出来讲别跳过去。3. 分工具实操superpowers安装全过程3.1 在Codex CLI中安装superpowersCodex CLI是我最先折腾的工具也是最适合理解原理的入口。整体分四步第一步把技能包clone到Codex的技能目录。先确认Codex CLI的技能读取路径# 查看用户级技能目录是否存在 ls ~/.codex/skills如果目录不存在就手动创建mkdir -p ~/.codex/skills然后进入这个目录把superpowers的技能仓库拉下来cd ~/.codex/skills git clone https://github.com/你的技能仓库地址/superpowers.git这里需要注意不同作者维护的superpowers仓库结构可能略有差异。有的仓库clone下来就是标准技能目录结构有的则是一个更高层的包里面还有skills/子目录需要你把内容再复制一层。具体做法clone完成后打开目录看一眼如果里面有SKILL.md这类技能定义文件说明结构正确如果顶层是skills/文件夹就把里面的内容拿出来放在~/.codex/skills/superpowers/下。第二步修改Codex配置文件声明加载superpowers。不同版本配置文件名不一样常见的是~/.codex/config.json或~/.codex/config.toml。以JSON版本为例在配置里找到技能相关字段没有就手动新增{ skills: { enabled: [superpowers] } }配置写法不同版本差异较大如果拿不准用Codex CLI提供的设置命令最稳妥它会自动帮你写对路径和格式。第三步验证技能是否被识别。重新打开一个Codex会话直接问它你目前加载了哪些技能如果回复里能明确提到superpowers并且能说出它包含的主要技能名称就说明加载成功了。如果回复含糊不清大概率是配置路径没对上回到上一步检查。第四步启用具体的技能能力。superpowers不会把所有技能都默认打开它依赖一个主技能相当于总入口来分发子任务。在对话中明确提出请使用superpowers来处理这个需求让Agent知道本次任务要走强化流程。之后就可以看到它开始执行规划、拆解任务、逐项推进整个对话节奏都会明显不一样。3.2 在WorkBuddy中安装skill superpowersWorkBuddy比Codex CLI省心一些它有可视化的技能管理界面但安装前最好把新版Work configuration里的自动导入功能搞清楚否则很容易重复安装。整体流程如下第一步打开WorkBuddy的技能面板。在首页或设置里找到Skills或技能管理入口你会看到一个已安装技能的列表。第二步选择导入本地技能或从市场安装。如果你的superpowers技能包已经下载到了本地压缩包或文件夹选导入本地然后指定到技能包所在位置。WorkBuddy一般会自动识别技能包结构放到它管理的技能目录下。第三步如果WorkBuddy有内置技能市场可以直接搜索superpowers。搜索结果可能会有多个同名技能注意看维护者头像和更新时间尽量选更新频繁、说明文档完整的版本。这也提醒一点superpowers有很多人做过改版不必纠结哪个是正版以你所在团队的推荐版本为准即可。第四步在WorkBuddy配置中启用。有些版本会自动启用新导入的技能但保险起见还是在技能列表里确认superpowers的开关是打开状态。安装完成后同样用对话验证可以问你现在能用superpowers帮我规划一个项目吗这里有一个坑我必须提醒WorkBuddy的技能目录如果是自动生成的路径可能是~/.workbuddy/skills而不是~/.workbuddy/skills字母大小写导致的路径错位很常见。导入后如果技能列表里没出现先去这个目录看一眼实际文件夹名Kebab-casesuperpowers和PascalCaseSuperpowers的区别有时候就是能不能被识别的关键。3.3 在Trae Work CN中安装superpowers skillTrae Work CN的安装思路和Codex CLI类似但因为它是IDE和Agent结合的形态多了一层项目配置维度。我建议你优先采用项目级技能目录这样配置文件和技能包都能保存到当前工程仓库里团队成员共用同一套配置。第一步在项目根目录创建Trae使用的技能目录mkdir -p .trae/skills第二步把superpowers技能包的内容放进去。可以直接git clone也可以复制文件cd .trae/skills git clone https://github.com/你的技能仓库地址/superpowers.git第三步在Trae Work的配置中启用技能。Trae的配置方式通常是在项目根目录放一个trae.json或在工作区设置里调整需要将superpowers加入启用的技能列表。你可以在Trae Work的Agent设置界面里看到技能管理项如果界面里没有就手动编辑配置文件增加技能路径映射。第四步在Trae Work CN中打开Agent面板发起一个新会话明确输入使用superpowers技能帮我分析这个项目的结构并给出重构计划。如果技能生效你会看到Agent先吐出一份结构分析和任务清单而不是直接动手改代码。用Trae Work CN还有一个独特便利它能配合IDE的代码高亮、文件树、终端面板来展示superpowers的执行过程。比如Agent规划阶段会生成一份计划文档你可以直接点击打开看执行阶段它会自动打开相关文件、标记修改位置审查阶段它能调用Diff视图让你逐行确认改动。这种可视化体验是Codex CLI给不了的。3.4 验证安装是否成功别只看装上就完安装完成后我习惯做一轮系统性的验证避免其实没生效但自己不知道。验证分三层第一层Agent能说出技能名字。问你加载了哪些技能能准确回答superpowers才算第一步通过。第二层Agent能描述出技能的用法。接着问superpowers包含哪几个子技能分别在什么场景下使用如果回答具体、准确说明技能内容真的被Agent读进去了而不只是文件名被注册了。第三层用一个实际小任务跑一遍。挑一个你有明确预期的任务比如给这个模块加错误处理让Agent明确使用superpowers流程。观察它是否先做了规划、是否列出了风险点、执行完是否主动做审查。这三件事都做了才算真装透。这一层最容易被忽略。很多人的装了但感觉没变化其实就是栽在这——技能文件加载了但Agent在任务执行时并没有按技能指引行动等于挂了个空壳。4. 核心技能拆解与调用方式4.1 一个典型superpowers技能包通常包含什么不同版本的superpowers内容会有差异但优秀的技能包基本都覆盖以下几个技能模块任务规划planning负责把模糊需求转化为清晰任务清单。使用时Agent会先向你提问补齐需求中的歧义点然后输出一个按优先级排列的执行计划包含每项任务的完成定义。上下文探索context-exploration在动手改代码之前先检索项目中与任务相关的文件、接口和依赖关系。它会整理出一份影响面分析告诉你哪些模块会被波及、哪些测试可能会失败。代码实施implementation在规划通过后开始写代码。这个技能强调小步提交一次只改一个逻辑点每完成一部分就停下来给你确认避免像脱缰野马一样一口气改完十几个文件。测试与验证testing主动补充或更新测试用例。不只是跑一遍现有测试还会分析新改动可能破坏哪些边界情况生成对应的回归测试。代码审查review用第三视角审查本轮改动检查是否存在Bug风险、性能隐患、代码风格不一致等问题并给出修改建议。重构优化refactoring在功能正确的基础上分析结构中不合理的地方提出并实施低风险的重构操作。这六个技能模块放在人身上就是一个完整的软件交付流程放在AI身上就是一套超能力组合拳。4.2 从规划到重构的完整工作流实际运行时这些技能不是彼此独立的而是一条链条。我以自己最近重构一个订单模块的真实过程为例。接到任务后Agent先启动任务规划问我几个问题这个重构的边界是什么、能不能接受接口变动、兼容旧数据结构吗。我把约束说明白后它输出了一份分阶段计划。然后是上下文探索。它自己扫描了订单模块引用的几个核心数据表结构、调用方代码整理出一份影响面清单指出有3个外部服务在调用旧接口如果贸然改字段名会破坏联调。进入代码实施阶段后Agent没有一口气全改完。它先改数据层验证通过后再改业务层再改接口层。每个阶段都会暂停用git diff让我看改动内容确认没问题再继续。改动完成它自动触发测试与验证补了几个边界情况的测试用例空订单列表、金额为0、并发状态下重复提交。跑完测试后发现一个竞态条件又回头修了代码。最后代码审查阶段它对我之前手写的一段旧代码也提了改进建议我才发现一个多年的潜在问题。那一次重构给我的感受是AI不再只是我的工具更像一个流程严谨、愿意自查的结对程序员。4.3 在对话中如何准确唤起superpowers要让superpowers进入工作状态确实需要在对话里明确唤起否则Agent默认仍按基础模式执行。我常用的唤起方式有三种明确命令式在任务的结尾带上使用superpowers流程比如使用superpowers流程重构支付模块。这个方法最直观效果稳定。技能名称调用式直接说启用planning技能为日志系统迁移做规划。适合只想用其中某一个子技能不想走完整流程的场景。自然暗示式说这个改动影响面比较大帮我先做个影响分析再动手。这种情况Agent会自行判断是否需要调用superpowers里的对应技能。效果不太稳定取决于工具的意图识别能力。一开始我习惯用第一种用得多了发现其实把superpowers作为默认工作流配置在工具里更省事。它把每次会话的默认行为改成task approved后先输出计划文档再执行。保守起见我建议新手先手动唤起等熟悉了这套流程再放开默认。4.4 善用配置项让superpowers贴合自己的节奏superpowers并非只能按默认模式运行很多配置项值得调一调这里分享三个我实际调过的规划粒度默认情况下Agent可能拆得很碎一次任务列出十几个步骤看着累。我一般把粒度调粗一点以一个可独立验证的里程碑为一个步骤控制在3到7步之间既不啰嗦也有节奏。确认频率有些人喜欢Agent每改完一个文件就停下来等确认有些人希望它一口气干完再统一审查。如果你是后者把自动确认打开让Agent自己在内部循环中完成自查只在关键节点比如改动公共接口、修改数据库Schema才停下来等确认。上下文深度技能包在影响面分析阶段会检索大量文件非常耗上下文。小项目没问题但大仓库里经常把上下文撑爆。我通常把检索深度限制在两层以内只分析直接相关文件和一级调用方兼顾准确性和效率。5. 常见问题与排查技巧实录5.1 常见问题速查表我把安装使用中遇到的典型问题整理成一张速查表方便你对照排查。问题现象可能原因排查与解决办法技能包clone失败网络问题或仓库地址错误检查Git地址是否可访问改用手动下载压缩包后解压技能文件已存在但Agent说没加载目录结构不符合工具约定打开目录检查是否有SKILL.md或对应技能定义文件配置了enabled但还是不生效配置文件格式错误用工具自带配置命令重新生成手动编辑很容易写错路径技能能识别但任务不走流程没有在对话中明确唤起在任务描述中显式加上使用superpowers流程用了superpowers后响应变慢上下文中加载了过多技能文件调低上下文探索深度关闭不常用的子技能和另一个技能包冲突Agent行为混乱多个技能包指令相互覆盖暂时禁用其他技能包逐个测试定位冲突源Trae Work CN里找不到技能目录版本不同目录名不同在设置界面查看实际技能路径确认大小写无误修改配置后重启还是老样子配置文件被缓存完全退出工具进程而不是关闭窗口再重新启动5.2 安装后技能完全不生效最可能忽略的一件事我在多个朋友的项目里排查过安装后不生效的问题十次里有七次都是同一个原因技能目录的层级放错了。举个例子我们把superpowers clone到~/.codex/skills/superpowers后很多工具要求这个目录内直接就是技能定义文件。但有的仓库结构是这样的superpowers/skills/planning/SKILL.md多套了一层skills。Agent去加载时在superpowers目录下找不到顶层技能定义就默认它不是一个合法技能直接跳过。解决办法很简单看文档或者打开目录结构把仓库内的实际技能层级对齐到工具约定的格式。不要怕多复制几层文件夹技能文件多放在几层目录不太影响使用关键是让工具在入口处能找到技能定义文件。这个坑非常隐蔽很多人检查了路径、检查了配置愣是没发现是多了一层目录。5.3 Agent回复无法读取技能文件怎么破这种情况多数和权限有关。最常见的是技能目录是从对方机器上整个拷过来的文件权限变得很奇怪当前用户没有读取权限。# 修复技能目录及文件的读取权限 chmod -R ur ~/.codex/skills/superpowers如果是在公司电脑上用户目录可能被安全软件接管技能文件被标记为外部来源需要手动解除限制。在macOS上还会遇到来自未识别开发者的提示用xattr -dr com.apple.quarantine清除隔离属性即可。还有一种容易被忽略的情况文件夹名里有空格或特殊字符导致Agent解析路径失败。技能目录的命名尽量全小写字母加短横线是最稳妥的。5.4 技能装好了、也能识别但用起来表现和宣传不一样这个问题最难排查因为不是不生效而是效果打折。我遇到过的情况是Agent虽然加载了superpowers但在实际执行时仍然跳过了规划阶段上来就改代码。反复试了几次之后发现根因是模型本身的能力倾向小模型在长对话里容易遗忘已经读过的技能指令导致中间执行环节漏掉关键动作。解决办法有两个一是给Agent更明确的约束在每次对话的关键节点重复强调要走规划流程二是升级到能力更强、上下文理解更稳的模型版本。如果是企业内部用的私有化模型受限于模型能力superpowers的强化效果可能会明显打折这不是你操作问题是模型本身理解复杂指令的能力有限。还有一个我后来才意识到的问题我用了太多插件和superpowers的指令打架。比如另一个代码生成插件会抢在前面直接输出代码superpowers还没来得及规划整个流程就被带偏了。我的建议是安装superpowers后先临时禁用其他同类Agent增强类插件跑通一轮确认稳定再逐个加回来。6. 实操心得哪些场景收益最大哪些场景别硬上6.1 我连续用了一周后的真实体感说实话安装superpowers的第一天我非常不适应。它把原本我说一句AI写一段的节奏变成了我说需求、它问我问题、输出规划、逐个确认、插入测试、最后审查。以前十分钟能干完的小活用了它可能要半小时。我一度想卸载。但用了三天后我开始发现收益需要返工的次数显著减少。以前让AI改个模块它改完我总能挑出几处问题来回拉扯要好几轮。现在它自己会先过一遍审查很多低级错误在交付前就被拦截了。一周之后我算了一笔账单次任务的完成时间是变长了但整体时间包含沟通、返工、测bug反而少了。我的结论是superpowers本质上是拿前期规划时间换后期返工时间。对于一次性、小改动的任务这种交换不划算对于多文件、复杂逻辑、需要长期维护的工程任务这种交换稳赚不赔。6.2 适合与不适合的场景经过一段时间的对比我总结出相对可靠的使用边界。适合用superpowers的场景有大型重构、跨模块功能开发、接手不熟悉的旧项目、需要高质量测试覆盖的模块、多人协作时对代码风格有统一要求的仓库。不适合用superpowers的场景有单行修改、临时调试打印、紧急修一个线上Bug、写一次性脚本、探索性原型验证。这些场景走完整流程太重了我一般会手动关闭技能或新建一个不加载superpowers的会话。还有一种情况要特别提醒如果项目里既有非常旧的代码又有大量自动化测试要求比如覆盖率80%以上superpowers在规划阶段会花非常长时间去理解旧代码逻辑。这时候不能只依赖它自动分析你需要手动补充一些领域背景把项目历史约束告诉它否则产出的计划可能很正确但很外行。6.3 与团队成员协作时的一点建议如果你的团队成员都在用AI编程工具那配置一个团队统一的技能包目录非常有必要。建一个共享的Git仓库里面放superpowers技能包和一份统一的配置文件每个成员clone项目时通过项目级技能目录自动加载。这样能保证大家用同一套流程标准Agent产出的代码风格、提交逻辑、测试习惯都保持一致。不过这里有一个容易被忽视的问题团队里不同成员的模型版本可能不一样对同一套技能的服从度也不同。Skill明明是一样的有人用得很顺有人觉得AI根本不听。这通常不是技能包的问题是模型差异。这种情况我建议为团队统一模型版本或至少在文档里标注哪类版本的模型跑superpowers效果最佳。6.4 后续还能怎么扩展superpowers不是终点它这套技能化工作流的思路可以延伸到很多地方。我自己就在它的基础上做了两件事一是把团队内部的代码规范、命名约定写成一个自定义技能和superpowers一起挂载让AI在写码时自动遵守团队规范二是把常见的发布检查清单做成一个技能每次提PR之前让AI逐项核对。你可以把这个思路理解成一个积累过程第一次用superpowers是在消费别人总结好的经验等你熟悉了它的结构完全可以把自己的实践沉淀成技能逐步搭建起一套贴合自己团队和项目的AI工作流。这也是目前AI编码工具应用里最值得投入的方向之一。从我这段实操经历来看superpowers真正教会我的不是怎么装一个技能包而是怎么把一个稳定的好习惯变成AI可以复用的工作流。工具一直在变但这个思路值得长期坚持。如果你也正在折腾建议从今天开始给自己建立一个只使用superpowers流程的新会话先把第一次完整流程跑通后面的事情就顺理成章了。