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 定义在两边基本可以互通你完全可以在两个工具上都装一遍对比着用。对比维度Claude CodeCodex CLI上手难度较低配置项少中等需要理解配置文件结构技能生态成熟skill 机制原生支持好灵活可深度定制模型选择官方模型为主可接开源模型自由度高环境要求需要稳定的网络与账号可本地运行依赖可控适合人群个人开发者、快速验证团队、有本地资源的技术人员2.3 把方法论编码化的核心价值superpowers 最打动我的一点是它真正把software development methodology落到了可执行的层面。以前我们说要写测试要做代码审查要遵循命名规范这些都是口头约定靠人的自觉。现在把这些约定写成 skillAI 每次执行任务时都会按这个流程走相当于给团队配了一个永远不会偷懒的流程监督员。举个具体例子。我们团队有个 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 安装类问题速查安装阶段的问题最集中我整理了一个速查表基本覆盖热词里出现的高频报错。问题现象可能原因排查方向提示找不到 CLI 二进制或运行时组件环境变量未配置、运行时缺失检查 PATH确认 Node.js/Python 版本安装后命令无法识别全局安装路径不在 PATH手动把安装目录加入 PATHWindows 下安装失败路径分隔符、权限问题改用 WSL 环境重试授权登录卡住网络或账号状态异常检查网络连通性确认账号可用skill 不生效目录放错、未重启工具确认 skill 目录路径重启后重试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。

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

相关推荐

Axure Bridge Chrome插件安装与排错全指南

RTK Query日志精简：3个钩子将500行测试输出压缩为LLM友好摘要

superpowers 框架实战：AI 编程助手能力增强与 Java 落地指南

更多资讯

蔡司三坐标测量仪是什么？一文读懂原理、型号、精度与行业应用

Xoodyak算法的各种密码分析方法全面盘点

【LLM】第五章：LangChain框架介绍+开发前的准备工作

CBC-MAC算法的各种密码分析方法全面盘点

XHS-Downloader：免费开源的小红书原图下载工具，链接一贴作品就落盘

分享Claude进行AI编程的相关技巧及程序员未来发展方向

今日更新

AI辅助技术栈评估：提升研发决策效率60%

从生成Token到直接决策：Jev如何重塑AI Agent工程实践

32G统一内存跑大模型：内存账、TPS实测与端云分流

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

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