Superpowers 框架：为 Claude Code 与 Codex CLI 构建可复用 AI 编程技能体系

1. 这套东西到底在解决什么问题

第一次听到 "superpowers" 这个名字，很多人会以为是某个新出的编辑器插件或者某个大模型的代号。其实都不是。它是一套围绕 AI 编程助手构建的agentic skills framework，翻译成人话就是"给 AI 编程助手装上一整套可复用的技能包"。你平时用 Claude Code 或者 Codex CLI 写代码，默认状态下它就是一个"聪明但没受过专门训练的新人"——你问它什么它答什么，但每次都要从头解释项目规范、代码风格、测试要求。superpowers 要做的，就是把这些重复性的"规矩"和"套路"沉淀成一个个 skill，让 AI 在需要的时候自动调用。

我最初接触它是因为一个很现实的痛点：团队里几个人都在用 Claude Code 写代码，但每个人给 AI 的提示词风格不一样，导致生成的代码质量参差不齐。有人让 AI 直接写完整文件，有人让 AI 一步步来，有人根本不写测试。后来发现 superpowers 这套框架的核心思路就是把软件工程的方法论编码成 AI 能理解的技能单元，这跟传统意义上"写个 prompt 模板"完全不是一个层次的东西。

它适合谁？三类人最值得花时间研究。第一类是已经在用 Claude Code 或 Codex CLI 但觉得"AI 写代码还是不够靠谱"的开发者；第二类是想把 AI 编程助手引入团队工作流但不知道怎么统一规范的技术负责人；第三类是对 agentic skills framework 这个概念本身感兴趣、想看看别人怎么设计技能体系的人。哪怕你暂时不用 Claude Code，这套框架的设计思路对你理解"怎么让 AI 按规矩干活"也很有参考价值。

需要提前说清楚的是，superpowers 本身不是一个独立软件，它更像是挂在 Claude Code 或 Codex CLI 上的一套配置和技能集合。所以你的第一步永远是先把底层工具装好，再谈 superpowers 的安装和使用。下面我会从整体设计思路开始拆，然后一步步讲到实操、踩坑和排查。

2. 整体设计思路与方案选型拆解

2.1 为什么是"技能框架"而不是"提示词模板"

很多人第一次接触 AI 编程助手，习惯的做法是写一个超长的系统提示词，把所有要求塞进去。我早期也这么干过，结果就是提示词越写越长，最后自己都维护不动，而且 AI 经常"选择性失忆"，前面说的规范到后面就忘了。superpowers 的设计者显然想明白了这件事：与其写一个万能提示词，不如把能力拆成一个个独立的 skill，按需加载。

这个思路跟软件工程里的"单一职责原则"是一脉相承的。一个 skill 只负责一件事，比如"写单元测试"是一个 skill，"做代码审查"是另一个 skill，"生成 API 文档"又是另一个。当你的任务需要某个能力时，AI 才去调用对应的 skill。这样做的好处非常直接：每个 skill 可以独立迭代、独立测试，不会因为改了一处就影响全局。而且 skill 可以复用，今天在这个项目里写的"Python 测试规范"skill，明天换个项目照样能用。

从架构上看，这套框架大致分三层。最底层是skill 定义层，每个 skill 用结构化的方式描述"什么时候触发、需要什么输入、执行什么步骤、输出什么结果"。中间是调度层，负责判断当前任务该调用哪些 skill。最上面是集成层，对接 Claude Code 或 Codex CLI 的具体接口。理解这三层，后面排查问题的时候你就知道该往哪个方向找。

2.2 Claude Code 与 Codex CLI 的选型考量

热词里同时出现了 Claude Code 和 Codex CLI，这两个是目前最主流的两个 AI 编程命令行工具，superpowers 对两者都有支持。那到底选哪个？我的实际体验是这样：

Claude Code 的优势在于上下文理解能力强、技能生态相对成熟，尤其是它对 skill 这类扩展机制的支持比较自然，配置起来心智负担小。缺点是国内直接使用会有一些网络和账号层面的门槛，热词里那句 "claude code might not be available in your country" 说的就是这个情况。Codex CLI 的优势是开源、可本地部署、对自定义模型友好，热词里 "claude code接入deepseek"、"claude code接deepseek" 这些搜索，本质上就是大家在想办法把 Claude Code 的体验和开源模型结合起来。

