给 Codex 装上“超能力”Superpowers Skill 的完整实战指南最近在折腾 AI 编程工作流的时候我在社区里刷到一个很有意思的项目叫superpowers。第一反应是这名字起得够狂第二反应是装完之后确实没让人失望——它不是一个传统意义上的插件也不是一个新的 CLI 工具而是一整套 Skill 技能包能让 Codex CLI 这类编程助手从“听话的实习生”变成“能独立拆解任务的老手”。简单说它解决的问题非常具体默认状态下的 AI 编程助手你让它改个需求它可能直接把整个文件重写了你让它跑个测试它能给你编出十种不跑的借口。而 superpowers 做的事情就是把 AI 的行为方式重新“调教”一遍让它有规划、有节奏、有检查机制地干活。这篇文章我不打算只讲安装命令而是把 superpowers 的底层逻辑、和其他 Skill 体系的关系、在不同环境Codex CLI、Workbuddy、Trae Work里的配置差异以及我实际踩过的坑都梳理清楚。适合正在用或准备用 AI 编程助手的开发者尤其是对 Codex CLI 感兴趣、想进一步提升 AI 输出质量的人。文章偏实操我会尽量把每一步都写明白。1. 到底什么是 superpowers——从“AI 的能力需要结构化管理”说起很多人在第一次听说 Skill 的时候会有一个误解以为 Skill 是给 AI 增加“云端能力”装上之后 AI 就能访问更多数据、调用更强大的模型。其实完全不是。Skill 的核心作用是给 AI 提供一套结构化的“工作方法和行为约束”它改变的不是模型本身的能力上限而是模型在当前任务里的输出质量下限。1.1 它不是“云能力”是一套可复用的技能包我打个比方。同样一个资深工程师你直接丢给他一个需求让他写代码和他拿着你们团队沉淀的《编码规范》《代码评审清单》《重构流程手册》再动手产出的东西是完全不一样的。superpowers 之于 Codex就相当于那套沉淀好的《工程师工作手册》。从 GitHub 仓库的结构上也能看出来superpowers 的 skill 分成几大类有脑暴brainstorming类让 AI 在动手写代码之前先和你把需求对清楚有规划planning类把一个大任务拆成可以逐步交付的小步骤有执行execution类比如编写代码、运行测试、修复错误还有复盘retrospective类让 AI 做完一件事之后自己总结经验为下一轮工作做准备。这套结构不是随便拍的它对应的是一个人真正在写代码时的工作状态先想清楚为什么做、再拆解怎么做、然后动手做、做完再回头看。在 AI Agent 的圈子里这套东西通常被称为“技能Skill”而 superpowers 是最早把整套软件开发流程做成 Skill 体系开源出来的项目之一。它的设计哲学是不要试图让 AI 一步到位地写出完美代码而是给它搭一条流水线让它在流水线的每个环节都用最正确的方式工作。这也是我后来在 Codex 里越用越顺手的核心原因——AI 不再是“一步到位瞎写”而是“分步推进稳做”。1.2 为什么我用了一圈最后还是保留了它说实话今年我试过的 Skill 框架不少各有各的思路有的偏向代码安全审计有的偏向测试生成有的偏向文档编写。superpowers 最大的区别在于它把“行为管理”做成了体系而不是孤立的几个技巧。我用一个很典型的例子来说明。以前直接用 Codex 写一个小工具我的指令是“帮我写一个批量重命名文件的 Python 脚本”。Codex 会很快给我生成一段能跑的代码但往往没有错误处理、没有日志、没有边界检查。而装上 superpowers 之后如果它的规划 skill 被激活Codex 会反过来问我几个问题你希望用正则匹配还是精确匹配覆盖式重命名还是先预览一遍需要保留原文件名映射表吗如果你确认了这些信息它才真正开始写。写完之后它还会主动提出要不要跑一遍测试或者做一次代码审查。这体验完全不一样。所以 superpowers 的定位很清晰它不是给你增加“魔法”而是给 AI 装上一套自我管理机制让它的每一步都可解释、可追溯、可验证。对开发团队来说这意味着 AI 生成的代码不再是“黑盒产物”而是可评审、可维护的工程产物。对一个独立开发者来说这意味着你可以把更多琐碎的编码任务放心地交给 AI 去干自己专注在架构和关键决策上。在我目前的日常开发流里superpowers 已经是 Codex CLI 环境的标配了而且我也把同一套 skill 配置同步到了 Workbuddy 和 Trae Work 里这样无论我在哪个编辑器环境下工作AI 助手的行为都是统一的。2. 核心机制拆解skill 文件、引导词与技能链如果你只是想把 superpowers 装上然后用起来可以直接跳到第 3 节。但我觉得还是有必要花点时间讲清楚它内部到底是怎么运作的因为这决定了你会不会用以及能不能自己扩展它。2.1 每一个 skill 都是“流程 清单 范例”superpowers 里的每一个技能在仓库里其实就是一个目录目录里面通常包含一个SKILL.md文件有的还有额外的参考文档或模板。这个文件的内容是 Markdown 格式核心结构是这样的技能描述description告诉 AI 这个技能在什么场景下使用它服务的任务类型是什么。执行流程workflow把做这件事的步骤拆开比如“先收集需求 - 再制定方案 - 再写代码 - 最后自测”。检查清单checklist在做完关键动作后逐项确认相当于给 AI 设定一个“飞行前的检查单”。范例examples给出一段理想的输入输出让 AI 理解“做得好”的标准到底是什么。我拆开来看一下。以它内置的“写代码”类技能为例不同分支可能命名略有差异SKILL.md 里会强调在真正开始写之前先确认已经理解了需求代码要符合当前项目的风格关键逻辑必须有注释实现完成后要主动提出测试方案。这些看起来是“天然的常识”但对大语言模型来说如果没有明确的文本指令它并不会每次都自动遵守。Skill 的作用就是用确定性的文本去对冲模型输出的不确定性。这和提示词工程Prompt Engineering是一脉相承的但 Skill 做得更工程化它把提示词拆散成可插拔的模块你不需要在每次对话里都重复写一大段规则只要让 AI 在合适的时机读取对应的 SKILL.md 文件就行了。从这个角度理解superpowers 本质上是“一套标准化的提示词管理方案”。2.2 superpowers 的技能链是如何串联的我刚接触的时候有个困惑superpowers 提供了这么多技能AI 怎么知道在哪个阶段调用哪一个后来我把整个 skill 体系理了一遍发现它其实有一条清晰的“技能链”对应一个完整软件的研发周期。拿一个典型任务举例。当你对 Codex 说“帮我优化一下登录模块的性能”如果 superpowers 的会话引导技能被激活Codex 不会马上动手改代码而会先进入“需求澄清”环节。确认完需求之后它会进入“任务分解”环节把性能优化拆成分析瓶颈、设计优化方案、实施修改、回归测试几个子任务。在编码阶段它调用“编码规范”相关技能来约束代码风格。写完代码后它会进入“质量检查”环节主动检查边界条件甚至尝试跑测试。这套串联机制靠的是 SKILL.md 文件里的“触发条件”。每个技能文件里都会写清楚当什么情况出现时你应该读取并使用这个技能。Codex 的 Agent 循环会判断当前的环境状态去匹配最适合的技能。所以你在使用的时候并不需要手动去切换技能而是通过任务描述本身让 AI 自动激活对应的流程。2.3 自己在什么时候“喂”它自定义技能superpowers 的价值不只是开箱即用更在于它是一个可扩展的框架。我们团队在后端项目里加了两个自定义技能一个是“数据库迁移规范”另一个是“API 错误码约定”。做法很简单仿照仓库里已有的技能结构建一个目录里面写一个 SKILL.md描述清楚触发场景和执行步骤然后在 Codex 的配置里把 skills 路径指向我们自己的目录就行了。这样做的意义在于团队的知识沉淀不再只存在于 Wiki 里而是变成了 AI 可以直接读取并执行的活文档。写代码时AI 会自觉遵守团队的数据库变更规范返回错误时AI 会按约定的错误码格式来组织响应。哪怕是一个刚入职的新人只要他使用这套开发环境写出来的代码也基本能符合团队规范。这就是 Skill 体系在生产环境里最有价值的应用场景。3. 实操在 Codex CLI 安装并激活 superpowers前面讲了那么多原理接下来直接上实操。我在安装过程中试过几种不同的方式也遇到过先装后失效的情况这里把最稳妥的路径完整走一遍。3.1 环境准备在安装前先把环境梳理清楚。superpowers 本质上是给 Codex 这类 CLI Agent 使用的 Skill 集合所以你本机得先有 Codex CLI 环境并且能正常调用模型。需要确认的环境可以看一下这个表格项目建议要求说明操作系统macOS / Linux 为主Windows 用户建议用 WSL后面我会专门说Codex CLI最新稳定版旧版本可能缺少技能加载能力Node.js / npm≥ 18Codex CLI 本身依赖 Node 环境不同安装方式依赖不同按官方要求来模型权限可正常对话和读文件技能文件需要在本地被读取磁盘空间500MB 以上仓库克隆 模型缓存足够用在开始之前最好先跑一次codex --version确认版本号没问题。如果你是第一次安装 Codex CLI直接用官方推荐的安装方式就好我这里不赘述但有一个小提醒装好之后一定要先把某个小 demo 跑通确认 AI 能正常回复再继续下一步装 superpowers。我见过太多人直接从安装 superpowers 开始装了半小时发现是 Codex 本身没配好全白忙活。3.2 Windows 用户建议换到 WSL 环境再动手superpowers 官方文档里的安装命令几乎都是 Unix shell 风格所以 Windows 用户如果直接在 PowerShell 或 CMD 里跑大概率会遇到路径问题。我自己实测下来最省事的方式是在 WSLWindows Subsystem for Linux里安装和运行 Codex CLI。WSL 的好处有几点文件路径遵循 Linux 规范和官方文档里的示例完全一致。脚本执行不会因为权限或路径分隔符问题卡壳。后续如果要扩展 skill 或用 Git 管理配置文件体验都更顺。如果你不想用 WSL那至少装一个 Git Bash然后用它来执行安装命令也可以救急。但从稳定性角度我还是推荐 WSL尤其你是重度 Codex 用户的话这个投入非常值得。注意这里说的 WSL 只是日常开发环境的建议不涉及任何特殊网络配置。VSCode 对 WSL 的支持已经很完善你在 Windows 里写代码、在 WSL 里跑 Agent完全无缝衔接。3.3 安装步骤全记录下面是在 macOS / Linux含 WSL环境下我从零到一安装 superpowers 的完整过程。第一步克隆仓库到本地的一个固定目录。我习惯把这类工具统一放在~/workspace/tools/下面避免散落到用户的根目录mkdir -p ~/workspace/tools cd ~/workspace/tools git clone https://github.com/obra/superpowers.git克隆完成之后检查一下目录结构ls -la ~/workspace/tools/superpowers正常情况下你会看到一个skills目录里面放着所有技能子目录。这是关键路径后面配置时要用到。第二步确认 Codex CLI 能识别到这个技能目录。不同版本的 Codex CLI 配置方式略有差异但核心路径配置逻辑是一致的——它会在你的用户配置目录下寻找包含 skill 的路径。以当前的主流版本为例Codex CLI 会读取~/.codex/config.toml这个配置文件可以由codex初始化命令自动生成。我们需要在配置里指认“额外的技能目录”[experimental] skill_paths [ /你的用户目录/workspace/tools/superpowers/skills ]注意把这里的具体路径替换成你自己的真实路径。如果skill_paths这个配置项在你看的文档里存在那直接用如果版本提示字段不正确可以走下面的软链接方案mkdir -p ~/.codex/skills ln -s ~/workspace/tools/superpowers/skills/* ~/.codex/skills/第三步重启 Codex CLI 会话。这一步很容易被忽略但非常重要。Codex 只在启动时加载一次技能配置如果你是在已经打开的会话里修改的配置不重启根本不会生效。第四步验证技能是否被加载。打开一个新的 Codex 会话先问一个简单的技能相关问题或者直接查看会话的日志输出。能确认的方法有两个一是看启动日志里有没有类似loading skills from ...的信息二是在对话里让 AI 自己描述一下“你有哪些可用技能”。如果 AI 能讲出 superpowers 里特有的技能名和行为规范说明加载成功了。提示不要在安装阶段直接丢一个大型开发任务去测效果会受网络和模型波动影响不好判断是配置问题还是任务本身的问题。先做小验证确认技能已加载再上真实任务。3.4 验证安装后的第一个测试让技能真正跑起来安装完成后我最常用的一行测试指令是请使用你掌握的最佳实践帮我设计并实现一个小工具功能是从一组 Markdown 文件中提取所有的一二级标题并生成目录索引。注意这句话重点在“最佳实践”。如果 superpowers 已生效Codex 会先跟你确认细节比如输出的目录格式、是否包含文件路径、是否跳过特定目录等然后给出一个实施计划最后才动笔写代码。它写的代码里会有错误处理会包含测试建议而不是被蹦出来一个光秃秃的函数。我第一次测试时它真的先问了四个问题才动手我一开始觉得“怎么这么啰嗦”后来才意识到这正是 superpowers 的价值——在动手前把需求和边界确认清楚比事后返工高效得多。4. 进阶配置Workbuddy 和 Trae Work 里的差异与坑Codex CLI 只是 superpowers 的一个运行环境。随着 Skill 体系流行起来很多 AI 编程工具都开始兼容这套规范比如 Workbuddy 和 Trae Work前面热词里也出现了。我也把 superpowers 同步到了这两个环境里整理一下配置差异和各自容易踩的坑。4.1 Workbuddy 安装 Skill 的正确姿势Workbuddy 对 Skill 的支持逻辑和 Codex 类似也是扫描指定目录里的 SKILL.md 文件注入到对话上下文中。但因为 Workbuddy 是 IDE 插件形态它的配置入口藏在插件设置里比命令行工具要隐蔽一些。我实际安装时用的是它的 CLI 辅助路径先确保 workbuddy 能识别到用户级目录下的 skills 文件夹然后把 superpowers 的 skills 目录软链接过去。如果你是 macOS 用户重点检查~/Library/Application Support/Workbuddy/下面有没有可识别的 skills 目录Windows 则去查%APPDATA%\Workbuddy\。不同版本路径名可能有差异最稳的办法是在设置面板里搜skill看它有没有暴露路径字段。这里有一个和 Codex 不一样的地方Workbuddy 的技能加载粒度更细它会要求每个技能目录下必须有一个完整的 SKILL.md如果缺少元信息这个技能会被静默忽略而且不报错。所以如果你在 Workbuddy 里发现某些能力没生效先别急着怀疑 superpowers很可能只是某个技能的元信息不兼容。4.2 Trae Work 里的一个坑技能路径别乱放Trae Work 是国内团队出品的 AI 编程环境配置上整体很友好默认会扫描工作区下的.trae/skills目录。如果你想全局使用 superpowers而不是只在某个项目里用就需要在用户目录的 settings 里设置trae.skills.extraPaths。我在这里踩过一个具体问题最初我想把 superpowers 的 skills 目录直接放到工作区某个项目的.trae/skills下发现只有那个项目能识别换一个项目就全失效了。后来改成在用户级配置里声明全局路径问题才彻底解决。建议的做法是在 Trae Work 的 settings.json 里加这样一段{ trae.skills.extraPaths: [ /你的绝对路径/superpowers/skills ] }配置好之后同样记得重启 Trae Work让它重新加载技能索引。如果你同时开着多个项目最好把 Trae Work 重启干净避免索引没刷新导致技能“时灵时不灵”。4.3 多环境共用一套 superpowers如果你和我一样在 Codex CLI、Workbuddy、Trae Work 三个环境里都要用就不用把仓库复制三份了。做法是本地只保留一份 superpowers 仓库其他几个环境通过配置或者软链接指向同一份文件。这样后续升级知识库时只需git pull一次全局生效维护成本最低。不过多环境共用一个技能目录也有一个细节要注意不同工具对技能文件里 frontmatterYAML 元信息的解析规则并不完全一致有些工具要求有描述字段有些则要求有触发词。如果你在 A 环境里能用、在 B 环境里失效大概率就是这个原因。我的经验是尽量保持元信息完整把 description、当触发场景、示例字段都写全这样兼容性最好。如果遇到个别工具还是识别不了就在该工具里建一个本地 override 目录只放需要额外适配的那几个技能。5. 扩展与自定义把 superpowers 变成你自己的武器库superpowers 是一个开源框架不是一套固化的流程所以你在掌握用法之后完全可以往里面填自己的东西。这一节我讲讲如何给 superpowers 添加自定义技能以及我在实际项目中是怎么扩展的。5.1 自定义技能的结构范例新增一个技能非常简单就是创建一个目录和一份 Markdown 文件。目录名就是技能名SKILL.md 是技能核心。我以一个“代码提交信息规范”技能为例展示一下 SKILL.md 里的关键要素--- name: commit-message-standard description: 当 AI 准备生成 git commit message 时使用确保提交信息符合团队的 Conventional Commits 规范。 --- ## 触发时机 - 用户要求提交代码 - AI 完成一段代码修改后准备总结变更 - 用户要求改写或优化现有提交信息 ## 执行流程 1. 查看当前项目的 git diff了解变更类型。 2. 根据 diff 确定是 feat、fix、docs、refactor、test 中的哪一类。 3. 写出格式为 type(scope): description 的提交信息。 4. 如果涉及破坏性变更追加 BREAKING CHANGE 段落。 ## 检查清单 - [ ] commit message 是英文还是中文按团队惯例执行。 - [ ] 是否包含关联的 issue 编号 - [ ] 描述是否简洁、避免无意义词汇 ## 示例 feat(auth): 增加基于短信验证码的登录方式 - 新增发送验证码接口 - 新增验证码校验逻辑 - 补充单元测试 Closes #1024以后只要 AI 准备生成 commit message它就会先读这一份规范按照团队约定来写。这个能力不是来自更强的模型而是来自一套“情景化的工作标准”也就是 Skill 的价值。5.2 我实际加的 3 个小技能在项目实践中我往里加了几个更垂直的技能这里挑三个有代表性的讲一下。第一个是“安全审查技能”。在我们做支付相关的模块时我建了一个 security-review 技能里面列出了常见漏洞清单比如 SQL 注入、越权、敏感信息硬编码、日志泄漏等。AI 在写完代码后会自动按这个清单做一轮自审能堵住不少低级的疏漏。第二个是“架构一致性检查”。我们有个项目历史悠久个别模块目录结构比较混乱。我把理想目录规范写进技能里要求 AI 在增加新文件时先检查目录是否符合规范不符合就提示重构建议。这听起来不起眼但在多人协作的项目里它能明显减少代码仓库“越摊越乱”的速度。第三个是“交接文档生成”。我们团队规定 AI 完成一个较大的任务后必须输出一份交接文档包括变更背景、改动文件、测试结果、潜在风险。这个技能很大程度改善了 AI 产出的可读性也让代码评审的效率提升了一个档次。5.3 版本管理与升级注意superpowers 本身迭代也很快所以升级时要注意几个点。第一升级前先看改动日志别盲目的git pull有时候新版本会调整技能目录结构或触发方式导致你之前自定义的技能失效。第二如果你在本地 fork 了仓库并加了大量自定义技能升级时优先用git fetchgit rebase减少合并冲突。第三升级后必须在新会话里测试旧会话不会自动加载变更后的技能定义。我自己吃过一次亏有一次直接git pull结果冲突把本地改过的 SKILL.md 覆盖了后来发现所有 AI 都不遵守自定义规范排查了半天才发现问题。所以现在我的习惯是fork 一份自己的仓库superpowers 的上游代码放在 remote upstream升级时先看 diff再去合并。6. 常见问题与排查经验实录这节集中回答我在安装和使用 superpowers 过程中遇到的典型问题。很多问题你搜官方文档都不一定有答案纯靠实际操作踩坑总结所以值得重点看一下。6.1 症状速查表症状可能原因解决办法安装后 AI 行为没有任何变化技能目录路径没配对或没重启会话检查配置里的绝对路径重启 Codex部分技能生效部分不生效对应 SKILL.md 的元信息不完整补全 description / 触发场景字段在 Workbuddy 里完全识别不了技能目录没有放在它要求的路径下查插件设置里的 skill 扫描路径Trae Work 里只有某项目能识别技能路径配在了项目级 settings 里改成用户级 settings 的 extraPaths升级后自定义技能全部失效仓库冲突覆盖了本地文件用 git 管理本地自定义内容升级前看 diff技能加载慢、响应变长技能文件过多每次都要读入精简技能数量只保留高频使用的6.2 两次真实的故障排查过程我第一次装完 superpowers 后在 Codex 里怎么测都感觉 AI 没什么变化它还是像以前那样不假思索地直接写代码。我当时差点怀疑这项目是个“PPT 项目”。后来排查了半天发现我配置skill_paths的路径时手滑多加了一个字符目录不存在Codex 静默忽略了它压根没报错。所以如果你装了没效果第一件事永远是确认路径有没有写对而不是去研究技能内容。第二次是在 Workbuddy 里技能列表里能看见内容但实际问题是被另一个同类型的本地技能“抢先”匹配了。在 Workbuddy 这种插件环境里它会把自己的技能和自定义技能合并成一个池子如果有多个技能描述相似AI 可能会选错优先级。解决办法是给不常用或优先级低的技能改名为zz-前缀开头相当于把它们的匹配顺序往后压。这个教训就是技能并不仅仅是加载就行还要管理好优先级和命名尤其是在同时使用多个技能包的时候。6.3 几个独家避坑心得最后聊几个我在实战中总结出来的心得这些是常规文档里不会写的内容。第一技能不是越多越好。我把十几个技能全部开着的阶段Codex 的响应速度明显变慢而且它经常在多个技能之间“反复横跳”。后来我精简到六个核心技能效果反而更稳定。技能的本质是“上下文约束”一次塞太多规则模型会不知所措。第二用一段时间后要注意垃圾技能堆积。有些技能你可能只是临时用一次之后再也用不上但它们仍然会在每次会话里被扫描、被载入。建议每隔一段时间就清理一次不常用的技能目录保持整个技能库干净。第三如果你发现 superpowers 在某些任务上让你觉得“太啰嗦”、总是先问一堆问题不用担心那是它的设计。你可以在指令里明确说“这次不要额外确认直接做”AI 就会跳过中间的澄清步骤直接进入执行。换句话说技能不是束缚更像是一套默认的安全策略你有权在任何时候手动退出。第四建议把技能配置纳入版本管理无论是个人项目还是团队项目。我自己的做法是把.codex/和技能目录都放进 Git 仓库这样每次环境出问题都能快速把配置恢复到稳定状态。对于团队协作来说这也能保证所有人都用同一套“AI 工作标准”。写在最后的体会做了一段时间的 AI 辅助编程之后我的一个核心体会是大模型本身的能力其实差别没那么大真正拉开体验差距的是你有没有给它搭一套优秀的工作框架。superpowers 最打动我的地方就是它把“怎样才能写好代码”这件事拆成了可执行的流程和清单让 AI 从“会说话的代码生成器”变成了“有章法的编码搭档”。如果你之前一直觉得 Codex 写代码虽然快但不够“稳”我强烈建议你去试试 superpowers。安装方式在 GitHub 上很清晰学习曲线也不陡峭花一个下午搞明白技能机制之后每天开发效率的提升都是看得见的。如果你在用的过程中发现了一些有意思的自定义玩法也可以顺着这套思路自己去扩展技能那才是真正让 superpowers 变成“你的超能力”的时刻。
