1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后我的第一反应是这东西不是又一个花哨的提示词合集它更像是一套软件研发方法论的工程化封装。简单来说superpowers 是一套面向 AI 编程代理agent的技能框架。它把“怎么让 AI 代理稳定、可复现地完成软件开发任务”这件事从零散的提示词技巧升级成了一套有结构、有层次、可组合的技能体系。你如果用过 Claude Code 或者 Codex CLI 这类命令行 AI 编程工具大概率遇到过这样的场景同一个需求今天让它写能跑通明天换个会话就翻车或者它写出来的代码风格飘忽不定一会儿用这个库一会儿用那个模式。superpowers 想解决的就是这种不确定性问题。它适合谁我认为有三类人值得认真看第一类是已经在用 Claude Code、Codex CLI 做日常开发的工程师想让 AI 代理的输出更可控第二类是想把 AI 编程能力引入团队工作流的技术负责人需要一套可复制的方法论而不是个人经验第三类是对 agentic skills framework 这个概念好奇、想搞清楚“技能框架”和“提示词工程”到底差在哪里的学习者。这篇文章我会从设计思路、核心机制、实操落地、常见坑四个层面把 superpowers 这套东西拆开讲透。中间会穿插 Claude Code 和 Codex CLI 的具体配置细节包括安装、模型接入、命令使用这些热词里高频出现的问题。你不需要先成为 AI 编程专家只要写过代码、用过命令行就能跟着走下来。2. 核心设计思路拆解为什么是“技能框架”而不是“提示词库”2.1 从提示词工程到技能框架的范式转变大部分人接触 AI 编程起点都是提示词。你写一段话AI 回一段代码不满意就改提示词再试。这种方式在单次任务上够用但一旦任务变复杂、步骤变多问题就暴露了提示词是扁平的它没有结构没有复用机制也没有办法表达“先做什么、再做什么、什么条件下走哪条分支”这种逻辑。superpowers 的核心洞察在于软件开发本身是有结构的。一个完整的开发任务通常包含需求理解、方案设计、代码实现、测试验证、重构优化这几个阶段每个阶段又有各自的子技能。如果把这些阶段和子技能抽象成一个个独立的“技能单元”每个单元有明确的输入、输出和触发条件那么 AI 代理就可以像搭积木一样组合这些技能来完成复杂任务。这就是 agentic skills framework 和普通提示词库的本质区别。提示词库是“一堆句子”技能框架是“一套有依赖关系的技能图谱”。前者靠人记住什么时候用哪句后者靠框架本身来编排调用顺序。提示理解这一点很关键。如果你只是把 superpowers 当成“更长的提示词”来用那它的价值会大打折扣。它的威力在于技能之间的组合和编排。2.2 技能单元的设计原则单一职责与可组合性我研究了一段时间后发现superpowers 里每个技能单元的设计遵循了两个很朴素的工程原则。第一个是单一职责。一个技能只做一件事。比如“解析需求”是一个技能“生成接口定义”是另一个技能“写单元测试”又是另一个。这样做的好处是每个技能的行为边界清晰AI 代理在执行时不容易跑偏。你想想如果一个技能既要做需求分析又要写代码AI 很容易在中间某一步就开始自由发挥最后输出一堆你不需要的东西。第二个是可组合性。技能之间通过标准化的输入输出对接。前一个技能的输出就是后一个技能的输入。这种设计让整个框架具备了类似函数式编程的灵活性——你可以按顺序串起来也可以根据条件选择不同的技能分支。这两个原则听起来简单但落地的时候有很多细节。比如技能的输出格式怎么定义是用自然语言还是结构化数据superpowers 的选择是结构化优先自然语言兜底。能用 JSON、YAML 这种结构化格式表达的就用结构化实在不行的才用自然语言描述。这个取舍很务实因为结构化数据在技能之间传递时不会失真而自然语言每传递一次就可能被“理解偏”一点。2.3 与 Claude Code、Codex CLI 的协作关系superpowers 本身不是一个独立的编程工具它更像是一层方法论中间件需要依附在具体的 AI 编程代理上运行。目前最主流的两个载体就是 Claude Code 和 Codex CLI。Claude Code 是 Anthropic 推出的命令行 AI 编程工具它的特点是上下文理解能力强适合处理需要深度推理的任务。Codex CLI 则是另一条技术路线更偏向于快速代码生成和命令执行。superpowers 的技能框架可以同时适配这两者因为它的技能定义是工具无关的——技能描述的是“做什么”而不是“用哪个工具做”。这个设计选择背后有很实际的考量。AI 编程工具这个领域变化太快了今天 Claude Code 是主流明天可能又冒出新的工具。如果技能框架和某个具体工具深度绑定那工具一换框架就废了。保持工具无关性虽然短期内需要做一些适配工作但长期来看是更稳妥的策略。3. 核心细节解析技能框架的组成与运行机制3.1 技能定义文件的结构superpowers 里每个技能通常用一个独立的定义文件来描述。根据我的实际使用经验一个典型的技能定义包含这几个部分技能名称与标识唯一标识符用于在框架内引用触发条件什么情况下应该调用这个技能输入规范需要哪些参数格式是什么执行逻辑具体的操作步骤或提示词模板输出规范产出什么格式是什么依赖关系依赖哪些前置技能可能触发哪些后续技能这个结构看起来有点像函数签名加函数体。实际上它就是这么设计的——把技能当成函数来管理整个框架就变成了一个可以静态分析、可以测试、可以版本控制的系统。我试过把技能定义写成 YAML 格式可读性和可维护性都不错。也有人用 Markdown 加 frontmatter 的方式好处是提示词部分写起来更自然。两种方式各有优劣关键是要保持团队内统一。3.2 技能编排从线性执行到条件分支单个技能再强也只能解决单一问题。superpowers 真正有意思的地方在于技能编排。最基础的编排是线性执行技能 A 完成后执行技能 BB 完成后执行 C。这种模式适合流程固定的任务比如“生成 CRUD 接口”这种套路化的工作。进阶一点的是条件分支根据某个技能的输出结果决定下一步走哪条路径。比如代码审查技能发现严重问题就跳到修复技能没问题就跳到测试技能。这种编排让 AI 代理具备了一定的“判断力”。再往上还有循环和重试某个技能执行失败后自动回退到上一步重新执行或者带着错误信息重试。这个机制在处理复杂重构任务时特别有用因为 AI 第一次改代码经常改不干净需要多轮迭代。注意编排逻辑越复杂调试难度越高。我的建议是从线性编排开始跑通了再逐步加分支和循环。一上来就搞复杂编排出问题的时候你根本不知道是哪一步的锅。3.3 上下文管理技能之间怎么传递信息这是很多人容易忽略但极其关键的一环。技能 A 的输出要传给技能 B中间涉及一个上下文管理的问题。如果所有信息都塞进一个巨大的上下文里很快就会超出模型的上下文窗口而且无关信息会干扰 AI 的判断。superpowers 的做法是分层上下文每个技能只接收自己需要的那部分上下文执行完只输出结果不把中间过程全部带下去。具体实现上可以用一个共享的上下文对象技能按需读取和写入特定字段。这样既保证了信息传递又避免了上下文膨胀。我在实际项目里会额外加一个“上下文清理”步骤在关键节点把不再需要的中间数据清掉实测能明显提升后续技能的稳定性。3.4 技能版本管理与团队协作技能定义是代码就应该像代码一样管理。版本控制、代码审查、变更记录这些软件工程的实践同样适用于技能框架。我见过一些团队把技能定义直接写在提示词文件里改了就改了没有版本记录。结果某天发现 AI 代理行为变了排查半天才发现是某个人上周改了一个技能定义。这种问题在团队协作场景下特别常见。superpowers 的思路是让技能定义成为一等公民纳入正常的代码管理流程。每个技能有版本号变更需要审查重大变更需要测试验证。这套流程虽然增加了前期成本但换来的是可追溯性和稳定性长期来看非常划算。4. 实操落地从安装到跑通第一个技能4.1 环境准备Claude Code 与 Codex CLI 的安装在跑 superpowers 之前你得先把底层的 AI 编程工具装好。这里我分别说一下 Claude Code 和 Codex CLI 的安装要点。Claude Code 的安装官方推荐的方式是通过 npm 全局安装。在 macOS 或 Ubuntu 上确保 Node.js 版本在 18 以上然后执行安装命令。安装完成后需要配置 API 凭证这一步是很多人卡住的地方。如果你用的是官方订阅登录流程会引导你完成授权如果你想接入第三方模型或者本地模型就需要额外配置。Codex CLI 的安装类似也是通过包管理器。它的配置文件和 Claude Code 不太一样需要单独设置模型端点和密钥。两个工具可以共存互不干扰。提示安装过程中如果遇到网络相关的报错先检查你的包管理器源和网络环境。这类问题占安装失败的绝大多数。4.2 模型接入本地模型与第三方 API 的配置思路热词里有很多关于“Claude Code 调用 LM Studio 本地模型”“使用 cc switch 接入 DeepSeek、Qwen、GLM 等模型”的搜索。这说明大家对这个需求很强烈。核心思路是Claude Code 和 Codex CLI 都支持自定义模型端点。你需要在配置文件里把默认的模型端点替换成你的本地服务地址或第三方 API 地址。本地模型的话LM Studio 或者类似的推理服务会暴露一个兼容 OpenAI 格式的接口把这个地址填进去就行。这里有几个坑要注意。第一不是所有模型都支持工具调用function calling而 Claude Code 这类工具高度依赖工具调用来执行终端命令和文件操作。如果模型不支持很多功能会用不了。第二本地模型的上下文窗口通常比云端模型小处理大项目时容易截断。第三第三方 API 的稳定性和延迟差异很大建议先用小任务测试。4.3 跑通第一个技能以“代码审查”为例环境准备好之后我们跑一个最简单的技能来验证整条链路。我选“代码审查”这个技能因为它输入输出清晰容易验证。第一步准备一个待审查的代码文件。随便写一个有点小问题的函数比如缺少边界检查或者命名不规范。第二步在 superpowers 的技能定义里找到代码审查技能确认它的输入规范。通常需要提供文件路径和审查规则。第三步通过 Claude Code 或 Codex CLI 触发这个技能。你会看到 AI 代理读取文件、分析代码、输出审查意见。第四步检查输出是否符合技能定义的输出规范。如果格式不对说明技能定义或者模型配置有问题需要排查。这个流程跑通之后你就有了一个可复现的 AI 代码审查能力。接下来可以尝试把多个技能串起来比如“代码审查 → 自动修复 → 重新审查”这样的循环。4.4 在 VS Code 中集成工作流很多人习惯在 VS Code 里写代码所以把 Claude Code 集成到 VS Code 里是个刚需。官方提供了 VS Code 插件安装后在设置里配置好 Claude Code 的路径和参数就行。集成之后的好处是你可以在编辑器里直接触发 AI 代理任务不用来回切换终端。对于 superpowers 这种需要频繁调用技能的场景编辑器集成能明显提升效率。不过要注意VS Code 插件和命令行版本的配置是分开的。你在终端里配好的模型端点插件里可能还需要再配一遍。这个坑我踩过排查了半天才发现是两套配置。5. 常见问题与排查技巧实录5.1 安装与配置类问题速查问题现象可能原因排查方向安装命令报错找不到包包管理器源配置问题检查 npm 或对应包管理器的源登录授权失败网络或账号状态问题确认账号可用检查网络连通性模型调用返回空结果模型端点配置错误核对 API 地址、密钥、模型名称工具调用不生效模型不支持 function calling换用支持工具调用的模型上下文频繁截断模型上下文窗口太小减少单次输入或换大窗口模型这张表是我在实际使用中总结出来的覆盖了大部分新手会遇到的问题。遇到报错先对照这张表排查能省不少时间。5.2 技能执行不稳定的排查思路技能执行不稳定表现通常是同样的输入有时候输出正确有时候跑偏。这个问题比安装配置类问题更难排查因为它不是必现的。我的排查思路是这样的首先确认是不是模型本身的问题换一个模型跑同样的技能如果稳定了那就是原模型的随机性太大。其次检查技能定义里的提示词是不是有歧义模糊的描述会让模型在不同会话里做出不同理解。最后看上下文管理如果技能之间传递的信息太多太杂模型容易被干扰。实测下来把技能定义写得更具体、更结构化是提升稳定性最有效的手段。与其写“审查这段代码”不如写“检查以下五个方面边界条件、错误处理、命名规范、性能隐患、安全风险每项给出具体行号和修改建议”。后者虽然啰嗦但输出稳定得多。5.3 模型切换与兼容性避坑不同模型对技能框架的兼容性差异很大。我试过用同一个技能定义在几个不同模型上跑结果有的模型能完整执行有的模型执行到一半就开始自由发挥。经验是技能定义里的指令越依赖模型的推理能力兼容性越差。如果技能主要是格式转换、模板填充这类确定性任务大部分模型都能胜任。如果技能需要模型做复杂判断那就得挑推理能力强的模型。另外切换模型之后一定要重新跑一遍回归测试。我见过有人换了模型没测试结果之前跑得好好的技能全部失效排查了半天才发现是模型不兼容。5.4 团队协作中的技能管理经验团队里用 superpowers最大的挑战不是技术是一致性。每个人对技能的理解不一样写出来的技能定义风格也不一样最后整个框架变得很混乱。我的做法是定一套技能定义的模板和规范所有人按这个来写。规范包括命名规则、输入输出格式、注释要求、版本管理流程。刚开始大家会觉得麻烦但用一段时间之后就体会到好处了——技能可以互相复用新人上手也快。还有一个经验是定期做技能审查。就像代码审查一样定期看看现有技能有没有冗余、有没有可以合并的、有没有需要更新的。技能框架是会“腐烂”的不维护的话半年后就没人敢动了。6. 技能框架的扩展与进阶玩法6.1 自定义技能的开发流程当内置技能不够用的时候就需要开发自定义技能。流程其实不复杂先明确这个技能要解决什么问题然后定义输入输出再写执行逻辑最后测试验证。难点在于执行逻辑的编写。你需要把人的经验转化成模型能理解的指令。这个过程有点像写单元测试——你得把“什么算正确”这件事描述得非常清楚模型才知道往哪个方向努力。我一般会先手动做几遍这个任务记录下自己的思考过程然后把这个过程抽象成步骤再翻译成技能定义。这样写出来的技能比凭空想象的靠谱得多。6.2 技能组合的进阶模式除了前面说的线性、分支、循环还有一些更高级的组合模式。比如并行执行多个独立技能同时跑最后汇总结果。这在处理大型代码库分析时很有用可以同时分析多个模块。再比如递归调用技能在执行过程中调用自身处理嵌套结构。这在处理树形数据或者递归算法时很自然。还有动态编排根据运行时的情况动态决定下一步调用哪个技能。这种模式最灵活但也最难调试。我的建议是除非确实需要否则不要轻易上动态编排。6.3 把技能框架接入现有研发流程superpowers 不是孤立存在的它需要嵌入到现有的研发流程里才能发挥价值。我的做法是在几个关键节点接入代码提交前的自动审查、CI 流程里的测试生成、代码重构时的辅助分析。这些节点任务明确、重复性高最适合用技能框架来自动化。接入的时候要注意不要试图一次性替换所有人工环节。先从辅助角色开始让人和 AI 协作等稳定了再逐步扩大 AI 的职责范围。这个渐进式的策略比激进替换要稳妥得多。7. 我在实际使用中的几点体会用 superpowers 这套东西有一段时间了踩过的坑不少也积累了一些文档里不会写的经验。第一个体会是技能框架的价值不在于技能本身而在于技能之间的组合方式。单个技能再精巧能解决的问题也有限。真正让效率提升的是把多个技能串成一条完整的流水线。所以前期不要花太多时间打磨单个技能先把组合跑通。第二个体会是稳定性比智能性更重要。一个能稳定输出 80 分结果的技能比一个偶尔输出 100 分但经常翻车的技能有价值得多。在工程场景下可预测性就是生产力。第三个体会是技能定义要当代码来维护。版本控制、审查、测试一个都不能少。我见过太多团队把技能定义当成一次性文档写完就不管了最后整个框架变成一团乱麻。最后分享一个小技巧给每个技能加一个“失败回退”逻辑。当技能执行失败或者输出不符合预期时自动回退到上一个稳定状态而不是让错误继续往下传。这个机制看起来简单但能避免很多连锁故障。我在几个项目里加上这个逻辑之后整体稳定性提升很明显。
到O(log n)的优化之路)