我的建议是：如果你追求开箱即用、不想折腾环境，优先考虑 Claude Code；如果你有本地模型资源、或者对数据隐私有要求，Codex CLI 更合适。两者并不是互斥的，superpowers 的 skill 定义在两边基本可以互通，你完全可以在两个工具上都装一遍，对比着用。

2.3 把方法论"编码化"的核心价值

superpowers 最打动我的一点，是它真正把software development methodology落到了可执行的层面。以前我们说"要写测试""要做代码审查""要遵循命名规范"，这些都是口头约定，靠人的自觉。现在把这些约定写成 skill，AI 每次执行任务时都会按这个流程走，相当于给团队配了一个永远不会偷懒的流程监督员。

举个具体例子。我们团队有个 skill 叫"提交前检查"，它规定任何代码在提交前必须经过三步：跑一遍 lint、跑一遍单元测试、检查是否有硬编码的密钥。以前这三步全靠人记，十次里总有两三次漏掉。写成 skill 之后，AI 在你说"帮我提交"的时候会自动触发这个流程，漏检率直接降到零。这就是"编码化"的威力——把依赖记忆的软约束，变成依赖流程的硬约束。

3. 核心细节解析与实操要点

3.1 环境准备：先把底层工具装明白

在装 superpowers 之前，你得先有一个能跑的 Claude Code 或 Codex CLI。这一步看起来简单，但热词里大量 "claude code安装"、"codex cli安装"、"windows claude code"、"ubuntu安装claude code" 的搜索说明，卡在这一步的人非常多。我按平台分别说一下。

Claude Code 的安装，官方推荐的方式是通过包管理器。在 macOS 或 Linux 上，通常是一条命令搞定；在 Windows 上，建议先装好 Node.js 环境，再通过 npm 全局安装。安装完成后，第一次运行需要完成账号授权，这一步会打开浏览器让你登录。如果你在 Ubuntu 上装，注意 Node.js 版本不要太老，我实测 18 以上比较稳。热词里 "claude code存储位置" 也是常见疑问，默认情况下配置和缓存会放在用户主目录下的隐藏文件夹里，具体路径可以在工具内用命令查询。

Codex CLI 的安装，因为它开源，所以方式更灵活。你可以用包管理器装，也可以从源码构建。Windows 用户注意，热词里 "codex cli windows安装" 是个高频问题，我的经验是优先用 WSL 环境，原生 Windows 下偶尔会遇到路径和权限的坑。装完之后用codex --version验证一下，能打印版本号就说明装好了。

提示：安装过程中如果遇到 "unable to locate the codex cli binary or required runtime components" 这类报错，九成是环境变量没配好，或者运行时依赖缺失。先确认二进制文件在不在 PATH 里，再检查 Node.js 或 Python 运行时版本是否满足要求。

3.2 superpowers 的安装与目录结构

底层工具就绪后，superpowers 的安装其实不复杂，核心就是把 skill 定义文件放到工具能识别的位置。热词里 "superpowers安装"、"claude code怎么手动装github上的skills" 问的就是这件事。

手动安装的通用流程是这样的：先把 superpowers 的仓库克隆到本地，然后找到 Claude Code 或 Codex CLI 的 skill 目录，把需要的 skill 复制或软链接过去。软链接的好处是以后更新 superpowers 仓库，skill 会自动同步，不用每次手动复制。目录结构上，一般每个 skill 是一个独立文件夹，里面至少有一个描述文件（说明这个 skill 干什么、什么时候触发）和若干执行脚本或提示词文件。

我建议第一次装的时候只装两三个 skill 试水，别一股脑全装上。原因很简单：skill 太多，AI 在调度时反而容易选错，而且你也不清楚每个 skill 到底靠不靠谱。先装一个"代码审查"、一个"写测试"，用顺了再逐步加。

3.3 skill 定义文件的关键字段

一个 skill 能不能被正确触发，全看定义文件写得好不好。根据我的实践，几个字段最关键：

