1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后我的第一反应是这东西本质上不是又一个“提示词合集”而是一套把软件开发方法论拆成可复用技能单元的框架。它想干的事情是让 Claude Code、Codex CLI 这类命令行 AI 编程代理从“你问一句它答一句”的被动模式升级成“你给个目标它自己拆任务、自己调工具、自己验证结果”的主动模式。说白了superpowers 是一套面向 AI 编程代理的技能框架。它把软件工程里那些反复出现的动作——读代码、写测试、跑构建、查日志、改配置、做代码审查——抽象成一个个独立的 skill然后让代理在执行任务时按需加载。这个思路和传统的“把一大段系统提示词塞给模型”完全不同。传统做法的问题是提示词越长模型越容易在中途丢失重点而且不同任务需要的上下文差异很大一刀切的提示词必然浪费 token 还降低准确率。superpowers 的做法更像是给代理配了一个“技能工具箱”用到哪个拿哪个。这套框架适合谁来研究我的判断是三类人。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师想把自己的工作流进一步自动化第二类是在搭内部 AI 编程平台的技术团队需要一套可扩展的技能组织方式第三类是对 agentic 工作流感兴趣、想理解“代理怎么自己干活”的产品和架构同学。如果你只是偶尔用 AI 补全几行代码那这套东西对你来说可能偏重但了解一下思路没坏处。我在这篇文章里会把这套框架的设计逻辑、核心机制、实操落地、常见坑都拆开讲。涉及 Claude Code 和 Codex CLI 的安装配置、模型接入、技能编写、调试排查都会给出可以直接抄的操作步骤。内容基于我对这类工具链的实际使用经验以及社区里大量真实反馈的整理不是照搬官方文档。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从单体提示词到技能组合的范式转变要理解 superpowers 的价值得先理解它反对的是什么。早期大家用 Claude Code 或者 Codex CLI基本套路是写一个巨大的 CLAUDE.md 或者 AGENTS.md把项目规范、编码风格、常用命令、注意事项全塞进去。这个做法在项目初期还行但很快会撞到几堵墙。第一堵墙是上下文窗口的边际效益递减。你把 5000 字的规范塞进系统提示模型在前几轮可能还记得但对话一长这些规范就被稀释了。第二堵墙是任务相关性。你写前端组件的时候根本不需要知道数据库迁移的规范你调 CI 配置的时候也不需要知道组件命名约定。一刀切的提示词让模型在无关信息上浪费注意力。第三堵墙是维护成本。规范越写越长改一处要通读全文最后没人敢动。superpowers 的解法是把这些规范按“技能”切分。一个 skill 就是一个独立目录里面有说明文档、有可执行脚本、有触发条件。代理在执行任务时先判断当前任务需要哪些技能再把这些技能的内容加载进上下文。这样每次加载的都是高度相关的信息token 利用率高模型注意力集中维护起来也简单——改一个 skill 不影响其他 skill。这个思路其实借鉴了软件工程里的“关注点分离”原则。你把一个复杂系统拆成高内聚、低耦合的模块每个模块只负责一件事。superpowers 把这个原则应用到了 AI 代理的能力组织上。2.2 技能的生命周期发现、加载、执行、验证一个 skill 在 superpowers 框架里的完整生命周期大致分四个阶段。发现阶段代理接到任务后先扫描可用的 skill 列表。每个 skill 都有一个简短的元数据描述说明它解决什么问题、什么时候该用。代理根据任务描述和这些元数据做匹配决定加载哪些 skill。这一步的关键是元数据要写得精准既不能太宽泛导致误触发也不能太窄导致该用的时候没被选中。加载阶段选中的 skill 内容被注入到代理的上下文中。这里有个设计细节值得注意skill 的内容不是一次性全塞进去而是分层加载。核心指令先加载详细的参考文档和示例代码按需加载。这样即使一个 skill 很复杂也不会一上来就占满上下文。执行阶段代理按照 skill 里定义的步骤执行任务。skill 可以包含具体的命令、代码模板、检查清单。比如一个“写单元测试”的 skill会告诉代理先读被测函数、再确定测试边界、然后生成测试用例、最后跑一遍确认通过。验证阶段执行完之后代理需要验证结果是否符合预期。好的 skill 会内置验证步骤比如“跑测试套件确认全绿”“检查生成的配置文件语法是否正确”。这一步是很多自制 skill 容易忽略的但恰恰是保证可靠性的关键。2.3 和 Claude Code、Codex CLI 的关系superpowers 本身不是一个独立的工具它更像是架在 Claude Code 和 Codex CLI 之上的一层技能组织框架。Claude Code 和 Codex CLI 提供了代理运行的基础能力——读写文件、执行命令、调用模型——而 superpowers 提供了“怎么把这些基础能力组织成可复用工作流”的方法论和具体实现。这就解释了为什么热词里同时出现了 superpowers、Claude Code、Codex CLI。这三者是配套使用的。你用 Claude Code 或 Codex CLI 作为代理运行时用 superpowers 来管理技能三者组合起来才是一套完整的 agentic 开发工作流。理解了这个关系后面的安装配置就有了清晰的脉络先装好代理运行时再接入模型最后配置 superpowers 技能框架。3. 环境准备Claude Code 与 Codex CLI 的安装配置实操3.1 Claude Code 的安装与模型接入Claude Code 的安装方式取决于你的操作系统。在 macOS 和 Linux 上最省事的方式是通过包管理器。以 macOS 为例如果你装了 Homebrew一条命令就能搞定。Ubuntu 用户可以用对应的包管理命令安装。Windows 用户需要注意社区里反馈过“与 64 位版本 Windows 不兼容”的情况通常是因为 Node 运行时的版本或架构不匹配建议先确认 Node 版本在 18 以上并且是 64 位版本。安装完成后的第一件事是配置模型接入。Claude Code 默认走官方模型但很多人想接本地模型或者第三方 API。这里有个关键点Claude Code 的模型配置是通过环境变量和配置文件共同控制的。你可以在项目根目录放一个配置文件指定模型端点、API 密钥、超时时间等参数。接本地模型比如通过 LM Studio 起的本地推理服务的时候要注意几个参数。第一是端点地址通常是本地回环地址加端口第二是模型名称必须和本地服务加载的模型标识一致第三是上下文长度本地模型的上下文窗口往往比云端小配置的时候要如实填写否则代理会在长对话里出错。提示接第三方 API 的时候先确认该 API 是否兼容 Claude Code 使用的消息格式。不兼容的话中间需要加一层转换否则会出现请求格式错误。社区里有个叫 cc switch 的工具用来在多个模型提供商之间切换。它的作用是帮你管理不同提供商的配置一键切换 DeepSeek、Qwen、GLM 等模型。这个工具的思路值得借鉴把模型配置和项目配置分离切换模型不影响项目本身的设置。3.2 Codex CLI 的安装与常用命令Codex CLI 的安装同样依赖 Node 环境。装好之后有几个命令是你必须熟悉的。/compact用来压缩当前对话历史。当你和代理聊了很久上下文快满的时候用这个命令把历史对话压缩成摘要释放上下文空间。这个操作会丢失一些细节所以建议在任务告一段落的时候用不要在任务中途用。/model用来切换当前使用的模型。你可以在会话中随时切换比如写代码用强模型跑简单命令用快模型。/resume用来恢复之前的会话。如果你不小心关了终端或者想接着昨天的进度继续这个命令能帮你找回上下文。删除 Codex CLI 的指令也很直接用对应的包管理卸载命令即可。但要注意卸载之前先备份你的配置文件里面可能有你调了很久才调好的模型参数和技能配置。3.3 VS Code 插件配置与终端命令执行Claude Code 和 Codex CLI 都有 VS Code 插件。插件的好处是你不用离开编辑器就能调用代理而且插件能拿到当前打开的文件、光标位置、选中内容这些上下文代理的响应会更精准。配置插件的时候有几个选项需要留意。第一个是“是否允许代理直接执行终端命令”。这个选项默认可能是关闭的你需要手动打开。打开之后代理就能自己跑构建、跑测试、跑 git 命令。这个能力很强大但也要注意安全边界——建议在受控的项目目录里使用不要在有敏感凭据的环境里放开。第二个是“自动保存”选项。代理改完文件后插件可以自动保存省去你手动保存的步骤。第三个是“diff 预览”选项开启后代理的每次修改都会以 diff 形式展示你可以逐条审查再决定是否接受。Ubuntu 用户配置插件的时候如果遇到权限问题通常是 VS Code 的沙箱限制导致的。可以在设置里调整沙箱策略或者把项目目录加入白名单。4. superpowers 技能框架的落地从零搭一套自己的技能库4.1 技能目录结构设计superpowers 的技能库组织方式我建议按“领域-动作”两级来分。比如frontend/component-scaffold、backend/api-endpoint、devops/ci-config。每个技能一个目录目录里至少包含三个文件SKILL.md写技能说明和触发条件steps.md写具体执行步骤examples/放示例代码或配置。SKILL.md的写法有讲究。开头一段要写清楚“这个技能解决什么问题”这是给代理做匹配用的。然后写“什么时候该用这个技能”列出触发场景。最后写“使用这个技能的前提条件”比如需要哪些工具已安装、需要哪些环境变量已配置。这三段写好了代理才能准确判断该不该加载这个技能。steps.md是执行手册。每一步都要写清楚做什么、用什么命令、预期结果是什么、如果失败怎么排查。步骤要原子化一步只做一件事。这样代理执行的时候哪一步出错一目了然。4.2 技能触发条件的写法与调试触发条件是整个技能框架里最容易出问题的地方。写得太宽代理动不动就加载一堆无关技能浪费上下文写得太窄该用的时候不加载代理就自己瞎猜。我的经验是触发条件里要同时包含“正向信号”和“负向信号”。正向信号是“出现这些关键词或场景时加载”负向信号是“出现这些情况时不要加载”。比如一个“数据库迁移”技能正向信号是“涉及 schema 变更、涉及 migration 文件”负向信号是“只是查询数据、只是改索引名”。调试触发条件有个笨办法但很有效拿一批历史任务描述手动跑一遍匹配逻辑看哪些该匹配的没匹配上哪些不该匹配的匹配上了。根据结果调整关键词和场景描述。这个工作做一轮触发准确率能提升不少。4.3 技能之间的依赖与组合真实任务往往需要多个技能组合。比如“新增一个 API 接口”这个任务可能需要“读现有接口规范”“生成接口代码”“写接口测试”“更新接口文档”四个技能。superpowers 支持技能之间的依赖声明你可以在SKILL.md里写“本技能依赖 xxx 技能”代理加载时会自动把依赖的技能也带上。组合技能的时候要注意执行顺序。有些技能有先后依赖比如必须先读规范再生成代码。这个顺序要在技能定义里写清楚不能指望代理自己推断。代理再聪明也不如你明确告诉它先做什么后做什么来得可靠。注意技能组合不要超过五个。超过五个之后上下文里塞的东西太多代理的注意力会被分散执行质量反而下降。如果任务确实复杂拆成多个子任务分轮执行。5. 实操全流程用 superpowers 完成一个真实开发任务5.1 任务定义与技能匹配假设我们要完成的任务是“给现有项目加一个用户头像上传接口”。这个任务涉及后端接口、文件存储、数据库字段、接口测试、文档更新。我先把这个任务描述写清楚然后让代理做技能匹配。代理匹配到的技能可能有backend/api-endpoint生成接口骨架、backend/file-upload处理文件上传、database/schema-change加字段、testing/api-test写接口测试、docs/api-doc更新文档。五个技能刚好在建议上限内。匹配完之后代理会把这五个技能的内容加载进上下文。这时候你可以检查一下加载了哪些技能如果发现多了或少了手动调整。这个检查步骤很重要我见过太多人直接让代理开跑结果跑偏了才发现技能加载错了。5.2 分步执行与中间验证执行阶段我建议开启“逐步确认”模式。代理每完成一个技能的执行就暂停一下让你确认结果再继续。这样虽然慢一点但能及早发现问题避免一路错到底。第一步执行database/schema-change代理会生成一个迁移文件给用户表加一个头像字段。生成完之后代理会跑迁移命令然后查一下表结构确认字段加上了。这一步的验证点是迁移文件语法正确、迁移执行成功、字段类型和长度符合预期。第二步执行backend/file-upload代理会生成文件上传的处理逻辑。这里有个细节要注意文件存储路径、文件大小限制、允许的文件类型这些参数要在技能配置里提前定好不要让代理自己决定。代理默认生成的可能不符合你的项目规范。第三步执行backend/api-endpoint代理生成接口路由和控制器。第四步执行testing/api-test代理写测试用例并跑一遍。第五步执行docs/api-doc代理更新接口文档。每一步的验证结果都要记录。如果某一步失败先排查是技能本身的问题还是任务描述的问题。技能问题就改技能任务描述问题就改描述。这个排查过程本身就是对技能库的打磨。5.3 结果验收与技能库迭代任务完成后做一次整体验收。跑一遍完整测试套件确认没有回归问题。检查生成的代码是否符合项目规范检查文档是否准确。验收通过后把这次任务中发现的技能问题记录下来回头改进技能定义。技能库的迭代是个持续过程。每用一次就发现一些可以改进的地方。触发条件可以更精准步骤可以更细致示例可以更丰富。用上十几次之后你的技能库就会变得相当好用代理的执行质量也会明显提升。6. 常见问题与排查技巧实录6.1 安装与配置类问题问题一Claude Code 提示“在你所在的国家不可用”。这个提示通常和账号注册地区有关。社区里的经验是注册账号时填写的地区信息会影响可用性。如果你遇到这个提示检查一下账号的地区设置。另外有些第三方 API 提供商不受这个限制可以考虑通过第三方 API 接入。问题二Windows 上提示“与 64 位版本不兼容”。这个问题九成是 Node 运行时的问题。先确认node -v输出的版本号再确认node -p process.arch输出的是x64还是ia32。如果是ia32说明你装的是 32 位 Node需要卸载后重装 64 位版本。问题三VS Code 插件连不上代理。先检查代理的 CLI 是否能在终端正常跑。如果 CLI 正常但插件连不上通常是插件的路径配置问题。在插件设置里手动指定 CLI 的完整路径试试。6.2 技能加载与执行类问题问题四代理不加载任何技能。先检查技能目录的位置是否正确。superpowers 默认从项目根目录的特定子目录读取技能如果你把技能放在别的地方需要在配置里指定路径。再检查SKILL.md的元数据格式是否符合要求格式错误会导致技能被跳过。问题五代理加载了错误的技能。这是触发条件写得太宽导致的。检查触发关键词是不是太泛比如用了“代码”这种万能词。把关键词收窄到具体的技术名词和动作词。问题六技能执行到一半卡住。常见原因是技能步骤里有一条命令需要交互式输入而代理没法处理交互。解决办法是在技能定义里给这条命令加上非交互参数或者用管道把输入提前喂进去。6.3 模型接入类问题问题七接本地模型后响应质量明显下降。本地模型的参数量通常比云端小复杂任务的执行能力会弱一些。建议把复杂任务拆成更小的步骤每个步骤的指令写得更明确。另外检查一下本地模型的上下文窗口设置如果设得太小代理会丢失中间步骤的信息。问题八第三方 API 调用频繁超时。先确认网络连通性再检查 API 的速率限制。有些第三方 API 对并发请求有限制代理如果同时发多个请求会被限流。在配置里把并发数调低试试。问题九切换模型后技能行为不一致。不同模型对同一段技能描述的理解可能有差异。切换模型后建议先跑一个简单任务验证一下确认技能加载和执行都正常再跑正式任务。6.4 常见问题速查表问题现象可能原因排查方向代理不加载技能技能路径错误或元数据格式错误检查目录位置和 SKILL.md 格式加载了无关技能触发条件过宽收窄关键词增加负向信号执行中途卡住命令需要交互输入加非交互参数或预喂输入本地模型质量差模型能力不足或上下文太小拆细任务调大上下文窗口API 频繁超时网络问题或速率限制检查连通性降低并发切换模型后行为异常模型理解差异先跑简单任务验证7. 我踩过的坑和几条实用建议第一个坑是技能写得太大。我一开始把“后端开发”写成一个技能结果这个技能文件几千字代理加载后根本抓不住重点。后来拆成“接口生成”“数据库操作”“文件处理”三个独立技能每个控制在几百字效果立刻好了。技能粒度宁可细一点也不要粗。第二个坑是忽略验证步骤。早期我写的技能只有“做什么”没有“怎么确认做对了”。代理执行完就往下走错了也不知道。后来每个技能都加上验证步骤比如“跑测试确认通过”“检查文件语法”可靠性提升明显。第三个坑是技能库不维护。用了一段时间后技能定义和项目实际情况脱节了代理按老技能执行会出错。现在我养成了习惯每次项目结构或规范有变化就同步更新相关技能。技能库和代码库一样需要持续维护。几条实用建议。技能描述用主动语态别用被动语态代理对主动语态的理解更准。技能步骤用编号列表别用大段文字代理按编号执行不容易漏。技能示例要真实可运行别放伪代码代理会照着示例的风格生成代码。技能版本要管理改之前先备份改坏了能回滚。最后分享一个提高技能匹配准确率的小技巧在技能元数据里加一个“反例”字段写清楚“这个技能不适用于什么场景”。代理看到反例会主动排除匹配准确率能提升不少。这个字段官方文档里没提是我自己试出来的实测有效。 
长河君 · 2026/10/6 13:42:59 · 阅读 1.2k superpowers 技能框架：Claude Code 与 Codex CLI 的 agentic 工作流实战
1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后我的第一反应是这东西本质上不是又一个“提示词合集”而是一套把软件开发方法论拆成可复用技能单元的框架。它想干的事情是让 Claude Code、Codex CLI 这类命令行 AI 编程代理从“你问一句它答一句”的被动模式升级成“你给个目标它自己拆任务、自己调工具、自己验证结果”的主动模式。说白了superpowers 是一套面向 AI 编程代理的技能框架。它把软件工程里那些反复出现的动作——读代码、写测试、跑构建、查日志、改配置、做代码审查——抽象成一个个独立的 skill然后让代理在执行任务时按需加载。这个思路和传统的“把一大段系统提示词塞给模型”完全不同。传统做法的问题是提示词越长模型越容易在中途丢失重点而且不同任务需要的上下文差异很大一刀切的提示词必然浪费 token 还降低准确率。superpowers 的做法更像是给代理配了一个“技能工具箱”用到哪个拿哪个。这套框架适合谁来研究我的判断是三类人。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师想把自己的工作流进一步自动化第二类是在搭内部 AI 编程平台的技术团队需要一套可扩展的技能组织方式第三类是对 agentic 工作流感兴趣、想理解“代理怎么自己干活”的产品和架构同学。如果你只是偶尔用 AI 补全几行代码那这套东西对你来说可能偏重但了解一下思路没坏处。我在这篇文章里会把这套框架的设计逻辑、核心机制、实操落地、常见坑都拆开讲。涉及 Claude Code 和 Codex CLI 的安装配置、模型接入、技能编写、调试排查都会给出可以直接抄的操作步骤。内容基于我对这类工具链的实际使用经验以及社区里大量真实反馈的整理不是照搬官方文档。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从单体提示词到技能组合的范式转变要理解 superpowers 的价值得先理解它反对的是什么。早期大家用 Claude Code 或者 Codex CLI基本套路是写一个巨大的 CLAUDE.md 或者 AGENTS.md把项目规范、编码风格、常用命令、注意事项全塞进去。这个做法在项目初期还行但很快会撞到几堵墙。第一堵墙是上下文窗口的边际效益递减。你把 5000 字的规范塞进系统提示模型在前几轮可能还记得但对话一长这些规范就被稀释了。第二堵墙是任务相关性。你写前端组件的时候根本不需要知道数据库迁移的规范你调 CI 配置的时候也不需要知道组件命名约定。一刀切的提示词让模型在无关信息上浪费注意力。第三堵墙是维护成本。规范越写越长改一处要通读全文最后没人敢动。superpowers 的解法是把这些规范按“技能”切分。一个 skill 就是一个独立目录里面有说明文档、有可执行脚本、有触发条件。代理在执行任务时先判断当前任务需要哪些技能再把这些技能的内容加载进上下文。这样每次加载的都是高度相关的信息token 利用率高模型注意力集中维护起来也简单——改一个 skill 不影响其他 skill。这个思路其实借鉴了软件工程里的“关注点分离”原则。你把一个复杂系统拆成高内聚、低耦合的模块每个模块只负责一件事。superpowers 把这个原则应用到了 AI 代理的能力组织上。2.2 技能的生命周期发现、加载、执行、验证一个 skill 在 superpowers 框架里的完整生命周期大致分四个阶段。发现阶段代理接到任务后先扫描可用的 skill 列表。每个 skill 都有一个简短的元数据描述说明它解决什么问题、什么时候该用。代理根据任务描述和这些元数据做匹配决定加载哪些 skill。这一步的关键是元数据要写得精准既不能太宽泛导致误触发也不能太窄导致该用的时候没被选中。加载阶段选中的 skill 内容被注入到代理的上下文中。这里有个设计细节值得注意skill 的内容不是一次性全塞进去而是分层加载。核心指令先加载详细的参考文档和示例代码按需加载。这样即使一个 skill 很复杂也不会一上来就占满上下文。执行阶段代理按照 skill 里定义的步骤执行任务。skill 可以包含具体的命令、代码模板、检查清单。比如一个“写单元测试”的 skill会告诉代理先读被测函数、再确定测试边界、然后生成测试用例、最后跑一遍确认通过。验证阶段执行完之后代理需要验证结果是否符合预期。好的 skill 会内置验证步骤比如“跑测试套件确认全绿”“检查生成的配置文件语法是否正确”。这一步是很多自制 skill 容易忽略的但恰恰是保证可靠性的关键。2.3 和 Claude Code、Codex CLI 的关系superpowers 本身不是一个独立的工具它更像是架在 Claude Code 和 Codex CLI 之上的一层技能组织框架。Claude Code 和 Codex CLI 提供了代理运行的基础能力——读写文件、执行命令、调用模型——而 superpowers 提供了“怎么把这些基础能力组织成可复用工作流”的方法论和具体实现。这就解释了为什么热词里同时出现了 superpowers、Claude Code、Codex CLI。这三者是配套使用的。你用 Claude Code 或 Codex CLI 作为代理运行时用 superpowers 来管理技能三者组合起来才是一套完整的 agentic 开发工作流。理解了这个关系后面的安装配置就有了清晰的脉络先装好代理运行时再接入模型最后配置 superpowers 技能框架。3. 环境准备Claude Code 与 Codex CLI 的安装配置实操3.1 Claude Code 的安装与模型接入Claude Code 的安装方式取决于你的操作系统。在 macOS 和 Linux 上最省事的方式是通过包管理器。以 macOS 为例如果你装了 Homebrew一条命令就能搞定。Ubuntu 用户可以用对应的包管理命令安装。Windows 用户需要注意社区里反馈过“与 64 位版本 Windows 不兼容”的情况通常是因为 Node 运行时的版本或架构不匹配建议先确认 Node 版本在 18 以上并且是 64 位版本。安装完成后的第一件事是配置模型接入。Claude Code 默认走官方模型但很多人想接本地模型或者第三方 API。这里有个关键点Claude Code 的模型配置是通过环境变量和配置文件共同控制的。你可以在项目根目录放一个配置文件指定模型端点、API 密钥、超时时间等参数。接本地模型比如通过 LM Studio 起的本地推理服务的时候要注意几个参数。第一是端点地址通常是本地回环地址加端口第二是模型名称必须和本地服务加载的模型标识一致第三是上下文长度本地模型的上下文窗口往往比云端小配置的时候要如实填写否则代理会在长对话里出错。提示接第三方 API 的时候先确认该 API 是否兼容 Claude Code 使用的消息格式。不兼容的话中间需要加一层转换否则会出现请求格式错误。社区里有个叫 cc switch 的工具用来在多个模型提供商之间切换。它的作用是帮你管理不同提供商的配置一键切换 DeepSeek、Qwen、GLM 等模型。这个工具的思路值得借鉴把模型配置和项目配置分离切换模型不影响项目本身的设置。3.2 Codex CLI 的安装与常用命令Codex CLI 的安装同样依赖 Node 环境。装好之后有几个命令是你必须熟悉的。/compact用来压缩当前对话历史。当你和代理聊了很久上下文快满的时候用这个命令把历史对话压缩成摘要释放上下文空间。这个操作会丢失一些细节所以建议在任务告一段落的时候用不要在任务中途用。/model用来切换当前使用的模型。你可以在会话中随时切换比如写代码用强模型跑简单命令用快模型。/resume用来恢复之前的会话。如果你不小心关了终端或者想接着昨天的进度继续这个命令能帮你找回上下文。删除 Codex CLI 的指令也很直接用对应的包管理卸载命令即可。但要注意卸载之前先备份你的配置文件里面可能有你调了很久才调好的模型参数和技能配置。3.3 VS Code 插件配置与终端命令执行Claude Code 和 Codex CLI 都有 VS Code 插件。插件的好处是你不用离开编辑器就能调用代理而且插件能拿到当前打开的文件、光标位置、选中内容这些上下文代理的响应会更精准。配置插件的时候有几个选项需要留意。第一个是“是否允许代理直接执行终端命令”。这个选项默认可能是关闭的你需要手动打开。打开之后代理就能自己跑构建、跑测试、跑 git 命令。这个能力很强大但也要注意安全边界——建议在受控的项目目录里使用不要在有敏感凭据的环境里放开。第二个是“自动保存”选项。代理改完文件后插件可以自动保存省去你手动保存的步骤。第三个是“diff 预览”选项开启后代理的每次修改都会以 diff 形式展示你可以逐条审查再决定是否接受。Ubuntu 用户配置插件的时候如果遇到权限问题通常是 VS Code 的沙箱限制导致的。可以在设置里调整沙箱策略或者把项目目录加入白名单。4. superpowers 技能框架的落地从零搭一套自己的技能库4.1 技能目录结构设计superpowers 的技能库组织方式我建议按“领域-动作”两级来分。比如frontend/component-scaffold、backend/api-endpoint、devops/ci-config。每个技能一个目录目录里至少包含三个文件SKILL.md写技能说明和触发条件steps.md写具体执行步骤examples/放示例代码或配置。SKILL.md的写法有讲究。开头一段要写清楚“这个技能解决什么问题”这是给代理做匹配用的。然后写“什么时候该用这个技能”列出触发场景。最后写“使用这个技能的前提条件”比如需要哪些工具已安装、需要哪些环境变量已配置。这三段写好了代理才能准确判断该不该加载这个技能。steps.md是执行手册。每一步都要写清楚做什么、用什么命令、预期结果是什么、如果失败怎么排查。步骤要原子化一步只做一件事。这样代理执行的时候哪一步出错一目了然。4.2 技能触发条件的写法与调试触发条件是整个技能框架里最容易出问题的地方。写得太宽代理动不动就加载一堆无关技能浪费上下文写得太窄该用的时候不加载代理就自己瞎猜。我的经验是触发条件里要同时包含“正向信号”和“负向信号”。正向信号是“出现这些关键词或场景时加载”负向信号是“出现这些情况时不要加载”。比如一个“数据库迁移”技能正向信号是“涉及 schema 变更、涉及 migration 文件”负向信号是“只是查询数据、只是改索引名”。调试触发条件有个笨办法但很有效拿一批历史任务描述手动跑一遍匹配逻辑看哪些该匹配的没匹配上哪些不该匹配的匹配上了。根据结果调整关键词和场景描述。这个工作做一轮触发准确率能提升不少。4.3 技能之间的依赖与组合真实任务往往需要多个技能组合。比如“新增一个 API 接口”这个任务可能需要“读现有接口规范”“生成接口代码”“写接口测试”“更新接口文档”四个技能。superpowers 支持技能之间的依赖声明你可以在SKILL.md里写“本技能依赖 xxx 技能”代理加载时会自动把依赖的技能也带上。组合技能的时候要注意执行顺序。有些技能有先后依赖比如必须先读规范再生成代码。这个顺序要在技能定义里写清楚不能指望代理自己推断。代理再聪明也不如你明确告诉它先做什么后做什么来得可靠。注意技能组合不要超过五个。超过五个之后上下文里塞的东西太多代理的注意力会被分散执行质量反而下降。如果任务确实复杂拆成多个子任务分轮执行。5. 实操全流程用 superpowers 完成一个真实开发任务5.1 任务定义与技能匹配假设我们要完成的任务是“给现有项目加一个用户头像上传接口”。这个任务涉及后端接口、文件存储、数据库字段、接口测试、文档更新。我先把这个任务描述写清楚然后让代理做技能匹配。代理匹配到的技能可能有backend/api-endpoint生成接口骨架、backend/file-upload处理文件上传、database/schema-change加字段、testing/api-test写接口测试、docs/api-doc更新文档。五个技能刚好在建议上限内。匹配完之后代理会把这五个技能的内容加载进上下文。这时候你可以检查一下加载了哪些技能如果发现多了或少了手动调整。这个检查步骤很重要我见过太多人直接让代理开跑结果跑偏了才发现技能加载错了。5.2 分步执行与中间验证执行阶段我建议开启“逐步确认”模式。代理每完成一个技能的执行就暂停一下让你确认结果再继续。这样虽然慢一点但能及早发现问题避免一路错到底。第一步执行database/schema-change代理会生成一个迁移文件给用户表加一个头像字段。生成完之后代理会跑迁移命令然后查一下表结构确认字段加上了。这一步的验证点是迁移文件语法正确、迁移执行成功、字段类型和长度符合预期。第二步执行backend/file-upload代理会生成文件上传的处理逻辑。这里有个细节要注意文件存储路径、文件大小限制、允许的文件类型这些参数要在技能配置里提前定好不要让代理自己决定。代理默认生成的可能不符合你的项目规范。第三步执行backend/api-endpoint代理生成接口路由和控制器。第四步执行testing/api-test代理写测试用例并跑一遍。第五步执行docs/api-doc代理更新接口文档。每一步的验证结果都要记录。如果某一步失败先排查是技能本身的问题还是任务描述的问题。技能问题就改技能任务描述问题就改描述。这个排查过程本身就是对技能库的打磨。5.3 结果验收与技能库迭代任务完成后做一次整体验收。跑一遍完整测试套件确认没有回归问题。检查生成的代码是否符合项目规范检查文档是否准确。验收通过后把这次任务中发现的技能问题记录下来回头改进技能定义。技能库的迭代是个持续过程。每用一次就发现一些可以改进的地方。触发条件可以更精准步骤可以更细致示例可以更丰富。用上十几次之后你的技能库就会变得相当好用代理的执行质量也会明显提升。6. 常见问题与排查技巧实录6.1 安装与配置类问题问题一Claude Code 提示“在你所在的国家不可用”。这个提示通常和账号注册地区有关。社区里的经验是注册账号时填写的地区信息会影响可用性。如果你遇到这个提示检查一下账号的地区设置。另外有些第三方 API 提供商不受这个限制可以考虑通过第三方 API 接入。问题二Windows 上提示“与 64 位版本不兼容”。这个问题九成是 Node 运行时的问题。先确认node -v输出的版本号再确认node -p process.arch输出的是x64还是ia32。如果是ia32说明你装的是 32 位 Node需要卸载后重装 64 位版本。问题三VS Code 插件连不上代理。先检查代理的 CLI 是否能在终端正常跑。如果 CLI 正常但插件连不上通常是插件的路径配置问题。在插件设置里手动指定 CLI 的完整路径试试。6.2 技能加载与执行类问题问题四代理不加载任何技能。先检查技能目录的位置是否正确。superpowers 默认从项目根目录的特定子目录读取技能如果你把技能放在别的地方需要在配置里指定路径。再检查SKILL.md的元数据格式是否符合要求格式错误会导致技能被跳过。问题五代理加载了错误的技能。这是触发条件写得太宽导致的。检查触发关键词是不是太泛比如用了“代码”这种万能词。把关键词收窄到具体的技术名词和动作词。问题六技能执行到一半卡住。常见原因是技能步骤里有一条命令需要交互式输入而代理没法处理交互。解决办法是在技能定义里给这条命令加上非交互参数或者用管道把输入提前喂进去。6.3 模型接入类问题问题七接本地模型后响应质量明显下降。本地模型的参数量通常比云端小复杂任务的执行能力会弱一些。建议把复杂任务拆成更小的步骤每个步骤的指令写得更明确。另外检查一下本地模型的上下文窗口设置如果设得太小代理会丢失中间步骤的信息。问题八第三方 API 调用频繁超时。先确认网络连通性再检查 API 的速率限制。有些第三方 API 对并发请求有限制代理如果同时发多个请求会被限流。在配置里把并发数调低试试。问题九切换模型后技能行为不一致。不同模型对同一段技能描述的理解可能有差异。切换模型后建议先跑一个简单任务验证一下确认技能加载和执行都正常再跑正式任务。6.4 常见问题速查表问题现象可能原因排查方向代理不加载技能技能路径错误或元数据格式错误检查目录位置和 SKILL.md 格式加载了无关技能触发条件过宽收窄关键词增加负向信号执行中途卡住命令需要交互输入加非交互参数或预喂输入本地模型质量差模型能力不足或上下文太小拆细任务调大上下文窗口API 频繁超时网络问题或速率限制检查连通性降低并发切换模型后行为异常模型理解差异先跑简单任务验证7. 我踩过的坑和几条实用建议第一个坑是技能写得太大。我一开始把“后端开发”写成一个技能结果这个技能文件几千字代理加载后根本抓不住重点。后来拆成“接口生成”“数据库操作”“文件处理”三个独立技能每个控制在几百字效果立刻好了。技能粒度宁可细一点也不要粗。第二个坑是忽略验证步骤。早期我写的技能只有“做什么”没有“怎么确认做对了”。代理执行完就往下走错了也不知道。后来每个技能都加上验证步骤比如“跑测试确认通过”“检查文件语法”可靠性提升明显。第三个坑是技能库不维护。用了一段时间后技能定义和项目实际情况脱节了代理按老技能执行会出错。现在我养成了习惯每次项目结构或规范有变化就同步更新相关技能。技能库和代码库一样需要持续维护。几条实用建议。技能描述用主动语态别用被动语态代理对主动语态的理解更准。技能步骤用编号列表别用大段文字代理按编号执行不容易漏。技能示例要真实可运行别放伪代码代理会照着示例的风格生成代码。技能版本要管理改之前先备份改坏了能回滚。最后分享一个提高技能匹配准确率的小技巧在技能元数据里加一个“反例”字段写清楚“这个技能不适用于什么场景”。代理看到反例会主动排除匹配准确率能提升不少。这个字段官方文档里没提是我自己试出来的实测有效。