1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了一句“想要安装 superpowers”底下立刻有人接“你是说 Claude Code 那套还是 Codex CLI 那套”。聊了十几分钟我才反应过来大家嘴里的 superpowers 并不是某个单独的软件而是一套围绕agentic skills framework构建的软件开发方法论——它把“让 AI 帮你写代码”这件事从零散的对话式提问升级成了一套有结构、可复用、能沉淀的技能体系。说白了过去我们用 Claude Code、Codex CLI 这类工具大多数人的用法是打开终端敲一句需求等它吐代码不满意就再补一句。这种用法能解决小问题但一旦项目复杂起来上下文丢失、风格漂移、重复劳动的问题就全冒出来了。superpowers 这套框架的核心思路是把开发者的意图拆解成一个个独立的“技能单元”skill每个技能单元有明确的输入、输出、约束条件和调用方式然后让 agent 按照编排好的流程去执行。这就像从“每次都要口头交代一遍”变成“写好一份标准作业程序谁来都能照着干”。这套东西适合谁我的判断是三类人。第一类是已经在用 Claude Code 或 Codex CLI但总觉得效率没拉满的开发者第二类是想把 AI 编程能力引入团队、但苦于没有统一规范的 tech lead第三类是对 agentic skills framework 这个概念好奇想找一个具体落地的切入点来理解它的人。不管你用的是 Claude Code 还是 Codex CLI底层的方法论是相通的差别主要在配置方式和命令细节上。我写这篇东西的出发点很简单网上关于 superpowers 的中文资料太碎了要么是零散的安装截图要么是互相矛盾的配置说明。我把自己从零搭建这套框架的过程完整记录下来包括踩过的坑、验证过的参数、以及那些文档里不会写的经验。你如果照着走一遍应该能少花好几个晚上。2. 核心思路拆解为什么是“技能框架”而不是“提示词合集”2.1 从提示词工程到技能工程的思维转变大多数人接触 AI 编程的第一站是提示词工程prompt engineering研究怎么把一句话说得更清楚。但提示词工程有个天然缺陷它是无状态的。你这次调教好的提示词下次换个会话就失效了换个项目更是要从头再来。superpowers 背后的 agentic skills framework 想解决的就是这个“不可沉淀”的问题。技能工程skill engineering的思路是把每个可复用的能力封装成独立模块。举个例子“生成一个符合项目规范的 React 组件”这件事在提示词工程里你可能要写两百字描述在技能框架里它被固化成一个 skill 文件里面定义了组件模板、命名规范、样式方案、测试要求agent 每次调用这个 skill 时自动加载全部约束。这个转变的价值在于约束被前置了而不是每次靠嘴说。我自己的体会是当你手上积累了十几个这样的 skill 之后开发节奏会发生质变。以前是“想清楚要什么→描述给 AI→检查结果→修正”现在是“选对 skill→补充业务参数→检查结果”。中间那步“描述给 AI”被大幅压缩了因为大部分通用约束已经在 skill 里了。2.2 Claude Code 与 Codex CLI 在框架中的角色分工这里要澄清一个常见的混淆superpowers 不是 Claude Code 的插件也不是 Codex CLI 的扩展。它是一套独立的方法论Claude Code 和 Codex CLI 是执行这套方法论的两种“运行时”。Claude Code 的优势在于它对项目上下文的感知能力比较强能读取整个代码库的结构适合处理跨文件的复杂改动。Codex CLI 的优势在于命令行的交互效率高适合快速迭代和脚本化调用。我在实际项目里的分工是这样的用 Claude Code 做架构级的重构和新功能设计用 Codex CLI 做具体的代码生成和批量修改。两者共享同一套 skill 定义只是调用方式不同。注意不要试图让两个工具同时操作同一个文件。我踩过这个坑Claude Code 和 Codex CLI 各改了一半最后合并时冲突得一塌糊涂。正确做法是串行使用一个改完提交另一个再基于最新版本操作。2.3 框架的分层结构skill 层、编排层、执行层把 superpowers 拆开看它其实是三层结构。最底层是skill 层存放一个个独立的技能定义文件每个文件描述一个具体能力。中间是编排层定义这些 skill 之间的调用顺序和依赖关系比如“先跑代码分析 skill再跑重构 skill最后跑测试 skill”。最上面是执行层也就是 Claude Code 或 Codex CLI 实际执行的地方。这个分层的好处是解耦。你想换执行工具只需要改执行层的配置skill 和编排逻辑不用动。你想加一个新能力只需要在 skill 层加一个文件然后在编排层注册一下。我见过有人把所有逻辑写在一个巨大的提示词里改一处牵动全身那种维护成本高得吓人。2.4 为什么这套框架对团队协作特别有价值个人开发者用 superpowers收益是效率提升。团队用 superpowers收益是一致性。想象一下五个人用五种不同的方式跟 AI 对话产出的代码风格五花八门code review 的时候光统一风格就要吵半天。但如果五个人共用同一套 skill 定义AI 产出的代码天然就是统一的。我们团队的做法是把 skill 文件纳入 Git 管理跟代码一起走版本控制。谁想改某个 skill 的约束提 PRreview 通过才合并。这样一来AI 的行为规范也变成了团队资产的一部分而不是散落在每个人脑子里的隐性知识。3. 环境准备Claude Code 与 Codex CLI 的安装配置实操3.1 Claude Code 的安装路径选择与常见报错处理Claude Code 的安装方式取决于你的操作系统。macOS 和 Ubuntu 上的流程比较顺畅Windows 上则容易遇到一些兼容性问题。我先说 macOS 和 Ubuntu 的通用流程再单独讲 Windows 的注意事项。在 macOS 上最省事的方式是通过官方提供的安装脚本。打开终端执行安装命令后它会自动检测你的系统架构并下载对应的二进制文件。安装完成后你需要把 Claude Code 的可执行路径加到 shell 的 PATH 里。我用的是 zsh所以编辑~/.zshrc加一行 export 语句指向安装目录然后source ~/.zshrc让配置生效。Ubuntu 上的流程类似但要注意权限问题。如果你用的是非 root 用户安装目录最好选在用户主目录下避免每次执行都要 sudo。我试过装在/usr/local/bin下结果每次调用都提示权限不足后来改到~/.local/bin就顺畅了。Windows 用户要特别注意那个“由于与64位版本的 Windows 不兼容”的报错。这个问题的根源通常是安装包架构和系统架构不匹配或者缺少某些运行时依赖。我的建议是优先使用 WSL2 环境在 WSL2 里按照 Ubuntu 的流程安装稳定性比原生 Windows 好很多。如果你坚持用原生 Windows确保下载的是 64 位版本并且系统已经装了最新的 VC 运行库。提示安装完成后先跑一个最简单的命令验证环境是否正常比如让它输出当前目录的文件列表。如果这一步就报错说明环境配置有问题不要急着往下走。3.2 Codex CLI 安装与命令体系速查Codex CLI 的安装相对轻量它本质上是一个命令行工具依赖比较少。安装完成后你会用到几个核心命令我把常用的整理成表格方便查阅。命令作用使用场景/compact压缩当前会话上下文对话太长导致响应变慢时/model切换底层模型需要在不同模型间对比效果时/resume恢复之前的会话中断后继续未完成的任务/clear清空当前上下文切换到不相关的新任务时这几个命令里/compact是我用得最频繁的。长时间对话后上下文会变得非常臃肿响应速度明显下降这时候跑一次/compact能把无关的历史信息压缩掉只保留关键上下文。/model在需要对比不同模型输出质量时很有用比如同一个重构任务我会分别用不同模型跑一遍看哪个更符合预期。删除 Codex CLI 的指令也很简单找到安装目录直接移除即可但记得清理 shell 配置里相关的 PATH 和环境变量否则每次开终端都会报“command not found”的警告。3.3 VS Code 插件配置把 Claude Code 接入编辑器工作流很多人不知道 Claude Code 有 VS Code 插件配置好之后可以在编辑器里直接调用不用来回切终端。安装插件后需要在设置里填入 Claude Code 的可执行路径以及配置一些偏好项比如默认模型、上下文窗口大小、是否自动保存会话记录。VS Code 插件的价值在于它能把 AI 的输出直接映射到编辑器里。比如你让 Claude Code 重构某个函数它生成的新代码会以 diff 的形式展示在编辑器里你可以逐行 review 后决定接受还是拒绝。这比在终端里看纯文本输出直观太多了。配置过程中有个细节容易忽略插件的上下文感知范围。默认情况下它只读取当前打开的文件但你可以配置让它读取整个工作区的文件结构。这个选项在处理跨文件重构时特别重要不开的话 AI 看不到其他文件的定义生成的代码可能引用不存在的接口。3.4 接入第三方模型通过 cc switch 切换 deepseek、qwen、glmClaude Code 默认用的是官方模型但通过 cc switch 这类工具你可以把底层模型切换成 deepseek、qwen、glm 等第三方模型。这个能力在实际使用中很有价值因为不同模型在不同任务上的表现差异很大。配置的核心是修改模型接入的 endpoint 和 API key。cc switch 会帮你管理多套配置切换时只需要指定配置名称。我一般会准备三套配置一套用官方模型处理复杂推理任务一套用 deepseek 处理代码生成一套用 qwen 处理中文文档相关的任务。切换命令执行后后续的调用就会走新的模型。注意第三方模型的上下文窗口大小和官方模型可能不同切换后要相应调整 skill 里的上下文配置否则可能出现截断导致的信息丢失。3.5 本地模型接入让 Claude Code 调用 LM Studio如果你对数据隐私有要求或者想在没有网络的环境下使用可以把 Claude Code 接到 LM Studio 的本地模型上。LM Studio 会在本地起一个兼容 OpenAI 接口的服务你只需要把 Claude Code 的 endpoint 指向本地的端口即可。这个方案的瓶颈在于本地模型的推理速度和能力上限。我实测下来7B 级别的模型跑简单的代码补全还行复杂重构就力不从心了。13B 以上的模型效果好一些但对显存的要求也上去了。如果你的机器配置一般建议只把本地模型用于辅助性任务核心开发还是走云端模型。配置时要注意端口冲突问题。LM Studio 默认端口可能和其他本地服务撞车建议改成不常用的端口号并且在 Claude Code 的配置里同步修改。4. 搭建 superpowers 技能框架的完整实操流程4.1 目录结构设计让 skill 文件可管理、可检索搭建框架的第一步是设计目录结构。我的方案是按“领域-技能”两级来组织。顶层目录按开发领域划分比如 frontend、backend、devops、testing每个领域下面放具体的 skill 文件。这样当 skill 数量增长到几十个时你依然能快速定位到需要的那个。每个 skill 文件我建议用统一的命名规范比如领域-动作-对象.md像frontend-generate-component.md、backend-create-api-endpoint.md。命名清晰的好处是当你在编排层引用 skill 时一眼就能看出这个步骤在干什么不用打开文件看内容。目录里还要有一个registry.md文件相当于技能的总索引。每新增一个 skill就在 registry 里登记一条包括 skill 名称、路径、输入参数、输出格式、依赖关系。这个索引文件在编排复杂流程时特别有用agent 可以先读 registry 了解有哪些能力可用再决定调用顺序。4.2 编写第一个 skill从需求到可执行定义的转化我拿“生成 React 组件”这个最常见的需求来演示。一个完整的 skill 定义应该包含几个部分触发条件什么情况下用这个 skill、输入参数需要用户提供什么信息、执行约束代码规范、命名规则、样式方案、输出格式生成的文件结构、验证标准怎么判断生成结果合格。触发条件我写的是“当需要创建新的 UI 组件且项目使用 React 技术栈时”。输入参数包括组件名称、props 定义、是否需要状态管理、是否需要测试文件。执行约束里我固化了团队的规范函数式组件、TypeScript、CSS Modules、组件名用 PascalCase、文件名用 kebab-case。输出格式定义了生成的文件列表和每个文件的内容模板。验证标准包括类型检查通过、lint 无报错、测试覆盖率达标。写这个 skill 的过程本身就是一次团队规范的梳理。很多平时靠口头约定的东西写进 skill 里就变成了硬约束。我建议第一次写的时候不要追求完美先写一个能跑的版本在实际使用中逐步补充约束条件。4.3 编排层设计定义 skill 之间的调用顺序单个 skill 只能解决单点问题真正的威力在于把多个 skill 编排成一条流水线。比如“新增一个带表单的页面”这个需求可以拆解成生成页面骨架 skill → 生成表单组件 skill → 生成 API 调用 skill → 生成测试 skill → 运行验证 skill。编排层的定义我用一个 YAML 文件来描述每个步骤指定调用的 skill 名称和传入的参数。步骤之间可以定义依赖关系比如“生成测试 skill”依赖“生成表单组件 skill”的输出。这种依赖关系让 agent 知道哪些步骤可以并行哪些必须串行。编排设计的一个关键原则是每个步骤的输出要能被下一个步骤直接消费。如果 skill A 输出的是自然语言描述skill B 需要的是结构化数据中间就要加一个转换步骤。我在早期设计时忽略了这一点导致 agent 在步骤之间反复询问“你刚才说的那个是什么意思”效率极低。4.4 执行层对接Claude Code 与 Codex CLI 的调用差异编排层定义好之后执行层负责实际调用。Claude Code 和 Codex CLI 在调用方式上有一些差异需要分别配置。Claude Code 的调用更偏向“对话式执行”你把编排文件的内容作为上下文传给它它会逐步执行并在每一步询问确认。这种方式适合需要人工介入的关键步骤。Codex CLI 的调用更偏向“批处理执行”你把编排文件路径传给它它会一口气跑完所有步骤最后输出结果。这种方式适合已经验证过的成熟流程。我的做法是新流程先用 Claude Code 跑每一步都人工确认确认无误后再用 Codex CLI 批量执行。这样既保证了安全性又保证了效率。4.5 验证框架是否跑通一个最小可行案例搭建完成后用一个最小案例验证整条链路。我选的是“生成一个 Hello World 级别的 API 接口”。这个案例足够简单能在几分钟内跑完同时又能覆盖 skill 调用、编排执行、结果验证的完整流程。验证时重点观察几个指标skill 是否被正确加载、参数是否被正确传递、输出是否符合约束、验证步骤是否通过。如果任何一环出问题回到对应的层去排查。我第一次跑的时候卡在参数传递上原因是 skill 定义里的参数名和编排文件里写的对不上改了一致之后就通了。5. 常见问题与排查技巧实录5.1 安装与登录类问题速查问题现象可能原因解决思路提示组织已禁用订阅访问账号权限配置问题检查账号所属组织的策略设置提示当前地区不可用服务可用性限制确认所在地区的服务支持情况桌面版安装包无法运行系统架构不匹配确认下载的安装包与系统架构一致注册与不注册的差异功能权限不同根据需求决定是否注册关于注册与否的差异我的经验是不注册也能用基础功能但会话记录、技能同步、团队协作这些能力会受限。如果你只是个人临时用用不注册问题不大如果要长期使用并搭建 skill 体系建议注册以获得完整能力。5.2 模型调用失败的排查路径模型调用失败是最常见的问题排查要按顺序来。先确认网络连通性再确认 API key 是否有效然后确认 endpoint 配置是否正确最后确认模型名称是否拼写无误。这四步能覆盖百分之九十的调用失败场景。我遇到过一次很隐蔽的问题API key 有效、endpoint 正确、模型名称也对但就是调不通。排查了半天才发现是配置文件里多了一个空格导致解析失败。这种问题没有报错信息只能靠逐字符检查配置来发现。提示建议把模型配置单独放在一个文件里每次修改后先用一个最简单的测试命令验证确认通了再跑正式任务。5.3 上下文丢失与响应变慢的处理长时间对话后响应变慢根本原因是上下文窗口被占满了。处理方式有两种一是用/compact压缩上下文二是用/clear清空后重新开始。选择哪种取决于当前任务是否依赖之前的历史信息。如果任务还在进行中用/compact保留关键信息如果已经切换到新任务直接/clear更干净。我个人的习惯是每完成一个独立任务就/clear一次保持上下文清爽。5.4 skill 不生效的几种典型情况skill 不生效通常有三个原因路径配置错误、格式不符合规范、依赖缺失。路径错误最好排查检查 registry 里的路径和实际文件位置是否一致即可。格式问题需要对照 skill 定义的模板逐项检查特别是必填字段有没有遗漏。依赖缺失比较隐蔽比如某个 skill 依赖另一个 skill 的输出但那个 skill 没有被正确调用。我的排查习惯是先单独调用目标 skill看它能不能独立跑通。如果能跑通说明 skill 本身没问题问题出在编排层如果跑不通说明 skill 定义有问题回到 skill 层排查。5.5 第三方模型切换后的兼容性问题切换到第三方模型后最常见的问题是输出格式不符合预期。官方模型可能天然遵循某些格式约定但第三方模型不一定。解决方法是在 skill 定义里把输出格式的约束写得更明确甚至给出具体的示例。另一个问题是上下文窗口大小不同导致的截断。切换模型后要重新评估 skill 里的上下文配置必要时把大任务拆成小任务避免超出窗口限制。6. 我在这套框架上踩过的坑与沉淀的经验6.1 不要一开始就追求大而全的 skill 库我最初的想法是把所有能想到的能力都写成 skill结果写了三十多个真正用起来的不到十个。后来我调整了策略只把高频、重复、有明确规范的任务写成 skill低频任务直接用对话解决。skill 库的价值在于精而不在于多维护三十个半成品 skill 的成本远高于维护十个成熟 skill。6.2 版本控制是 skill 体系的命脉skill 文件一定要纳入 Git 管理。我吃过亏有一次改了一个 skill 的约束条件结果之前依赖这个 skill 的编排流程全挂了想回滚却发现没有版本记录。从那以后所有 skill 变更都走 PR 流程每次改动都有记录可查。6.3 人工确认环节不能省即使流程已经跑得很顺我依然保留关键步骤的人工确认。AI 生成的东西百分之九十五的情况没问题但剩下百分之五可能引入难以察觉的 bug。在代码合并、配置修改、数据操作这些环节多花三十秒确认能省下几个小时的排查时间。6.4 定期回顾和清理 skill 库skill 库会随着项目演进逐渐积累冗余。我每个月会花半小时回顾一遍把不再使用的 skill 归档把可以合并的 skill 整合把约束条件过时的 skill 更新。这个习惯让 skill 库始终保持精简和有效。6.5 团队推广要循序渐进在团队里推广这套框架时不要一上来就要求所有人按同一套规范来。我的做法是先找两三个愿意尝试的同事一起用跑通几个实际项目积累出可展示的成果再逐步推广。有了实际案例说服力比任何文档都强。7. 框架的扩展方向从单点技能到完整开发流水线7.1 把代码审查纳入 skill 体系代码审查是一个很适合 skill 化的环节。我定义了一个 review skill输入是待审查的代码 diff输出是审查意见列表约束条件包括团队的安全规范、性能规范、可读性规范。每次提交 PR 时自动触发这个 skill先过一遍 AI 审查人工审查时只需要关注 AI 标记出的疑点效率提升明显。7.2 与 CI/CD 流程的对接思路skill 体系可以和 CI/CD 流程对接。比如在构建阶段调用“依赖检查 skill”在测试阶段调用“测试生成 skill”在部署阶段调用“配置验证 skill”。对接的关键是让 skill 的输入输出格式和 CI/CD 工具的要求匹配这需要在 skill 定义时就把接口设计好。7.3 跨项目复用 skill 的组织方式当你有多个项目时skill 的复用就变得重要。我的做法是把通用 skill 放在一个独立的仓库里项目专属 skill 放在各自项目仓库里。项目仓库通过引用通用仓库的 skill 来复用能力同时保留项目特有的约束。这样既保证了复用又保证了灵活性。7.4 技能框架的长期维护策略长期维护的核心是建立反馈循环。每次使用 skill 后记录下哪些地方顺畅、哪些地方卡顿定期根据这些反馈优化 skill 定义。我建了一个简单的反馈文档每次遇到问题就记一笔月底统一处理。这个习惯让框架始终在进化而不是搭好之后就僵化了。这套东西说到底核心不是工具本身而是把开发经验固化成可复用资产的那套思路。工具会变Claude Code 会更新Codex CLI 会迭代但“把重复劳动沉淀成技能”这个方向不会变。我在实际操作中的体会是前期投入在 skill 编写上的时间大概两到三周就能通过效率提升收回来之后就是纯赚。如果你也在用这类工具不妨从手头最重复的那个任务开始试着把它写成一个 skill跑通之后再逐步扩展。