最近连续折腾了几天总算把一个叫 superpowers 的技能包接到了我的 Codex CLI 上跑通之后最直观的感受是AI 编码助手终于不是那个“一换对话就失忆”的工具了而是真的带着一套干活规范在跟我协作。这篇文章就把我这几天的思路、安装步骤、踩过的坑一起整理出来给同样在用 Codex、Trae 这类 AI 编程工具的朋友做个参考。如果你是那种已经对 AI 写代码上头、但总觉得它“时灵时不灵”的人这篇应该能帮你少走不少弯路。1. 先搞懂superpowers 到底给 AI 加了什么“超能力”先说清楚这个项目解决的是什么问题。日常用 AI 编程助手时最烦的一件事是什么是新开一个会话之后所有设定都得重新讲一遍。你得反复叮嘱“先读一下项目结构”“不要急着改代码”“先写测试”“按这个规范来”“最后再总结变更”这些事情每来一遍都是一堆 token而且 AI 还不一定完全遵守。superpowers 这类“技能包”项目思路就是把这些叮嘱沉淀成结构化的指令文件让 AI 在开始干活之前先自动加载一套“行为说明书”。1.1 我为什么会对这个项目感兴趣我平时工作流里Codex CLI 承担了相当一部分代码生成和重构的活。用得越多就越发现一个问题模型本身的能力已经很强但你如果不给足上下文不把工作流约束清楚它给出的结果质量波动非常大。我试过把一套复杂的指令直接写在系统提示词里也试过在每次对话开头复制一大段“使用说明”效果都不理想。要么太占上下文要么换个会话就忘了。后来看到社区里有人讨论 superpowers说它是一个专门用来给编码智能体加技能的仓库把 TDD、代码审查、规格驱动开发这些“专家工作流”都做成了可加载的 skill 文件。这个思路一下就戳中我了与其每次靠人肉提醒不如把流程交给文件。1.2 它的核心思路把“怎么干活”写进文件而不是存在对话里superpowers 解决的核心问题可以拆成三个层面来看第一上下文可控。技能文件不需要永远挂在对话里需要的时候激活不需要的时候不加载省 token。第二行为可预期。AI 每次执行同一类任务时遵循的是同一套规则不会因为换模型、换会话就飘。第三经验可沉淀。你踩过的坑、总结出来的最佳实践可以写进技能文件以后所有项目都能复用。我自己的体会是这类“技能包”本质上不是给模型打什么鸡血而是给团队发了一本战术手册。球员还是那个球员但有了手册之后跑位会合理很多。superpowers 这个名字取得挺贴切因为真正起作用的不是魔法而是有结构、有纪律的协作方式。2. superpowers 的关键机制与设计拆解要把这类工具用好还是得先理解它的内部机制。superpowers 的核心是一堆 skill 文件每个 skill 对应一种工作流。这里面的设计其实不复杂但很讲究。2.1 skill 到底长什么样一个标准的 skill通常不是一个单文件而是一个目录。目录里最重要的文件是SKILL.md这个文件有点像一个“使用手册”AI 会先读它来理解这个技能是干嘛的、什么时候该用、该怎么执行。下面是一个典型的 skill 目录结构skills/ code-review/ SKILL.md references/ checklist.md examples/ review-sample.md tdd/ SKILL.md templates/ test-first-template.mdSKILL.md一般会带一段 frontmatter里面声明技能的名称、描述、适用场景然后在正文里写详细的执行步骤和规则。对 AI 来说这段 frontmatter 就像一道索引可以让它在合适的时机主动想到调用这个技能。我自己在写自定义技能的时候最花心思的不是步骤本身而是怎么让描述足够精确。比如“检查代码质量”这种描述就很模糊AI 不知道你要查什么。但如果写成“逐函数检查是否有未处理的边界条件、是否有重复代码、是否有明显性能隐患按严重程度输出清单”AI 的产出质量会立刻上一个台阶。2.2 为什么模块化技能比长提示词更靠谱我一开始也有个疑问这些内容我直接复制到提示词里不也一样吗后来对比下来发现差别很大。提示词是一次性的你在一个会话里写了下一个会话还得重新写就算你存成模板时间久了也容易失修。技能文件不一样它是放在项目目录或者全局配置里的有版本、有更新记录、能被团队所有人共用。改一处所有人同步生效。这里面还有一个更微妙的好处长提示词容易“稀释”注意力。之前我试过把七八条规则一次性塞进提示词模型的表现反而不稳定经常顾此失彼。而技能文件走的是“按需加载”的路子AI 接任务后先判断该用哪个技能再集中精力读那份技能文档。注意力和 token 都花在刀刃上效果自然不一样。2.3 有哪些值得关注的“超能力”场景从我看到的内容和实际测试来看superpowers 这类仓库里比较常见的技能方向有这么几个技能方向典型场景我的实测感受代码库地图让 AI 先梳理项目结构再动手对刚接手的老项目特别友好测试驱动开发强制先写失败用例再补实现适合对测试要求高的项目规格驱动开发先写行为规格再写代码做需求拆解时思路清晰很多代码审查按清单逐项审代码比随口说“review 一下”规范多了重构助手约束 AI 小步重构、不改变语义重构风险肉眼可见地下降我不建议一上来就把所有技能全启用。项目给的技能是参考真正生产环境里你只需要先用好两三个跟当前项目最匹配的跑通之后再加。3. 实操从零把 superpowers 接入 Codex CLI理论聊完进入正题。下面是我按照自己的实操经验整理出来的接入流程。为了方便理解我会拿 Codex CLI 举例Trae 的接入方式放在后面单独讲。3.1 准备环境在开始之前确保本机满足几个条件已经安装并配置好 Codex CLI并且确认能正常调用模型接口。已经安装 Git用来克隆技能仓库。建议先掌握基础的命令行操作至少知道cd、ls这些命令的用法。我这边环境是 macOS zsh如果你用的是 Windows 的 PowerShell 或者 WSL命令会略有差异但思路是一样的。3.2 安装步骤第一步把超级技能仓库拉到本地的 Codex 技能目录。不同版本的 Codex CLI 技能目录位置可能不同常见的有~/.codex/skills/、~/.codex/skills/下的子目录以及项目内的.codex/skills/。先确认你自己的版本把技能目录放在哪然后执行mkdir -p ~/.codex/skills git clone superpowers仓库地址 ~/.codex/skills/superpowers第二步检查技能目录结构是否正确。规范的做法是让仓库里所有 skill 平铺在skills/下但有些仓库会多一层包裹目录这时候需要在 Codex 配置里指定include路径。以配置 TOML 文件为例路径一般在~/.codex/config.toml[skills] enabled true paths [~/.codex/skills/superpowers]第三步重启 Codex CLI让配置重新加载。这一步看上去简单但经常有人忘记。我一开始就是没重启导致怎么激活技能都没反应。3.3 在 Trae 等其他工作台里接入Trae 这类 IDE 类的 AI 工作台接入方式略有不同。你不太需要手动写 TOML 配置而是把技能目录软链到 Trae 认可的工作区目录里。以 Trae 为例常见的做法是把superpowers里的各个 skill 目录放到当前项目的.trae/skills/或者用户级配置目录下然后在 Trae 的设置界面里刷新或重新加载。这里的核心点只有一个目录结构和SKILL.md的格式要符合 Trae 的解析规范。所以优先用对方项目里自带的安装说明不要默认所有工具通用。顺带提一个我踩过的坑不要直接把整个 superpowers 仓库塞进项目目录然后指望 AI 自动找到技能。超能力技能仓库里往往有很多文档、模板、示例直接全量塞进去不仅加载慢还会让 AI 在判断用哪个技能时变得混乱。正确做法是只暴露你需要的技能目录或者用软链接按需引入。3.4 验证是否生效接入是否成功验证方法很简单。进入 Codex 交互界面输入一句跟技能相关的触发指令比如“请激活 code-review 技能然后审查一下当前改动”。如果配置成功AI 会先引用 SKILL.md 中的规则来给你反馈而不是直接泛泛地看两眼代码。另外一个更严谨的办法是看 CLI 的日志输出在调试模式下能看到它加载了哪些技能文件。我每次新增技能之后都会刷一遍日志确认加载路径没有写错再进入正式对话。4. 实操过程中的常见问题与排查实录这一节全是干货。下面这些问题都是我这几天实际遇到过的或者跟朋友讨论时收集到的真实案例。4.1 技能装了但 AI 完全不理会这是最让人抓狂的问题。我的排查顺序是这样的先看路径。技能目录是否真的在 Codex 会去扫描的路径下。再看配置。配置里的路径是绝对路径还是相对路径~符号是否被正确解析。然后用最简单的技能做测试。不要用复杂的组合技能用一个描述清晰、步骤简单的小技能如果连它都没反应说明基础接入就有问题。最后看冲突。项目目录里如果同时存在多个同名技能Codex 可能会优先加载其中一个导致你以为装了新的却不生效。4.2 技能加载后对话变慢、token 不够用技能文件也是要占上下文的。有些技能文档写得很长动辄几千字对所有任务都全量加载的话很快对话窗口就满了。我的解决办法是只启用当前项目真正需要的技能而不是全局启用整个 superpowers 技能库。把技能文档精简成“摘要版”把核心规则压缩到一页以内。在配置里按目录隔离不同项目加载不同技能集合。顺带说一句模型的上下文窗口越大不代表你可以肆无忌惮地堆材料。材料越多模型越容易忽略关键指令。技能文件要是能压到重点突出效果远好于事无巨细的长篇大论。4.3 团队协作时技能版本漂移如果你是一个人用技能文件怎么改都行。但团队协作时很常见的一个问题是A 同事的技能更新了B 同事用的还是旧版导致同一个诉求在两个环境下产生不同的输出。我个人建议的做法是把技能仓库统一管理团队内 fork 一份作为唯一可信源。项目根目录里用AGENTS.md或类 AI 指导文件来声明“本项目应该使用哪个版本的哪些技能”。关键的技能文件写清楚版本号AI 在加载时可以判断当前版本是否满足项目要求。4.4 模型兼容性差异这里要特别注意不同模型对技能指令的遵循程度差别很大。某些模型对SKILL.md这种长上下文指令的敏感度很高能严格按步骤执行有些模型则容易“跳读”会把技能文件当成参考而不是必须遵守的规则。所以如果你换了模型之前好用的技能可能突然就失效了。不要怪技能写得不好先测一下模型对指令的遵循度再决定是换回原模型还是针对新模型调整技能文案。5. 影响范围从个人效率到团队协作最后聊点宏观的。有人可能会觉得超能力技能这种项目不就是个“大号提示词合集”吗有这么大影响吗我自己试用下来答案是影响确实不小。5.1 对个人工作流的改变最明显的变化是我不再需要重复“教育”AI 了。以前接一个新项目我得花很长时间告诉 AI 这个项目的结构是什么、代码风格是什么、测试规范是什么等等。现在我把这些说明固化成了技能文件和项目指导文件AI 一进项目就能自动感知。省下来的时间和 token其实不只是几倍的问题而是把整个“人机协作”的起点往前拨了一大截。5.2 团队级收益同样可观团队场景下这类技能包最大的价值在于“统一的 AI 行为标准”。很多团队不敢让 AI 大规模写代码就是怕它写出来的东西风格不一、质量不可控。如果团队把代码规范、审查清单、测试要求都固化成了技能文件那么每个人用 AI 写出来的代码底子就是一致的。这比靠“自觉”靠谱多了。5.3 扩展思路自己动手写一个轻量 skill如果你也想试水建议从最基本的开始。找一个你日常重复率最高的 AI 指令把它写成一个 skill 文件。比如我给自己写过一个小技能叫“变更总结生成器”每次代码写完激活它就会按照固定格式输出本次变更的要点、风险点和测试建议。写这个技能只花了我十几分钟但每天都在用。模板结构类似这样--- name: change-summary description: 生成结构化的代码变更总结 --- 按照以下结构输出本次变更总结 1. 变更背景 2. 主要改动 3. 风险点 4. 测试建议不要小看这种小技能。日积月累你自己的“技能库”会越来越大AI 的使用效率也会跟着指数级上升。到那时候你就真的体会到什么叫“给 AI 配上超能力”了。最后再分享一个小技巧如果你和我一样是从 Codex CLI 这类命令行工具入手的我强烈建议你在配置里先只启用一个skills路径把超级技能仓库里用不到的子目录都挡住。用的时候再按需把目录加进来。别怕麻烦这一步能帮你省下后面大量的调试时间。等整个流程顺了再根据自己的需求深度定制那才是这个项目真正开始发挥威力的时候。