1. 从“superpowers”说起：这套 agentic skills framework 到底在解决什么问题

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“这玩意儿把 Claude Code 和 Codex CLI 的玩法又往上抬了一层”。点进去看完之后，我大概理解了它想干的事：把零散的、靠个人经验堆出来的 AI 辅助开发流程，抽象成一套可复用、可组合、可迁移的 agentic skills framework。说白了，就是给“让 AI 帮你写代码”这件事，定一套方法论和工具箱。

你如果只是偶尔用 Claude Code 补个函数、用 Codex CLI 跑个脚本，可能觉得这东西离你有点远。但只要你开始把 AI 编程工具往日常开发流程里塞——比如让它读整个仓库、改多个文件、跑测试、提交 commit——你就会发现一个很现实的问题：每次都要重新解释一遍上下文，每次都要手动纠正它的行为，每次换个项目就得从头调教。superpowers 想解决的，就是这个“重复调教”的痛点。

它本质上是一套围绕agentic skills构建的框架。所谓 agentic skills，你可以理解成“给 AI agent 预置的一套技能包”：每个 skill 定义了一类任务该怎么拆、该调什么工具、该遵守什么约束、该输出什么格式。比如“重构一个函数”“给现有代码补测试”“排查一个报错”“生成一份变更说明”，这些都可以被封装成独立的 skill。框架负责调度这些 skill，让 agent 在面对不同任务时，自动加载对应的能力，而不是每次都靠你在 prompt 里现写。

这套东西为什么最近被频繁和 Claude Code、Codex CLI 放在一起讨论？因为这两个工具恰好是当前最主流的两种“终端里的 AI 编程 agent”形态。Claude Code 偏向交互式、对话式地操作本地仓库，Codex CLI 偏向命令行驱动、可脚本化地执行任务。superpowers 作为一层方法论和框架，理论上可以架在它们之上，也可以作为你自建 agent 流程的参考架构。热搜词里那一堆“claude code 安装”“codex cli 安装”“vscode 配置 claude code”“claude code 调用 lmstudio 的本地模型”，其实反映的是同一件事：大家已经过了“尝鲜”阶段，开始认真琢磨怎么把 AI agent 嵌进真实开发流里了。

这篇文章适合谁看？如果你满足下面任意一条，那接下来的内容应该对你有用：你已经在用 Claude Code 或 Codex CLI，但觉得每次都要重复交代背景很烦；你想把 AI 编程从“单次问答”升级成“可复用的工作流”；你在团队里负责推 AI 工具落地，需要一套能讲清楚、能复制给别人的方法论；或者你只是好奇“agentic skills framework”这个词到底指什么，不想被概念忽悠。我会尽量用从业者之间聊天的口吻，把 superpowers 背后的设计思路、核心机制、实操要点、踩坑经验都摊开讲，不堆术语，不写那种读完等于没读的总结。

2. 核心设计思路拆解：为什么是 skills，而不是又一套 prompt 模板

2.1 从“写 prompt”到“定义 skill”的思维转变

大部分人用 AI 编程工具的第一阶段，都是写 prompt。想让 AI 改个 bug，就写一段描述；想让它加个功能，再写一段。这个阶段的问题很明显：prompt 是一次性的、上下文绑定的、不可复用的。你今天写了一段很精妙的 prompt 让 AI 完成了一次重构，明天换个项目，这段 prompt 大概率要重写，因为项目结构、命名习惯、依赖版本都不一样。

superpowers 这类 agentic skills framework 的核心主张，是把“怎么写 prompt”这件事，升级成“怎么定义一个 skill”。一个 skill 不是一段话，而是一个结构化的能力单元，通常包含几个部分：触发条件（什么情况下该用这个 skill）、输入约定（需要哪些上下文，比如文件路径、函数名、报错信息）、执行步骤（先做什么、再做什么、遇到分支怎么处理）、工具调用（需要读文件、跑命令、查文档还是调外部 API）、输出规范（结果以什么格式返回，是 diff、是报告还是直接改文件）、约束与禁忌（哪些操作绝对不能做，比如不能动生产配置、不能删测试）。

