最近给我常用的 Codex CLI 折腾了一套叫 superpowers 的技能包装上之后最直观的感受是这个命令行助手终于不只是“会接话的代码补全”而是开始像一位有经验的工程师一样在下笔之前先跟你确认需求动代码之前先拆任务改完代码还会主动要求做一轮全面审查。之前很多要翻来覆去用 prompt 去“教”它的流程现在变成了默认动作。如果你也在用 codex cli 这类 AI 编程工具或者正在研究怎么让 AI 更好地融入真实项目这篇文章能帮你省下不少自己摸索的时间。我会把 superpowers 是什么、核心技能怎么拆解、完整安装配置流程以及我实际使用中踩过的坑一次性讲清楚。1. superpowers 到底是什么不是魔法是一套可复用的技能框架先给没接触过的朋友定个位。superpowers 是 GitHub 上一个开源项目本质是一套“Agent Skills”集合专门给 Codex CLI 这类支持技能机制的 AI 编程工具准备的。它里面封装了多种工程实践能力比如代码审查、清理烂代码、写测试、研究代码库、逐步调试、任务拆解等。把这些能力以“技能”的形式安装到本地之后AI 助手会在合适的时机自动调用展示出比默认行为更有章法的工程素养。1.1 从 Codex CLI 的 skills 机制说起Codex CLI 是 OpenAI 推出的命令行编程助手核心使用方式和很多 AI 编程工具一样你在终端里描述任务它读代码、改代码、执行命令、给出结果。但默认状态下它的行为比较“裸”——你问什么它答什么你让改什么它才改什么没有太多主动的工程化意识。后来这类工具普遍开始支持“技能skills”机制。所谓技能其实就是一个目录加一份 Markdown 文件目录里可以放参考资料和子文件Markdown 文件里用 frontmatter 写明技能的名称、描述正文部分详细规定 AI 在调用这个技能时应该遵循什么步骤、什么输出格式、什么注意事项。Codex CLI 会扫描本地的 skills 目录在任务上下文中注册这些技能。等到真实任务来了模型根据技能描述判断“这个任务该用哪个技能”然后按照技能文档里定义的流程去执行。说人话就是技能相当于给 AI 写好的“操作手册”和“岗位说明书”。没手册的时候AI 凭感觉做事有手册了它按流程做事。superpowers 的价值就在于它把资深工程师多年积累的工作方法整理成了一套统一、可落地的技能文档而不是零散的几条 prompt。1.2 superpowers 技能包解决了什么问题我自己用下来最大的痛点在于AI 编程助手很强但“不靠谱”。它可以三分钟写一个功能模块也可以三分钟把模块改成灾难现场。问题是它自己意识不到。你让它写测试它会写但写完你可能发现测试根本没覆盖核心分支你让它重构代码它会重构但重构完接口变了调用方全炸了。你当然可以在 prompt 里事无巨细地约束但每次都要重复交代累而且容易漏。superpowers 解决的正是“流程缺位”的问题。它把任务拆解成固定套路AI 一上来先读技能说明然后按步骤执行先分析现状再列计划再动手最后自检。这套流程更像一个靠谱同事的工作习惯而不是一个“有问必答的工具”。装上之后你会发现AI 在动手前会先跟你确认边界遇到不明确的点会主动提问写完代码会自己尝试审查一遍。这些行为不是模型变聪明了而是被技能文档“教”出来了。另外还有一个很实际的价值它把技能做成了模块化。你不用把几十条 prompt 塞在配置文件里有些技能用不上可以直接删有些场景觉得不够可以自己补。整个技能库是开放结构适合团队内部沉淀复用。这一点我后面会展开讲。2. 核心技能拆解这份“超能力清单”里都有什么打开 superpowers 的技能目录你会看到十几个子目录每个子目录都对应一个独立的技能。不同版本会有增删我挑几个我实际用过、并且觉得最有代表性的展开说。2.1 元技能让 AI 在动手前先想清楚superpowers 的根目录里有一个 SKILL.md这是一个比较特殊的“元技能”。它的作用不是说“你能写测试”而是规定 AI 在接到任务时先遍历一遍整个技能库理解有哪些能力可以调用再判断当前任务应该启用哪些技能。你可以把它理解成“总控调度”先看家底再定方案。这个设计很聪明。因为模型本身并不知道自己的“技能清单”到底是什么它只能感知到 prompt 上下文里被塞进去的描述信息。如果每个技能是零散的它可能漏掉最合适的那个。元技能的存在相当于强制 AI 在每次任务开始前做一次“技能匹配”提高正确技能被调用的概率。我实际用下来这个机制对“AI 主动使用技能”的影响非常明显。2.2 常用技能逐个看clean-code、code-review、testing 等我把比较核心的几个技能整理成了表格方便对照。技能名称核心作用典型使用场景clean-code清理代码坏味道命名不清、重复代码、过长函数等写新功能之前先看旧代码或重构一个文件comprehensive-code-review按架构、性能、可读性、边界条件等维度做全面代码审查写完一个功能模块后做自查或审查队友代码comprehensive-testing设计并补充单元测试、集成测试关注边界和异常分支新模块没有测试覆盖或修复 bug 后补回归测试researching-codebase系统性地搜索、阅读、理解项目代码结构接手旧项目或者让 AI 找出某个功能实现位置debugging按“复现问题 - 定位根因 - 修复 - 验证”的流程排查 bug日志报错但不确定根因在哪里explaining-projects用通俗语言解释项目整体结构和工作原理新人入职、外部协作者快速了解项目这里我说一下我对 clean-code 这个技能的理解。很多开发者觉得代码写得乱没关系反正机器能跑。但 AI 改代码时如果库里全是命名混乱、逻辑纠缠、一坨上千行的函数它的判断能力会大打折扣。clean-code 技能的作用不是做一次性的格式化而是让 AI 在动手改某段代码之前先把附近的结构问题识别出来避免“在烂地基上盖楼”。comprehensive-code-review 也很有用。默认情况下你让 AI “review 一下代码”它往往只给几条泛泛的评论比如“建议增加错误处理”“建议提取公共函数”之类。而有了 review 技能之后它会按固定维度列表逐项检查架构上有没有问题性能和并发有没有隐患边界条件和异常路径有没有覆盖命名和可读性是否达标测试是否足够安全上有无明显漏洞。这样产出的审查意见才真正是可以直接拿去改代码的东西。2.3 技能之间怎么配合还有一个值得说的点这些技能不是独立的招式而是一套组合拳。比如你接到一个“修复搜索接口超时”的任务。按照 superpowers 的套路AI 可能会先调用 researching-codebase 找到搜索接口的实现位置和调用链再调用 debugging 技能定位超时的核心原因修复之后触发 comprehensive-testing 要求补充一个回归测试最后还会用 comprehensive-code-review 做一遍整体检查。整个过程一气呵成中间状态是连贯的。这种配合带来的体验提升是巨大的。以前我要分多次对话才能让 AI 走完整条流程现在一次任务它自己就知道什么时候该切换技能。其实就是把“工程师的施工方法”前置成了 AI 的运行规则。3. 安装与配置实操给 codex cli 装上 superpowers下面进入实操环节。如果你的环境是 Codex CLI安装时间基本在十分钟以内。如果你用的是 Trae 这类支持技能体系的 AI IDE思路也差不多就是把技能目录放到 IDE 能扫描到的地方。3.1 环境准备安装之前确认三件事。第一Codex CLI 已经装好并且能正常使用。如果你还没装可以先通过 npm 或 Homebrew 安装完成登录和授权。这一步的前提是 Node.js 环境正常建议 Node.js 18 以上。第二本机有 Git并且能从 GitHub 拉取仓库。代码就放在 GitHub 上这是最基本的依赖。第三知道 Codex CLI 的技能目录位置。对 mac 和 Linux 用户来说默认是~/.codex/skillsWindows 用户的路径一般在用户目录下的.codex\skills。如果你改过配置可以在 Codex 的配置文件里搜 “skill” 关键词确认目录位置。我在项目里看到的最常见装机错误就是把技能仓库 clone 到了错误路径导致 Codex 扫不到。所以别急着执行命令先确认目录。3.2 方式一用安装脚本一键完成superpowers 官方推荐的方式是用安装脚本我印象里大致是这个命令curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash这个脚本会帮你把仓库克隆到 Codex CLI 的技能目录同时做一些基础环境检查。如果你是第一次安装建议先看一眼脚本内容再执行看看它到底要往你机器里写什么curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | less脚本本身通常不复杂就是创建目录、git clone、失败时给提示。如果网络不通或者 raw.githubusercontent.com 访问失败脚本会中断这时候可以退回手动安装。3.3 方式二手动克隆到技能目录我更推荐新手用手动克隆因为路径掌握在自己手里出了问题也好排查。假设技能目录是~/.codex/skills就先创建目录再克隆mkdir -p ~/.codex/skills git clone https://github.com/obra/superpowers.git ~/.codex/skills这里有一种情况值得说明有些版本会建议把仓库克隆到~/.codex/skills/superpowers这种带一层子目录的位置而不是直接作为 skills 目录本身。经验告诉我Codex 扫描技能时会把 skills 目录下的每个子目录当做一个独立技能来识别每个子目录里必须有一个SKILL.md。所以装完之后建议检查一下目录结构是不是长这样~/.codex/skills/ ├── SKILL.md ├── skills/ │ ├── clean-code/ │ │ ├── SKILL.md │ │ └── ... │ ├── comprehensive-code-review/ │ │ ├── SKILL.md │ │ └── ... │ └── ...注意你看到~/.codex/skills/SKILL.md是元技能入口skills/子目录里才是各个具体技能。如果 clone 之后发现多了一层嵌套比如~/.codex/skills/superpowers/skills/...Codex 可能只会把最外层当做一个技能导致内部技能全部失效。解决办法也很简单把仓库里的内容整体移到~/.codex/skills根目录下或者把 clone 路径改成目标位置的上一级再移动目录。3.4 在 Trae 等 AI IDE 里接入技能热词里有人提到“trae work cn 安装 superpowers skill”这里单独说一下。Trae 是字节跳动推出的 AI IDE国内版叫 Trae CN。它和 Codex CLI 不是同一个产品但同样在往 Agent Skills 的方向兼容。如果你用的是 Trae想装 superpowers核心思路是找到 Trae 的技能目录再把 superpowers 的内容放进去。不同版本的 Trae 设置入口会有差异。我试过的办法是在 Trae 的设置面板里搜索 “skill” 或 “技能”看看它把用户级技能目录放在哪里。有些版本会默认读取用户目录下的某个工作区目录比如~/.trae/skills有些版本则需要你在项目配置文件里显式指定。这个路径很容易因为版本更新而变化别硬记最好的方式是先在 IDE 里查设置。找到目标目录后其他操作和 Codex CLI 一样git clone https://github.com/obra/superpowers.git 你的Trae技能目录装完重启 IDE让技能索引重新加载。如果在配置面板里能看到已加载的技能列表就说明成功了。3.5 验证安装是否成功安装完成不表示万事大吉我建议做一次快速验证。直接在 Codex CLI 里提问你有哪些可用的技能请尽量把技能名称和高频用途列出来。如果它能把 clean-code、comprehensive-code-review、comprehensive-testing 这些技能名说出来说明技能注册成功了。如果它说“我没有技能”多半是目录路径没对上或者 SKILL.md 的结构有问题。另一种验证方式是看调试日志。Codex CLI 在 verbose 模式下会输出它加载了哪些上下文文件如果日志里能看到技能文档被加载那基本就稳了。不同版本命令参数不同可以在帮助信息里查 verbose 或 debug 参数。提示验证技能是否被“加载”是一回事验证技能是否被“调用”是另一回事。前者只代表 AI 知道技能存在后者需要实际任务触发。我通常用一个简单测试任务比如让它写一个带边界检查的函数看它是否主动触发 comprehensive-testing 流程。4. 实战使用经验与配置调优装好只是第一步真正让 superpowers 发挥价值关键在于你怎么用、怎么配合团队。我总结了一些实战经验也算不上标准答案但至少能帮你少走弯路。4.1 推荐的工作流需求进来先定套路我现在的使用习惯是拿到一个新需求不会直接甩给 AI 让它“实现一下”。我会先简单说一下业务背景和目标让它用 planning 或者 scoping 类技能拆解任务。拆解完之后我再跟它对齐计划确认没问题才让它进入编码阶段。编码结束之后我会主动触发 comprehensive-code-review必要的时候让它补 comprehensive-testing。这个过程看起来多花了轮次实际上总耗时反而更短。因为 AI 不再“闷头写一个和你预期不一致的东西”而是先把边界问题暴露出来。有一次我让 AI 做一个数据导入功能它先问我“导入文件的格式是固定的吗重复数据要不要去重失败时是整批回滚还是逐条跳过”这三个问题问完我就知道后面的实现方向基本不会跑偏。这类提问不是免费的它可能多消耗一些 token但比起“写错重来”的成本这点消耗非常划算。我的经验是注重结果的工程任务宁可前期多聊两句也不要后期返工。4.2 自定义技能把团队规范也做成 skillsuperpowers 本身是个不错的模板但它毕竟是一个通用项目。你团队的代码规范、提交格式、接口设计约定它不可能都覆盖。好在技能机制天生支持自定义。你完全可以照抄它的技能目录结构写一个属于自己团队的 skill。我做过的一个例子是把“后端接口开发规范”做成了技能。里面包含了接口路径命名规则、请求参数校验要求、错误码设计约定、返回结构模板、必须补充的测试用例类型。然后在 SKILL.md 的描述里写清楚“在处理控制器、服务层、接口相关任务时优先使用”。这样团队里不管谁用 AI 写接口写出来的风格都高度统一。自定义技能的注意事项主要有三个。第一目录结构要对。每个技能目录下必须有 SKILL.md这是硬性要求。第二frontmatter 的 description 要写清楚使用场景。模型决定要不要用某个技能很大程度上就是看这段描述。写得太泛它就不容易被触发写得太窄又可能错过使用机会。第三参考资料可以放在技能目录的子文件里正文里用相对路径引用。这样避免把大段文档直接塞进技能主文件毕竟每多一段引用文本都会增加一次任务上下文消耗。4.3 当技能不够用时的兜底方案superpowers 不是万能的。我在实际使用中就遇到过几次“它选错了技能”的情况。最典型的一次是我让它研究一个模块的实现它却触发了 comprehensive-code-review 流程直接开始挑代码毛病而不是回答我的“这个模块怎么工作”的问题。原因可能是技能描述里有“深入了解项目代码”之类的字眼模型把它和“审查代码”混在了一起。碰到这种情况最简单的兜底方案是显式指定技能。在 prompt 里直接写“不要使用 code review 技能尽量定位模块的调用链并解释实现流程”。这相当于手动切断了模型的自动技能匹配逻辑。要记住技能只是工具优先级永远低于用户的显式指令。另外技能之间偶尔也会“打架”。比如 clean-code 技能要求它重构代码而 comprehensive-testing 技能要求它先补充测试覆盖。如果 AI 在一次任务里同时触发了这两个技能可能会出现“先重构后补测试导致测试覆盖的是旧逻辑”的尴尬。这类问题没有完美的自动解法只能靠人盯流程。我的建议是并不是所有任务都需要所有技能该关闭的关闭该临时禁用的就禁用。5. 踩坑记录与常见问题排查这部分是纯经验分享了。我把装 superpowers 之后遇到的高频问题整理成速查表不一定每条都发生在你身上但可以在出问题时先对照看一下。问题现象可能原因解决办法AI 根本不知道 superpowers 技能存在技能目录路径不对或 clone 层级错误检查~/.codex/skills和 SKILL.md 位置安装脚本执行失败网络无法访问 raw.githubusercontent.com改成手动 git clone技能偶尔没有生效技能描述不精确模型没有触发自动匹配在 prompt 中显式指定使用某个技能token 消耗明显上涨技能文档被完整塞进上下文特别是 reference 文件很多精简技能主文件参考资料按需读取自定义技能始终不触发description 写得像功能描述不像“什么时候该用”重写描述强调适用场景和触发条件5.1 技能没有被自动加载这是安装类问题的第一名。大多数时候不是 superpowers 坏了而是目录层级不对。Codex 对技能目录的扫描方式比较“死板”它只认 skills 目录下的直接子目录然后要求子目录里存在 SKILL.md。如果你 clone 的时候没有拆掉多余的层级比如变成了skills/superpowers/skills/clean-code/SKILL.md那它很有可能只识别到superpowers这个技能或者干脆一个都识别不到。遇到这种情况最快的排查方式是在终端手动查看目录树。用tree命令或者find命令确认每个技能的 SKILL.md 都在“skills 目录的下一级”里。如果层级不对直接把 superpowers 仓库里的内容移动到技能目录的根下即可。5.2 安装脚本执行失败虽然一键脚本很方便但它的前提是你本机能正常访问 GitHub 和 raw.githubusercontent.com。如果环境访问不通脚本就会卡住。这时候别硬试改用 git clone 方式安装。如果 git clone 也慢可以通过设置 git 代理或使用镜像仓库解决但这部分属于网络问题不是 superpowers 本身的问题我就不展开了。还有一类少见的情况是环境变量问题。比如 HOME 路径没有正确设置导致脚本把技能目录写到奇怪的地方。这种情况建议先执行echo $HOME确认家目录路径再确认 Codex 的配置文件指向的技能目录确实在你预期的位置上。5.3 Token 消耗变大了装上 superpowers 之后token 消耗确实会比原来高。原因是技能文档本身就是一段上下文每个技能都会把 SKILL.md 的内容带进来元技能可能还会引用整份技能清单。如果你的任务同时触发多个技能上下文消耗会明显增加。这不算 bug但可以优化。最简单粗暴的办法是删掉你不常用的技能目录只保留核心的几种。我的做法是保留 clean-code、comprehensive-code-review、comprehensive-testing、debugging 这几个其他的按需补回去。另一个技巧是给技能文档“瘦身”把大段参考代码移到 reference 目录中在 SKILL.md 里只用一两句话说清楚“详细示例见 reference/xxx.md”让模型在需要时才去读取而不是把内容全部预加载。5.4 与团队协作时的注意事项如果你们团队多人共享同一个技能包我建议把技能目录纳入代码仓库管理。这样每个人 clone 项目后能通过一个同步脚本快速安装统一版本的技能避免因为各自改了技能文件导致行为不一致。你可以建一个scripts/install-skills.sh里面写好 clone 和目录同步逻辑大家一起用。技能描述也要有人维护业务逻辑变了技能里的规范文档也得跟着更新。最后提醒一句superpowers 再怎么强大也只是给 AI 立规矩的工具。真正关心项目质量的人还是得盯最后一关。AI 写的代码我会当成“实习生写的代码”来看先让它按流程走但最终的架构决策、安全设计、关键逻辑我会自己再过一遍。把技能当帮手别把它当信仰这才是它发挥价值的正确姿势。