• 触发条件：描述什么情况下该用这个 skill。写得太宽，AI 动不动就调用；写得太窄，该用的时候用不上。我的经验是用具体的动作词，比如"当用户要求审查代码时"比"当涉及代码时"精确得多。
• 输入要求：明确这个 skill 需要哪些信息。比如代码审查 skill 需要知道审查哪个文件、遵循什么规范。
• 执行步骤：把流程拆成有序的步骤，每一步说清楚做什么、产出什么。
• 输出格式：规定结果长什么样。这一步很多人忽略，但恰恰最重要——没有统一输出格式，AI 每次给你的东西结构都不一样，没法用。

注意：skill 定义里的语言要尽量"指令化"，少用"可以""建议"这类模糊词。AI 对确定性指令的执行率远高于模糊建议。我踩过的坑就是早期写"建议添加注释"，结果 AI 十次有五次不加；改成"必须为每个公开函数添加注释"之后，执行率立刻上来了。

4. 实操过程与核心环节实现

4.1 从零跑通第一个 skill 的完整流程

光说概念没意思，我带你走一遍完整流程。假设你已经装好了 Claude Code，现在要装一个"代码审查"skill 并跑通它。

第一步，克隆 superpowers 仓库到本地任意目录，比如~/tools/superpowers。第二步，找到 Claude Code 的 skill 目录，通常在配置目录下的skills文件夹里。第三步，把仓库里skills/code-review这个文件夹软链接过去。第四步，重启 Claude Code，让它重新加载 skill 列表。第五步，在一个测试项目里输入"帮我审查一下这个文件的代码"，观察 AI 是否触发了 code-review skill。

判断是否触发成功，看 AI 的回复结构。如果它开始按"问题清单—严重程度—修改建议"这种结构化方式输出，说明 skill 生效了；如果它还是自由发挥，那就是没触发，回去检查定义文件的触发条件。

4.2 参数选择与配置调优

skill 跑起来之后，接下来是调优。这里涉及几个可以调的参数，我逐个说。

触发灵敏度。有些框架允许你设置 skill 的触发阈值。阈值高，AI 只在非常确定的时候才调用；阈值低，稍微沾边就调用。我的建议是初期设低一点，先观察 AI 在哪些场景下会调用，收集一批实际案例后再往上调。这跟调推荐系统是一个道理，先召回再精排。

上下文窗口占用。每个 skill 加载都会占用一部分上下文。如果你同时装了很多 skill，上下文会被大量占用，导致 AI 处理实际任务的空间变小。热词里 "claude code 1m上下文" 说明大家很关心上下文容量，但再大的容量也经不住乱用。我的做法是按项目启用 skill，这个项目只需要测试相关的，就只启用测试 skill，其他的先关掉。

执行超时。有些 skill 会执行外部命令，比如跑测试、跑 lint。这些命令可能耗时较长，需要设置合理的超时。设太短，任务没跑完就被中断；设太长，卡住了你也不知道。我一般设 60 到 120 秒，具体看项目规模。

4.3 把 skill 接入实际开发流程

skill 单独跑通只是第一步，真正有价值的是把它接入日常开发流程。我分享一个我们团队的实际做法。

我们在代码仓库里放了一个配置文件，声明这个项目启用哪些 skill。开发者克隆项目后，运行一个初始化脚本，脚本会自动把项目需要的 skill 链接到本地工具的 skill 目录。这样每个人拿到的 AI 助手行为是一致的，不会出现"张三的 AI 会写测试、李四的 AI 不写"这种情况。

具体到日常操作，我们设了三个关键触发点。写新功能时，触发"测试先行"skill，让 AI 先写测试再写实现。提交代码前，触发"提交检查"skill，自动跑 lint 和测试。合并请求时，触发"审查"skill，生成结构化的审查意见。这三个点覆盖了开发流程的主要环节，实测下来团队代码质量有明显提升。

提示：接入流程时不要一次性全上，先在一个小项目或者一个开发者身上试点，跑顺了再推广。我见过太多团队一上来就全面铺开，结果 skill 配置有问题，反而拖慢了所有人的节奏。

5. 常见问题与排查技巧实录

5.1 安装类问题速查

安装阶段的问题最集中，我整理了一个速查表，基本覆盖热词里出现的高频报错。

5.2 运行时的典型故障

