最近我把手头的 AI 编码工作流彻底重装了一遍起因是同事甩给我一个词superpowers。他说这不是形容词而是一套能直接装进 Codex CLI、WorkBuddy、Trae Work 这些 AI 编程工具里的“技能包”。我花了一个周末研究、安装、实用了几天说句实话这套东西对日常编码效率的提升是实打实的。这篇文章就把 superpowers 的技术原理、安装步骤、常用技能和个人踩坑记录完整整理出来给正在折腾 AI Agent 工作流的朋友一个参考。如果你已经受够了“让它改个需求结果把我的代码拆散重写”这种场面也受够了 AI 助手每次都要从零开始理解你的项目规范那你会理解我为什么愿意折腾这套东西。继续往下看之前建议你先确认一个问题你手头至少有一个 AI 编程工具在正常使用并且你已经能接受让 Agent 直接读代码库、改文件。如果没有这个前提superpowers 装起来也白搭。1. superpowers 到底是什么以及为什么 AI 编程工具突然需要它1.1 从“能写代码”到“会干活”差的不是模型而是流程过去一年我用过不少 AI 编程助手最直观的感受是模型聪明了很多但干起活来还是像个“只会写代码片段的新实习生”。你问它一个问题它能给出看起来非常正确的答案你让它改一个模块它改完可能连编译都不检查。问题不是模型智商而是缺少工程流程。举个例子你让 AI 实现一个函数它直接给你甩出几十行代码。可要是你在一个真实项目里你会期望它先搞清楚这个函数的调用方、依赖、异常处理、测试覆盖最好还能自己跑一遍测试。这些流程如果每次都靠你在对话里一遍遍交代效率会很低而且稍微漏一点Agent 就会自由发挥。superpowers 解决的就是这件事把“工程方法”变成一套可插拔的“技能包”让 AI 在合适的时候自动调用对应的流程而不是每次靠临场发挥。1.2 我理解的 superpowers一套可插拔的 AI 技能框架我一开始看到“superpowers”这个名字以为是某个大模型插件后来才搞明白它更像一个技能框架核心是一系列结构化的技能定义文件。每个技能会告诉 AI这个技能在什么场景下使用应该遵循哪些步骤最终要输出什么格式。AI 编码工具比如 Codex CLI、WorkBuddy、Trae Work在运行时会把这些技能描述加载到上下文里触发到对应场景时按技能中定义的流程执行。这套框架里最重要的一个文件叫 SKILL.md。它通常长这样--- name: tdd description: 当需要实现新功能或修复 bug 时先编写并运行测试再实现代码。 --- # TDD 技能 1. 先根据需求写一个失败测试。 2. 运行测试确认它因为目标功能缺失而失败。 3. 编写最小实现让测试通过。 4. 运行完整测试套件确认没有回归。 5. 提交前再跑一次格式化与静态检查。当 Agent 拿到一个“实现登录接口”的任务时它看到 tdd 这个技能覆盖当前场景就会按这个流程走先写测试再写实现。比起直接生成代码看起来多花了点时间但最终产物的稳定性能高出一大截。为了更直观我整理了一个对比能力维度原生 AI 助手安装 superpowers 后任务理解依赖用户一条条补充约束技能自动触发按流程确认需求测试习惯基本不会主动写测试默认先写测试再写实现代码审查用户要求才做有专门的 review 技能自动执行出错恢复常常原地反复改调试技能先定位根因再动手知识沉淀每次会话从零开始团队规范可写成技能长期复用1.3 谁适合用什么场景收益最大说实话并不是所有用 AI 写代码的人都适合装 superpowers。我总结下来下面三类人受益最大第一类是重度使用 CLI 编程代理的人。比如你已经在终端里用 Codex CLI 做多轮任务让 Agent 自己改代码、跑命令、读报错。这种情况下一套完整的技能包能明显减少你“帮它擦屁股”的次数。第二类是希望 AI 稳定完成多步骤任务的团队。比如“实现新功能 写测试 跑回归 更新文档”这种链路原生 Agent 很容易漏掉其中一步靠技能包可以把它固化下来。第三类是团队里想统一 AI 编码规范的人。与其在每个人的系统提示词里复制粘贴不如做成技能文件放进同一个目录所有人都用同一套标准和流程。如果你只是偶尔用 AI 聊天窗生成一段代码没有让 Agent 直接操作项目文件的习惯那 superpowers 对你来说大概率是过度配置。先把这个基础设施搭起来再考虑它也不迟。2. 安装前必须搞懂的两个问题它靠什么跑装完影响什么2.1 核心组成技能定义、触发规则和全局上下文很多人第一次看到 superpowers 的目录结构会有点懵怎么全是 Markdown 文件其实这些 Markdown 就是它最核心的“程序”。每个技能目录下通常都有一个 SKILL.md里面包含 frontmatter 和正文。frontmatter 里的name和description字段特别重要因为工具扫描技能时主要靠 description 判断当前任务是否需要这个技能。你可以把 description 理解成技能的“简历”写得好不好直接决定了 Agent 能不能在正确时机把它认出来。除了单个技能文件superpowers 还常带一个全局上下文文件类似 AGENTS.md。AGENTS.md 是很多 AI 编程工具约定俗成的规则文件放在项目根目录后Agent 每次启动都会读取它。superpowers 会把一些通用工程原则写进去比如“在任何修改前先确认变更范围”“不要在测试失败时继续堆功能”等。这些规则和技能文件配合才能让 Agent 的行为更贴近老工程师。2.2 它和 Codex CLI / WorkBuddy / Trae Work 的协作方式这个可能是大家最困惑的地方同一个技能包怎么能同时适配三个不同的工具其实这些 AI 编程工具在技能加载机制上有一套相似的约定读取某个固定目录下的技能文件并把匹配到的内容拼进上下文。superpowers 的安装脚本做的事情非常简单就是把这些技能文件拷贝到工具约定好的目录里。以我本地的目录为例~/.codex/skills/ # Codex CLI 默认技能目录 ~/.workbuddy/skills/ # WorkBuddy 默认技能目录 ~/.trae/skills/ # Trae Work 默认技能目录装完之后你打开任意一个工具让它完成一个“给用户列表加缓存”的任务工具的调度逻辑会先读取技能列表发现里面有类似refactoring、tdd、performance的技能就会把对应的 SKILL.md 内容注入到当前会话的提示词里。Agent 拿到这些提示词再结合代码库上下文按技能定义的步骤干活。用一个生活化的类比技能文件不是驱动插上就能改变 AI 的“硬件”它更像一本 SOP 手册。工具负责把手册翻到正确的一页AI 负责照着手册执行。明白这一点之后你遇到问题就知道往哪个方向排查了。2.3 安装前注意版本、目录和依赖虽然 superpowers 是开源项目安装命令看起来也无脑复制粘贴但我在实操中还是踩过几个坑提前说清楚可以帮你少折腾。第一确认工具版本。不少技能文件用了较新的 Markdown 解析特性或者 frontmatter 格式旧版本工具可能识别不全。我见过有人的 Codex CLI 因为版本太老技能目录扫描不到装了等于没装。稳妥的做法是先把工具升级到最新稳定版。第二确认技能目录的真实路径。不同操作系统、不同安装方式目录可能不一样。比如 macOS 上默认是/Users/你的用户名/.codex/skillsLinux 则要留意是不是被安装脚本写到了/usr/local/share这种全局目录。装完以后最好手动ls看一眼别急着进入下一步。第三注意模型上下文长度。技能文件会在每次会话时占用一定上下文 token。如果项目本身很大再叠加一堆技能模型很容易“忘事”。建议先装少量高频技能跑通之后再慢慢加。这个我在后面专门讲。3. 实操把 superpowers 装进 Codex CLI、WorkBuddy 和 Trae Work CN3.1 Codex CLI 安装 superpowers官方脚本与手动两种方式我日常主力工具是 Codex CLI所以先讲它。第一种方式是官方脚本安装你只需要在终端里执行项目 README 里的安装命令通常是类似curl -fsSL https://example.com/superpowers/install.sh | bash这种形式。跑完之后脚本会往~/.codex/skills/下写入多个技能目录。安装脚本执行完我建议不要急着用先做三件事。第一确认技能目录已经生成ls ~/.codex/skills第二确认技能总数和目录名比如tdd、code-review、debugging之类的名字。第三跑一个最小验证任务。我常用的验证问题是“请列出你当前可用的技能并说明在什么场景下会使用它们。”如果模型能清楚地列出来说明技能加载成功。第二种方式是手动安装。这种方式适合网络受限、或者你想自己维护技能集合的场景。手动安装的核心就是下载技能目录里的 SKILL.md 等文件按相同结构放进 Codex 的 skills 目录然后重启 Codex CLI。手动安装没有魔法只要目录结构正确技能就能被识别。3.2 WorkBuddy 安装 skill superpowers图形界面与管理命令WorkBuddy 是我最近在评测的另一个 Agent 工具它和人交互的方式更偏向对话式支持通过命令或市场安装技能。官方支持的命令大概是workbuddy skills install superpowers如果你更习惯图形界面也可以在 WorkBuddy 的设置面板里找到类似“Skills”的入口搜索 superpowers 后一键安装。装完之后需要确认它是否有独立的技能目录。我这边实测WorkBuddy 给每个技能生成的目录里除了 SKILL.md还会有一个meta.json记录版本号和依赖关系。这个不用太关心只要记住一点如果你想临时停用某个技能直接把对应目录名改掉或移走即可不需要卸载整个 superpowers。需要提醒的是WorkBuddy 安装 skill 后有可能要新开会话才会生效。如果你发现当前会话里技能没有加载先别急着重新安装重启或者/new一个新会话再试。这是 Agent 上下文机制导致的正常现象不是安装失败。3.3 Trae Work CN 安装 superpowers skill在 AI IDE 中开启外挂技能Trae Work 作为集成度比较高的 AI IDE装技能的方式比命令行工具更“图形化”一点。我用的版本里侧边栏有一个“技能”面板点开后可以搜索 superpowers直接安装。如果你想手动安装思路和前面一样把技能文件放到 Trae Work 的工作区.trae/skills/目录下再重启应用。这里有个细节我一开始忽略了Trae Work 的技能目录既有用户级也有项目级。用户级技能对所有项目生效项目级技能只对当前项目生效。如果你只是想在某一个项目里实验直接把 superpowers 装进项目级的 skills 目录就够了别全局装免得影响其他项目。另外Trae Work 里技能的触发受当前打开项目的影响。如果你在项目 A 里安装了 superpowers切到项目 B 前最好确认项目 B 的 skills 目录下有对应文件否则技能不生效。这个问题很隐蔽我一开始排查了很久。3.4 安装后必做的四件事不管你是哪个工具装完 superpowers 后建议按这个清单走一遍能避免后面 80% 的诡异问题挨个工具检查技能目录是否存在且能读取。用“列出当前可用技能”验证加载。先跑一个最简单的任务比如“检查当前目录下最大的文件并解释原因”确认技能没有影响基础能力。把你团队的工程规范补充到项目的 AGENTS.md 里让 superpowers 的技能和团队规则互相配合。这套检查逻辑不仅适用于 superpowers你以后安装任何 skill 类插件都可以复用。4. 上手用起来几个让我“路转粉”的 superpowers 技能4.1 任务拆解技能从一句话需求到可执行的步骤清单我第一个想夸的是任务拆解。以前我让 AI 干活最怕它把一个复杂需求当成一个小改动来办。有一次让它“给项目加一个导出 CSV 的功能”它直接打开主文件往里面塞了一段导出逻辑没有考虑命令入口、文件命名、格式校验、错误提示这些事。装完 superpowers 之后它接到复杂需求会先输出一个任务清单把目标拆成几个阶段每个阶段标记了验收标准。你可以直接这样提问请使用 superpowers 的任务规划技能帮我完成“用户每次登录后在后台记录一条登录日志并提供一个查询接口”这个需求先给出步骤不要动手改代码。这时 Agent 通常会先梳理现状列出“数据表设计、日志写入时机、查询接口、测试用例、文档更新”等步骤并且告诉你它打算先做哪一步。你确认后它再开始动手。这个先规划再执行的习惯对中大型需求价值极大能让你在 AI“跑偏”之前及早拦住它。4.2 TDD 技能让 AI 先写红再写绿TDD测试驱动开发技能是我认为最容易被低估的一个。很多人觉得让 AI 先写测试太麻烦但实际上它会显著降低后面改代码的返工率。superpowers 中的 TDD 技能会强制 Agent 遵循“红-绿-重构”循环先写测试并运行看清楚失败原因再写最简实现让测试通过最后重构。我印象最深的一次是让 AI 实现一个带时区转换的日期解析函数。没有 TDD 技能时它直接写了一个看起来正确的实现有了 TDD 技能后它先写了几个边界测试用例包括夏令时、闰年、无效输入。测试果然先挂了一批然后它才一点点补实现。整个过程我只需要在关键节点审查它的测试用例是否合理。对使用者来说TDD 技能给你带来的不是“更快的代码”而是“更敢让 AI 自动改代码”的信心。4.3 调试与根因分析技能停止“瞎改代码”调试技能是我认为最能体现 superpowers 价值的地方。原生的 AI 遇到报错经常直接猜测原因、修改代码然后让你重新跑一次试试。如果没通过它换个地方再猜一次。你要是录了一段操作过程会发现它的大部分尝试都是在“打地鼠”。装了调试技能后Agent 的行为会变得很不一样。它先要求你提供报错日志和最小复现步骤然后静下心分析调用链定位可疑代码再做一个最小改动。我记得有一次遇到一个偶发的内存占用问题Agent 没有急着改代码而是先让我在关键位置打印了几条日志复现一次后它根据日志推断是某个全局缓存没有被清理而不是之前代码里看起来最可疑的死循环。这种“先取证、后动手”的思路是很多原生模型不具备的。4.4 自建自己的技能把团队的 code review 规范做成 SKILL.mdsuperpowers 另一个让我喜欢的地方是它不只是别人给什么你就用什么你完全可以自建技能。我后来就把团队的代码评审清单做成了一门技能。具体操作很简单在 skills 目录下新建一个子目录比如code-review-team里面放一个 SKILL.mdfrontmatter 写好名称和描述正文写清楚评审步骤和红线规则示例--- name: code-review-team description: 对代码变更进行团队规范的代码评审检查安全性、性能和可维护性。 --- # 团队代码评审 1. 先阅读 diff理解变更意图。 2. 检查是否包含硬编码密钥或敏感信息。 3. 检查是否缺少必要测试。 4. 检查是否影响既有接口兼容性。 5. 输出评审结论按 P0、P1、P2 分级列出问题。保存后重启工具再发起一次评审请求Agent 就会按这套团队规范来输出评审意见。这个能力的意义在于superpowers 最终不只是一堆别人写好的技能而是一个让团队工程经验可复用、可版本化的框架。5. 常见问题与排查技巧实录5.1 装了没反应先查这三处很多朋友装完之后发现 AI 表现和以前一模一样第一反应是“是不是没装成功”根据我的经验大概率是下面三处之一出了问题。首先是技能目录没有被正确扫描。你需要确认工具读的是你放技能的目录。比如 Codex CLI 可能同时存在全局配置和项目级配置superpowers 装到了全局目录但你的项目级配置文件里可能设置了一个空的其他目录导致技能没加载。其次是技能描述触发条件太苛刻。Agent 判断是否使用技能主要看技能 description 和当前任务的相关性。如果你安装了很多技能但任务的表述方式和 description 对不上就不会触发。解决办法是说得直白一些主动点名“请使用 xxx 技能”。最后是工具没重启。技能加载通常发生在会话初始化阶段旧会话里不会动态更新。装完技能后新开一个会话再测。5.2 提示“没有权限读取 skills 目录”这个问题多出现在手动安装或脚本安装到系统目录的场景。原因是技能文件的权限设置成了只有 root 可读或者你的用户对某个父目录没有读取权限。我用一句话排查ls -l ~/.codex/skills如果发现文件属主是root就执行sudo chown -R $USER ~/.codex/skills如果你把这些技能放在共享目录或通过符号链接引用的目录里还要额外检查链接目标是否存在。符号链接断掉之后工具会静默忽略整个目录看起来就是“没装”。5.3 安装脚本被安全策略拦截有些公司的开发机装了终端安全代理会对curl | bash这类执行方式产生告警或直接拦截。这里不鼓励你去关闭防护更推荐的做法是手动安装先下载脚本逐行读一遍再执行或者直接把技能文件手动拷贝到目录。手动拷贝本质上没有风险也不会触发安全告警。如果你确实需要使用安装脚本建议用curl -fsSL 地址 -o install.sh先保存到本地检查内容没有问题之后再bash install.sh这样也比直接管道执行要稳妥。5.4 模型上下文窗口被技能塞满技能文件也不是越多越好。如果 superpowers 自带了几十个技能而你全部装上每次会话都会把它们的描述塞进上下文token 开销不小项目代码一多就会提示上下文超限。我的做法是只保留高频技能低频技能用单独目录存起来需要时临时启用。另外一个技巧是在技能描述上做减法把 description 写得足够精准这样 Agent 只会在相关场景加载正文不会每个技能都完整读一遍。5.5 快速排查表现象可能原因解决办法装了之后没变化技能目录不对/工具未重启/描述未触发检查目录、新开会话、调整提问技能目录权限报错文件属主 root、符号链接断开chown 修复恢复链接安装脚本被拦截安全代理拦截管道执行先下载到本地检查后手动执行上下文超限技能装太多、description 太宽裁剪技能、精简描述多工具部分生效装错用户级/项目级目录确认工具各自的扫描路径输出格式和技能不符工具版本过低、frontmatter 解析不全升级工具到最新版6. 一些使用建议和我的个人体会6.1 先小范围试点不要一上来装全量技能我在第一次使用 superpowers 时犯过的最大错误就是一上来把所有技能都装上了结果不仅上下文压力大Agent 的很多行为也让我摸不着头脑。后来我把技能裁剪到五个左右包括任务拆解、TDD、调试、代码评审和重构整个体验立刻清爽了很多。建议你也这样先选一个你最痛的点比如“AI 不写测试”只装对应的技能用几周再逐步增加。6.2 把 superpowers 当成团队工程规范而不是个人玩具如果你是一个团队的 lead我特别推荐把 superpowers 跟团队规范结合起来。你可以先把团队的代码规范、评审标准、发布检查清单写进技能再让每个成员的 AI 工具统一加载。这样一来大家用 AI 写代码遵循的不再是每个人自己的“野路子”而是团队沉淀下来的流程。这个过程本身比装一个工具更加值钱。6.3 后续还能怎么玩自己写技能沉淀自己的“超能力”最后再分享一个我的扩展玩法。我把自己平时处理线上问题时的排查思路写成了一门叫oncall-playbook的技能里面包含了“先看监控、再看日志、最后看代码”的步骤以及一些常用命令模板。之后每次让 AI 帮忙处理线上告警它都会自动按照这个 playbook 走一遍少漏掉不少关键环节。superpowers 的意义不在于装完那一刻有多炫而在于它给你搭好了一个沉淀经验的框架。用久了你会发现真正强的东西其实是你自己总结出来的那套流程。我现在的体会是superpowers 不会让 AI 从笨变聪明但它能让 AI 从“聪明但不可靠”变成“聪明且按套路办事”。对任何一个想把 AI 编码助手真正用到生产环境的人来说这一步的重要性怎么强调都不过分。如果你也在折腾这些工具建议今天花十几分钟先装一遍跑一个简单任务试试也许你就能体会到我说的“路转粉”是怎么回事了。