Superpowers：用MCP协议为Codex CLI加AI技能-北京尧图网络

先给你交个底Superpowers 不是一个给你加超能力的彩票它是一个给 AI 编码助手“加技能”的框架。说白了它是套在 Codex CLI 外面的一层技能系统通过 MCP 协议让 AI 不只是“会写代码”而是“懂你的工作流”。如果你已经受够了裸 Codex 每次都要重复交代项目背景、测试习惯、提交规范那这篇就是给你写的。我最早接触 Superpowers 是因为一直在用 Codex CLI 跑一些重构和跨仓库的活裸用的问题很明显单次对话很强但每次都要把同样的上下文反复喂给它而且遇到不熟悉的命令、不常见的框架组合它会一本正经地瞎编。Superpowers 解决的就是这个问题——把“经验”沉淀成一个个技能skill让 Codex 按需调用像给实习生配了一本可检索的操作手册。适合谁适合每天跟 CLI、AI 结对编程的开发者也适合想在团队里统一 AI 编码规范的人。1. 先搞懂 Superpowers 到底在解决什么问题1.1 裸 Codex 的痛点有智商没经验很多人第一次用 Codex CLI 的感觉是哇好强。但用上两周就会遇到几个绕不开的坎。第一个是上下文窗口被浪费每次开新会话都要重新解释项目结构、构建命令、测试方式、代码风格一轮对话还没干正事几千 token 就没了。第二个是“知识盲区”表现得非常自信你让它跑一个你们团队内部封装的部署脚本它会猜一个不存在的命令然后信誓旦旦地告诉你跑完了。第三个也是最要命的AI 不会从错误中学习。你今天纠正它“测试要用 JUnit 5 而不是 JUnit 4”明天新开一个会话它照样用 JUnit 4 给你生成测试。这些经验明明已经在你脑子里、在团队文档里、在历史 commit 里但 AI 看不到于是每个会话都是“失忆重生”。Superpowers 的出发点就是把这些“经验”显性化。它不改变 Codex 的底层能力而是在 Codex 和你之间加了一层“技能路由”。每个技能是一个独立的 Markdown 指令包里面写清楚这个技能在什么场景下触发、需要哪些输入、执行步骤是什么、应该遵守什么约束。Codex 在接到任务的时候会先去技能库里检索匹配的技能把对应的指令注入到对话上下文中再开始干活。1.2 技能Skill到底是什么用生活类比来解释你请了一个很聪明的助理Codex他脑子转得快但对你们公司的业务一无所知。你不可能每次交代任务都从“我们公司是做什么的”开始讲。于是你给他一本 SOP 手册Superpowers 技能库每页写着一类任务的标准化做法。比如“提交代码前要跑哪些检查”“写单元测试要有哪些固定套路”“处理某个框架升级时要注意哪些坑”。助理接到新任务时自己翻手册找到对应那页照着执行。在 Superpowers 里每一页 SOP 就是一个技能目录里面有一个核心的SKILL.md文件用 frontmatter 写元信息名称、描述、触发条件正文写执行步骤和约束。Codex 会根据任务描述和技能描述做匹配匹配上了就把整个技能内容加载进上下文。就这么简单没有魔法但它把“调教 AI”这件事从“每次对话临时调教”变成了“一次沉淀、永久复用”。1.3 为什么选 MCP 协议而不是硬编码这里要聊一下技术选型的逻辑。Superpowers 没有去 fork Codex 或者给 Codex 打补丁而是用 MCPModel Context Protocol作为桥梁。MCP 是 Anthropic 推出来的一个标准化协议本质是让 AI 应用能统一地调用外部工具和数据源。Codex CLI 原生支持 MCP所以 Superpowers 可以作为一个 MCP 服务端挂在 Codex 上完全解耦。这个选型的聪明之处在于第一你不需要魔改 Codex升级 Codex 也不会影响技能系统第二技能库不绑定特定 AI理论上任何支持 MCP 的客户端都能用第三技能的管理是纯文件系统操作你可以用 Git 管理技能库团队共享一套技能甚至给不同项目配不同的技能子集。我后来把技能库直接放到团队仓库里新人 clone 下来就能获得一套完整的“AI 使用规范”这个收益是实打实的。2. 安装与环境准备把 Superpowers 跑起来2.1 前置条件与最简安装路径安装 Superpowers 的前置条件不算苛刻但有几个地方容易踩坑我按顺序说。首先你得装了 Node.js版本建议 18 以上我实测在 Node 16 上跑会报一些fetch相关的兼容问题所以别偷懒先升级。其次你本机要有 Codex CLI 并且登录过具体版本不限但尽量保持最新老版本对 MCP 的支持有差异。安装本身就是一个 clone 加 install 的过程。我习惯把它放到一个专门的目录比如~/tools/superpowersgit clone https://github.com/obra/superpowers.git cd superpowers npm install这里有个容易被忽略的点项目里可能有个bin目录或者mcp-server.js作为 MCP 服务端的入口安装完记得看一眼 package.json 的 bin 字段或者 README 里写的启动命令。我一开始没看直接去找superpowers命令结果发现人家是让你用 node 直接跑脚本的。以官方仓库为准但通常就是类似node mcp-server.js这种方式启动。2.2 配置 Codex CLI 接入 MCP接下来把 Superpowers 注册成 Codex 的 MCP 服务端。Codex CLI 的配置文件在~/.codex/config.toml你需要手动加一个 MCP server 的配置块。每个人本机路径不同这里给一个通用的写法[mcp_servers.superpowers] command node args [/absolute/path/to/superpowers/mcp-server.js]写完保存然后重启 Codex CLI。怎么确认生效你可以在 Codex 里直接问它“你有哪些可用的 MCP 工具”如果配置成功它会列出 Superpowers 提供的工具比如技能列表查询、技能内容读取这类。第一次配置完不生效是常态百分之八十是因为路径写成了相对路径MCP 服务端的 cwd 和你的 shell 不是同一个所以务必用绝对路径别嫌麻烦。还有个小坑如果你正在用 zsh 或者 oh-my-zsh环境变量里有些 PATH 配置可能没被 Codex CLI 继承到导致node命令找不到。稳妥的办法是在配置里把node写成绝对路径先执行which node看一下具体位置然后填进去。2.3 验证安装是否真正可用配置完别急着干活先跑一个最小验证。Superpowers 默认会带一些内置技能你可以通过命令或者直接在 Codex 里问来确认技能列表加载正常。我一般是这样验证第一步在 Codex 里输入“请列出你已加载的技能以及每个技能的用途”。如果它开始背技能清单说明 MCP 通信正常技能库读取成功。第二步故意给一个会触发技能的任务比如“帮我写一个 git worktree 的脚本”观察 Codex 是否引用了技能里的约束和步骤。如果它只是像普通对话一样直接开始写说明技能匹配没生效多半是技能描述写得太抽象Codex 没识别出来。这一步是判断系统是否真正工作的关键很多人装完觉得“没啥变化”就是卡在这里。技能匹配不是自动的它靠的是技能描述和用户指令之间的语义匹配所以你写的技能描述越具体、关键词越接近真实业务触发率越高。3. 核心机制拆解技能如何被编写、检索和调用3.1 一个技能目录的标准结构Superpowers 的技能组织方式很直观一个技能就是技能根目录下的一个子目录。技能根目录默认在~/skills但你可以在配置里改到你项目仓库里。每个技能目录里必须有一个SKILL.md这是技能的入口文件。结构大概是这样的~/skills/ ├── git-worktree/ │ ├── SKILL.md │ └── templates/ │ └── worktree-summary.md ├── junit5-test-writer/ │ ├── SKILL.md │ └── examples/ │ └── user-service-test.java └── dependency-audit/ └── SKILL.mdSKILL.md的开头是 YAML frontmatter里面至少要有name和description这是 Codex 用来做匹配的依据。description是重中之重它直接影响技能能否被正确触发。写 description 的原则是说清楚这个技能做什么、在什么情况下用、涉及哪些关键技术词。比如你写一个处理 Spring 升级的技能描述里就该出现Spring Boot 3、Jakarta EE、javax 迁移这些具体词汇这样用户问“帮我迁移到 Spring Boot 3”时才能命中。正文部分写执行步骤和规则语气要让 AI 能理解用祈使句把流程拆到可执行粒度。有些技能还会带一个args的说明不同版本写法有差异用来告诉模型执行这个技能需要哪些参数模型在触发技能时会把缺失的信息通过提问补齐。3.2 匹配机制Codex 如何决定用哪个技能这个机制值得多说两句因为很多人会误以为“技能是插件点一下就调用”实际上它更像“搜索引擎规则引擎”。Codex 在每轮对话中会把当前用户消息和历史上下文综合起来生成一个“当前意图”的向量表示然后去遍历所有技能的描述计算相关性挑出最相关的几个技能加载进上下文。这意味着两件事第一技能不保证被触发它只是增加了触发概率描述质量直接影响命中率第二技能列表越长检索的开销越大匹配准确率也会下降。所以技能库不是越多越好而是围绕你真实高频的场景来沉淀。我在团队里定的规矩是每个技能必须有明确的“触发条件”清单描述里先用一句话讲适用场景再讲具体做法。我给你一个我最常用的技能描述模板做参考--- name: junit5-test-writer description: 在 Java 项目中编写 JUnit 5 单元测试时使用。包括测试类命名规范、断言风格、Mockito 使用约定适用于 Maven 或 Gradle 项目。 ---实际用下来这种“场景技术栈生命周期”的描述方式识别率最高。你光写“生成单元测试”是不够的因为“生成单元测试”这个意图太宽泛匹配器拿不准你用的框架和风格。3.3 技能内容应该怎么组织AI 才能照着做SKILL.md正文的写法跟你平时写技术文档的习惯可能不太一样。普通文档给人看讲究逻辑完整技能文档给 AI 看讲究“可执行”。AI 是靠逐条指令来行动的所以每一段都应该是明确的动作指令而不是背景阐述。我写技能正文时会强制用这种结构先说这个任务的输入是什么再说执行步骤最后说验收标准。所谓验收标准就是告诉模型“做到什么程度这个任务才算完成”。比如写 JUnit 测试的技能验收标准就是“每个公共方法至少一个测试用例”“测试运行全绿”“不修改被测代码的公共接口”。有了验收标准模型就有一套自检清单输出质量会稳定很多。另外技能里可以引用模板文件。比如你希望测试类有统一的文件头格式可以放一个模板文件在技能目录里然后在 SKILL.md 里写“参考 templates/test-template.java 的格式”这样技能的内容更整洁也方便单独维护模板。模板文件对 AI 来说就是字符串样本它会在生成时模仿结构和风格。我强烈建议你用模板而不是在 SKILL.md 里贴大段示例代码因为技能正文太长会影响指令的执行优先级。4. 实战从一个 Java 技能看完整落地流程4.1 场景定义与技能设计光讲机制不给例子等于白讲。我拿一个真实场景来演示我所在的项目组维护着一个 Java 微服务仓库用的 Spring Boot 3.2 Maven JUnit 5 Mockito。之前的痛点很集中AI 生成的测试乱七八糟有的用 JUnit 4 的注解毕竟它在训练数据里见过太多 JUnit 4 的代码有的测试方法名是test1()有的把 Mockito 的静态方法用错。于是我们沉淀了一个junit5-test-writer技能。设计这个技能的时候我先列清楚了要约束的点测试类命名必须以Test结尾测试方法名要描述行为用should_前缀Mock 对象统一用Mock加构造器注入禁止使用MockitoJUnitRunner要使用MockitoExtension断言用 AssertJ不用 JUnit 自带断言。这些规则全部来自实际的 code review 记录不是拍脑袋写的。4.2 SKILL.md 的完整写法与参数说明下面是这个技能SKILL.md的简化版我删掉了一些公司内部信息保留核心框架。这里注意一下每种技能的写法会随着 Superpowers 版本迭代有差异但这个结构基本通用。--- name: junit5-test-writer description: 为 Java 类编写 JUnit 5 Mockito AssertJ 单元测试。适用于 Maven 或 Gradle 管理的 Spring Boot 项目。当用户请求生成测试、补充测试、修复失败测试时使用。 args: targetClass: 被测类的完整类名或文件路径 testClass: 生成的测试类完整类名 --- # 编写 JUnit 5 单元测试 ## 背景本技能用于保证生成的测试符合团队的编码规范。被测代码基于 Spring Boot 3.2使用 Maven 构建测试框架为 JUnit 5 与 Mockito断言库使用 AssertJ。 ## 执行步骤 1. 读取目标类识别它的公共方法和依赖。 2. 若目标类依赖外部服务使用 Mockito 的 Mock 注解创建 mock并手动 setter/构造器注入不启动 Spring 上下文。 3. 测试类命名{TargetClass}Test放在 src/test/java 对应包目录下。 4. 测试方法命名should_{预期行为}_{条件}。 5. 断言使用 AssertJ 的 assertThat。 6. 每个公共方法至少写一个主路径测试和一个异常路径测试。 ## 验收标准 - 测试类使用 org.junit.jupiter.api.Test 注解不使用 junit.framework.TestCase。 - 项目中不出现 org.junit.TestJUnit 4 的注解。 - mvn test 通过所有新增测试运行成功。写这种技能文档的时候有个很容易犯的错误把“为什么”写太多。AI 不需要理解你们团队的架构决策来写测试它只需要知道“怎么做”。所以正文里每一句话要么是动作要么是验收条件这才是 AI 能高效执行的语言。我见过有人把技能写成论文结果模型上下文被无关的背景信息塞满输出的代码反而不稳定。4.3 把这个技能接入实际编码流程技能文件写好之后放在~/skills/junit5-test-writer/目录下重启 Codex CLICodex 会在新会话开始时重新扫描技能目录。然后你就可以直接提需求“给UserService写测试”理想情况下 Codex 会加载这个技能并且按照里面的步骤来写。但是这里我建议你做一次“技能调试”。我个人的习惯是第一次触发之后紧接着追问一句“你用了哪个技能技能里对断言风格是怎么规定的”用来确认它确实读取了技能内容而不是凭训练记忆在硬写。这一步能帮你抓出两类问题一是技能描述写得太宽泛导致模型选择了别的技能二是技能本身加载了但指令写得模糊模型不知道优先级。技能不是一次性写好就完了它会随团队规范演进而迭代。每次 code review 里出现的新风格问题我会塞进对应技能的“验收标准”或者“禁止事项”里。一段时间之后AI 生成的代码会越来越接近老手风格这个积累过程就是 Superpowers 最值钱的地方。5. 常见问题与排查技巧实录5.1 技能不触发的排查顺序这是所有人装上 Superpowers 后第一个遇到的问题。“我明明写好了技能Codex 怎么不理它”。按我踩过多次坑的经验排查顺序是固定的。先看技能目录路径对不对。默认扫描~/skills如果你改了配置确认配置里的路径是绝对路径。然后用 Codex 问一句“你加载了哪些技能”看它是否列出了你期望的技能。如果列表里没有说明路径或者 frontmatter 有问题常见的是 frontmatter 语法错误导致整个文件被跳过。如果列表里有但任务不触发那问题就出在 description 上描述里的词汇和用户指令匹配度不够。还有个隐蔽问题Codex 的上下文里有历史对话残留导致当前意图被带偏。比如用户前面聊了两轮部署脚本突然说“写点测试”模型可能把上下文主题理解成“改部署脚本”技能匹配就落空了。遇到这种情况最简单的办法是开新会话把问题描述得更具体再试一次。5.2 安装和启动阶段的报错处理安装阶段最常见的报错是 Node 版本太老造成依赖安装失败报错信息一般会指向某个包不支持当前 Node 版本这时候不要试图去降依赖版本直接升 Node 大版本最省事。第二个常见坑是 MCP 服务配置了但 Codex 启动时提示连不上这种十有八九是路径问题把node命令和mcp-server.js的路径都改成绝对路径然后手动在终端里跑一次node /absolute/path/to/mcp-server.js看有没有报错比如缺依赖或者端口冲突。还有一类问题跟网络环境有关比如在部分受限网络环境下MCP 服务端访问某些资源超时。这个就不展开网络层面的因素了但你可以确认一下是不是技能里引用的外部 URL 无法访问导致的超时。5.3 工作台类工具怎么接入 Superpowers最近有朋友在问类似 worbuddy 这类 Agent 工作台怎么用 Superpowers。这里给一个通用结论只要这个工具支持配置 MCP 客户端原理和 Codex CLI 是一样的——把 Superpowers 的 MCP 服务端地址指过去就行。具体做法是在对应工具的 MCP 设置里新增一个 servercommand 填nodeargs 填服务端脚本的绝对路径。如果某个工具不支持 MCP那就没法直接用但你可以退一步只使用技能文档的编写思路把自己的规范整理成一个普通 Markdown 文件每次新建会话时手动贴给模型做前置上下文效果约等于阉割版的 Superpowers。我自己用下来的体会是工作台类工具和 CLI 的差异主要在交互层底层的技能驱动逻辑是一样的。核心不是工具本身而是你有没有把经验整理成结构化指令的习惯。5.4 一个我差点放弃的坑技能内容“太长被忽略”最后一个坑很有代表性。我早期往一个技能里塞了大量内容包括完整示例代码、历史背景、多个模板文件引用结果模型触发技能后仍然我行我素完全没按技能里的规范来。后来排查才意识到技能加载只是把内容注入上下文但模型的注意力是有限的当技能内容超过一定长度后面的指令权重会被前面的背景和示例稀释。这个问题的解决思路是控制单个技能的体量一个技能只解决一类任务不要做“全能技能”。如果任务确实复杂拆成多个技能或阶段每个技能只负责一个步骤的规范。另外把最重要的约束放在 SKILL.md 开头因为模型对前置部分的执行优先级通常高于后半部分。凡是“禁止使用 JUnit 4”“断言必须用 AssertJ”这类硬性规则我会在文首和验收标准里各出现一次用重复来强化约束实测触发率会明显提升。最后再顺手分享一点我的使用心得Superpowers 这个东西表面上看是一套技能框架实际上它逼着我养成了一个很好的习惯——把零散的经验系统化。以前我写代码规范文档写完之后基本吃灰AI 来了之后反而这些文档有了直接消费者。我个人体验是技能不在多而在精准。先把你日常最高频的 3 到 5 个场景沉淀成技能跑顺了再慢慢扩。另外一个小建议技能库最好纳入 Git 管理团队共用一套每次更新走 code review。你会意外发现这比给新人写一堆 onboarding 文档管用得多。因为技能不是给人读的是给 AI 照着执行的而 AI 每次执行都会把这些规范落到实处。说到底Superpowers 真正的“超能力”不是工具本身而是你愿意把自己的经验结构化地喂养给 AI让它越用越懂你。

Superpowers：用MCP协议为Codex CLI加AI技能

相关推荐

Harness SDK 核心原理与 Python/TypeScript 实战避坑指南

三菱FX1s老PLC改造：用Modbus RTU与RS485控制三台台达变频器

给AI Agent写的Install文档：可验证、可恢复、可组合的环境初始化协议

更多资讯

DeepSeek本地部署实战：Ollama + Open WebUI完整部署指南

MCP与A2A如何选？从JSON-RPC到Agent协议分层解析

Seedance 2.0角色一致性视频生成全解析：从原理到实操

C语言指针与数组交互：内存地址、类型退化与安全修改

JavaScript刷算法：V8引擎约束下的最优解法

STM32裸机驱动OV2640输出JPEG流实战指南

今日更新

NetSpot 实战：用信道分析与频宽优化解决 Wi-Fi 卡顿

C++ split() 字符串分割的五种实现与性能实测

R语言坐标轴范围设置：从xlim/ylim到coord_cartesian的完整指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？