1. 从会写代码到会做事Superpowers 到底给 AI 加了什么这两年我身边的开发者几乎都在用 AI 编程工具但大家普遍有一个感受AI 写代码很快快得让人上瘾可它犯起错来也快快得让人崩溃。你让它加一个功能它三秒钟给你甩出一大段代码看起来像模像样一跑就报错你让它修 bug它不先定位问题上来就我改成这样可以吗改完接着坏。说到底它不是在帮你解决问题它只是在用最快的速度生成一段看起来对的文本。我大概是在社群刷到superpowers这个词的紧接着就是各种安装教程、使用指南尤其是 Codex CLI、WorkBuddy、Trae 这几款工具相关的讨论几乎刷了屏。当时我以为是某个新出的 IDE 或者框架点进去才发现它根本不是什么大厂发布的新产品而是一个开源项目——obra/superpowers它做的事情非常朴素给 AI 编程助手配一套完整的工作方法论让 AI 从急急忙忙写代码变成先想清楚再动手。这套东西的形态既不是插件也不是 IDE 扩展而是一组Skills技能。你可以把它理解成给 AI 看的一本岗位手册里面写了各种高质量的工作流程怎么拆解需求、怎么写测试、怎么做调试、怎么做代码审查。AI 在干活的时候会按需翻到对应章节照着里面教的方法一步步执行。这个项目适合谁如果你正在用 Claude Code、Codex CLI、Trae、WorkBuddy 这一类支持 Skills 机制的 AI 编程工具并且觉得AI 聪明是聪明就是毛毛躁躁、不够靠谱那 Superpowers 就是冲着你来的。它不会让模型的能力突然提升几个档次但它能让模型的行为方式发生肉眼可见的改变——这一点装上之后的第一轮对话你就能感觉到。2. SKILL.md 的魔法一套 Markdown 协议如何重构 AI 的工作方式2.1 一个技能到底长什么样先别急着 clone 仓库搞清楚它的底层机制比什么都重要。Superpowers 依赖的是 Anthropic 提出并推动的Agent Skills 标准这个标准后来被很多工具接受。一个技能在文件系统里就是一个文件夹里面最重要的文件叫SKILL.md。这个SKILL.md的格式非常简单最上面是 YAML 格式的 frontmatter包含name和description下面就是大段的 Markdown 正文。正文里写的是这个技能的具体操作流程、行为规范、注意事项。举个例子一个TDD技能的SKILL.md可能是这样的--- name: tdd description: 遵循测试驱动开发流程编写代码。当用户要求新增功能、修复缺陷或重构代码时应该先编写失败的测试再实现功能使其通过。 --- # TDD 工作流 1. 充分理解需求列出验收标准 2. 根据验收标准编写一个最小化的失败测试 3. 运行测试确认为什么失败这一步很重要不能跳过 4. 写出让测试通过的最简实现 5. 运行全部测试确认没有破坏其他功能 6. 重构……技能文件夹里除了SKILL.md还可以放一些辅助文件——分类的说明文档、模板、代码片段甚至脚本。这些文件会在SKILL.md里被引用AI 需要的时候会主动去读而不是一股脑全塞进上下文。2.2 AI 是怎么选中一个技能的这是整个机制里最有意思的部分。工具在启动时会扫描技能目录读取每一个技能 frontmatter 里的name和description然后把这份技能清单交给模型。当用户提出需求时模型会根据当前任务的语义判断候选中哪个技能最匹配再决定要不要把对应的SKILL.md全文加载进来。也就是说description写得好不好直接决定技能会不会被触发。如果描述写得太笼统比如帮助写代码那模型遇到任何写代码的请求都可能触发它反而造成干扰写得太狭窄比如只用于修复 Python 网络库的 SSL 报错那稍微换个场景它就看不见这个技能了。Superpowers 这个项目之所以口碑好很大程度上就是因为在description的措辞上下了功夫触发率非常准。你可以把这种机制类比成按需查手册 AI 兜里揣着一本技能目录遇到问题先翻目录找到对口的章节再精读而不是一上来就把整本手册背下来。2.3 为什么它比复制一段超长提示词更聪明在 Skills 机制出现之前大家想让 AI 按照特定流程干活最粗暴的办法是在对话开头粘贴一大段 prompt。这个方案的缺陷很明显提示词越长上下文被占用的就越多模型早期的注意力还会被稀释而且它是一次性加载不管这次任务用不用得上都占着位置。Skills 是模块化、按需加载的。平时只有一行行的描述在系统里待命几 KB 而已当任务真正匹配某个技能时才把对应的完整指令读入。多个技能之间还可以组合、衔接比如先按 brainstorming 思路澄清需求再按 TDD 流程实现就像拼乐高一样。这套机制带来的直接好处是上下文更省、触发更准、流程更可控。3. 三端安装实录Codex CLI、WorkBuddy、Trae 分别怎么接3.1 先把 Superpowers 仓库拿到本地所有安装方式的第一步都一样把开源仓库克隆到本地。打开终端执行git clone https://github.com/obra/superpowers.git cd superpowers装之前建议先花一分钟看看目录结构对后面配置路径很有帮助。仓库里核心的东西是一个skills/目录里面每一个子文件夹就是一个独立技能比如tdd/、debugging/、brainstorming/每个文件夹下都有各自的SKILL.md。这里有个重要的概念区分系统级全局技能和项目级本地技能。系统级技能放在用户主目录下的配置文件夹里装一次所有项目都能用。项目级技能放在当前项目的隐藏目录里跟着仓库走团队成员 clone 下来就自带。个人日常使用推荐做全局安装图省事公司团队协作则更建议项目级安装方便统一工作流。后面三个工具的安装路径我都按全局 项目两种写法给出来。3.2 Codex CLI复制、软链、验证三步走Codex CLI 是 OpenAI 出的命令行编程助手装上之后终端里敲codex就能进入会话。它对 Skills 的支持比较早社区里讨论度也最高。安装 Superpowers 的方法如下。第一步创建全局技能目录如果不存在mkdir -p ~/.codex/skills第二步把仓库里的 skills 内容同步过去。这里我推荐用软链接而不是直接复制因为以后拉取更新很方便一条git pull就完事ln -s $(pwd)/skills ~/.codex/skills/superpowers如果你想按项目维度装就在项目根目录创建.codex/skills同样做软链mkdir -p .codex/skills ln -s /绝对路径/superpowers/skills .codex/skills/superpowers第三步验证是否识别。启动codex直接问它你有哪些可用的技能或者更直接一点提出一个带明确开发任务的问题比如帮我规划一个新功能但先不要写代码。如果 Superpowers 生效模型通常会先套用 brainstorming 或 TDD 那一套流程主动和你确认需求而不是上来就写代码。3.3 WorkBuddy目录不同思路一致WorkBuddy 这阵子在中文社区热度很高核心卖点同样是把 AI 编程助手装进终端并且兼容了 Skills 机制。它的全局技能目录一般是在~/.workbuddy/skills项目级则是.workbuddy/skills。# 全局安装 mkdir -p ~/.workbuddy/skills ln -s /绝对路径/superpowers/skills ~/.workbuddy/skills/superpowers # 项目级安装 mkdir -p .workbuddy/skills ln -s /绝对路径/superpowers/skills .workbuddy/skills/superpowers需要注意有些工具的 Skills 功能默认是关闭的需要到配置文件里手动开启或者在初始化向导里勾选。如果你装完之后发现模型完全无视技能里的流程先别怀疑技能文件本身去翻一下工具的配置项找找有没有类似skills_enabled、enable_skills的设置把它打开再试。3.4 TraeIDE 里的安装方式略有不同Trae 是字节跳动出的 AI IDE界面和 VS Code 一脉相承用起来很顺手。它同样支持 Skill路径惯例是项目目录下的.trae/skills或者用户目录下的~/.trae/skills。在 Trae 里安装可以走纯图形化操作把superpowers/skills目录里的内容复制到对应 skills 文件夹然后在 IDE 里重启 AI 会话。不过我实测下来命令行软链的方式在 Trae 里同样可用而且更好维护mkdir -p ~/.trae/skills ln -s /绝对路径/superpowers/skills ~/.trae/skills/superpowers有一个细节值得注意Trae 的国内版和国际版在功能迭代上经常有差异Skills 的目录位置可能在前者/后者之间略有不同。最稳妥的办法是在 IDE 设置里搜一下 skill会直接显示当前生效的技能根目录在哪里以那个路径为准。3.5 装完之后的第一轮测试不管用哪个工具装完我都建议跑一遍同样的试金石问题验证效果。不要问你会什么而要直接给一个带约束的开发任务比如我要给这个项目新增一个用户登录功能请你按合适的流程推进先不要急着写代码。如果 Superpowers 生效了你会看到 AI 开始反问你的用户数据存在哪登录用邮箱还是手机号需不需要验证码有没有现成的用户表这些追问就是 brainstorming 或 spec-writing 技能在起作用。如果它还是二话不说开始生成代码那说明技能没被加载回到上面的排查流程。4. 装了别急着用先跑通一个 TDD 闭环再说4.1 从需求澄清到测试落地的完整链路工具装上之后最容易犯的错就是立刻扔一个大型需求进去然后因为 AI 的表现不如预期直接得出这玩意没用的结论。我建议你第一次使用一定挑一个小而完整的任务完整跑通需求澄清 → 写规格 → 写测试 → 实现 → 重构这一条链路。我自己测试时用的是给一个 Python 脚本加 read time 统计功能的例子。我当时对 AI 说的第一句话很简单我想给博客文章加一个预计阅读时间功能按中文语速计算。接下来发生的事情让我印象很深——它没有直接给代码而是先确认了几个问题文章正文是纯文本还是 HTML标题和代码块要不要排除在统计范围之外中文字数按每分钟多少字计算这些正是我原本打算事后才告诉它的细节。确认完需求之后它进一步输出了一段简短的实现规格里面写清楚了输入输出、边界条件然后才开始写测试。注意顺序是先写了一个失败的单测再写实现。整个过程相当于把 TDD 的红-绿-重构循环完完整整走了一遍。这比我平时直接用 AI 写功能时它在测试上偷工减料的现象要改善太多。4.2 调试场景下的行为差异TDD 是 Superpowers 里最出名的技能但调试debugging技能的体验反差更大。普通的 AI 调试模式是你贴一段报错它看一眼就给出修改建议十次里有三次是猜的改完还有新问题。Superpowers 的 debugging 技能要求 AI 遵循一条严格的排查链路先完整复述问题和自己对现状的理解列出可能导致该现象的全部假设按可能性排序给出验证假设的最小实验方案而不是直接改代码在确认根因之后再提出修复方案修复后补上回归测试我第一次跑这个流程时AI 对着一个偶现的空指针问题先让我检查调用链中的某一处是否可能传入了None并解释了为什么它怀疑这里然后建议我加一个日志输出验证。这个验证步骤做完问题定位就板上钉钉了整个修复时长甚至比它以前直接改还短——因为不用来回试错的回合了。4.3 代码审查技能让 AI 当会挑刺的同事Superpowers 里还有个代码审查code-review技能它非常有用。普通 AI 做 review 的毛病是商业互吹只会说代码很清晰逻辑正确这类废话即使有问题也是轻描淡写。这个技能会让 AI 按一套明确的标准去检查有没有安全隐患、异常路径有没有处理、命名是否准确传达意图、有没有过度设计、测试覆盖是否真实有效。我拿自己之前一段写得很糙的爬虫代码试过一次AI 给出的意见包括异常捕获范围过宽会吞掉真实错误、User-Agent 没有设置导致容易被封、没有处理分页出现重复数据的去重策略。每一条都点在关键点上最后还补了一句建议增加针对单页与多页两种情况的测试。那个认真劲比不少团队的正式 code review 都强。不过要提醒一句review 技能对模型能力有一定要求能力太弱的小模型可能学不会这套流程效果会打折扣。4.4 组合使用才是完整形态Superpowers 最大的价值不在单个技能而在技能之间的组合。比如你接手一个遗留项目可以这样安排整个工作流先用 brainstorm 技能澄清优化目标再用 spec-review 技能确认改动范围接着用 system-thinking 技能分析模块间的依赖影响然后用 TDD 技能写测试保护现有行为最后用 code-review 技能自查改动质量。这一套组合下来AI 的行为已经不像一个自动补全器更像一个有章法的协作者了。5. 高频踩坑记录从没生效到胡乱触发的完整排查链路5.1 技能完全没有加载问题出在哪这是最常遇到的问题装好了问 AI 它会什么它一脸茫然。排查顺序我建议按下面这个链路走一步一步排除不要跳。第一确认技能目录位置正确。很多工具对目录名有严格要求比如必须叫skills而不是skill或plugins软链接的目标层级也必须对——我之前就把skills目录整个链了过去结果工具在skills/superpowers/skills/tdd里找不到技能因为路径深了一层。第一轮排查先进入目录执行ls -la人工确认SKILL.md文件存在于预期的层级。第二确认工具版本支持 Skills 功能。有些工具的旧版本压根没有技能加载器装了也白装升级到最新版、重启会话之后再测。第三确认安全策略没拦截。部分工具出于安全考虑对技能目录有白名单限制不在白名单里的路径会被忽略。如果是这种情况工具启动时通常会在日志里输出 Warning留意终端输出或者查看日志文件。5.2 技能加载了但行为完全没变如果你问 AI 有哪些可用技能它能完整列出但实际干活时依然我行我素那通常不是路径问题而是触发机制问题。重点检查description的语义匹配度。比如一个技能描述是当用户需要新增功能时使用理论上触发面很广但如果你的对话上下文里明说了这是一个 bug模型可能更倾向于把它归类到调试而不是新功能开发于是 skill 没被选中。此时最直接的验证方式是把description改得更有指向性或者直接换一种问法把任务里的关键词往技能的描述上靠。如果改了描述之后立刻生效说明就是触发层面的问题。另外也要注意有些工具会在多轮对话的中间阶段才动态加载技能早期回合模型可能还没意识到有技能可用多对话几轮再观察。5.3 装得太全反而乱了套Superpowers 仓库里各种技能加起来有二三十个一股脑全塞进去对模型的上下文窗口和调度能力都是考验。我实测过在上下文较短的工具里技能过多会导致模型在该用哪个技能这件事上犹豫不决甚至出现每个技能的流程都执行一半又跳去另一个技能的情况。建议的做法是按项目裁剪。比如写后端接口的项目保留 brainstorming、spec-writing、TDD、debug 就够用做数据处理脚本可能只要 system-thinking 和 debug。裁剪方法很简单在技能目录里只复制你需要的子文件夹或者建一个skills/目录用软链接只指到仓库里对应技能的路径而不是整个仓库一次性链过去。5.4 版本更新带来的意外Superpowers 迭代速度不慢仓库更新频繁但装在人家的工具目录里并不会自动更新。如果你发现某个技能的行为和文档描述不一致先git pull拉一下最新版。另外拉取更新之后一定要重启 AI 会话因为工具通常只在启动时扫描技能目录运行中不会热加载。还有一类坑是仓库升级后改了目录结构或者内部文件名导致旧的软链接指向失效。遇到这种情况删掉旧的链接按新目录结构重新建一次就好不用重新 clone。5.5 我的个人使用结论用了三四周之后我的整体感受是Superpowers 的价值不在于它让 AI 突然变聪明而在于它把优秀工程师做事的章法外化成了 AI 可以遵循的显式流程。对我个人来说它最大的收获反而是反向的——为了让 AI 更好地执行这些流程我越来越习惯在提需求时先把验收标准讲清楚把约束条件列明白。换句话说我自己的需求表达能力也被这套工作流带着提升了。所以我的建议是别把它当成一个一劳永逸的神器把它当成一份最佳实践教科书工具在变但 TDD、先澄清再动手、系统化排查这些底层方法放哪个时代都不过时。