装好之后，运行时也会遇到各种问题。最常见的是skill 触发了但执行失败。这种情况先看日志，大部分框架都会把 skill 的执行过程记下来。日志里通常能看到是哪一步出的错，是输入格式不对，还是外部命令返回了非零退出码。

另一个高频问题是AI 选错了 skill。比如你让它审查代码，它却触发了"写文档"skill。这通常是触发条件写得太模糊导致的。解决办法是把触发条件写得更具体，或者在 skill 定义里加上"排除条件"，明确什么情况下不要用这个 skill。

还有一种情况是skill 之间互相干扰。两个 skill 的触发条件有重叠，AI 不知道该用哪个。我的处理原则是：同一类任务只保留一个 skill，如果有多个候选，合并成一个，用内部分支处理不同情况。这样调度逻辑清晰，不会打架。

5.3 我踩过的几个坑

说几个文档里不会写、但实际一定会遇到的坑。

第一个坑是软链接在 Windows 上的兼容性。我在 Windows 上用软链接链接 skill 目录，结果工具识别不了。后来改成直接复制文件，虽然更新麻烦点，但至少能用。如果你在 Windows 上折腾，建议直接用复制，别跟软链接较劲。

第二个坑是skill 更新后缓存没清。superpowers 仓库更新了 skill 定义，但工具还在用旧版本，因为缓存没刷新。解决办法是更新后手动清一次缓存，或者重启工具。这个坑很隐蔽，你会以为是新 skill 有问题，其实是旧缓存在作祟。

第三个坑是过度依赖 skill 导致 AI 变"死板"。skill 装多了之后，AI 有时候会机械地套用流程，哪怕当前场景并不适合。比如一个简单的改错别字任务，它也非要跑一遍完整的测试流程。这时候需要你在 skill 定义里加上"轻量任务跳过"的判断逻辑，让 AI 学会区分任务轻重。

注意：skill 是工具不是教条。发现 AI 行为僵化时，先反思是不是 skill 定义太死，而不是一味怪 AI 不聪明。

6. 进阶玩法与扩展思路

6.1 自定义 skill 的编写要点

用顺了现成的 skill，你迟早会想写自己的。写自定义 skill 有几个要点。第一，从真实痛点出发，别为了写而写。你团队反复出现的问题，才值得做成 skill。第二，先手动跑通流程再编码，你自己都没跑通的流程，写成 skill 也是错的。第三，保持 skill 短小，一个 skill 只解决一个问题，超过两百行的 skill 定义基本就该拆了。

我写过一个"数据库迁移检查"skill，起因是我们有一次迁移脚本写错，把测试库的数据清了。这个 skill 的逻辑很简单：检测到迁移相关操作时，先检查目标环境是不是生产库，是的话强制二次确认。就这一条规则，帮我们避免了好几次事故。

6.2 团队协作中的 skill 管理

团队用 skill，管理比编写更重要。我们的做法是把 skill 定义纳入代码仓库，跟业务代码一起做版本管理。谁改了 skill，走正常的代码审查流程。这样 skill 的变更历史清清楚楚，出问题能追溯。

另外建议给 skill 分等级。核心 skill（比如提交检查）必须所有人启用，可选 skill（比如某个语言特有的规范）按需启用。分级之后，新人的配置负担小，团队的底线又有保障。

6.3 与其他工具的联动

superpowers 不是孤立的，它可以跟你现有的工具链联动。比如把 skill 和 CI 打通，本地 skill 跑完的检查，CI 上再跑一遍做双重保险。再比如把 skill 和 IDE 结合，热词里 "vscode配置claude code"、"vscode安装claude code" 说明很多人希望在编辑器里直接用。我的经验是，编辑器集成能提升日常使用的顺手程度，但复杂的 skill 编排还是命令行更灵活，两者可以配合。

我个人在实际操作中的体会是，superpowers 这类框架的价值不在于它自带多少 skill，而在于它提供了一套把工程经验沉淀成可复用资产的机制。你投入时间写 skill 的过程，本质上是在梳理自己团队的开发规范。哪怕哪天不用这个框架了，这些规范本身也是财富。最后分享一个小技巧：每次写完一个新 skill，先让 AI 用它跑三个真实任务，观察输出是否稳定。稳定了再纳入正式流程，不稳定就继续改定义。这个"三任务验证法"帮我过滤掉了不少半成品 skill。