1. 先搞清楚 superpowers 到底是什么第一次看到 superpowers 这个词很多人会以为是某个新出的 AI 模型或者某个大厂的新产品。其实不是。它是一套面向 AI 编程助手的agentic skills framework翻译过来就是智能体技能框架。你可以把它理解成给 AI 编程助手装的一套外挂技能包让原本只会按指令写代码的助手变成一个有章法、有流程、有工程思维的开发搭档。我最初接触它是在折腾 Claude Code 的时候。当时用 Claude Code 写代码最大的感受是它能写但写得很散。你让它改一个函数它就改一个函数你让它加个测试它就加个测试。它不会主动去想这个改动会不会影响别的模块要不要先跑一遍回归提交信息该怎么写才规范。每次都要我在旁边当项目经理一条条喂指令累得不行。superpowers 解决的正是这个问题。它本质上是一套software development methodology软件开发方法论的代码化封装把需求分析、方案设计、编码实现、测试验证、提交归档这一整套工程流程拆解成一个个可复用的 skill技能然后注入到 AI 编程助手的执行链路里。装上之后AI 不再是你说一句它动一下的工具人而是会按照既定流程主动推进任务的协作方。这套框架目前主要适配两个主流的命令行 AI 编程工具Claude Code和Codex CLI。前者是 Anthropic 推出的终端编程助手后者是 OpenAI 系的命令行工具。两者都是在终端里跟 AI 结对编程的形态superpowers 作为技能层叠加在它们之上。所以你在热搜里会看到 codex superpowersclaude code skill 这类组合词说的就是这套框架在不同宿主工具上的落地方式。适合谁来用我的判断是三类人。第一类是刚上手 AI 编程助手的新手不知道怎么把 AI 用好superpowers 相当于给你一套现成的最佳实践模板照着走就不会太离谱。第二类是有一定经验的独立开发者平时一个人扛前后端希望 AI 能分担更多流程性工作而不是只当个代码补全器。第三类是团队里的技术负责人想把 AI 编程的规范固化下来让团队里每个人用 AI 的方式保持一致减少各写各的带来的混乱。需要提前说明的是superpowers 不是那种装完就自动变强的魔法。它更像一套脚手架你得理解它的设计逻辑知道每个 skill 在什么场景下触发、怎么配置、怎么跟自己的项目结合才能真正发挥价值。下面我会从设计思路、核心机制、实操部署、常见坑几个维度把我自己踩过的路完整讲一遍。2. 核心设计思路为什么要把开发流程技能化2.1 从提示词工程到技能工程的转变早期用 AI 编程大家的做法是堆提示词。写一个巨长的 system prompt把你要先分析需求、再设计方案、然后写代码、最后写测试这些话全塞进去。我试过效果不稳定。原因很简单提示词是软约束AI 在长对话里很容易把前面的要求忘掉尤其是上下文一长那些流程性指令就被稀释了。superpowers 的思路不一样。它把流程拆成独立的 skill 文件每个 skill 是一个自包含的单元有自己的触发条件、执行步骤和输出规范。AI 在执行任务时会根据当前所处的阶段去加载对应的 skill而不是靠一段长提示词硬撑。这就好比从背一整本操作手册变成了按需翻到对应章节认知负担小得多执行也更稳定。这个设计背后有个关键判断AI 编程的瓶颈不在模型能力而在流程编排。模型本身已经足够聪明能写出高质量代码但它不知道什么时候该做什么。superpowers 补的就是这块。它把人类工程师脑子里的隐性流程显性化、结构化变成 AI 可以遵循的显式步骤。2.2 skill 的粒度设计为什么不是一个大而全的流程有人可能会问为什么不干脆做一个完整开发流程的大 skill从头管到尾我一开始也这么想后来发现不行。原因有三个。第一不同任务的流程差异很大。修一个 typo 和实现一个新功能需要的步骤完全不同。如果用一个统一的大流程简单任务会被过度流程化浪费时间复杂任务又可能覆盖不全。第二粒度太粗会导致上下文膨胀。一个大 skill 文件可能几千行每次都要全量加载进上下文既慢又贵。拆成小 skill 后只加载当前需要的那几个效率高很多。第三小粒度便于组合和替换。你可以把官方的某个 skill 换成自己团队定制的版本而不影响其他环节。这种可插拔性是框架能长期演进的基础。所以 superpowers 的 skill 设计遵循单一职责原则一个 skill 只干一件事比如分析需求生成测试用例规范提交信息。多个 skill 按顺序组合就形成了完整的开发流水线。2.3 与宿主工具的协作边界理解 superpowers 的另一个关键是搞清楚它和 Claude Code、Codex CLI 的分工。宿主工具负责的是底层能力读写文件、执行命令、调用模型、管理会话。superpowers 负责的是上层编排在什么时机、用什么方式去调用这些底层能力。打个比方Claude Code 和 Codex CLI 像是发动机和变速箱superpowers 像是驾驶策略。发动机决定车能跑多快驾驶策略决定车怎么开才省油、才安全。两者缺一不可但职责清晰。这个边界很重要因为它决定了你排查问题的方向。如果 AI 连文件都读不了那是宿主工具的问题如果 AI 能读文件但流程乱套那大概率是 skill 配置的问题。分清楚这两层排障效率会高很多。3. 核心机制拆解skill 是怎么被触发和执行的3.1 skill 的文件结构与元数据一个标准的 skill 通常是一个 Markdown 文件放在约定的目录下。文件头部有一段元数据frontmatter声明这个 skill 的名称、描述、触发条件等。正文部分则是具体的执行指令。元数据里的触发条件是核心。它决定了 AI 在什么情况下会加载这个 skill。触发条件可以基于关键词、任务类型、当前对话状态等多种信号。比如一个代码审查skill可能配置成当用户提到 review、检查、审查或者刚完成一段代码编写时触发。我自己的经验是触发条件不要写得太宽泛。见过有人把触发词写成代码结果几乎每个任务都会命中skill 被反复加载反而干扰了正常流程。触发条件要精准宁可漏触发让用户手动调用也不要滥触发。3.2 执行链路从任务输入到 skill 编排当你在 Claude Code 或 Codex CLI 里输入一个任务superpowers 的编排层会做几件事。首先解析任务意图判断这属于哪类工作。然后根据意图匹配对应的 skill 集合。接着按依赖关系排序决定执行顺序。最后逐个加载 skill把指令注入到当前上下文驱动 AI 执行。这个链路里最容易出问题的是意图解析环节。如果任务描述太模糊比如只说优化一下AI 可能匹配不到合适的 skill或者匹配错。所以我在实际使用中养成了一个习惯任务描述尽量带上动作和对象比如优化用户登录接口的响应时间而不是优化一下。多打几个字能省掉后面一堆来回确认。3.3 上下文管理与 skill 卸载skill 加载进上下文后不是一直留着的。执行完对应阶段编排层会把它卸载释放上下文空间。这个机制对长任务特别重要。一个完整的开发任务可能涉及十几个 skill如果全部堆在上下文里很快就会超出窗口限制。这里有个实操细节skill 的卸载时机要跟任务阶段对齐。如果卸载太早后续步骤可能还需要前面的信息卸载太晚又占着空间。superpowers 默认的策略是按阶段卸载但你可以根据项目情况调整。我在处理大型重构任务时会把需求分析和方案设计这两个 skill 的输出保留得久一点因为后面写代码时经常要回头对照。4. 环境准备Claude Code 与 Codex CLI 的安装配置4.1 Claude Code 的安装路径选择Claude Code 的安装方式有几种我按推荐度排一下。最省事的是用官方提供的安装脚本一条命令搞定。但国内网络环境下直接从官方源拉取可能会遇到超时。这时候有两个思路一是配置镜像源二是手动下载安装包。手动安装的话需要先确认你的运行环境。Claude Code 支持 macOS、Linux 和 Windows通过 WSL。Windows 原生环境的支持一直是个痛点热搜里 windows claude code 的搜索量很高说明踩坑的人不少。我的建议是Windows 用户优先用 WSL2别硬刚原生环境。WSL2 里的 Linux 子系统和 Claude Code 的兼容性最好省去大量折腾。安装完成后用claude --version验证。如果提示找不到命令大概率是 PATH 没配好。检查一下安装目录有没有加到环境变量里。这个坑很常见尤其是手动安装的情况。4.2 Codex CLI 的安装与运行时依赖Codex CLI 的安装相对直接但它对运行时组件有要求。热搜里那条 unable to locate the codex cli binary or required runtime components 是高频报错我专门查过。这个错误通常意味着两种情况要么二进制文件没装到位要么依赖的运行时比如特定版本的 Node.js 或 Python缺失。排查顺序是这样的。先确认二进制文件在不在用which codex或where codex查。如果找不到说明安装没成功重新装。如果找得到但还是报错那就是运行时的问题。检查 Node.js 版本Codex CLI 对版本有下限要求太老的版本会直接报这个错。升级到 LTS 版本基本能解决。Ubuntu 用户注意热搜里 ubuntu codex cli 也是高频词。Ubuntu 上装 Codex CLI建议用包管理器装 Node.js别用系统自带的旧版本。系统自带的 Node 往往版本很低装完 Codex CLI 跑不起来。4.3 两个工具的共存与切换很多人是 Claude Code 和 Codex CLI 都装根据任务切换。这两个工具可以共存不冲突。但要注意配置文件的位置别搞混了。Claude Code 的配置一般在用户目录下的.claude文件夹Codex CLI 有自己的配置目录。superpowers 的 skill 目录需要分别配置到两个工具里或者用软链接指向同一个 skill 仓库这样改一处两边都生效。我自己的做法是维护一个独立的 skill 仓库然后用软链接挂到两个工具的配置目录下。这样我定制 skill 的时候只需要改一个地方两边同步更新。这个技巧在同时用多个 AI 编程工具时特别省事。5. superpowers 的安装与 skill 加载实操5.1 获取 skill 包的几种方式superpowers 的 skill 包获取方式主流的有两种。一种是从官方仓库克隆另一种是手动下载后放到指定目录。官方仓库的方式便于后续更新git pull一下就能拿到最新 skill。手动下载适合网络受限或者想锁定特定版本的情况。克隆的时候注意分支。主分支通常是最新的开发版可能包含未稳定的 skill。如果你追求稳定切到 release 标签对应的提交。我一般会在正式项目里锁定版本避免某天git pull之后 skill 行为变了导致流程突然不按预期走。5.2 skill 目录的配置与验证skill 放对位置是关键。不同宿主工具的 skill 目录约定不一样。Claude Code 有它自己的 skills 目录规范Codex CLI 也有对应的位置。你需要把 skill 文件放到工具能扫描到的目录下。配置完之后怎么验证最简单的办法是启动工具输入一个会触发 skill 的任务看 AI 的行为有没有变化。比如你装了一个提交信息规范的 skill那就做一次代码提交看 AI 生成的 commit message 是不是按规范来的。如果没变化说明 skill 没被加载。验证的时候有个小技巧先只装一个 skill 测试。一次性装一堆出问题了你不知道是哪个 skill 的锅。单个验证通过后再批量装排障成本低很多。5.3 手动安装 GitHub 上的 skill热搜里 claude code怎么手动装github上的skills 这个问题问的人很多。手动装的流程其实不复杂但有几个细节容易漏。第一步是找到 skill 文件。GitHub 上的 skill 通常以.md结尾放在仓库的特定目录里。第二步是下载到本地。可以直接下载文件也可以克隆整个仓库。第三步是放到宿主工具的 skill 目录。第四步是检查元数据格式确保 frontmatter 的字段符合工具要求。最容易出问题的是第四步。不同工具对元数据字段的要求有差异直接拿别的工具的 skill 过来用可能因为字段不匹配而加载失败。遇到这种情况对照官方文档的字段说明改一下就行。6. 把 superpowers 用起来典型工作流拆解6.1 需求分析阶段的 skill 应用一个完整的开发任务从需求分析开始。这个阶段 superpowers 通常会触发需求澄清类的 skill。它的作用是让 AI 主动追问模糊点而不是闷头就写。我实测下来这个 skill 的价值在于把返工提前。以前我描述一个需求AI 直接开写写到一半发现理解偏了推倒重来。现在 AI 会先问几个关键问题比如这个功能的边界条件是什么要不要考虑并发场景。花两分钟回答省掉半小时返工。这里有个使用心得别嫌 AI 问得多。它问的问题往往是你自己也没想清楚的地方。认真回答等于帮自己把需求理了一遍。6.2 方案设计与技术选型需求明确后进入方案设计。这个阶段的 skill 会引导 AI 输出技术方案包括模块划分、接口设计、数据流走向。superpowers 在这里的设计思路是先对齐再动手避免 AI 直接跳到编码。我一般会在这个阶段让 AI 给出两到三个方案然后对比取舍。skill 会提示 AI 说明每个方案的优缺点和适用场景。这个对比过程很有价值有时候 AI 提出的方案是我没想到的角度。技术选型上skill 会要求 AI 说明选型理由而不是随便挑一个库。比如选某个 HTTP 客户端要说明为什么不用另一个。这种强制说理的机制能有效减少 AI 的随意性。6.3 编码实现与增量提交编码阶段是 skill 密度最高的环节。superpowers 会把编码拆成写实现写测试跑验证提交几个子步骤每个子步骤对应一个 skill。增量提交是我最喜欢的一个设计。它要求 AI 每完成一个逻辑单元就提交一次而不是攒一大堆改动最后一起提交。这样做的好处是出问题时容易定位回滚粒度细代码审查也轻松。以前 AI 一口气改十几个文件我 review 的时候头都大了。现在一次改两三个文件看得清楚也敢放心合并。6.4 测试验证与回归检查测试环节的 skill 会驱动 AI 生成测试用例并执行。这里有个细节值得说superpowers 倾向于让 AI 先写测试再写实现也就是测试驱动开发TDD的思路。虽然实际执行中不一定严格遵循但这个倾向本身是有价值的它让 AI 在写代码前先想清楚怎么算写对了。回归检查的 skill 会在改动完成后提示 AI 检查是否影响了其他模块。这个环节以前我经常忘现在有 skill 兜底省心不少。7. 常见问题与排查技巧实录7.1 安装类问题速查问题现象可能原因排查方向提示找不到命令PATH 未配置检查安装目录是否加入环境变量提示运行时组件缺失Node/Python 版本过低升级到 LTS 版本skill 加载失败元数据字段不匹配对照官方文档检查 frontmatter工具启动报错配置文件格式错误检查配置文件的语法网络超时源站访问受限配置镜像源或手动下载这张表是我自己踩坑总结的覆盖了大部分安装阶段的问题。遇到报错先对号入座能省不少搜索时间。7.2 skill 不生效的排查思路skill 装了但没反应是最让人抓狂的问题。我的排查顺序是这样的。先确认 skill 文件确实在正确的目录下用ls看一眼。然后确认文件格式没问题尤其是 frontmatter 的语法YAML 格式对缩进很敏感多一个空格都可能解析失败。接着确认触发条件是否匹配当前任务可以手动构造一个明显会触发的任务测试。最后看工具的日志很多工具会输出 skill 加载的调试信息。如果以上都正常但还是不生效可能是版本兼容问题。宿主工具更新后skill 的接口规范可能变了。这时候要么更新 skill要么回退工具版本。7.3 上下文超限与性能问题用久了会遇到上下文超限的报错尤其是长任务。superpowers 虽然有 skill 卸载机制但如果你的 skill 本身写得太大或者任务链条太长还是可能撑爆。应对办法有几个。一是精简 skill 内容把不必要的历史信息去掉。二是拆分长任务别让一个会话干太多事。三是调整 skill 的保留策略让不活跃的 skill 尽早卸载。我处理大型任务时会主动在阶段之间开新会话把上一阶段的结论带过去而不是让所有上下文堆在一个会话里。7.4 与国内模型的配合使用热搜里 claude code接入deepseek 这类词出现频率很高说明不少人想用国内模型驱动 Claude Code。这个思路是可行的Claude Code 支持配置自定义的模型端点。配置的关键是接口兼容性模型端点要符合工具期望的 API 格式。配置好之后superpowers 的 skill 依然能正常工作因为 skill 层和模型层是解耦的。但要注意不同模型对指令的遵循程度有差异。有些模型对 skill 里的流程指令执行得不够严格可能需要调整 skill 的措辞把要求写得更明确。8. 我踩过的坑和几条实在建议第一个坑是贪多。刚上手时我把能找到的 skill 全装了结果 AI 的行为变得很混乱动不动就触发一堆流程简单任务也要走完整套。后来我精简到只留核心的几个反而顺畅了。skill 不是越多越好够用就行。第二个坑是不改 skill。官方 skill 是通用设计不一定贴合你的项目。我一开始照搬发现有些流程跟我的技术栈对不上。后来我基于官方 skill 改了几个版本把项目特定的规范写进去效果明显提升。skill 是要养的不是装完就不管。第三个坑是忽略版本。有次工具自动更新后skill 突然不生效了。查了半天才发现是接口变了。现在我锁定了工具和 skill 的版本更新前先看 changelog确认兼容再升。最后分享一个实用技巧给 skill 写注释。我在每个自定义 skill 的头部加了一段说明写清楚这个 skill 是干什么的、什么时候触发、改过哪些地方。过几个月回头看能快速想起来当初为什么这么设计。这个习惯在 skill 数量多起来之后特别有用。superpowers 这套框架的价值不在于它有多复杂而在于它把 AI 编程从随机发挥拉到了有章可循。它不会让 AI 变聪明但会让 AI 的输出更稳定、更可预期。对于想把 AI 编程真正用进日常工作流的人来说花点时间理解它的设计逻辑比急着装一堆 skill 更有意义。