这么设计的好处，是把“个人经验”变成了“可传递的资产”。你团队里那个最会用 AI 的同事，他的调教技巧不再只存在于他的聊天记录里，而是被固化成一个 skill 文件，别人直接加载就能用。这跟当年从“手写 SQL”到“用 ORM”的转变有点像：不是说手写 SQL 不行，而是当重复模式足够多的时候，抽象一层能显著降低边际成本。

2.2 为什么选择“框架”而不是“插件”或“平台”

热搜词里能看到大量关于 Claude Code 和 Codex CLI 的安装、配置、模型接入问题。这说明一个现实：工具本身还在快速迭代，生态远没到稳定期。今天 Claude Code 的某个配置项，下个版本可能就改了；今天 Codex CLI 支持的命令，明天可能就废弃了。在这种环境下，superpowers 选择做“框架”而不是“插件”或“平台”，是很务实的。

插件的问题在于强绑定。你写一个 Claude Code 插件，就只能用在 Claude Code 里；Codex CLI 一升级，插件可能就挂了。平台的问题在于太重。你要先把自己的流程迁到平台上，才能享受它的能力，迁移成本高，而且平台一旦不维护了，你的资产就锁死了。框架的好处是松耦合：它定义的是 skill 的抽象结构和调度逻辑，具体执行可以对接 Claude Code，也可以对接 Codex CLI，甚至可以对接你自己写的脚本。框架本身不依赖某个具体工具的 API 稳定性，工具变了，换一层适配就行。

这其实也是很多资深开发者在选型时的默认思路：在快速变化的领域里，优先投资那些“抽象层”的东西，而不是“实现层”的东西。抽象层活得久，实现层换得快。superpowers 把自己定位成 agentic skills framework，就是在赌这个抽象层有价值。

2.3 和 Claude Code、Codex CLI 的关系：不是替代，是编排

很多人第一次接触 superpowers，会误以为它是 Claude Code 或 Codex CLI 的替代品。其实不是。更准确的关系是：Claude Code 和 Codex CLI 是“执行器”，superpowers 是“编排层”。

Claude Code 擅长的是交互式地理解你的意图，在本地仓库里做多文件编辑，它能读代码、能跑命令、能根据你的反馈调整。Codex CLI 擅长的是命令行驱动、可脚本化、可放进 CI 流程里跑。两者各有适用场景。superpowers 要做的是：当你面对一个复杂任务时，自动判断该用哪个执行器、该加载哪些 skill、该按什么顺序执行、中间结果怎么传递、失败了怎么回滚。

举个例子。你要给一个老项目补测试。这个任务可以拆成几个 skill：先“扫描项目结构，识别测试框架和现有测试模式”，再“分析目标模块的公开接口和边界条件”，然后“生成测试用例草稿”，接着“运行测试并收集失败信息”，最后“根据失败信息迭代修正”。这几个 skill 里，扫描和分析适合用 Claude Code 交互式做，生成和运行适合用 Codex CLI 脚本化做。superpowers 负责把它们串起来，让整个流程不需要你手动切换工具、手动复制粘贴中间结果。

这种“编排层”的价值，在任务越复杂、步骤越多的时候越明显。单步任务你手动做也就做了，五步十步的任务，手动编排的认知负担和出错概率都会陡增。

3. 核心细节解析：一个 skill 到底长什么样，怎么落地

3.1 skill 的结构化描述：从模糊意图到可执行单元

前面说了 skill 包含触发条件、输入约定、执行步骤、工具调用、输出规范、约束禁忌。这些听起来有点抽象，我拿一个具体例子来拆。假设你要定义一个“给指定函数补单元测试”的 skill。

触发条件可以写成：当用户提到“补测试”“加测试”“test coverage”并且指定了函数名或文件路径时，加载此 skill。输入约定包括：目标文件路径、目标函数名、项目使用的测试框架（从项目配置里自动探测）、现有测试文件的命名和存放约定。执行步骤可以拆成：读取目标函数源码，识别它的输入参数、返回值、副作用、异常分支；读取同项目下已有的测试文件，学习断言风格和 mock 方式；生成测试用例，覆盖正常路径、边界值、异常路径；把生成的测试写入符合项目约定的位置；运行测试命令，收集结果；如果有失败，分析原因并修正，最多迭代三轮。

