1. 从“superpowers”说起这套技能框架到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个超级英雄题材的游戏或者插件。但如果你最近在折腾 Claude Code、Codex CLI 这类命令行 AI 编程工具大概率已经在各种社区里刷到过它。简单说superpowers 是一套面向 AI 编程代理agentic coding的技能框架和方法论集合它把“怎么让 AI 更靠谱地写代码”这件事从零散的提示词技巧沉淀成了一套可复用、可组合、可版本管理的技能包。我自己的理解是它更像是一本“给 AI 代理看的操作手册 工具箱”。你平时用 Claude Code 或者 Codex CLI默认状态下 AI 是“裸奔”的——它有能力但不知道你的项目规范、不知道你团队的代码风格、不知道你踩过哪些坑。superpowers 做的事情就是把这些隐性知识显性化变成一个个独立的 skill技能让 AI 在需要的时候自动加载、按需调用。这套东西能干什么举几个我实际用下来的场景。第一统一代码规范。你可以在 skill 里写清楚“这个项目用 4 空格缩进、函数必须写 JSDoc、禁止使用 any 类型”AI 每次生成代码都会遵守。第二固化工作流。比如“改完代码必须跑 lint、必须更新 CHANGELOG、必须写单元测试”这些步骤可以写成一个 skillAI 执行任务时会自动走完流程。第三沉淀领域知识。比如你公司内部有一套特殊的部署流程、有一套自研的 SDK这些文档丢给 AI 它记不住但写成 skill 就能随时调用。适合谁来参考我觉得有三类人最值得花时间研究。一是重度使用 Claude Code / Codex CLI 的开发者你已经在用这些工具写代码了superpowers 能让你的效率再上一个台阶。二是团队技术负责人你想让团队里所有人用 AI 写出来的代码风格一致、质量可控这套框架提供了一个很好的抓手。三是对 agentic skills framework 感兴趣的技术爱好者想搞清楚“AI 代理的技能系统”到底是怎么设计的superpowers 是一个非常好的学习样本。需要提前说明的是superpowers 本身不是一个独立的软件它更像是依附于 Claude Code、Codex CLI 这类宿主工具的扩展层。所以你在安装和使用它之前得先把宿主环境搭好。这也是为什么热词里会出现大量“claude code 安装”“codex cli 安装”“superpowers 安装”这类搜索——大家卡的第一步往往不是 superpowers 本身而是它依赖的那些命令行工具。2. 核心概念拆解skill、agent 与宿主工具的关系2.1 什么是 skill它和普通提示词有什么区别很多人第一次接触 skill 这个概念会懵这不就是提示词吗我直接写在对话里不行吗区别其实挺大的。普通提示词是一次性的、临时的你这次对话说了下次开新会话就没了。而 skill 是持久化的、结构化的、可被检索的。它通常以文件形式存在磁盘上有固定的目录结构包含元数据名称、描述、触发条件和正文内容具体的指令、示例、约束。打个比方普通提示词像是你临时跟同事口头交代一件事说完就完了。skill 像是你写了一份 SOP 文档放在共享盘里任何人任何时候需要都能翻出来看。superpowers 的核心价值就是提供了一套组织和管理这些 SOP 的规范让 AI 代理能够自动判断“现在该用哪个 skill”。从技术实现角度看一个典型的 skill 通常包含这几部分name技能名称用于检索、description什么时候该用这个技能这段描述很关键AI 靠它来判断触发时机、content具体的指令正文。有些实现还会支持examples示例输入输出、constraints硬性约束、dependencies依赖的其他 skill。2.2 agentic skills framework 的设计哲学“agentic”这个词是关键。传统的 AI 使用方式是“你问我答”你给一个指令AI 给一个结果结束。而 agentic 模式下AI 是有自主性的——它会自己规划步骤、自己决定调用哪些工具、自己判断任务是否完成。这种模式下skill 的作用就变得非常重要因为 AI 需要知道“我有哪些能力可用”“什么情况下该用哪个能力”。superpowers 这套框架的设计哲学我总结下来有三条。第一条是关注点分离每个 skill 只做一件事不要把“写代码”和“跑测试”和“提交 git”混在一个 skill 里。第二条是显式优于隐式AI 该做什么、不该做什么都要写清楚不要指望它“猜”。第三条是可组合小的 skill 可以组合成大的工作流就像乐高积木一样。这三条听起来简单但实际落地的时候很容易走偏。我见过有人把所有规范塞进一个巨大的 skill 文件里结果 AI 加载的时候上下文爆炸反而效果变差。也见过有人写得太抽象AI 根本不知道什么时候该触发。这些坑后面会详细讲。2.3 Claude Code 与 Codex CLI 在其中的角色Claude Code 和 Codex CLI 是两类不同的宿主工具但它们在 superpowers 生态里扮演的角色类似——都是skill 的运行容器。Claude Code 是 Anthropic 推出的命令行编程助手Codex CLI 是 OpenAI 系的命令行工具。两者都支持加载外部 skill只是加载机制和配置方式略有差异。这里要提醒一句热词里出现了“claude code might not be available in your country”这类提示这是工具本身的区域可用性问题跟 superpowers 无关。你在安装宿主工具时如果遇到这类提示属于正常现象具体怎么处理不在本文讨论范围建议查阅工具官方文档。从使用体验上对比Claude Code 的 skill 加载机制相对成熟一些社区里分享的 skill 也更多。Codex CLI 相对新一些但胜在和 OpenAI 生态的整合更紧密。如果你两个都在用superpowers 的 skill 大部分是可以通用的只需要注意路径配置和触发语法的差异。3. 环境准备宿主工具安装与常见卡点3.1 Claude Code 安装的几条路径安装 Claude Code 这件事说简单也简单说坑也多。官方推荐的方式是通过 npm 全局安装命令大概是npm install -g anthropic-ai/claude-code这种形式。但实际执行的时候你会遇到几个典型问题。第一个是Node.js 版本问题。Claude Code 对 Node 版本有要求太老的版本会报错。我建议直接用 nvm 或者 fnm 管理 Node 版本装一个 LTS 版本比如 20.x 或 22.x省得折腾。第二个是权限问题在 Linux 和 macOS 上全局安装可能需要 sudo但用 sudo 装又会导致后续权限混乱。我的做法是配置 npm 的全局目录到用户目录下避免 sudo。# 配置 npm 全局目录到用户目录 mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加到 PATH 里 export PATH~/.npm-global/bin:$PATH第三个是网络问题。这个不多说懂的都懂反正安装过程中如果卡住先检查网络连通性。Windows 用户额外注意建议在 WSL2 里装原生 Windows 环境下有些依赖会出问题。热词里“windows 安装 claude code”“windows claude code cc-connect 飞书”这些搜索说明 Windows 用户的踩坑率确实高。Ubuntu 用户的话流程相对顺畅ubuntu 安装 claude code这个搜索词下的方案基本都可用。装完之后用claude --version验证一下能输出版本号就说明装好了。3.2 Codex CLI 安装与“unable to locate”报错处理Codex CLI 的安装热词里有个很具体的报错“unable to locate the codex cli binary or required runtime components. check”。这个报错我遇到过本质上是宿主工具找不到 codex 的可执行文件或者运行时依赖。排查思路分三步。第一步确认 codex 是否真的装上了。在终端里直接敲codex --version如果提示 command not found那就是没装成功或者没加到 PATH。第二步如果命令能跑但宿主工具报这个错那大概率是路径配置问题——宿主工具用的是自己的 PATH 环境跟你终端里的不一样。这时候需要在宿主工具的配置里显式指定 codex 的绝对路径。第三步如果路径也对那就检查运行时组件比如 Python 版本、Node 版本是否满足要求。# 查找 codex 的实际安装位置 which codex # 或者 whereis codex # 拿到绝对路径后写进宿主工具配置Windows 上安装 codex cli 的话热词里“codex cli windows 安装”也是高频搜索。我的建议还是 WSL2原生 Windows 下路径分隔符、权限模型都不一样容易出玄学问题。如果非要在原生 Windows 下跑注意把 codex 的安装目录加到系统环境变量 PATH 里然后重启终端。3.3 superpowers 安装的正确姿势宿主工具装好之后superpowers 的安装反而简单了。它的本质是把 skill 文件放到宿主工具能识别的目录下。不同宿主工具的 skill 目录不一样Claude Code 通常在~/.claude/skills/或者项目根目录的.claude/skills/下Codex CLI 类似。安装方式一般有两种。一种是从 GitHub 上 clone 整个 superpowers 仓库然后把 skills 目录拷贝或者软链接到宿主工具的 skill 目录。另一种是用包管理器安装如果 superpowers 发布了 npm 包或者 pip 包的话。我推荐第一种因为软链接方式方便更新——你 git pull 一下所有 skill 自动更新不用重新拷贝。# 假设 superpowers 仓库 clone 到了 ~/superpowers # 创建软链接到 Claude Code 的 skill 目录 ln -s ~/superpowers/skills ~/.claude/skills/superpowers这里有个细节要注意skill 目录的层级结构。有些宿主工具要求 skill 必须放在特定层级的子目录里比如skills/skill-name/SKILL.md这种结构。你如果直接把一堆 md 文件平铺在 skills 目录下可能识别不了。安装前先看一眼宿主工具的文档确认目录规范。4. 实操从零搭建一套可用的 skill 工作流4.1 第一个 skill从“代码规范检查”开始理论说再多不如动手写一个。我建议第一个 skill 从代码规范检查入手因为需求明确、效果直观、不容易翻车。假设你的项目是 Java 项目你想让 AI 每次生成代码都遵守团队的规范。先创建目录结构~/.claude/skills/ └── java-code-style/ └── SKILL.md然后写 SKILL.md 的内容。这里的关键是description 字段它决定了 AI 什么时候会触发这个 skill。写得太宽泛AI 动不动就加载浪费上下文写得太窄该用的时候用不上。--- name: java-code-style description: 当需要编写、修改或审查 Java 代码时使用。适用于所有 .java 文件的生成和编辑场景。 --- # Java 代码规范 ## 缩进与格式 - 使用 4 空格缩进禁止使用 Tab - 每行不超过 120 个字符 - 左大括号不换行 ## 命名规范 - 类名用 UpperCamelCase - 方法名和变量名用 lowerCamelCase - 常量用 UPPER_SNAKE_CASE ## 注释要求 - 所有 public 方法必须写 Javadoc - 复杂逻辑必须写行内注释说明意图 ## 禁止事项 - 禁止使用魔法数字必须定义为常量 - 禁止空的 catch 块 - 禁止使用 System.out.println 做日志必须用日志框架写完保存然后在 Claude Code 里开一个新会话让它写一段 Java 代码观察它是否遵守了这些规范。如果没触发检查 description 是不是写得太抽象试着加上更具体的关键词。4.2 skill 的触发机制与调试方法skill 不触发是新手最常见的问题。排查思路我整理成一个表现象可能原因排查方法完全不触发description 不匹配检查 description 是否包含任务相关的关键词偶尔触发触发条件太模糊收窄 description 的适用范围触发但内容没生效文件格式错误检查 frontmatter 的 YAML 语法加载报错目录结构不对确认 SKILL.md 的路径层级上下文爆炸skill 内容太长拆分 skill或精简内容调试的时候有个技巧在对话里直接问 AI“你现在加载了哪些 skill”。有些宿主工具会返回当前激活的 skill 列表这样你就能确认 skill 到底有没有被识别。另外很多宿主工具支持手动触发 skill比如用/skill java-code-style这种命令调试阶段可以先用手动触发验证内容是否正确再排查自动触发的问题。4.3 组合多个 skill 构建完整工作流单个 skill 只是开始superpowers 真正的威力在于组合。举个实际例子我给自己搭的一套“功能开发工作流”包含四个 skillrequirement-analysis接到需求时先让 AI 分析需求、列出验收标准code-implementation根据需求写代码遵守代码规范test-generation为新增代码生成单元测试changelog-update更新 CHANGELOG 文件这四个 skill 可以串起来用。我在 Claude Code 里下指令“实现 XXX 功能”AI 会先触发 requirement-analysis 分析需求然后触发 code-implementation 写代码接着触发 test-generation 写测试最后触发 changelog-update 更新日志。整个过程我只需要在关键节点确认一下剩下的它自己走完。这里的关键是skill 之间的衔接。每个 skill 的结尾要写清楚“完成后应该做什么”引导 AI 进入下一个 skill。比如 requirement-analysis 的结尾可以写“分析完成后如果用户确认需求无误进入代码实现阶段”。这种显式的引导比指望 AI 自己判断要靠谱得多。5. 进阶玩法让 skill 真正融入日常开发5.1 项目级 skill 与全局 skill 的取舍skill 可以放在两个位置全局目录比如~/.claude/skills/和项目目录比如project/.claude/skills/。这两者的区别很重要。全局 skill 对所有项目生效适合放通用的、跨项目的规范比如“Git 提交信息格式”“通用代码风格”。项目级 skill 只对当前项目生效适合放项目特有的知识比如“这个项目的部署流程”“这个项目用的自研框架的用法”。我的经验是通用规范放全局项目知识放项目级。但要注意项目级 skill 如果提交到 git 仓库团队其他人 clone 下来就能直接用这是团队协作的好方式。不过要小心别把敏感信息比如内部 API 密钥、服务器地址写进 skill 里这些应该用环境变量或者单独的配置文件管理。5.2 用 skill 固化团队协作规范团队场景下superpowers 的价值会被放大。我帮一个团队搭过一套 skill效果挺明显。他们的痛点是团队里有人用 AI 写代码有人不用导致代码风格不统一review 的时候经常为格式问题吵架。我们的做法是把团队的代码规范、review checklist、提交信息格式全部写成 skill放在项目仓库的.claude/skills/目录下。然后要求所有人用 Claude Code 或 Codex CLI 写代码时必须加载这些 skill。这样一来不管是谁用 AI 生成的代码风格都是一致的review 的时候只需要关注逻辑不用纠结格式。这里有个实操细节skill 的版本管理。skill 文件本身也是代码应该走 git 流程。修改 skill 要提 PR要 review要有变更记录。我见过有团队把 skill 改得乱七八糟最后没人知道哪个版本是对的。把 skill 当代码管理这个问题就解决了。5.3 与现有工具链的集成思路superpowers 不是孤立的它可以和现有工具链集成。几个我试过有效的方向和 lint 工具集成。skill 里可以写“生成代码后自动运行 eslint/checkstyle如果有报错就修复”。这样 AI 写完代码会自己跑一遍 lint把低级错误消灭在提交之前。和测试框架集成。skill 里写“新增函数必须配套单元测试测试覆盖率不低于 80%”。AI 写代码的时候会顺手把测试写了省得你后面补。和 CI/CD 集成。这个稍微复杂一点思路是在 CI 流程里加一步检查 AI 生成的代码是否符合 skill 里定义的规范。不符合就 fail倒逼大家把 skill 写好。和 IDE 集成。热词里“vscode 配置 claude code”“vscode 安装 claude code”说明很多人想在 VSCode 里用。Claude Code 有 VSCode 插件装完之后可以在编辑器里直接调用。skill 的加载机制和命令行版本一致配置好目录就行。6. 常见问题与避坑指南6.1 安装类问题速查问题原因解决方案unable to locate the codex cli binaryPATH 未配置或路径错误用which codex找绝对路径写进宿主配置Claude Code 安装后命令找不到npm 全局目录不在 PATH配置 npm prefix 并加到 PATHWindows 下安装失败原生环境依赖问题改用 WSL2skill 目录不识别目录层级不对确认skills/name/SKILL.md结构安装后 AI 不加载 skilldescription 不匹配检查触发关键词手动触发测试6.2 使用类问题与排查思路skill 内容太长导致上下文爆炸。这是最常见的问题。一个 skill 写了几千字AI 加载后上下文被占满反而影响正常对话。解决办法是拆分把大 skill 拆成多个小 skill按需加载。单个 skill 建议控制在 500 字以内超过就考虑拆。skill 之间冲突。两个 skill 给了矛盾的指令AI 会懵。比如一个 skill 说“用 4 空格缩进”另一个说“用 2 空格缩进”。排查方法是逐个禁用 skill 测试找到冲突的两个然后合并或者明确优先级。AI 不遵守 skill 里的约束。这个要分情况。如果是软约束比如“建议写注释”AI 可能忽略如果是硬约束比如“禁止使用某 API”AI 通常会遵守。如果硬约束也不遵守检查 skill 的措辞是不是太委婉改成“必须”“禁止”这种强指令。skill 更新后不生效。宿主工具通常有缓存机制skill 改了但 AI 还在用旧版本。解决办法是重启宿主工具或者找找有没有清除缓存的命令。有些工具支持热重载改完自动生效这个要看具体实现。6.3 我踩过的几个坑第一个坑skill 写得太抽象。我一开始写了个“写高质量代码”的 skill结果 AI 完全不知道该怎么执行。后来改成具体的“函数不超过 50 行、圈复杂度不超过 10、必须有错误处理”效果立刻好了。skill 要具体到可执行不能是口号。第二个坑skill 目录用软链接但宿主工具不跟随。有些工具解析软链接有问题导致 skill 加载不了。解决办法是改用硬链接或者直接拷贝文件但这样更新麻烦。我最后是写了个脚本git pull 之后自动同步文件到 skill 目录。第三个坑在 skill 里写了敏感信息。有一次我把内部服务器的地址写进了 skill结果提交到了公开仓库。虽然及时删了但也是个教训。skill 里只放规范和方法不放配置和密钥。第四个坑过度依赖 skill。有段时间我把所有东西都往 skill 里塞结果 AI 每次对话要加载十几个 skill响应变慢效果也变差。后来我学会了克制只把真正高频、真正重要的规范写成 skill其他的靠对话临时说明就行。7. 关于这套框架的一些个人体会用 superpowers 这套东西大半年下来我最大的感受是它改变的不是 AI 的能力而是你和 AI 协作的方式。以前你用 AI 写代码像是在指挥一个能力很强但完全不了解你项目的临时工你得反复交代各种细节。现在有了 skill你像是在带一个已经熟悉项目规范的老员工交代任务的时候只需要说“做什么”不用反复说“怎么做”。另一个体会是skill 的质量比数量重要得多。我见过有人收集了几百个 skill但真正用起来的没几个。与其贪多不如把三五个核心 skill 打磨好让它们真正融入你的日常流程。一个写得好的 skill价值超过一百个写得烂的。还有一点skill 是需要迭代的。你第一次写的 skill 肯定不完美用着用着会发现各种问题。这时候别嫌麻烦改就是了。我的几个核心 skill 都改了十几版每次改完效果都好一点。把 skill 当成一个持续演进的产品而不是一次性的配置。最后说个实际的如果你刚开始接触别一上来就搞复杂的多 skill 工作流。先从一个最简单的 skill开始比如代码格式规范跑通了、用顺了再逐步加。这套框架的学习曲线不算陡但需要你花时间理解它的设计思路。理解了之后你会发现它能做的事情比想象中多。 
长河君 · 2026/11/4 15:17:00 · 阅读 1.2k Superpowers 技能框架：让 Claude Code 与 Codex CLI 更靠谱地写代码
1. 从“superpowers”说起这套技能框架到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个超级英雄题材的游戏或者插件。但如果你最近在折腾 Claude Code、Codex CLI 这类命令行 AI 编程工具大概率已经在各种社区里刷到过它。简单说superpowers 是一套面向 AI 编程代理agentic coding的技能框架和方法论集合它把“怎么让 AI 更靠谱地写代码”这件事从零散的提示词技巧沉淀成了一套可复用、可组合、可版本管理的技能包。我自己的理解是它更像是一本“给 AI 代理看的操作手册 工具箱”。你平时用 Claude Code 或者 Codex CLI默认状态下 AI 是“裸奔”的——它有能力但不知道你的项目规范、不知道你团队的代码风格、不知道你踩过哪些坑。superpowers 做的事情就是把这些隐性知识显性化变成一个个独立的 skill技能让 AI 在需要的时候自动加载、按需调用。这套东西能干什么举几个我实际用下来的场景。第一统一代码规范。你可以在 skill 里写清楚“这个项目用 4 空格缩进、函数必须写 JSDoc、禁止使用 any 类型”AI 每次生成代码都会遵守。第二固化工作流。比如“改完代码必须跑 lint、必须更新 CHANGELOG、必须写单元测试”这些步骤可以写成一个 skillAI 执行任务时会自动走完流程。第三沉淀领域知识。比如你公司内部有一套特殊的部署流程、有一套自研的 SDK这些文档丢给 AI 它记不住但写成 skill 就能随时调用。适合谁来参考我觉得有三类人最值得花时间研究。一是重度使用 Claude Code / Codex CLI 的开发者你已经在用这些工具写代码了superpowers 能让你的效率再上一个台阶。二是团队技术负责人你想让团队里所有人用 AI 写出来的代码风格一致、质量可控这套框架提供了一个很好的抓手。三是对 agentic skills framework 感兴趣的技术爱好者想搞清楚“AI 代理的技能系统”到底是怎么设计的superpowers 是一个非常好的学习样本。需要提前说明的是superpowers 本身不是一个独立的软件它更像是依附于 Claude Code、Codex CLI 这类宿主工具的扩展层。所以你在安装和使用它之前得先把宿主环境搭好。这也是为什么热词里会出现大量“claude code 安装”“codex cli 安装”“superpowers 安装”这类搜索——大家卡的第一步往往不是 superpowers 本身而是它依赖的那些命令行工具。2. 核心概念拆解skill、agent 与宿主工具的关系2.1 什么是 skill它和普通提示词有什么区别很多人第一次接触 skill 这个概念会懵这不就是提示词吗我直接写在对话里不行吗区别其实挺大的。普通提示词是一次性的、临时的你这次对话说了下次开新会话就没了。而 skill 是持久化的、结构化的、可被检索的。它通常以文件形式存在磁盘上有固定的目录结构包含元数据名称、描述、触发条件和正文内容具体的指令、示例、约束。打个比方普通提示词像是你临时跟同事口头交代一件事说完就完了。skill 像是你写了一份 SOP 文档放在共享盘里任何人任何时候需要都能翻出来看。superpowers 的核心价值就是提供了一套组织和管理这些 SOP 的规范让 AI 代理能够自动判断“现在该用哪个 skill”。从技术实现角度看一个典型的 skill 通常包含这几部分name技能名称用于检索、description什么时候该用这个技能这段描述很关键AI 靠它来判断触发时机、content具体的指令正文。有些实现还会支持examples示例输入输出、constraints硬性约束、dependencies依赖的其他 skill。2.2 agentic skills framework 的设计哲学“agentic”这个词是关键。传统的 AI 使用方式是“你问我答”你给一个指令AI 给一个结果结束。而 agentic 模式下AI 是有自主性的——它会自己规划步骤、自己决定调用哪些工具、自己判断任务是否完成。这种模式下skill 的作用就变得非常重要因为 AI 需要知道“我有哪些能力可用”“什么情况下该用哪个能力”。superpowers 这套框架的设计哲学我总结下来有三条。第一条是关注点分离每个 skill 只做一件事不要把“写代码”和“跑测试”和“提交 git”混在一个 skill 里。第二条是显式优于隐式AI 该做什么、不该做什么都要写清楚不要指望它“猜”。第三条是可组合小的 skill 可以组合成大的工作流就像乐高积木一样。这三条听起来简单但实际落地的时候很容易走偏。我见过有人把所有规范塞进一个巨大的 skill 文件里结果 AI 加载的时候上下文爆炸反而效果变差。也见过有人写得太抽象AI 根本不知道什么时候该触发。这些坑后面会详细讲。2.3 Claude Code 与 Codex CLI 在其中的角色Claude Code 和 Codex CLI 是两类不同的宿主工具但它们在 superpowers 生态里扮演的角色类似——都是skill 的运行容器。Claude Code 是 Anthropic 推出的命令行编程助手Codex CLI 是 OpenAI 系的命令行工具。两者都支持加载外部 skill只是加载机制和配置方式略有差异。这里要提醒一句热词里出现了“claude code might not be available in your country”这类提示这是工具本身的区域可用性问题跟 superpowers 无关。你在安装宿主工具时如果遇到这类提示属于正常现象具体怎么处理不在本文讨论范围建议查阅工具官方文档。从使用体验上对比Claude Code 的 skill 加载机制相对成熟一些社区里分享的 skill 也更多。Codex CLI 相对新一些但胜在和 OpenAI 生态的整合更紧密。如果你两个都在用superpowers 的 skill 大部分是可以通用的只需要注意路径配置和触发语法的差异。3. 环境准备宿主工具安装与常见卡点3.1 Claude Code 安装的几条路径安装 Claude Code 这件事说简单也简单说坑也多。官方推荐的方式是通过 npm 全局安装命令大概是npm install -g anthropic-ai/claude-code这种形式。但实际执行的时候你会遇到几个典型问题。第一个是Node.js 版本问题。Claude Code 对 Node 版本有要求太老的版本会报错。我建议直接用 nvm 或者 fnm 管理 Node 版本装一个 LTS 版本比如 20.x 或 22.x省得折腾。第二个是权限问题在 Linux 和 macOS 上全局安装可能需要 sudo但用 sudo 装又会导致后续权限混乱。我的做法是配置 npm 的全局目录到用户目录下避免 sudo。# 配置 npm 全局目录到用户目录 mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加到 PATH 里 export PATH~/.npm-global/bin:$PATH第三个是网络问题。这个不多说懂的都懂反正安装过程中如果卡住先检查网络连通性。Windows 用户额外注意建议在 WSL2 里装原生 Windows 环境下有些依赖会出问题。热词里“windows 安装 claude code”“windows claude code cc-connect 飞书”这些搜索说明 Windows 用户的踩坑率确实高。Ubuntu 用户的话流程相对顺畅ubuntu 安装 claude code这个搜索词下的方案基本都可用。装完之后用claude --version验证一下能输出版本号就说明装好了。3.2 Codex CLI 安装与“unable to locate”报错处理Codex CLI 的安装热词里有个很具体的报错“unable to locate the codex cli binary or required runtime components. check”。这个报错我遇到过本质上是宿主工具找不到 codex 的可执行文件或者运行时依赖。排查思路分三步。第一步确认 codex 是否真的装上了。在终端里直接敲codex --version如果提示 command not found那就是没装成功或者没加到 PATH。第二步如果命令能跑但宿主工具报这个错那大概率是路径配置问题——宿主工具用的是自己的 PATH 环境跟你终端里的不一样。这时候需要在宿主工具的配置里显式指定 codex 的绝对路径。第三步如果路径也对那就检查运行时组件比如 Python 版本、Node 版本是否满足要求。# 查找 codex 的实际安装位置 which codex # 或者 whereis codex # 拿到绝对路径后写进宿主工具配置Windows 上安装 codex cli 的话热词里“codex cli windows 安装”也是高频搜索。我的建议还是 WSL2原生 Windows 下路径分隔符、权限模型都不一样容易出玄学问题。如果非要在原生 Windows 下跑注意把 codex 的安装目录加到系统环境变量 PATH 里然后重启终端。3.3 superpowers 安装的正确姿势宿主工具装好之后superpowers 的安装反而简单了。它的本质是把 skill 文件放到宿主工具能识别的目录下。不同宿主工具的 skill 目录不一样Claude Code 通常在~/.claude/skills/或者项目根目录的.claude/skills/下Codex CLI 类似。安装方式一般有两种。一种是从 GitHub 上 clone 整个 superpowers 仓库然后把 skills 目录拷贝或者软链接到宿主工具的 skill 目录。另一种是用包管理器安装如果 superpowers 发布了 npm 包或者 pip 包的话。我推荐第一种因为软链接方式方便更新——你 git pull 一下所有 skill 自动更新不用重新拷贝。# 假设 superpowers 仓库 clone 到了 ~/superpowers # 创建软链接到 Claude Code 的 skill 目录 ln -s ~/superpowers/skills ~/.claude/skills/superpowers这里有个细节要注意skill 目录的层级结构。有些宿主工具要求 skill 必须放在特定层级的子目录里比如skills/skill-name/SKILL.md这种结构。你如果直接把一堆 md 文件平铺在 skills 目录下可能识别不了。安装前先看一眼宿主工具的文档确认目录规范。4. 实操从零搭建一套可用的 skill 工作流4.1 第一个 skill从“代码规范检查”开始理论说再多不如动手写一个。我建议第一个 skill 从代码规范检查入手因为需求明确、效果直观、不容易翻车。假设你的项目是 Java 项目你想让 AI 每次生成代码都遵守团队的规范。先创建目录结构~/.claude/skills/ └── java-code-style/ └── SKILL.md然后写 SKILL.md 的内容。这里的关键是description 字段它决定了 AI 什么时候会触发这个 skill。写得太宽泛AI 动不动就加载浪费上下文写得太窄该用的时候用不上。--- name: java-code-style description: 当需要编写、修改或审查 Java 代码时使用。适用于所有 .java 文件的生成和编辑场景。 --- # Java 代码规范 ## 缩进与格式 - 使用 4 空格缩进禁止使用 Tab - 每行不超过 120 个字符 - 左大括号不换行 ## 命名规范 - 类名用 UpperCamelCase - 方法名和变量名用 lowerCamelCase - 常量用 UPPER_SNAKE_CASE ## 注释要求 - 所有 public 方法必须写 Javadoc - 复杂逻辑必须写行内注释说明意图 ## 禁止事项 - 禁止使用魔法数字必须定义为常量 - 禁止空的 catch 块 - 禁止使用 System.out.println 做日志必须用日志框架写完保存然后在 Claude Code 里开一个新会话让它写一段 Java 代码观察它是否遵守了这些规范。如果没触发检查 description 是不是写得太抽象试着加上更具体的关键词。4.2 skill 的触发机制与调试方法skill 不触发是新手最常见的问题。排查思路我整理成一个表现象可能原因排查方法完全不触发description 不匹配检查 description 是否包含任务相关的关键词偶尔触发触发条件太模糊收窄 description 的适用范围触发但内容没生效文件格式错误检查 frontmatter 的 YAML 语法加载报错目录结构不对确认 SKILL.md 的路径层级上下文爆炸skill 内容太长拆分 skill或精简内容调试的时候有个技巧在对话里直接问 AI“你现在加载了哪些 skill”。有些宿主工具会返回当前激活的 skill 列表这样你就能确认 skill 到底有没有被识别。另外很多宿主工具支持手动触发 skill比如用/skill java-code-style这种命令调试阶段可以先用手动触发验证内容是否正确再排查自动触发的问题。4.3 组合多个 skill 构建完整工作流单个 skill 只是开始superpowers 真正的威力在于组合。举个实际例子我给自己搭的一套“功能开发工作流”包含四个 skillrequirement-analysis接到需求时先让 AI 分析需求、列出验收标准code-implementation根据需求写代码遵守代码规范test-generation为新增代码生成单元测试changelog-update更新 CHANGELOG 文件这四个 skill 可以串起来用。我在 Claude Code 里下指令“实现 XXX 功能”AI 会先触发 requirement-analysis 分析需求然后触发 code-implementation 写代码接着触发 test-generation 写测试最后触发 changelog-update 更新日志。整个过程我只需要在关键节点确认一下剩下的它自己走完。这里的关键是skill 之间的衔接。每个 skill 的结尾要写清楚“完成后应该做什么”引导 AI 进入下一个 skill。比如 requirement-analysis 的结尾可以写“分析完成后如果用户确认需求无误进入代码实现阶段”。这种显式的引导比指望 AI 自己判断要靠谱得多。5. 进阶玩法让 skill 真正融入日常开发5.1 项目级 skill 与全局 skill 的取舍skill 可以放在两个位置全局目录比如~/.claude/skills/和项目目录比如project/.claude/skills/。这两者的区别很重要。全局 skill 对所有项目生效适合放通用的、跨项目的规范比如“Git 提交信息格式”“通用代码风格”。项目级 skill 只对当前项目生效适合放项目特有的知识比如“这个项目的部署流程”“这个项目用的自研框架的用法”。我的经验是通用规范放全局项目知识放项目级。但要注意项目级 skill 如果提交到 git 仓库团队其他人 clone 下来就能直接用这是团队协作的好方式。不过要小心别把敏感信息比如内部 API 密钥、服务器地址写进 skill 里这些应该用环境变量或者单独的配置文件管理。5.2 用 skill 固化团队协作规范团队场景下superpowers 的价值会被放大。我帮一个团队搭过一套 skill效果挺明显。他们的痛点是团队里有人用 AI 写代码有人不用导致代码风格不统一review 的时候经常为格式问题吵架。我们的做法是把团队的代码规范、review checklist、提交信息格式全部写成 skill放在项目仓库的.claude/skills/目录下。然后要求所有人用 Claude Code 或 Codex CLI 写代码时必须加载这些 skill。这样一来不管是谁用 AI 生成的代码风格都是一致的review 的时候只需要关注逻辑不用纠结格式。这里有个实操细节skill 的版本管理。skill 文件本身也是代码应该走 git 流程。修改 skill 要提 PR要 review要有变更记录。我见过有团队把 skill 改得乱七八糟最后没人知道哪个版本是对的。把 skill 当代码管理这个问题就解决了。5.3 与现有工具链的集成思路superpowers 不是孤立的它可以和现有工具链集成。几个我试过有效的方向和 lint 工具集成。skill 里可以写“生成代码后自动运行 eslint/checkstyle如果有报错就修复”。这样 AI 写完代码会自己跑一遍 lint把低级错误消灭在提交之前。和测试框架集成。skill 里写“新增函数必须配套单元测试测试覆盖率不低于 80%”。AI 写代码的时候会顺手把测试写了省得你后面补。和 CI/CD 集成。这个稍微复杂一点思路是在 CI 流程里加一步检查 AI 生成的代码是否符合 skill 里定义的规范。不符合就 fail倒逼大家把 skill 写好。和 IDE 集成。热词里“vscode 配置 claude code”“vscode 安装 claude code”说明很多人想在 VSCode 里用。Claude Code 有 VSCode 插件装完之后可以在编辑器里直接调用。skill 的加载机制和命令行版本一致配置好目录就行。6. 常见问题与避坑指南6.1 安装类问题速查问题原因解决方案unable to locate the codex cli binaryPATH 未配置或路径错误用which codex找绝对路径写进宿主配置Claude Code 安装后命令找不到npm 全局目录不在 PATH配置 npm prefix 并加到 PATHWindows 下安装失败原生环境依赖问题改用 WSL2skill 目录不识别目录层级不对确认skills/name/SKILL.md结构安装后 AI 不加载 skilldescription 不匹配检查触发关键词手动触发测试6.2 使用类问题与排查思路skill 内容太长导致上下文爆炸。这是最常见的问题。一个 skill 写了几千字AI 加载后上下文被占满反而影响正常对话。解决办法是拆分把大 skill 拆成多个小 skill按需加载。单个 skill 建议控制在 500 字以内超过就考虑拆。skill 之间冲突。两个 skill 给了矛盾的指令AI 会懵。比如一个 skill 说“用 4 空格缩进”另一个说“用 2 空格缩进”。排查方法是逐个禁用 skill 测试找到冲突的两个然后合并或者明确优先级。AI 不遵守 skill 里的约束。这个要分情况。如果是软约束比如“建议写注释”AI 可能忽略如果是硬约束比如“禁止使用某 API”AI 通常会遵守。如果硬约束也不遵守检查 skill 的措辞是不是太委婉改成“必须”“禁止”这种强指令。skill 更新后不生效。宿主工具通常有缓存机制skill 改了但 AI 还在用旧版本。解决办法是重启宿主工具或者找找有没有清除缓存的命令。有些工具支持热重载改完自动生效这个要看具体实现。6.3 我踩过的几个坑第一个坑skill 写得太抽象。我一开始写了个“写高质量代码”的 skill结果 AI 完全不知道该怎么执行。后来改成具体的“函数不超过 50 行、圈复杂度不超过 10、必须有错误处理”效果立刻好了。skill 要具体到可执行不能是口号。第二个坑skill 目录用软链接但宿主工具不跟随。有些工具解析软链接有问题导致 skill 加载不了。解决办法是改用硬链接或者直接拷贝文件但这样更新麻烦。我最后是写了个脚本git pull 之后自动同步文件到 skill 目录。第三个坑在 skill 里写了敏感信息。有一次我把内部服务器的地址写进了 skill结果提交到了公开仓库。虽然及时删了但也是个教训。skill 里只放规范和方法不放配置和密钥。第四个坑过度依赖 skill。有段时间我把所有东西都往 skill 里塞结果 AI 每次对话要加载十几个 skill响应变慢效果也变差。后来我学会了克制只把真正高频、真正重要的规范写成 skill其他的靠对话临时说明就行。7. 关于这套框架的一些个人体会用 superpowers 这套东西大半年下来我最大的感受是它改变的不是 AI 的能力而是你和 AI 协作的方式。以前你用 AI 写代码像是在指挥一个能力很强但完全不了解你项目的临时工你得反复交代各种细节。现在有了 skill你像是在带一个已经熟悉项目规范的老员工交代任务的时候只需要说“做什么”不用反复说“怎么做”。另一个体会是skill 的质量比数量重要得多。我见过有人收集了几百个 skill但真正用起来的没几个。与其贪多不如把三五个核心 skill 打磨好让它们真正融入你的日常流程。一个写得好的 skill价值超过一百个写得烂的。还有一点skill 是需要迭代的。你第一次写的 skill 肯定不完美用着用着会发现各种问题。这时候别嫌麻烦改就是了。我的几个核心 skill 都改了十几版每次改完效果都好一点。把 skill 当成一个持续演进的产品而不是一次性的配置。最后说个实际的如果你刚开始接触别一上来就搞复杂的多 skill 工作流。先从一个最简单的 skill开始比如代码格式规范跑通了、用顺了再逐步加。这套框架的学习曲线不算陡但需要你花时间理解它的设计思路。理解了之后你会发现它能做的事情比想象中多。