1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词很多人会以为是某个超级英雄主题的插件或者游戏模组。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手大概率已经在社区里刷到过它。简单说superpowers 是一套面向 AI 编程代理的 agentic skills framework同时也是一套围绕它生长出来的 software development methodology。它要解决的核心痛点非常具体当你把 Claude Code 或 Codex CLI 当成日常开发搭档之后会发现模型本身很聪明但每次都要重新解释项目规范、重新教它怎么跑测试、怎么组织提交信息重复劳动特别多。superpowers 的思路就是把这些“重复教”的东西沉淀成可复用的技能包skills让代理在需要的时候自动加载对应的能力。你可以把它理解成给 AI 编程助手装了一套“职业培训教材加工具箱”写前端的时候它知道你的组件规范写后端的时候它知道你的接口约定做代码审查的时候它知道你的检查清单。这套框架不是某个单一工具而是一种组织方式配合 Claude Code、Codex CLI 这类支持技能扩展的代理运行时使用。适合谁来参考三类人最值得花时间一是已经把 Claude Code 或 Codex CLI 当主力开发工具、但觉得“还不够顺手”的开发者二是团队里负责制定工程规范、想让 AI 代理遵守统一标准的技术负责人三是刚接触 agentic 编程、想搞清楚“技能框架”到底怎么落地的新手。这篇文章会从设计思路、核心机制、实操配置到常见坑完整拆一遍尽量让你看完就能动手搭一套自己的 superpowers 工作流。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 提示词工程的瓶颈在哪里大部分人用 Claude Code 的起点都是一段长长的系统提示词或者 CLAUDE.md 文件把项目背景、编码规范、常用命令一股脑塞进去。刚开始挺好用但项目一复杂就出问题。提示词是“全局常驻”的不管你现在是在写数据库迁移还是在调 CSS模型每次都要读完所有内容token 消耗大不说还容易互相干扰——写前端的时候被后端的规范带偏做重构的时候又被测试规范分散注意力。更麻烦的是维护。提示词是一整块文本改一处要小心翼翼团队多人协作时冲突不断。我试过在一个中型项目里维护一份 800 行的 CLAUDE.md两个月后已经没人敢动它了因为谁也不知道删掉哪段会影响什么。这就是提示词工程的天花板它是线性的、耦合的、难以组合的。2.2 技能框架的三个关键设计superpowers 这类 agentic skills framework 的破局点在于把“能力”拆成独立单元。每个 skill 是一个自包含的目录里面有说明文档、触发条件、具体步骤甚至附带脚本和模板。代理在运行时根据当前任务动态决定加载哪些 skill。这个设计有三个关键好处。第一是按需加载。你在改 React 组件时代理只加载前端相关的 skill你在写 SQL 时只加载数据库 skill。上下文窗口被用在刀刃上模型注意力更集中输出质量自然更稳。第二是可组合。一个“提交代码”的 skill 可以调用“运行测试”和“生成提交信息”两个子 skill像搭积木一样拼出复杂流程。第三是可版本化。每个 skill 是独立文件可以进 Git可以 code review可以单独迭代团队协作时冲突面小得多。提示不要把 skill 理解成“更长的提示词”。它的本质是“带触发条件的、可独立维护的能力模块”触发条件的设计比内容本身更重要。2.3 和 Claude Code、Codex CLI 的关系Claude Code 和 Codex CLI 都提供了让代理读取本地文件、执行终端命令、调用工具的能力这是技能框架能跑起来的基础。superpowers 本身更像是一套约定和模板集合告诉你 skill 应该长什么样、放在哪里、怎么被引用。Claude Code 通过项目根目录的配置和特定目录结构来发现 skillCodex CLI 则有自己的命令体系来管理这些扩展。两者机制不同但理念一致让代理在正确的时机拿到正确的知识。这里要澄清一个常见误解superpowers 不是必须依赖某个特定模型。它是一套方法论加文件组织方式理论上任何支持工具调用和文件读取的代理运行时都能用。只不过目前 Claude Code 和 Codex CLI 的生态最成熟社区分享的 skill 也最多所以大家默认在这两个平台上实践。3. 核心细节解析一个 skill 到底由什么组成3.1 目录结构与文件约定一个规范的 skill 通常是一个独立目录放在项目约定的 skills 路径下。目录名就是 skill 的标识建议用短横线连接的英文短语比如run-tests、commit-convention、api-design-review。目录内部一般包含这几个文件主说明文件通常是 markdown描述这个 skill 解决什么问题、什么时候触发、具体怎么做可选的脚本文件把重复的命令固化下来可选的模板文件比如提交信息模板、PR 描述模板。主说明文件的结构很关键。开头要有一段简短的“触发描述”用自然语言写清楚“当用户在做 X 的时候使用本 skill”。这段描述会被代理用来判断是否加载。中间是具体的操作步骤要写成可执行的指令而不是泛泛而谈。结尾可以放注意事项和边界情况。我见过太多 skill 写成了“科普文章”模型读完不知道下一步该干嘛这就是失败的 skill。3.2 触发条件的设计技巧触发条件是整个框架里最容易被低估的部分。写得太宽代理动不动就加载浪费上下文写得太窄该用的时候用不上。我的经验是围绕“动作 对象”来写比如“当需要为新功能编写单元测试时”“当准备提交代码到主分支时”。避免用“当涉及测试时”这种模糊表述。还有一个技巧是给触发条件加上“反例”。比如在run-tests的说明里写一句“如果用户只是询问测试覆盖率数字不需要加载本 skill”。这种负向约束能显著减少误触发。实测下来加了反例之后误加载率能降一半以上。3.3 参数化与复用好的 skill 不是写死的而是带参数的。比如一个“生成 API 端点”的 skill不应该把具体的资源名、字段名写死而是用占位符表示让代理在加载时根据当前任务填充。这样同一个 skill 能服务几十个不同的端点复用率极高。参数化的另一个层面是环境适配。同一个“运行测试”的 skill在不同项目里命令可能不一样有的用npm test有的用pytest有的用go test。解决办法是在 skill 里读取项目配置文件或者让 skill 引用一个项目级的变量文件。这样 skill 本身保持通用项目差异通过配置注入。4. 实操过程从零搭一套可用的 superpowers 工作流4.1 环境准备与工具安装先把基础环境搭好。Claude Code 的安装方式根据系统不同有差异Mac 和 Ubuntu 上通常通过包管理器或官方提供的安装脚本完成Windows 用户要注意 64 位兼容性问题部分旧版本会提示与系统不兼容建议直接用较新的安装包。安装完成后第一次运行需要处理账号相关配置社区里常讨论“注册账号和不注册有什么区别”简单说注册后能同步配置和使用云端能力不注册也能跑本地流程但功能受限。Codex CLI 的安装类似装完之后要熟悉几个高频命令/compact用来压缩上下文长会话里特别有用/model切换模型/resume恢复之前的会话。这几个命令在搭 skill 工作流时会反复用到。如果你在 VS Code 里工作可以装 Claude Code 的官方插件配置项里能指定 skill 目录、模型来源等。想接本地模型的话可以通过 LM Studio 暴露本地接口再让 Claude Code 指向这个接口这样敏感项目不用出本地。注意安装过程中如果遇到“组织已禁用订阅访问”之类的提示通常是账号权限或区域配置问题先检查账号状态不要急着重装。4.2 建立 skills 目录与第一个 skill在项目根目录下建一个skills文件夹这是社区最常见的约定。然后在里面建第一个 skill建议从最简单的开始比如commit-message。目录结构如下skills/ commit-message/ SKILL.md template.mdSKILL.md里写触发条件和步骤template.md放提交信息模板。内容大致这样组织触发描述写“当用户准备提交代码、需要生成提交信息时使用本 skill”步骤里写清楚先运行git diff --staged查看暂存区改动再根据改动类型套用模板生成信息最后用git commit提交。模板文件里定义好 feat、fix、docs、refactor 等类型的格式。写完第一个 skill 后在 Claude Code 里测试一下。故意说“帮我提交这些改动”看代理是否自动加载了这个 skill。如果没有检查触发描述是不是太窄或者 skill 目录路径有没有配对。4.3 逐步扩展技能库第一个跑通之后按同样的模式扩展。我建议按开发流程的顺序来建需求分析、接口设计、编码、测试、审查、提交、部署。每个环节建一到两个 skill。比如测试环节建write-unit-test和run-tests审查环节建code-review-checklist。扩展时要注意 skill 之间的依赖关系。commit-message可能依赖run-tests先跑通这种依赖要在说明里写清楚或者干脆做成组合 skill。但不要过度嵌套三层以上就会让代理困惑。我的经验是保持 skill 扁平组合逻辑交给代理自己判断而不是硬编码在 skill 里。4.4 参数计算与配置示例举个具体的参数化例子。假设你要建一个“生成数据库迁移”的 skill涉及表名、字段、索引等参数。不要把这些写死而是在 skill 里定义变量占位## 步骤 1. 确认迁移目标表名{{table_name}} 2. 列出需要新增的字段{{fields}} 3. 判断是否需要索引{{index_decision}} 4. 生成迁移文件命名格式为 {{timestamp}}_{{table_name}}_migration代理在加载时会根据当前对话填充这些变量。这样同一个 skill 能处理所有表的迁移维护成本极低。实测下来一个参数化良好的 skill 能覆盖 80% 以上的同类任务剩下 20% 的特殊情况再单独处理。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。排查顺序是这样的先看触发描述是不是太抽象改成具体的“动作 对象”再看 skill 目录是否在代理扫描的路径内不同工具的默认路径不一样Claude Code 和 Codex CLI 各有约定最后看是否有其他 skill 抢先触发多个 skill 触发条件重叠时会互相压制。我踩过的坑是触发描述里用了太多同义词导致代理判断混乱精简之后就好了。5.2 上下文被 skill 撑爆skill 加载多了上下文窗口很快就不够用。解决办法有三个一是给 skill 说明文件瘦身把详细内容拆到附属文件里主文件只留触发条件和步骤概要二是用/compact命令定期压缩三是给 skill 设置优先级低优先级的在上下文紧张时自动跳过。实测把主说明文件控制在 200 行以内整体表现最稳。5.3 多工具协同的冲突同时用 Claude Code 和 Codex CLI 的时候两边的 skill 目录和配置可能打架。建议给每个工具独立的 skill 目录共享的部分用软链接或者同步脚本处理。另外注意命令差异比如删除 Codex CLI 的某个指令和 Claude Code 的操作方式不同别搞混了。常见问题排查方向解决技巧skill 不触发触发描述、目录路径、优先级改成动作加对象检查扫描路径上下文溢出skill 体积、加载数量瘦身主文件用 compact设优先级多工具冲突目录隔离、命令差异独立目录软链接共享注意命令区别参数填充错误占位符格式、变量来源统一占位符语法明确变量注入方式5.4 团队协作中的 skill 管理团队用的时候skill 库要进 Git走 code review。但要注意别让 skill 库变成新的“大泥球”。我的做法是每个 skill 有明确的 owner改动需要 owner 审核。另外定期清理不再使用的 skill我见过一个团队攒了 60 多个 skill一半没人维护反而拖慢了代理的判断速度。季度清理一次保持精简。6. 进阶玩法把 superpowers 和本地模型、第三方接口结合6.1 接入本地模型的注意事项有些项目对数据敏感不想把代码发到云端。这时候可以用 LM Studio 在本地跑模型然后让 Claude Code 指向本地接口。配置的关键是接口地址和模型名称要对上另外本地模型的工具调用能力通常弱一些skill 的步骤要写得更明确减少代理的自由发挥空间。实测本地模型跑 skill 工作流成功率比云端低一些但通过细化步骤能补回来不少。6.2 第三方接口的接入技巧社区里也有人用第三方接口接入 DeepSeek、Qwen、GLM 等模型通过 cc switch 这类工具切换。这种玩法的好处是成本可控、模型选择灵活。要注意的是不同模型的指令遵循能力差异较大同一个 skill 在 A 模型上跑得好换到 B 模型可能就翻车。建议给每个模型单独调一版 skill或者至少测试一遍再上生产。6.3 和飞书等协作工具的连接有团队把 Claude Code 接到飞书里让代理在群里响应开发请求。这种场景下 skill 的设计要更偏向“对话式”触发条件要能识别群聊里的自然语言。我的经验是给这类场景单独建一套 skill不要和本地开发用的混在一起因为交互模式完全不同。7. 我个人的一些实操体会搭这套东西最深的体会是skill 的质量比数量重要得多。我一开始贪多建了三十多个 skill结果代理判断加载哪个都要花不少时间反而变慢。后来砍到十二个每个都打磨得很细整体效率明显提升。另一个体会是触发描述值得反复改我有个 skill 改了七版触发描述才稳定下来前面六版要么不触发要么乱触发。还有一点别指望 skill 能解决所有问题。它擅长的是“把重复的、有固定套路的任务固化下来”对于需要创造性判断的任务还是得靠人。把 skill 用在刀刃上比如代码规范检查、提交信息生成、测试脚手架搭建这些高频重复场景收益最大。至于复杂的架构设计让代理参与讨论就好别硬塞进 skill 里。最后分享一个小技巧给每个 skill 加一个“最后更新日期”和“适用版本”字段。代理运行时如果发现 skill 太久没更新或者和当前项目版本不匹配可以主动提醒你。这个小小的元数据字段帮我避免了好几次用过期 skill 导致的翻车。