工具调用部分要明确：读文件用什么、跑测试用什么命令、如果项目有 lint 要求要不要先跑 lint。输出规范要定义：是直接改文件，还是先输出 diff 让人确认；测试命名遵循什么模式；注释写不写、写多少。约束禁忌要写死：不能修改被测函数的签名，不能删除已有测试，不能引入项目里没有的测试依赖。

你看，这么一拆，一个原本模糊的“帮我补个测试”就变成了一个可执行、可检查、可复用的单元。别人拿到这个 skill 定义，即使不看你原来的 prompt，也能理解该怎么执行。这就是结构化描述的价值。

3.2 上下文管理：agentic skills 最容易被低估的难点

所有做 AI agent 的人，最后都会撞上同一堵墙：上下文管理。模型再强，上下文窗口也是有限的；就算窗口够大，塞太多无关信息也会稀释注意力，让效果变差。superpowers 这类框架，很大一部分复杂度其实花在“什么时候给 agent 喂什么上下文”上。

一个设计良好的 skill，应该明确声明自己需要哪些上下文，而不是让 agent 自己去猜。比如“补测试”这个 skill，它需要的是目标函数源码、同项目测试风格样本、测试框架配置。它不需要的是整个仓库的所有文件、无关模块的实现细节、构建脚本。如果框架不做区分，一股脑把仓库塞进去，agent 就会在噪音里挣扎。

实操中我常用的策略是分层加载：第一层是 skill 声明的必需上下文，必须给；第二层是相关上下文，比如目标函数的调用方、被调用方，按需给；第三层是背景上下文，比如项目 README、架构文档，只在 agent 明确要求时才给。这个分层策略能显著降低 token 消耗，同时提升输出质量。热搜词里有人问“claude code 调用 lmstudio 的本地模型”，本地模型上下文窗口通常更小，分层加载就更重要了，不然几轮对话下来窗口就爆了。

还有一个容易被忽略的点是上下文的时效性。agent 执行多步任务时，中间步骤产生的信息（比如跑测试的输出、lint 的结果）要及时更新到上下文里，过时的信息要清理掉。不然 agent 可能基于旧信息做决策，导致行为不一致。这个在框架层面需要有明确的机制来管理，不能靠 agent 自觉。

3.3 工具调用的边界与安全约束

让 AI agent 直接操作你的开发环境，安全问题是绕不开的。superpowers 这类框架在设计 skill 时，必须把工具调用的边界写清楚。哪些命令可以跑，哪些绝对不能跑；哪些文件可以改，哪些只能读；网络请求允不允许，允许的话访问哪些域名。这些约束不是可选项，是必选项。

我见过太多因为约束没写清楚导致的翻车案例。有人让 agent 帮忙清理临时文件，结果 agent 跑了一条范围过大的删除命令，把不该删的删了。有人让 agent 帮忙改配置，结果 agent 把生产环境的连接串改成了测试环境。这些问题的根源，都是 skill 定义里没有明确“禁止操作”清单。

一个实用的做法是白名单 + 确认机制。skill 里明确列出允许执行的命令模式，比如只允许跑npm test、pytest、go test这类测试命令，其他命令一律拒绝。对于文件修改，默认只允许改指定目录下的文件，改其他位置需要人工确认。对于网络请求，默认关闭，需要时显式开启并限定目标。这些约束在框架层面强制执行，而不是靠 prompt 里写一句“请不要做危险操作”——模型对自然语言约束的遵守程度，远不如对代码层面硬约束的遵守程度。

提示：如果你在团队里推这套东西，安全约束一定要在第一次落地时就写死，不要等到出了问题再补。事后补约束，往往意味着已经有过一次事故了。

4. 实操过程：从零搭一套可用的 agentic skills 工作流

