Superpowers 这个项目名字起得相当直白——给 AI 编码代理“超能力”。如果你已经在用 Codex CLI、Claude Code 这类跑在终端里的 AI 编程工具大概率会遇到同一个瓶颈模型本身很聪明但真让它独立完成一个有点复杂的任务时往往不会“干活”——不拆需求、不写测试、改着改着就把上下文丢了最后给你一坨能跑但很难维护的代码。Superpowers 就是冲着这个问题来的。它不是又一个代码生成模板也不绑定特定厂商而是一套以 SKILL.md 文件为载体的技能包。装上之后AI 代理会按照一套被反复验证过的方法论来工作比如测试驱动开发TDD、任务拆解、代码审查、文档阅读、复盘重构等。这篇内容我会从安装方式、配置细节、实际工作流和踩坑记录四个维度展开给已经在用或准备用 Codex CLI、Trae 这类工具的人一份可以直接照着操作的手册。1. Superpowers 是什么解决 AI 编码代理“聪明但不会干活”的问题1.1 先说痛点模型很强但缺少工作方法我最早用 Codex CLI 的时候感觉就像招了一个名校毕业但没有任何工作经验的新人你问他某个 API 怎么用他答得飞快但你把一个完整的需求丢给他他会给你一个“看起来合理”的方案却从来不会先自己质疑需求、更不会主动写测试。更常见的情况是你让他改一个函数他直接把整个文件的逻辑重构了一遍然后告诉你“我觉得这样更好”。单看结果可能还行但你要 review 这样的改动成本非常高。这个问题的根源不在于模型能力而在于我们根本没有给模型一套“做事方法”。普通的 prompt 技巧比如“请先写测试再写实现”“请逐步思考”有一定效果但非常依赖你每次都记得写清楚而且一旦任务复杂模型很容易偏离最初的约束。Superpowers 的思路完全不同它把“做事方法”固化成项目的技能文件让代理在每次启动工作时先读取这些文件再按里面定义好的步骤去执行。1.2 Superpowers 的核心设计SKILL.md 驱动的技能包Superpowers 本质上是一个 GitHub 上的开源项目里面按“技能skill”维度组织了一堆 Markdown 文件。每个技能对应一个 SKILL.md文件里写清楚了这个技能解决什么问题、在什么场景启用、具体的执行步骤是什么、有哪些质量要求和禁忌。模型读这个文件本质上就是在“照章办事”。这个设计最聪明的地方在于透明和可改。Prompt 是人写的一段话写完了模型怎么理解你很难控制但 SKILL.md 是文本文件你可以打开看也可以按自己的团队规范去改。比如 Superpowers 默认的 TDD 技能要求先写测试再写实现但如果你维护的是一个测试覆盖本来就低的老项目完全可以改造一下流程让模型先做影响面分析再决定要不要补测试。这种灵活性是普通 prompt 模板给不了的。默认技能集里比较常用的几个TDD 工作流、任务拆解、代码审查、架构探索、深度研究、重构流程等。这些技能不是孤立存在的Superpowers 有一套“启动流程”代理先读主 SKILL.md搞清楚当前目标然后按需调用对应子技能一步一步推进。所以它更像一个“工作操作系统”而不是简单的命令集合。2. 从零安装Codex CLI 与 Trae 场景实测2.1 准备工作运行时与依赖安装 Superpowers 的前提是你已经装好了对应的 AI 编码代理。以 Codex CLI 为例它需要在本地有 Node.js 环境通过 npm 全局安装npm install -g openai/codex装完之后用codex命令确认版本正常codex --version同时需要确认git已安装因为克隆仓库和后续更新都要用到。如果你打算在 Trae 的 Agent 模式里使用技能包不需要额外的运行时但需要能找到 Trae 的自定义技能目录后面 2.4 会说。2.2 官方仓库的几种安装方式Superpowers 的官方仓库地址在 GitHub 上项目名就叫 superpowers维护者是 Jesse Vincent。安装方式大致分三种我实际用下来分别适合不同场景安装方式适用场景优点缺点一键安装脚本首次使用、图省事自动检测已安装的编码代理并把技能目录软链过去了解不到细节出问题不好排查手动 git clone 软链同时使用多个代理、需要自定义技能路径可控技能文件可以按需增删要自己维护软链复制进项目仓库团队协作、统一规范技能随仓库走提交即同步项目目录会变重更新麻烦我自己的做法是第一台机器用脚本安装快速跑通跑通之后再手动改成 clone 软链的形式方便我后续加自己的私有技能。脚本安装本质上是把仓库克隆到本地目录然后去~/.codex/skills、~/.claude/skills这类已知目录里建软链。2.3 Codex CLI 安装 Superpowers 的关键步骤如果你只打算给 Codex CLI 用最简单的方式是手动操作整个过程两三分钟# 1. 克隆仓库到本地目录名保持 superpowers git clone https://github.com/jesse-vent/superpowers.git ~/.superpowers # 2. 如果项目有依赖先装一下官方仓库会带一个简单的 Node 脚本做安装 cd ~/.superpowers npm install npm run build # 3. 把 skills 目录软链到 Codex CLI 的配置目录 mkdir -p ~/.codex ln -s ~/.superpowers/skills ~/.codex/skills # 4. 确认软链生效 ls -la ~/.codex/skillsCodex CLI 在工作时会自动读取~/.codex/skills下的技能文件前提是你所在的目录结构里配置了AGENTS.md或者在启动对话时明确要求它先读主 SKILL.md。更稳妥的做法是在项目的根目录放一个引用文件内容指向 Superpowers 的主 SKILL.md!-- AGENTS.md -- 请先阅读 ~/.superpowers/SKILL.md其中定义了完整的协作方式。每次开始任务前按里面的启动流程执行。这样一来Codex 进入项目目录时会优先读取 AGENTS.md然后顺着指引加载技能不需要每次手动敲一大段 prompt。2.4 Trae 工作区安装 Skill 的社区做法Trae 这边的情况稍微有点不一样。Trae 的 Agent 模式本身支持自定义技能社区里常见的做法是把 Superpowers 的 skill 目录复制到项目工作区的./trae/skills目录或者在 Trae 的设置里指定自定义技能路径。我在 Trae 里试过两种方式方式一在项目根目录创建trae/skills/文件夹把~/.superpowers/skills下的子技能目录整体复制进去。之后新建 Agent 会话时在提示词里写明“请先阅读项目内 trae/skills/SKILL.md”模型就会按流程走。方式二如果你用的是 Trae 的工作流Workflow功能可以把 Superpowers 的 TDD 技能拆成“生成测试用例 - 运行测试 - 实现代码 - 回归验证”四个节点每个节点对应一个 skill 文件。这样不需要靠 prompt 提示工作流本身就约束了执行顺序。需要注意Trae 对工作区技能的扫描策略可能随版本调整我遇到过“明明复制进去了但 Agent 不读”的情况大概率是 Trae 只扫描固定的AGENTS.md或skills目录这时候在系统提示词里显式加一句“请阅读 xxx/SKILL.md”最管用。3. 核心使用方式Superpowers 是把“项目管理方法论”塞进了代理3.1 理解 skill 的调用机制不是插件而是“工作要求”很多第一次用 Superpowers 的人会问这算不算一个插件装上之后要不要点按钮激活其实不是。Superpowers 的定位更像是“给代理看的入职培训手册”。它不劫持模型不改变模型本身的推理能力只是给模型提供了一套决策框架。在 Codex CLI 里你启动会话后如果项目下有 AGENTS.md 且里面引用了主 SKILL.md代理会自动加载技能定义。之后每一次任务它都会先根据主 SKILL.md 的指导判断当前属于什么类型的工作再选择调用哪个子技能。这个过程类似你给新人一份 SOP他遇到问题先查 SOP而不是凭感觉来。这里有个关键点skill 文件本身不是代码它对模型来说是“高优先级 prompt”。所以同一个模型在没装 Superpowers 和装了之后输出质量差异会非常大。我实测过同一个重构任务没装技能时模型直接给了整文件替换方案装了之后它会先列出影响面、写测试、再小步重构最后还要我确认测试结果。过程繁琐一些但每个 diff 都可 review安全性完全不同。3.2 最值得用的几个技能Superpowers 默认带的技能不少但说实话日常开发里我高频用到的就几个TDD 工作流核心是 red-green-refactor。模型先写一个会失败的测试再写最小实现让测试通过最后重构。这个技能对提升代码质量非常明显尤其适合新模块开发。任务拆解Breakdown把大需求拆成一个个可验证的小步骤。模型会给每个步骤标注依赖关系、完成标准和验证方式。这个技能帮我治好了“派活太模糊”的问题。代码审查Code Review让模型按照明确的维度去审查代码比如安全性、可测试性、边界条件、性能等。比直接说“帮我 review 一下代码”强很多因为它的审查标准是恒定的。深度研究Deep Research当遇到一个不熟悉的技术栈或框架时让模型先阅读项目源码和相关文档再给出结论。它在动手前会先建立“上下文地图”。这些技能是可以组合的。比如一个新功能可以先走任务拆解拆出若干个任务每个任务内部再走 TDD 流程全部完成后走一次代码审查。整个过程不需要你反复写大段 prompt只要你在一开始把目标说清楚代理会自己带着“流程意识”走完。3.3 实战示例一个最小功能从拆解到交付用一个小例子说明工作流长什么样。假设我让 Codex CLI 给一个 JavaScript 工具函数库增加“带缓存的 fetch 封装”codex启动后在提示里写请用 project scope 模式处理以下需求 为 utils 目录新增一个带缓存的 fetch 封装缓存失效时间可配置。 请按 Superpowers 标准流程执行。正常情况下代理会先读取主 SKILL.md然后输出任务拆解无需重新安装依赖。 根据标准流程我先把任务拆成 3 步 1. 写测试定义缓存命中、缓存过期、缓存清理的行为 2. 实现完成带 TTL 的 fetch 包装函数 3. 审查检查并发请求是否会导致重复请求 现在开始第 1 步先写会失败的测试。接下来它会创建utils/__tests__/cachedFetch.test.js里面是几个期望失败的测试用例跑一遍确认是红色然后写cachedFetch.js的实现让测试变绿最后可能还会主动提一句“可以考虑加一个防止缓存击穿的优化”。整个过程不需要你频繁打断你只需要在关键节点审查 diff。如果你用的是 Trae类似的效果可以在工作流里配置先让 Agent 写测试、跑测试、再实现。区别是 Trae 的界面会把每一步展示在面板里你可以在中间插话修正方向。4. 常见问题与避坑实录4.1 代理根本不读 skill 怎么办这是最多人遇到的问题。装完 Superpowers启动会话后代理表现和以前完全一样好像技能文件不存在。我排查这类问题的顺序是先确认软链有没有建对ls -la ~/.codex/skills看目标是否存在且指向正确目录。再确认项目里有没有 AGENTS.mdCodex CLI 默认只有在读取到 AGENTS.md 后才会把里面的内容写进上下文。没有这个文件代理根本不知道要去看主 SKILL.md。如果都确认了直接在对话里敲“请阅读 ~/.superpowers/SKILL.md 并执行其中的 process flow”观察代理是否复述技能内容。如果它连文件都读不到大概率是路径权限问题改用cat ~/.superpowers/SKILL.md | codex的方式强制喂给它。还有种隐蔽情况代理把它当成普通文档看了但没有按流程执行。这时候你需要在 AGENTS.md 里把引用写得更“强硬”一些比如明确写“所有任务必须严格遵循该文件中定义的 TDD 流程不得跳过测试步骤”。模型对命令式表述的遵从度明显更高。4.2 路径、软链和权限问题macOS 和 Linux 下用软链基本没问题但 Windows 环境要注意CMD 的ln -s需要管理员权限或者用 Git Bash 执行。如果在 WSL 里面装而 Codex CLI 装的是 Windows 原生版本路径对不上就会导致技能读了不生效。我的建议是Windows 上尽量直接复制目录不要用软链省去后面一堆麻烦。另外Superpowers 仓库更新比较快你如果通过软链引用git pull 更新后所有代理会立即生效但如果你复制到了多个项目目录就需要手动同步。我一般只在团队共享的模板仓库里用复制方式个人开发机一律用软链。4.3 与团队现有规范冲突怎么处理Superpowers 默认的工作流可能跟你团队现有的习惯冲突最典型的是 TDD。很多老项目连测试框架都没有硬让代理先写测试代理会卡住或者假装写测试。这种场景我不建议硬上。解决办法很简单改 SKILL.md。我会把默认 TDD 技能里的“必须先从测试开始”改成“先判断模块是否已有测试框架若有按 TDD 流程若没有先做影响面分析并建议是否值得引入测试”。模型读完这个改造后的文件行为就会贴合你的项目现状。这也正是 Skill 文件比固定 prompt 更友好的地方——你要的不是“统一标准”而是“可执行的流程”。4.4 几个容易踩的坑和我的使用心得我踩过最典型的坑是两个。第一把技能包当成万能钥匙任何任务都让对方跑完整套流程。结果一个“改个文案”的需求模型花半天拆步骤写测试浪费了大量 token。Superpowers 的 skill 应用应该有判断简单任务可以直接跳过流程。现在我会在启动对话时明确给一个“复杂度等级”比如“这是个 trivial change不用走完整流程”代理就会收敛很多。第二个坑是过度信任流程的产物。Superpowers 让代理写出来的测试不一定就是好测试。它可能写了个恒真断言或者测试根本没覆盖到核心逻辑。这个问题的本质是流程保证“做了”但不保证“做对了”。所以 review 不能省尤其是 agent 自认为“已通过”的测试要抽查断言质量。最后说一点个人体会Superpowers 适合的人群不是“不想写代码的人”而是“想把 AI 协作过程变得可控的人”。它不会让模型智商变高但能让它的交付方式更接近一个靠谱的同事。如果你正在用 Codex CLI 或 Trae又苦于每次都要在 prompt 里重复“先写测试、拆小步、给解释”这类要求那很值得花一个下午把 Superpowers 装起来体验一次“代理自己按流程走”的感觉。