1. 从superpowers这个标题说起它到底想解决什么问题第一次看到superpowers这个词很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但结合热搜词里的 agentic skills framework、software development methodology、Claude Code、Codex CLI 这些关键词方向就很清楚了——这是一个围绕 AI 编程助手构建的技能框架核心目标是让 AI 在软件开发流程中真正具备超能力而不是只会补全几行代码。我在实际项目里用 Claude Code 和 Codex CLI 有一段时间了最大的感受是裸用 AI 编程工具和给它装上一套结构化的技能框架完全是两个体验。裸用的时候你得反复解释上下文、手动纠正它的输出格式、每次都要重新交代项目规范而一旦有了 superpowers 这类框架AI 就像被注入了一套工作方法论知道什么时候该先读代码、什么时候该写测试、什么时候该做代码审查。所以这篇内容我想聊的不是superpowers 是什么这种百科式介绍而是一个从业者在真实开发场景里怎么理解、安装、配置并真正用起来这套东西。适合的读者包括刚接触 Claude Code 或 Codex CLI 的新手、想把手里的 AI 助手从玩具变成生产力工具的中级开发者以及正在评估要不要引入 agentic skills framework 的团队技术负责人。需要提前说明的是superpowers 本身是一个方法论层面的框架它不是一个独立的软件而是依附于 Claude Code、Codex CLI 这类 agent 运行环境的一套技能定义与调用机制。理解这一点很关键否则你会在superpowers 安装这一步卡很久找不到一个叫 superpowers 的独立安装包。2. superpowers 的核心机制agentic skills framework 到底在做什么2.1 从提示词到技能的思维转变大多数人用 AI 编程工具的方式是写提示词把需求描述清楚让 AI 生成代码。这种方式在简单任务上没问题但一旦项目复杂起来提示词会变得又长又乱而且每次对话都要重复。superpowers 代表的 agentic skills framework 思路完全不同。它把怎么做某类任务这件事固化成一个可复用的技能单元。比如写一个符合项目规范的 React 组件是一个技能对现有代码做安全审查是另一个技能根据报错信息定位根因又是一个技能。每个技能内部包含了触发条件、执行步骤、输出格式、注意事项。这就像你招了一个新员工。写提示词相当于每次口头交代任务说一遍做一遍而技能框架相当于给这个员工写了一份岗位操作手册他遇到对应场景会自动翻手册执行。后者的一致性和可复用性显然高得多。2.2 技能是怎么被 agent 调用的Claude Code 和 Codex CLI 这类工具的运行逻辑是接收用户输入 → 判断意图 → 选择工具或技能 → 执行 → 返回结果。superpowers 做的事情就是在选择技能这一步提供了更丰富的选项。具体来说技能通常以文件形式存在包含元数据名称、描述、触发关键词和正文执行逻辑。当你的输入匹配到某个技能的触发条件时agent 会加载这个技能的完整内容然后按照里面的步骤执行。这个过程对用户是透明的你只需要说帮我审查这段代码的安全性agent 就会自动调用对应的安全审查技能。提示技能文件的存放位置非常关键。Claude Code 通常读取项目根目录下的特定文件夹Codex CLI 的路径规则又不一样。装完之后第一件事就是确认技能有没有被正确加载否则你会以为框架没生效。2.3 为什么这套框架值得投入时间我算过一笔账在没有技能框架之前我每次让 AI 做代码审查都要花 3-5 分钟写清楚审查维度、输出格式、严重程度分级。有了框架之后这些全部内置我只需要说审查这个文件。按每天审查 5 次算一天省下 20 分钟一个月就是 10 个小时。更重要的是输出质量的一致性。人写提示词会有波动今天心情好写得详细明天赶时间写得潦草AI 的输出质量就跟着波动。技能框架把标准固定下来每次执行都是同一套流程这对团队协作尤其重要——大家用的是同一套技能产出物的风格和标准就统一了。3. 环境准备Claude Code 与 Codex CLI 的安装踩坑记录3.1 Claude Code 安装不同系统的真实体验Claude Code 的安装方式在不同操作系统上差异很大这也是热搜里claude code安装教程ubuntu安装claude codewindows安装claude code反复出现的原因。在 macOS 和 Linux 上最省事的方式是通过包管理器。以 Ubuntu 为例先确认 Node.js 版本不低于 18然后执行全局安装命令。安装完成后用claude --version验证能输出版本号就说明二进制文件已经就位。Windows 用户要注意官方推荐在 WSL2 环境下运行原生 PowerShell 虽然也能装但路径处理和权限问题会多不少。我见过太多人在 Windows 上装完之后发现技能目录读不到最后还是要回到 WSL。# Ubuntu/macOS 下的典型安装流程 node --version # 确认 18 npm install -g anthropic-ai/claude-code claude --version # 验证安装安装完之后还有一个容易忽略的步骤首次运行需要完成认证配置。这一步如果网络环境不稳定会出现各种超时。我的建议是提前把认证信息准备好一次性配置完成避免反复重试。3.2 Codex CLI 安装与unable to locate报错处理Codex CLI 的安装相对直接但热搜里那个 unable to locate the codex cli binary or required runtime components 报错几乎每个新手都会遇到一次。这个报错的本质是系统 PATH 里找不到 codex 的可执行文件或者运行时依赖缺失。排查顺序我总结成三步先确认安装是否真的成功。用which codexLinux/macOS或where codexWindows看能不能定位到二进制文件。如果定位不到检查全局安装目录是否在 PATH 里。npm 全局安装的包通常在~/.npm-global/bin或/usr/local/bin这个路径必须加入环境变量。如果二进制找到了但还报运行时组件缺失多半是 Node.js 版本或某个原生依赖的问题重新安装对应版本即可。# 检查 codex 是否在 PATH 中 which codex # 如果为空手动添加 npm 全局路径 export PATH$PATH:$(npm config get prefix)/bin注意修改 PATH 之后一定要重新打开终端或者执行source ~/.bashrc否则当前会话不会生效。这个细节坑过很多人明明配置对了却一直报错。3.3 版本更新与卸载的干净做法Codex CLI 更新频率不低热搜里codex cli如何更新也是高频问题。更新直接用包管理器的升级命令即可但更新后建议重启一次终端避免旧进程占用。卸载这件事反而更值得说。很多人卸载 Claude Code 之后发现配置目录还在重新安装时旧配置干扰新版本。干净的做法是先卸载包再手动删除配置目录通常在用户主目录下的隐藏文件夹里最后清理 shell 配置里相关的环境变量。4. superpowers 安装与技能加载从零到能用的完整链路4.1 安装前的三个前置检查在动手装 superpowers 之前我建议先做三个检查能省掉后面 80% 的麻烦。第一确认你的 agent 版本支持技能机制。老版本的 Claude Code 或 Codex CLI 可能没有技能加载能力装了也白装。第二确认技能目录的位置。不同工具、不同版本读取的路径可能不同这个必须查清楚。第三确认你有写入权限。技能文件需要放到指定目录权限不足会导致加载失败。4.2 技能文件的组织方式superpowers 的技能通常按功能分类存放。一个典型的目录结构是这样的skills/ code-review/ SKILL.md testing/ SKILL.md debugging/ SKILL.md每个SKILL.md里包含元信息头和正文。元信息头声明技能名称、描述、触发条件正文写具体的执行步骤。这种结构的好处是增删技能不影响其他技能你可以只装自己需要的几个。我个人的做法是先装核心的几个代码审查、测试生成、调试定位用顺了再逐步扩展。一次性装几十个技能反而会让 agent 的选择变慢而且很多技能你根本用不上。4.3 验证技能是否真正生效装完之后怎么确认技能生效了最直接的方法是触发一次技能调用。比如你装了一个代码审查技能就随便找个文件说帮我审查这个文件的潜在问题看 agent 的回复里有没有体现出技能定义的审查维度。如果 agent 的回复和平时没区别说明技能没加载。这时候按顺序排查技能目录路径对不对、文件格式是否符合要求、元信息头有没有语法错误。我遇到过最常见的问题是元信息头的格式写错了比如缺少必要的字段或者缩进不对导致整个技能被静默忽略。5. 把 superpowers 用进真实开发流程几个高频场景5.1 代码审查场景的实战配置代码审查是我用得最多的场景。配置好技能之后我的工作流变成写完一个模块 → 让 agent 用审查技能过一遍 → 根据输出修改 → 提交。审查技能里我重点配置了几个维度安全性有没有注入风险、敏感信息泄露、性能有没有明显的低效写法、可维护性命名、注释、函数长度、一致性是否符合项目既有风格。这四个维度覆盖了日常审查的绝大部分需求。实测下来AI 审查能抓住大约 70% 的明显问题剩下 30% 需要人工判断主要是业务逻辑层面的。所以我的定位是AI 做第一遍粗筛人做第二遍精审效率比纯人工高很多。5.2 调试定位场景让 agent 学会先看再猜调试是另一个价值很高的场景。传统做法是把报错信息丢给 AI让它猜原因。但 superpowers 的调试技能会强制 agent先读相关代码、再看日志、最后才给假设这个顺序很重要。我配置的调试技能里有一条硬性规则在给出任何修复建议之前必须先列出至少三个可能的原因并说明每个原因对应的验证方法。这条规则逼着 agent 做系统性思考而不是张口就给一个可能完全错误的答案。5.3 测试生成场景的边界控制测试生成技能要特别小心配置因为 AI 很容易生成一堆看起来对但实际没测到点子上的测试。我的做法是在技能里明确要求每个测试用例必须对应一个具体的边界条件或业务规则并且要说明这个用例在验证什么。另外测试技能里我会加一条生成的测试必须先跑一遍确认能通过再交付。这条规则能过滤掉大量语法正确但逻辑错误的测试代码。6. 常见问题排查那些让人抓狂的报错6.1 技能不生效的排查链路技能不生效是最常见的问题排查链路我整理成一张表现象可能原因排查方法agent 完全无视技能目录路径错误确认工具读取的技能目录位置部分技能生效部分不生效单个技能文件格式错误逐个检查元信息头技能加载但行为异常技能内容逻辑有冲突检查是否有重复触发的技能重启后技能消失目录被清理或权限问题检查目录持久性和权限排查的时候一定要一次只改一个变量改完立刻验证。同时改多个地方出问题了你根本不知道是哪个改动导致的。6.2 网络与环境导致的安装失败安装类问题里网络因素占很大比例。表现是下载卡住、认证超时、依赖拉取失败。这类问题的处理原则是先确认网络连通性再确认镜像源配置最后才怀疑工具本身。我一般会先用一个简单的网络请求测试连通性如果基础连通都有问题那后面所有步骤都白搭。如果连通正常但下载慢就检查包管理器有没有配置合适的镜像源。6.3 版本不兼容的典型表现版本不兼容的表现很隐蔽通常是功能时好时坏或者某个技能突然不认了。遇到这种情况第一反应应该是核对 agent 版本和技能框架要求的版本。我的习惯是升级 agent 之前先备份技能目录升级之后立刻跑一遍核心技能验证。如果发现不兼容可以快速回滚不至于影响正常工作。7. 我踩过的坑和总结出的几条经验先说几个具体的坑。第一个是技能目录放错位置我一开始把技能放在了项目目录下结果换个项目就找不到了。后来改成放在用户主目录的全局配置里所有项目都能用。第二个是技能写得过于宽泛。我早期写了一个帮我优化代码的技能触发条件太宽导致 agent 动不动就调用它反而干扰了正常对话。后来把触发条件收窄到具体场景问题就解决了。第三个是忽略技能之间的冲突。有两个技能都能处理代码问题结果 agent 不知道该用哪个行为变得不稳定。解决办法是给每个技能划定清晰的职责边界避免重叠。几条经验技能宁少勿多先把核心几个用熟技能内容要具体避免模糊描述每次改动技能后都要验证不要攒一堆改动一起测团队协作时把技能目录纳入版本管理保证大家用的是同一套。最后分享一个我觉得很实用的小技巧给每个技能写一个最小验证用例就是一句能触发这个技能的典型输入。改完技能之后用这个用例快速验证比漫无目的地测试高效得多。这个习惯帮我省了大量调试时间。这套东西的价值不在于它有多复杂而在于它把 AI 编程从每次重新教变成了一次配置长期复用。真正用起来之后你会发现省下的不只是时间还有反复解释上下文的心力。 Superpowers 技能框架实战：Claude Code 与 Codex CLI 安装配置指南
1. 从superpowers这个标题说起它到底想解决什么问题第一次看到superpowers这个词很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但结合热搜词里的 agentic skills framework、software development methodology、Claude Code、Codex CLI 这些关键词方向就很清楚了——这是一个围绕 AI 编程助手构建的技能框架核心目标是让 AI 在软件开发流程中真正具备超能力而不是只会补全几行代码。我在实际项目里用 Claude Code 和 Codex CLI 有一段时间了最大的感受是裸用 AI 编程工具和给它装上一套结构化的技能框架完全是两个体验。裸用的时候你得反复解释上下文、手动纠正它的输出格式、每次都要重新交代项目规范而一旦有了 superpowers 这类框架AI 就像被注入了一套工作方法论知道什么时候该先读代码、什么时候该写测试、什么时候该做代码审查。所以这篇内容我想聊的不是superpowers 是什么这种百科式介绍而是一个从业者在真实开发场景里怎么理解、安装、配置并真正用起来这套东西。适合的读者包括刚接触 Claude Code 或 Codex CLI 的新手、想把手里的 AI 助手从玩具变成生产力工具的中级开发者以及正在评估要不要引入 agentic skills framework 的团队技术负责人。需要提前说明的是superpowers 本身是一个方法论层面的框架它不是一个独立的软件而是依附于 Claude Code、Codex CLI 这类 agent 运行环境的一套技能定义与调用机制。理解这一点很关键否则你会在superpowers 安装这一步卡很久找不到一个叫 superpowers 的独立安装包。2. superpowers 的核心机制agentic skills framework 到底在做什么2.1 从提示词到技能的思维转变大多数人用 AI 编程工具的方式是写提示词把需求描述清楚让 AI 生成代码。这种方式在简单任务上没问题但一旦项目复杂起来提示词会变得又长又乱而且每次对话都要重复。superpowers 代表的 agentic skills framework 思路完全不同。它把怎么做某类任务这件事固化成一个可复用的技能单元。比如写一个符合项目规范的 React 组件是一个技能对现有代码做安全审查是另一个技能根据报错信息定位根因又是一个技能。每个技能内部包含了触发条件、执行步骤、输出格式、注意事项。这就像你招了一个新员工。写提示词相当于每次口头交代任务说一遍做一遍而技能框架相当于给这个员工写了一份岗位操作手册他遇到对应场景会自动翻手册执行。后者的一致性和可复用性显然高得多。2.2 技能是怎么被 agent 调用的Claude Code 和 Codex CLI 这类工具的运行逻辑是接收用户输入 → 判断意图 → 选择工具或技能 → 执行 → 返回结果。superpowers 做的事情就是在选择技能这一步提供了更丰富的选项。具体来说技能通常以文件形式存在包含元数据名称、描述、触发关键词和正文执行逻辑。当你的输入匹配到某个技能的触发条件时agent 会加载这个技能的完整内容然后按照里面的步骤执行。这个过程对用户是透明的你只需要说帮我审查这段代码的安全性agent 就会自动调用对应的安全审查技能。提示技能文件的存放位置非常关键。Claude Code 通常读取项目根目录下的特定文件夹Codex CLI 的路径规则又不一样。装完之后第一件事就是确认技能有没有被正确加载否则你会以为框架没生效。2.3 为什么这套框架值得投入时间我算过一笔账在没有技能框架之前我每次让 AI 做代码审查都要花 3-5 分钟写清楚审查维度、输出格式、严重程度分级。有了框架之后这些全部内置我只需要说审查这个文件。按每天审查 5 次算一天省下 20 分钟一个月就是 10 个小时。更重要的是输出质量的一致性。人写提示词会有波动今天心情好写得详细明天赶时间写得潦草AI 的输出质量就跟着波动。技能框架把标准固定下来每次执行都是同一套流程这对团队协作尤其重要——大家用的是同一套技能产出物的风格和标准就统一了。3. 环境准备Claude Code 与 Codex CLI 的安装踩坑记录3.1 Claude Code 安装不同系统的真实体验Claude Code 的安装方式在不同操作系统上差异很大这也是热搜里claude code安装教程ubuntu安装claude codewindows安装claude code反复出现的原因。在 macOS 和 Linux 上最省事的方式是通过包管理器。以 Ubuntu 为例先确认 Node.js 版本不低于 18然后执行全局安装命令。安装完成后用claude --version验证能输出版本号就说明二进制文件已经就位。Windows 用户要注意官方推荐在 WSL2 环境下运行原生 PowerShell 虽然也能装但路径处理和权限问题会多不少。我见过太多人在 Windows 上装完之后发现技能目录读不到最后还是要回到 WSL。# Ubuntu/macOS 下的典型安装流程 node --version # 确认 18 npm install -g anthropic-ai/claude-code claude --version # 验证安装安装完之后还有一个容易忽略的步骤首次运行需要完成认证配置。这一步如果网络环境不稳定会出现各种超时。我的建议是提前把认证信息准备好一次性配置完成避免反复重试。3.2 Codex CLI 安装与unable to locate报错处理Codex CLI 的安装相对直接但热搜里那个 unable to locate the codex cli binary or required runtime components 报错几乎每个新手都会遇到一次。这个报错的本质是系统 PATH 里找不到 codex 的可执行文件或者运行时依赖缺失。排查顺序我总结成三步先确认安装是否真的成功。用which codexLinux/macOS或where codexWindows看能不能定位到二进制文件。如果定位不到检查全局安装目录是否在 PATH 里。npm 全局安装的包通常在~/.npm-global/bin或/usr/local/bin这个路径必须加入环境变量。如果二进制找到了但还报运行时组件缺失多半是 Node.js 版本或某个原生依赖的问题重新安装对应版本即可。# 检查 codex 是否在 PATH 中 which codex # 如果为空手动添加 npm 全局路径 export PATH$PATH:$(npm config get prefix)/bin注意修改 PATH 之后一定要重新打开终端或者执行source ~/.bashrc否则当前会话不会生效。这个细节坑过很多人明明配置对了却一直报错。3.3 版本更新与卸载的干净做法Codex CLI 更新频率不低热搜里codex cli如何更新也是高频问题。更新直接用包管理器的升级命令即可但更新后建议重启一次终端避免旧进程占用。卸载这件事反而更值得说。很多人卸载 Claude Code 之后发现配置目录还在重新安装时旧配置干扰新版本。干净的做法是先卸载包再手动删除配置目录通常在用户主目录下的隐藏文件夹里最后清理 shell 配置里相关的环境变量。4. superpowers 安装与技能加载从零到能用的完整链路4.1 安装前的三个前置检查在动手装 superpowers 之前我建议先做三个检查能省掉后面 80% 的麻烦。第一确认你的 agent 版本支持技能机制。老版本的 Claude Code 或 Codex CLI 可能没有技能加载能力装了也白装。第二确认技能目录的位置。不同工具、不同版本读取的路径可能不同这个必须查清楚。第三确认你有写入权限。技能文件需要放到指定目录权限不足会导致加载失败。4.2 技能文件的组织方式superpowers 的技能通常按功能分类存放。一个典型的目录结构是这样的skills/ code-review/ SKILL.md testing/ SKILL.md debugging/ SKILL.md每个SKILL.md里包含元信息头和正文。元信息头声明技能名称、描述、触发条件正文写具体的执行步骤。这种结构的好处是增删技能不影响其他技能你可以只装自己需要的几个。我个人的做法是先装核心的几个代码审查、测试生成、调试定位用顺了再逐步扩展。一次性装几十个技能反而会让 agent 的选择变慢而且很多技能你根本用不上。4.3 验证技能是否真正生效装完之后怎么确认技能生效了最直接的方法是触发一次技能调用。比如你装了一个代码审查技能就随便找个文件说帮我审查这个文件的潜在问题看 agent 的回复里有没有体现出技能定义的审查维度。如果 agent 的回复和平时没区别说明技能没加载。这时候按顺序排查技能目录路径对不对、文件格式是否符合要求、元信息头有没有语法错误。我遇到过最常见的问题是元信息头的格式写错了比如缺少必要的字段或者缩进不对导致整个技能被静默忽略。5. 把 superpowers 用进真实开发流程几个高频场景5.1 代码审查场景的实战配置代码审查是我用得最多的场景。配置好技能之后我的工作流变成写完一个模块 → 让 agent 用审查技能过一遍 → 根据输出修改 → 提交。审查技能里我重点配置了几个维度安全性有没有注入风险、敏感信息泄露、性能有没有明显的低效写法、可维护性命名、注释、函数长度、一致性是否符合项目既有风格。这四个维度覆盖了日常审查的绝大部分需求。实测下来AI 审查能抓住大约 70% 的明显问题剩下 30% 需要人工判断主要是业务逻辑层面的。所以我的定位是AI 做第一遍粗筛人做第二遍精审效率比纯人工高很多。5.2 调试定位场景让 agent 学会先看再猜调试是另一个价值很高的场景。传统做法是把报错信息丢给 AI让它猜原因。但 superpowers 的调试技能会强制 agent先读相关代码、再看日志、最后才给假设这个顺序很重要。我配置的调试技能里有一条硬性规则在给出任何修复建议之前必须先列出至少三个可能的原因并说明每个原因对应的验证方法。这条规则逼着 agent 做系统性思考而不是张口就给一个可能完全错误的答案。5.3 测试生成场景的边界控制测试生成技能要特别小心配置因为 AI 很容易生成一堆看起来对但实际没测到点子上的测试。我的做法是在技能里明确要求每个测试用例必须对应一个具体的边界条件或业务规则并且要说明这个用例在验证什么。另外测试技能里我会加一条生成的测试必须先跑一遍确认能通过再交付。这条规则能过滤掉大量语法正确但逻辑错误的测试代码。6. 常见问题排查那些让人抓狂的报错6.1 技能不生效的排查链路技能不生效是最常见的问题排查链路我整理成一张表现象可能原因排查方法agent 完全无视技能目录路径错误确认工具读取的技能目录位置部分技能生效部分不生效单个技能文件格式错误逐个检查元信息头技能加载但行为异常技能内容逻辑有冲突检查是否有重复触发的技能重启后技能消失目录被清理或权限问题检查目录持久性和权限排查的时候一定要一次只改一个变量改完立刻验证。同时改多个地方出问题了你根本不知道是哪个改动导致的。6.2 网络与环境导致的安装失败安装类问题里网络因素占很大比例。表现是下载卡住、认证超时、依赖拉取失败。这类问题的处理原则是先确认网络连通性再确认镜像源配置最后才怀疑工具本身。我一般会先用一个简单的网络请求测试连通性如果基础连通都有问题那后面所有步骤都白搭。如果连通正常但下载慢就检查包管理器有没有配置合适的镜像源。6.3 版本不兼容的典型表现版本不兼容的表现很隐蔽通常是功能时好时坏或者某个技能突然不认了。遇到这种情况第一反应应该是核对 agent 版本和技能框架要求的版本。我的习惯是升级 agent 之前先备份技能目录升级之后立刻跑一遍核心技能验证。如果发现不兼容可以快速回滚不至于影响正常工作。7. 我踩过的坑和总结出的几条经验先说几个具体的坑。第一个是技能目录放错位置我一开始把技能放在了项目目录下结果换个项目就找不到了。后来改成放在用户主目录的全局配置里所有项目都能用。第二个是技能写得过于宽泛。我早期写了一个帮我优化代码的技能触发条件太宽导致 agent 动不动就调用它反而干扰了正常对话。后来把触发条件收窄到具体场景问题就解决了。第三个是忽略技能之间的冲突。有两个技能都能处理代码问题结果 agent 不知道该用哪个行为变得不稳定。解决办法是给每个技能划定清晰的职责边界避免重叠。几条经验技能宁少勿多先把核心几个用熟技能内容要具体避免模糊描述每次改动技能后都要验证不要攒一堆改动一起测团队协作时把技能目录纳入版本管理保证大家用的是同一套。最后分享一个我觉得很实用的小技巧给每个技能写一个最小验证用例就是一句能触发这个技能的典型输入。改完技能之后用这个用例快速验证比漫无目的地测试高效得多。这个习惯帮我省了大量调试时间。这套东西的价值不在于它有多复杂而在于它把 AI 编程从每次重新教变成了一次配置长期复用。真正用起来之后你会发现省下的不只是时间还有反复解释上下文的心力。