4.1 环境准备：Claude Code 与 Codex CLI 的安装与基础配置

要跑通 superpowers 这套思路，你得先有执行器。Claude Code 和 Codex CLI 是目前最顺手的两类选择，安装方式各有讲究。

Claude Code 的安装，官方推荐的方式是通过 npm 全局安装，命令大致是npm install -g @anthropic-ai/claude-code，装完之后在项目目录下跑claude就能进入交互模式。Mac 和 Ubuntu 上的流程基本一致，前提是 Node 版本不要太老，建议 18 以上。Windows 用户要注意，热搜词里有人提到“claude code 由于与64位版本的 windows 不兼容”，这类问题通常和 Node 架构、终端环境有关，建议在 WSL 里跑，体验会稳定很多。VSCode 用户可以直接装 Claude Code 的官方插件，在编辑器里就能调用，省去切换终端的麻烦。

Codex CLI 的安装类似，也是 npm 全局装，命令是npm install -g @openai/codex或者对应的包名，具体以官方文档为准。装完之后在终端里用codex命令驱动。Codex CLI 的特点是更适合脚本化，你可以把它写进 shell 脚本或者 CI 配置里，让它按预设流程跑。

配置环节有几个关键点。第一是模型接入。Claude Code 默认走官方模型，但很多人想接本地模型或者第三方 API。热搜词里“claude code 调用 lmstudio 的本地模型”“使用 cc switch 接入 deepseek、qwen、glm 等模型”说的就是这类需求。通常的做法是通过环境变量或者配置文件指定 base URL 和 API key，把请求指向本地或第三方服务。这里要注意，不同模型对工具调用的支持程度不一样，有些模型能很好地遵循 function calling 格式，有些则容易跑偏，选型时要实测。

第二是权限配置。Claude Code 和 Codex CLI 都会涉及文件读写和命令执行，第一次跑的时候会问你要不要授权。建议在项目级别配置好允许的操作范围，不要图省事全开。第三是项目级配置，比如.claude目录或者对应的配置文件，用来定义这个项目下的行为约定，比如测试命令是什么、代码风格是什么。这些配置越早定越好，后面所有 skill 都依赖它们。

4.2 定义你的第一批 skill：从最高频的任务开始

不要一上来就想定义几十个 skill，那是给自己挖坑。正确的做法是从你每天重复次数最多的任务开始。对大多数开发者来说，高频任务无非这几类：读代码理解逻辑、改 bug、加功能、补测试、写文档、review 变更。挑其中你最烦的一个，先把它 skill 化。

我拿“读代码理解逻辑”举例。这个任务看起来简单，其实很耗上下文。一个 skill 可以这样定义：输入是一个文件路径或函数名；执行步骤是先读目标代码，再读它的直接依赖和调用方，然后输出一份结构化说明，包括这个模块的职责、关键数据结构、主要流程、对外接口、潜在坑点；输出格式是 markdown，分节呈现；约束是只读不写，不跑任何修改性命令。

定义好之后，你在 Claude Code 里就可以用一句“用 read-code skill 分析 xxx 文件”来触发，而不是每次都写一大段“请帮我读一下这个文件，告诉我它做了什么，注意看它的依赖……”。省下来的不只是打字时间，更是每次都要重新组织思路的认知成本。

第一批 skill 建议控制在三到五个，覆盖你最常做的几类任务。每个 skill 先跑通，再优化。跑通的标准是：换一个项目、换一个文件，它依然能按预期工作。如果换个场景就失效，说明 skill 定义里绑定了太多项目特定信息，需要抽象。

4.3 编排多个 skill：让 agent 自己决定下一步

单个 skill 跑通之后，下一步是编排。真实任务很少是单一步骤的，通常是多个 skill 串起来。比如“给这个模块加一个新功能”，可能涉及：读现有代码理解结构、设计接口、写实现、补测试、跑测试、修失败、更新文档。这一串如果全靠你手动触发，那和不用框架差别不大。

