1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接说“这玩意儿把 Claude Code 和 Codex CLI 的玩法又往上抬了一层”。我当时的第一反应是又是一个包装概念的东西吧但真正花了一个周末把它的思路拆开、在自己的项目里跑了一遍之后我改主意了——它确实解决了一个很实际的问题。先说清楚 superpowers 是什么。它不是某个具体的软件也不是一个能一键安装的插件而是一套agentic skills framework翻译过来大概叫“智能体技能框架”。核心思路是把软件开发过程中那些重复出现的、有固定套路的任务抽象成一个个可复用的“技能skill”然后让 AI 编程助手比如 Claude Code、Codex CLI 这类命令行智能体在合适的时机自动调用这些技能而不是每次都从零开始“即兴发挥”。这解决的是什么问题用过 Claude Code 或者 Codex CLI 的人都知道这些工具很强但强得有点“随性”。你让它改个 bug它可能给你重写整个文件你让它加个功能它可能顺手把你没让它动的代码也重构了。每次对话都像开盲盒结果好坏很大程度上取决于你 prompt 写得好不好、模型当天状态怎么样。superpowers 想做的就是给这种“随性”套上一个方法论的外壳——用一套结构化的技能定义把“什么时候该做什么、怎么做、做完怎么验证”固化下来。这套东西适合谁我觉得有三类人值得花时间研究。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师你已经有基本的工具使用经验但总觉得输出不够稳定想让 AI 的行为更可控。第二类是团队里负责制定开发规范的人你想把团队的编码习惯、review 流程、测试标准“喂”给 AI让它按你们的规矩干活。第三类是对 agentic 开发方法论感兴趣的技术管理者你想搞清楚这套东西到底能不能落地值不值得在团队里推。需要提前说明的是superpowers 本身是一个方法论层面的框架它的具体落地高度依赖你用的 AI 编程工具。目前社区里讨论最多的组合是 Claude Code 加 Codex CLI前者负责交互式的代码修改和终端操作后者负责批量任务和自动化流程。所以这篇文章会围绕这两个工具展开但框架本身的思路是通用的你换成别的 agent 工具也能套。2. 核心思路拆解为什么要把“技能”从“对话”里抽出来2.1 传统 AI 编程的痛点每次都在重新发明轮子我先说说没有 superpowers 之前大家是怎么用 Claude Code 的。典型流程是这样的打开终端输入claude然后开始对话。“帮我看看这个函数为什么报错”“把这个接口改成支持分页”“给这个模块补一下单元测试”。每次都是自然语言描述需求AI 理解后直接动手改代码。这个模式在简单任务上没问题但一旦任务复杂起来问题就暴露了。最典型的是上下文漂移你跟 AI 聊了十几轮之后它可能已经忘了你最开始定的那些约束条件。比如你一开始说“不要引入新的第三方依赖”聊到后面它可能就给你加了个 lodash。另一个问题是行为不一致同样的需求你今天问和明天问它给出的方案可能完全不同因为模型本身有随机性而且你的 prompt 措辞也会有细微差别。还有一个更隐蔽的问题知识无法沉淀。你这次教会了 AI 怎么按你的规范写测试下次开一个新会话它又忘了。你只能把同样的要求再写一遍。这就导致每次使用 AI 编程工具都像是在带一个记忆力只有七秒的实习生你得反复交代同样的事情。2.2 superpowers 的解法把“怎么做”固化成技能superpowers 的核心洞察是软件开发中有大量任务是可模式化的。比如“写一个符合项目规范的 React 组件”“给一个函数补测试”“做一次代码 review”“修复一个 lint 错误”。这些任务的输入输出相对固定执行步骤也有章可循。既然这样为什么不把它们写成一份份“技能说明书”让 AI 在遇到对应场景时直接照着执行这就是 agentic skills framework 的基本形态。一个 skill 通常包含几个部分触发条件什么情况下该用这个技能、执行步骤具体怎么做分几步、约束条件不能做什么必须满足什么、验证标准做完之后怎么确认做对了。你可以把它理解成一份写给 AI 看的 SOP标准作业程序。这样做的好处很直接。第一输出稳定性大幅提升。因为执行路径是预先定义好的AI 的自由发挥空间被压缩结果的可预测性就上来了。第二知识可以复用。你花时间写好一个 skill之后所有会话都能用不用反复交代。第三团队协作有了抓手。skill 文件可以进版本控制可以 code review可以迭代改进这就把 AI 的使用从“个人技巧”变成了“团队资产”。2.3 为什么是 Claude Code 和 Codex CLI 这个组合社区里讨论 superpowers 时几乎都会提到 Claude Code 和 Codex CLI。这不是偶然的。Claude Code 的优势在于交互式终端操作它能直接在你的项目目录里读写文件、执行命令、跑测试而且对上下文的理解比较细腻。Codex CLI 的优势在于批量处理和自动化它更适合跑那种“给定一批任务逐个执行”的场景而且它的命令体系比如/compact、/model、/resume这些设计得比较适合脚本化调用。把两者结合起来一个典型的 superpowers 工作流是这样的用 Claude Code 做探索性的、需要来回讨论的任务比如“帮我分析这个模块的架构问题”用 Codex CLI 做确定性的、可以批量执行的任务比如“把 src 目录下所有不符合新 lint 规则的文件的修复一遍”。两者共享同一套 skill 定义保证行为一致。这里要补充一个实操细节。很多人卡在第一步怎么让这两个工具都能读到你的 skill 文件。常见做法是在项目根目录建一个.skills或者.agent目录里面放 markdown 格式的 skill 定义。然后在 Claude Code 的配置里通常是CLAUDE.md或者项目级的配置文件声明这个目录Codex CLI 那边则通过它的配置文件或者启动参数指定。具体路径和配置方式各版本可能有差异建议以你所用版本的官方文档为准但思路是通用的让 skill 文件成为项目的一部分而不是散落在各个会话里。3. 核心细节解析一个 skill 到底该怎么写3.1 skill 的结构触发、步骤、约束、验证写 skill 这件事看起来简单实际上很考验功力。我见过不少人写的 skill要么太笼统“写好代码”要么太琐碎把每一行代码都规定死这两种都不可取。一个好的 skill 应该像一份给资深工程师的 brief说清楚目标和边界但保留合理的执行空间。我自己的经验是一个 skill 至少包含四个部分。触发条件要写得具体比如“当用户要求新增一个 API 端点时”而不是“当涉及后端开发时”。执行步骤要分点但每点不要太细比如“1. 在 routes 目录下创建对应的路由文件2. 在 controllers 目录下实现业务逻辑3. 在 tests 目录下补充集成测试”而不是把每个函数名都写死。约束条件是最容易被忽略但最重要的部分比如“不得引入新的 npm 依赖”“所有数据库操作必须走 ORM 层”“错误处理必须使用项目统一的 errorHandler”。验证标准要可执行比如“运行npm test必须全部通过”“运行npm run lint不得有 error 级别的问题”。3.2 触发条件的设计让 AI 知道“什么时候该用”触发条件是 skill 的入口写不好就会出现两种情况该用的时候没用不该用的时候乱用。我的做法是触发条件里同时包含正向信号和负向信号。正向信号是“出现这些关键词或场景时启用”负向信号是“即使出现这些词如果同时满足某些条件也不要启用”。举个例子。假设你写了一个“数据库迁移”的 skill。正向信号可以是“用户提到 schema 变更、新增字段、修改表结构”。负向信号可以是“如果变更只涉及索引优化且不影响数据模型则不走这个 skill直接改 migration 文件即可”。这样 AI 在判断时就有了更明确的依据不会一看到“数据库”三个字就触发迁移流程。还有一个技巧给触发条件加上优先级。当多个 skill 都可能匹配时AI 需要知道先执行哪个。比如“修复 bug”和“重构代码”这两个 skill 可能同时被触发你可以规定“当任务是修复明确的功能缺陷时优先走 bug 修复 skill只有在用户明确要求改善代码结构时才走重构 skill”。这个优先级规则最好写在 skill 文件的头部方便 AI 快速判断。3.3 约束条件的写法把“不要做什么”说清楚约束条件是 skill 里最体现经验的部分。新手写 skill 往往只写“要做什么”但真正让输出可控的是“不要做什么”。我踩过的坑是早期写了一个“生成 React 组件”的 skill步骤写得很详细但没写约束结果 AI 每次生成的组件风格都不一样有的用函数式组件有的用 class 组件有的用 CSS Modules有的用 styled-components整个项目风格就乱了。后来我加了几条约束“统一使用函数式组件 hooks”“样式一律使用项目已有的 CSS Modules 方案”“不得引入 styled-components 或 emotion”“组件文件必须包含 PropTypes 或 TypeScript 类型定义”。加完之后生成的组件风格立刻统一了。约束条件还有一个作用是防止 AI 过度发挥。比如你让它改一个函数它可能顺手把整个文件格式化了一遍导致 diff 里全是无关改动。你可以在约束里写“只修改与任务直接相关的代码行不得进行无关的格式化或重构”。这条看起来有点“小气”但在实际协作中非常有用能省掉大量 review 时的噪音。3.4 验证标准怎么确认 AI 真的做对了验证标准是很多人会跳过的一步但我觉得它恰恰是 superpowers 这套框架最有价值的部分之一。因为 AI 编程最大的风险不是“做不出来”而是“做出来了但你看不出来它做错了”。一个明确的验证标准能让你在 AI 交付后快速判断结果是否可用。验证标准要尽量可自动化执行。比如“运行npm test全部通过”“运行npm run build无报错”“运行npm run lint无 error”“用 curl 请求新端点返回 200 且响应体符合预期”。这些命令可以直接写进 skill 文件让 AI 在执行完任务后自己跑一遍把结果贴出来。这样你 review 的时候第一眼就能看到“测试过了没”“构建过了没”而不是从头读代码。对于无法自动化的验证比如“代码可读性”“命名是否合理”可以写成检查清单让 AI 在交付前逐条自查。虽然这种自查不一定百分百可靠但至少能过滤掉一部分低级问题。4. 实操过程从零搭一套可用的 skill 体系4.1 环境准备Claude Code 和 Codex CLI 的安装与配置先把工具装好。Claude Code 的安装方式取决于你的系统。macOS 和 Linux 上通常是通过 npm 全局安装命令大概是npm install -g anthropic-ai/claude-code然后运行claude启动。Windows 上要注意有些版本对 64 位系统的兼容性有问题如果遇到安装失败可以试试用 WSL 或者检查一下 Node 版本。安装完成后第一次运行会引导你登录或配置 API。Codex CLI 的安装类似也是 npm 全局安装。装完之后你可以用codex命令启动交互模式也可以用codex run跑单次任务。它有几个常用命令值得记住/compact用来压缩上下文当对话太长时很有用/model用来切换模型/resume用来恢复之前的会话。这些命令在跑长任务时能帮你省不少事。配置方面两个工具都支持通过配置文件指定模型、API 端点、项目级指令等。如果你用的是第三方 API 或者本地模型比如通过 LM Studio 跑的模型需要在配置里改 base URL 和 model name。这里有个坑不同工具对 API 格式的要求可能不一样有的要求 OpenAI 兼容格式有的有自己的格式配置前最好先确认清楚。另外如果你在 VS Code 里用 Claude Code 插件配置方式又不一样通常是在插件的设置面板里填 API key 和模型信息。提示安装过程中如果遇到“your organization has disabled claude subscription access”之类的提示通常是账号权限或订阅状态的问题跟工具本身无关。先确认你的账号状态再排查工具配置。4.2 建立 skill 目录结构让项目自己“带说明书”工具装好后下一步是在项目里建立 skill 目录。我的习惯是在项目根目录建一个.agent/skills/目录里面按类别放 skill 文件。比如.agent/ skills/ frontend/ react-component.md css-module.md backend/ api-endpoint.md db-migration.md workflow/ bug-fix.md code-review.md test-coverage.md每个 skill 是一个 markdown 文件文件名就是 skill 的名字。这样组织的好处是AI 在扫描目录时能快速定位到相关 skill你也能一眼看出项目里有哪些“技能”可用。然后需要在 Claude Code 和 Codex CLI 的配置里声明这个目录。Claude Code 通常是在CLAUDE.md里写一段说明告诉它去.agent/skills/目录读取 skill 定义。Codex CLI 则可能需要在它的配置文件里指定 skill 路径或者在启动时通过参数传入。具体写法各版本有差异但核心就是让工具知道“去哪里找技能”。4.3 写第一个 skill以“新增 API 端点”为例我拿一个实际用过的 skill 来演示。假设你的项目是一个 Node.js 后端用 Express 框架有固定的目录结构routes、controllers、services、tests。你要写一个“新增 API 端点”的 skill。文件内容大概长这样# Skill: 新增 API 端点 ## 触发条件 - 用户要求新增一个 HTTP 接口 - 用户提到“加一个路由”“新增端点”“实现某个 API” ## 执行步骤 1. 在 src/routes/ 下创建或修改对应的路由文件按资源名命名 2. 在 src/controllers/ 下实现 controller 函数处理请求参数校验和响应 3. 在 src/services/ 下实现业务逻辑controller 不直接操作数据库 4. 在 src/tests/ 下补充集成测试覆盖正常流程和至少一个异常流程 5. 更新 src/routes/index.js注册新路由 ## 约束条件 - 不得引入新的 npm 依赖如需新依赖必须先询问 - 所有数据库操作必须通过 src/models/ 下的 ORM 方法 - 错误处理必须使用项目统一的 errorHandler 中间件 - 请求参数校验使用项目已有的 validate 工具函数 - 只修改与任务相关的文件不得进行无关格式化 ## 验证标准 - 运行 npm test 全部通过 - 运行 npm run lint 无 error - 用 curl 请求新端点正常参数返回 200异常参数返回 400这个 skill 写完之后你下次让 Claude Code 加一个端点它就会按这个流程走而不是随机发挥。实测下来输出的一致性提升非常明显。4.4 用 Codex CLI 跑批量任务把 skill 用在自动化流程里Claude Code 适合交互式任务但如果你有一批重复性任务比如“把 20 个旧组件全部迁移到新的样式方案”用 Codex CLI 更合适。你可以写一个脚本循环调用 Codex CLI每次传入一个文件路径和对应的 skill 名称。具体做法是先用codex run跑一个任务观察它的输出格式和退出码确认稳定后再把它包进 shell 脚本或者 CI 流程里。比如for file in src/components/legacy/*.jsx; do codex run --skill react-component-migration --input $file done这里的关键是skill 名称要能准确匹配而且 skill 里的约束条件要足够严格防止批量执行时出现意外改动。我建议在批量跑之前先拿一两个文件试跑确认输出符合预期再全量执行。注意批量任务一定要在版本控制下跑跑完先看git diff确认改动范围符合预期再提交。我吃过亏有一次批量格式化跑完diff 里混进了一堆无关改动回滚花了不少时间。5. 常见问题与排查技巧实录5.1 skill 不生效AI 没按 skill 走怎么办这是最常见的问题。你明明写了 skill但 AI 还是按自己的方式做。排查思路分几步。先确认 skill 文件是否被正确加载——可以在对话里直接问 AI“你现在能读到哪些 skill”看它列出来的列表里有没有你写的那个。如果没有说明配置路径有问题检查配置文件里的 skill 目录声明。如果 skill 被加载了但没触发通常是触发条件写得太窄或太模糊。试着在对话里显式提一下 skill 的名字比如“请用 api-endpoint 这个 skill 来做”看它是否按流程走。如果显式指定能走通说明触发条件需要放宽。反过来如果显式指定都不走那可能是 skill 文件格式有问题检查一下 markdown 结构是否符合工具的要求。还有一种情况是多个 skill 冲突。比如你同时有“快速修复”和“完整重构”两个 skillAI 可能不知道该用哪个。这时候需要在 skill 里加优先级规则或者在对话里明确指定。5.2 输出不稳定同样的 skill 每次结果不一样即使有 skillAI 的输出仍然会有一定随机性这是模型本身的性质决定的。但如果你发现差异大到影响使用可以从几个方面收紧。一是约束条件再加严把“建议”改成“必须”把模糊表述改成具体规则。二是验证标准再具体让 AI 在交付前必须跑某个命令并贴出结果这样你能快速判断是否合格。三是降低模型温度参数如果工具支持的话温度越低输出越确定。另外skill 本身也要迭代。我通常会记录每次输出不理想的案例分析是哪个环节的约束不够然后回头改 skill 文件。改了几轮之后稳定性会明显提升。5.3 上下文丢失长任务跑到一半 AI 忘了 skill长任务中上下文丢失是老大难问题。Claude Code 和 Codex CLI 都有上下文窗口限制对话太长时早期内容会被截断。应对办法有几个。一是用/compact命令主动压缩上下文把关键信息保留下来。二是把 skill 里的核心约束重复写在任务描述里不要完全依赖 AI 自己去读 skill 文件。三是把长任务拆成多个短任务每个短任务单独开一个会话用/resume恢复必要的上下文。我自己的习惯是对于超过 10 轮对话的任务每 5 轮左右就主动总结一下当前状态和待办事项让 AI 确认。这样即使上下文被压缩关键信息也不会丢。5.4 常见问题速查表问题现象可能原因排查动作skill 完全不生效配置路径错误或文件格式不对问 AI 能读到哪些 skill检查配置文件skill 加载了但不触发触发条件太窄或太模糊显式指定 skill 名称测试放宽触发条件多个 skill 冲突缺少优先级规则在 skill 头部加优先级说明输出风格不统一约束条件不够具体把建议改成必须补充具体规则长任务上下文丢失对话超出上下文窗口用 /compact 压缩拆分任务定期总结批量任务改动范围失控约束条件不够严格先试跑一两个检查 git diff 再全量执行验证标准跑不过skill 里的命令与实际项目不符更新 skill 里的命令和路径5.5 几个我踩过的坑第一个坑是skill 写得太细。我一开始把每个函数名、每个变量名都写进 skill结果 AI 变成了“照本宣科”遇到稍微不同的场景就卡住了。后来我改成只规定结构和约束具体实现留给 AI 发挥灵活性反而更好。第二个坑是忽略项目差异。我在 A 项目写的 skill 直接复制到 B 项目结果因为目录结构不同AI 找不到文件。后来我养成了习惯每个项目的 skill 都要根据实际目录结构调整不能直接照搬。第三个坑是验证标准写得太理想化。我写了个“运行npm run test:e2e全部通过”的验证标准结果项目里根本没有 e2e 测试配置AI 跑的时候直接报错。验证标准一定要基于项目实际情况写写完自己先跑一遍确认命令可用。6. 进阶玩法把 skill 体系接入团队工作流6.1 skill 的版本管理与 code reviewskill 文件既然是项目的一部分就应该进版本控制并且像代码一样做 review。我们团队的做法是skill 的修改走正常的 PR 流程至少一个人 review 通过才能合并。review 的重点是触发条件是否清晰、约束条件是否合理、验证标准是否可执行。这样能防止有人写了一个过于宽松的 skill导致 AI 行为失控。另外skill 也要有版本号或者变更记录。当 AI 行为出现异常时可以快速定位是不是最近改了某个 skill 导致的。我们会在 skill 文件头部加一个简单的 changelog记录每次修改的原因和影响范围。6.2 用 skill 统一团队编码风格团队里每个人写代码的习惯不一样用 AI 辅助之后这种差异会被放大。skill 体系的一个重要作用就是把团队规范固化下来。比如我们规定所有 React 组件必须用函数式写法、必须写 PropTypes、样式必须用 CSS Modules。这些规则写进 skill 之后不管是谁用 AI 生成代码出来的风格都是一致的。这比写一份“编码规范文档”然后指望大家自觉遵守要有效得多。因为 skill 是 AI 直接执行的不依赖人的记忆力。新人入职时只要把项目 clone 下来AI 就自动按团队规范干活上手成本大幅降低。6.3 把 skill 和 CI 结合起来更进一步的做法是把 skill 的验证标准接入 CI。比如 skill 里写了“运行npm test全部通过”那 CI 里也跑同样的命令。这样 AI 在本地交付的代码推到 CI 上也能通过同样的检查形成闭环。我们还试过在 CI 里加一步“skill 合规检查”用脚本扫描 AI 生成的代码是否符合 skill 里的约束条件比如有没有引入不该引入的依赖。虽然不能覆盖所有情况但能拦住大部分明显违规。6.4 关于模型选择的经验superpowers 这套框架本身不绑定特定模型但模型选择会直接影响效果。我的经验是复杂任务用能力强的模型简单任务用速度快、成本低的模型。Claude Code 默认用的模型在代码理解和指令遵循上表现不错适合做需要深入分析的任务。Codex CLI 可以配置不同的模型批量任务用便宜一点的模型能省不少成本。如果你用第三方 API 或者本地模型要注意指令遵循能力的差异。有些模型在简单对话上表现很好但一到复杂的多步任务就容易跑偏。这种时候要么换模型要么把 skill 拆得更细降低单次任务的复杂度。7. 我对这套框架的真实看法用了一段时间之后我的整体判断是superpowers 代表的这套 agentic skills framework 思路是对的但它不是一个“装上就灵”的银弹。它的价值取决于你愿意花多少时间在 skill 的设计和迭代上。如果你只是随便写几个 skill 就想让 AI 脱胎换骨大概率会失望。但如果你愿意把它当成项目的一部分认真维护它能带来的稳定性提升是实实在在的。我自己的项目里现在大概有十几个 skill覆盖了日常开发的大部分场景。最直观的感受是用 AI 改代码时心里更有底了因为我知道它会按什么流程走、会遵守哪些约束、做完之后会跑哪些验证。这种“可预期性”是之前纯对话式使用 AI 时完全没有的。当然也有局限。skill 体系对探索性任务的帮助有限比如“帮我设计一个新模块的架构”这种没有固定套路的事情还是得靠人来主导。另外skill 的维护本身也有成本项目结构变了、技术栈升级了skill 都得跟着改。所以我的建议是先从一两个高频场景开始跑通了再逐步扩展不要一上来就追求大而全。最后分享一个小技巧每次 AI 输出不理想时不要只是重试而是回头看看是哪个 skill 的哪个环节出了问题把它改掉。这样你的 skill 体系会越用越顺手AI 也会越来越像你团队里那个“懂规矩”的靠谱同事。