superpowers 这类框架的编排能力，体现在它能根据当前状态自动决定下一个该加载哪个 skill。实现方式通常有两种：一种是显式编排，你在配置里写清楚流程，比如“先 read-code，再 design-interface，再 implement，再 test”，框架按顺序执行；另一种是隐式编排，框架根据 agent 的输出判断下一步，比如 agent 说“实现完成，需要测试”，框架就自动加载 test skill。

显式编排可控性强，适合流程固定的任务；隐式编排灵活，适合探索性任务。实操中我建议混合使用：主干流程用显式编排保证稳定性，分支和异常处理用隐式编排保留灵活性。比如主流程固定为“读代码 → 改代码 → 跑测试”，但如果测试失败，就交给 agent 自主决定是修代码还是修测试，这里用隐式编排。

编排的难点在于状态传递。上一个 skill 的输出，怎么变成下一个 skill 的输入。比如 read-code 输出的模块说明，怎么传给 implement skill。常见做法是把中间结果存成结构化数据，比如 JSON 或者 markdown 文件，下一个 skill 从文件里读。这样即使中间隔了几轮对话，信息也不会丢。另一个难点是失败处理。某个 skill 执行失败了，是重试、跳过还是终止整个流程，需要在编排层定义清楚。我的经验是，对于可恢复的失败（比如测试没通过），让 agent 自主迭代；对于不可恢复的失败（比如权限不足、依赖缺失），直接终止并报告，不要让它瞎试。

4.4 与 VSCode 和终端工作流的整合

工具再好，如果和你现有工作流割裂，用起来就会别扭。Claude Code 和 Codex CLI 都提供了和 VSCode 整合的方式，值得花点时间配好。

VSCode 里装 Claude Code 插件之后，你可以在编辑器内直接唤起对话，选中的代码会自动作为上下文传进去。这个体验比在终端里手动复制粘贴好太多。配置的时候注意几点：一是把项目级的 skill 定义放在插件能读到的位置，二是配好模型接入，三是设置好权限范围。热搜词里“vscode 接入 claude code”“claude code for vs code”说的就是这类配置，官方文档里有详细步骤，照着做基本不会错。

终端工作流这边，Codex CLI 的优势更明显。你可以把它写进 Makefile 或者 shell 脚本，比如定义一个make ai-test命令，自动跑“分析变更 → 生成测试 → 执行测试”这一串。这样在 CI 里也能用，每次提交自动跑一遍 AI 辅助的测试补充和检查。注意 CI 环境里通常没有交互式授权，所有权限要提前配好，模型接入也要用环境变量注入，不要硬编码。

还有一个实用技巧是把 skill 定义纳入版本控制。skill 文件放在仓库里，跟着代码一起演进。这样团队成员拉下代码就自带一套 skill，不需要每个人重新配。skill 变更也走 code review，保证质量。这个做法在团队协作场景下价值很大，能把个人的调教经验变成团队的共同资产。

5. 常见问题与排查技巧实录

5.1 安装与配置阶段的典型坑

安装阶段最常见的问题是版本冲突和权限问题。Node 版本太老导致装不上，这个好解决，升级 Node 就行。权限问题通常出现在全局安装时，Linux 和 Mac 上可能需要 sudo，但更推荐用 nvm 管理 Node，避免全局权限问题。Windows 上的兼容性问题前面提过，WSL 是更稳的选择。

模型接入是另一个高发区。热搜词里“your organization has disabled claude subscription access”这类报错，通常是账号或组织策略问题，不是技术问题，需要走对应的账号流程解决。“claude code might not be available in your country”这类提示，属于服务可用性范围问题，遇到的话只能换用其他可用的模型接入方式。接第三方 API 时，注意 base URL 要写对，很多报错都是 URL 少了个路径或者多了个斜杠导致的。API key 的权限也要确认，有些 key 只能调特定模型。

配置文件的路径和格式也容易出错。不同工具读配置的位置不一样，有的是项目根目录下的隐藏目录，有的是用户主目录下的全局配置。改之前先确认工具读的是哪个文件，改完用--help或者对应的诊断命令验证一下。我踩过的坑是改了全局配置但项目里有覆盖配置，导致改了半天没生效，后来才发现优先级问题。

5.2 skill 执行不达预期的排查思路

skill 跑出来的结果不符合预期，排查顺序建议是：先看上下文给够没有，再看约束写清楚没有，最后看模型能力够不够。

上下文不够是最常见的原因。agent 输出泛泛而谈、答非所问，多半是它没拿到足够的项目信息。解决办法是在 skill 定义里明确声明需要哪些文件，或者让框架自动加载相关文件。有时候是上下文太多导致注意力分散，这时候要反过来做减法，把无关信息剔除。

约束不清是第二常见原因。agent 做了你不希望它做的事，比如改了不该改的文件、用了不该用的库，多半是约束没写死。解决办法是把禁止操作列成清单，在框架层面强制执行，而不是靠 prompt 里一句“请不要”。

模型能力不够是第三类原因。有些任务对模型的推理能力要求高，弱模型确实做不好。这时候要么换强模型，要么把任务拆得更细，降低单步难度。热搜词里有人问“claude code harness 可以不登录用其他模型吗”，这类问题的本质就是模型选型，不同模型在不同任务上的表现差异很大，需要实测。

5.3 常见问题速查表

5.4 几条踩坑换来的经验

第一条，skill 要小而专，不要大而全。一个 skill 只干一件事，干好。想覆盖太多场景的 skill，最后往往哪个场景都做不好。需要复杂流程就编排多个小 skill，而不是写一个大 skill。

第二条，约束要写在代码层，不要写在 prompt 层。prompt 里的“请不要”模型可能忽略，代码层的白名单它绕不过去。安全相关的约束，一律用硬机制实现。

第三条，skill 要跟着项目演进。项目结构变了、测试框架换了、代码风格调整了，skill 也要同步更新。把 skill 纳入版本控制，跟着代码一起 review，能保证它不过时。

第四条，不要追求一次到位。先跑通一个最小可用的 skill，用起来，发现问题再迭代。一上来就设计完美框架，大概率会过度设计，而且没经过实战检验的设计往往不靠谱。

第五条，模型选型要实测，不要看宣传。同一个 skill，在不同模型上的表现可能差很多。花点时间在你自己的真实任务上对比几个模型，比看任何评测都准。

6. 关于这套框架的适用边界与个人体会

superpowers 这套 agentic skills framework 的思路，不是银弹。它适合的是任务有重复模式、流程相对固定、对可复现性有要求的场景。如果你的工作每天都是全新的探索性任务，每次都要从零开始，那 skill 化的收益有限，因为没什么可复用的。如果你的任务简单到一步就能完成，那也不值得封装成 skill，直接写 prompt 更快。

它真正发力的地方，是那些步骤多、重复度高、容易出错、需要多人协作的开发流程。补测试、改 bug、代码 review、文档生成、依赖升级，这些任务在大多数团队里都是高频且模式化的，skill 化之后收益很明显。尤其是团队场景，把个人的调教经验固化成 skill，能让整个团队的 AI 使用水平拉齐，减少“只有某个人会用”的瓶颈。

我自己的体会是，这套东西的价值不在于让 AI 变聪明，而在于让 AI 的行为变得可预测、可管理、可传递。模型能力会继续涨，工具会继续换，但“把重复流程抽象成可复用单元”这个思路，在相当长一段时间里都会有效。与其追着每个新工具学一遍，不如花时间把自己的高频流程梳理清楚，用一套框架把它们管起来。工具是流水的，流程和资产是留下来的。

最后分享一个小技巧：如果你刚开始搞，先别急着写 skill 文件，拿一张纸把你一周内重复做过的 AI 辅助任务列出来，按频率排序，挑前三名，每个用自然语言把“触发条件、输入、步骤、输出、禁忌”写一遍。写完之后你会发现，很多你以为很复杂的任务，其实拆开就那么几步。这个过程本身就是一次很好的流程梳理，哪怕你最后不用任何框架，光是这份清单就能让你用 AI 的效率提升一截。