1. 从“superpowers”说起一个让 AI 编程助手真正长出“手脚”的技能框架第一次看到 “superpowers” 这个词是在几个做 AI 辅助开发的群里。有人甩出一张截图说自己的 Claude Code 突然会“自己规划任务、自己写测试、自己跑命令、自己修 bug”了底下配文就俩字superpowers。当时我第一反应是又一个营销噱头毕竟这两年“让 AI 自动写代码”的口号喊了太多真正能落地的没几个。但架不住好奇我还是去翻了这个项目的仓库和文档结果发现它跟我之前接触过的那些“提示词合集”完全不是一回事。superpowers 本质上是一个agentic skills framework翻译过来叫“智能体技能框架”。它不绑定某一个具体的模型也不绑定某一个具体的编辑器而是定义了一套让 AI 编程助手比如 Claude Code、Codex CLI 这类命令行智能体能够按需加载、组合、执行“技能”的机制。你可以把它理解成给 AI 装了一个“技能背包”平时背包是空的遇到什么任务就临时把对应的技能塞进去AI 拿着这个技能去干活干完再换下一个。这个思路听起来简单但它解决了一个非常核心的痛点——通用大模型在软件开发这种长链路、多步骤、强上下文的任务里光靠一个系统提示词是撑不住的。我自己用 Claude Code 和 Codex CLI 有一段时间了踩过的坑不算少。最典型的问题就是你让它写一个功能它写得挺快但写完不测、测了不修、修了不验证最后你还得自己从头到尾捋一遍。superpowers 想干的事情就是把这些“软件开发的隐性流程”显式地拆成一个个可复用的技能模块让 AI 在合适的时机调用合适的技能而不是一股脑把所有指令塞进上下文里。这个框架适合谁我觉得三类人最该关注一是已经在用 Claude Code 或 Codex CLI 做日常开发的人二是想把自己的开发流程沉淀成可复用资产的技术负责人三是单纯对 agentic 开发方法论感兴趣、想看看别人怎么设计这套东西的工程师。哪怕你暂时不用这些工具光看它的技能拆分思路也能对自己的工作流有不少启发。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从“一个大提示词”到“按需加载的技能包”传统做法里我们想让 AI 干好活通常是把所有要求写进一个巨大的系统提示词你要先理解需求、再设计方案、再写代码、再写测试、再跑测试、再修 bug、再写文档……写完之后发现提示词比代码还长而且模型经常“选择性失忆”前面说了后面忘。更麻烦的是不同任务需要的流程完全不一样写一个新功能和处理一个线上 bug步骤差异巨大硬塞进同一个提示词里只会互相干扰。superpowers 的做法是把这些流程拆成独立的“技能”。每个技能是一个自包含的单元包含这个技能的名字、描述、触发条件、执行步骤、以及需要的工具或上下文。当 AI 面对一个任务时它先判断这个任务需要哪些技能然后按顺序加载并执行。这个机制的关键在于“按需加载”——上下文里只保留当前正在用的技能用完就释放避免上下文被无关指令撑爆。我实测下来这个设计对长任务的稳定性提升非常明显尤其是那种需要来回切换“写代码”和“跑测试”的场景。2.2 技能框架和普通提示词模板的本质区别很多人会把 superpowers 和网上那些“Claude Code 提示词模板”混为一谈其实差别很大。普通提示词模板是静态的你复制粘贴进去模型照着做做完就完了。而 superpowers 的技能是可组合、可编排、可条件触发的。举个例子一个“写单元测试”的技能它可能包含“先读被测代码”“识别边界条件”“生成测试用例”“运行测试”“如果失败则分析原因”这几个子步骤而且这些子步骤之间是有状态传递的。更关键的是技能可以被其他技能调用比如“修复 bug”技能在执行过程中发现需要补测试就可以动态调用“写单元测试”技能。这种嵌套和组合能力是静态提示词做不到的。从工程角度看这其实借鉴了软件工程里“模块化”和“关注点分离”的思想。把一个大而全的流程拆成小颗粒度的技能每个技能只负责一件事做好一件事。这样不仅 AI 执行起来更稳人类维护起来也更容易——哪个技能效果不好单独改那个技能就行不用动整个流程。2.3 为什么这个框架对 Claude Code 和 Codex CLI 特别重要Claude Code 和 Codex CLI 这类工具的本质是“命令行里的 AI 智能体”它们能读文件、写文件、执行终端命令、查看输出。这个能力很强但也很危险——如果 AI 没有一个清晰的执行框架它很容易陷入“乱试”的状态比如反复执行同一个失败命令或者改了一个文件忘了改另一个。superpowers 提供的技能框架相当于给这些智能体加了一层“行为约束层”什么阶段该做什么、做完之后该验证什么、验证失败该回退还是继续都有明确的技能定义。我自己的体会是没有技能框架的时候Claude Code 更像一个“反应很快但有点莽的实习生”有了技能框架之后它更像一个“知道先看文档再动手、改完会自己跑测试的靠谱同事”。这个差别在简单任务上不明显但在涉及多文件、多步骤、需要反复验证的任务上差距是数量级的。3. 核心技能类型全解析superpowers 里到底有哪些 skills3.1 规划类技能让 AI 先想清楚再动手规划类技能是整个框架的入口。我见过的典型技能包括“需求澄清”“任务拆解”“方案对比”“风险评估”。这些技能的核心作用是在写第一行代码之前逼 AI 把问题想清楚。比如“任务拆解”技能它会要求 AI 把一个大需求拆成若干可独立验证的小任务每个小任务有明确的输入、输出和验收标准。这个步骤看起来简单但实际用下来它能挡掉至少一半的“方向性错误”。我印象很深的一次我让 Claude Code 帮我加一个“用户登录失败次数限制”的功能。没有规划技能的时候它直接就开始改中间件代码了。用了规划技能之后它先输出了一份拆解第一步确认现有登录流程、第二步确定计数存储位置、第三步设计过期策略、第四步改中间件、第五步补测试。结果在第一步就发现现有登录流程里已经有一个类似的计数逻辑只是没启用。如果直接改很可能就重复造轮子了。这个技能的价值就在于它强制 AI 在动手前先“看一眼全局”。3.2 编码类技能把“写代码”拆成可验证的小步编码类技能通常包括“读上下文”“写实现”“写测试”“重构”“处理边界条件”等。这里面的关键设计是每一步都要有验证。比如“写实现”技能执行完之后不是直接进入下一个功能而是触发“写测试”技能测试跑通之后才算这个技能完成。这种“小步验证”的思路跟敏捷开发里的 TDD 很像但执行者是 AI。我实测下来编码类技能里最有用的是“读上下文”这个看似不起眼的技能。它要求 AI 在改任何代码之前先读相关的文件、理解现有的代码风格、找到类似的实现作为参考。这个技能能显著减少“AI 写出来的代码风格跟项目格格不入”的问题。以前我经常要花时间把 AI 写的代码改成项目风格现在这个问题基本消失了。3.3 验证类技能跑测试、查日志、做回归验证类技能是 superpowers 里我最看重的部分包括“运行测试”“分析失败原因”“检查日志”“回归验证”等。这些技能的核心逻辑是AI 不能自己说自己写对了必须用外部信号来证明。跑测试是最直接的信号但测试通过不代表没问题所以还需要“检查日志”和“回归验证”来兜底。这里有个细节值得说验证类技能通常会定义“失败后的行为”。比如测试失败时AI 应该先分析失败原因判断是测试写错了还是实现写错了而不是直接改实现去迎合测试。这个判断逻辑如果写得好能避免很多“为了过测试而写错代码”的情况。我自己就遇到过 AI 把测试断言改弱来让测试通过的情况加了验证技能之后这种行为被明确禁止了。3.4 协作类技能提交、写文档、同步进度协作类技能包括“写提交信息”“更新文档”“同步任务状态”等。这些技能在单人开发时容易被忽略但在团队协作里非常重要。比如“写提交信息”技能它会要求 AI 按照项目的提交规范来写包含变更类型、影响范围、关联任务号等。这个技能看起来小但能省掉很多后期整理提交历史的时间。我个人的经验是协作类技能的价值在“交接”场景下最明显。当你把一个 AI 辅助完成的任务交给同事时如果提交信息清晰、文档更新到位同事接手成本会低很多。反之如果 AI 只改了代码没更新文档同事可能得花半天时间才能搞明白改了什么。4. 怎么把这些技能引入到 Claude Code 和 Codex CLI 里4.1 引入前的环境准备Claude Code 和 Codex CLI 的安装确认在引入 superpowers 之前得先确保你的 Claude Code 或 Codex CLI 能正常跑起来。Claude Code 的安装方式根据平台不太一样Mac 和 Ubuntu 上通常是通过包管理器或者官方提供的安装脚本Windows 上则需要注意 64 位兼容性问题有些老版本会报“与 64 位版本的 Windows 不兼容”的错误这种情况一般升级到最新版就能解决。安装完之后用claude --version确认一下版本再用claude进一次交互模式确保能正常对话。Codex CLI 的安装相对简单一些但要注意它的命令集和 Claude Code 不完全一样。常用的命令包括/compact用来压缩上下文、/model用来切换模型、/resume用来恢复之前的会话。如果你要删除 Codex CLI记得先退出所有会话再执行卸载命令否则可能会有残留进程。另外如果你在 VS Code 里用 Claude Code 插件需要在设置里配置好路径和模型参数不然插件可能找不到 CLI。提示安装过程中如果遇到“your organization has disabled claude subscription access”这类提示通常是账号权限或订阅状态的问题跟 superpowers 本身无关先确认账号状态再继续。4.2 技能引入的三种方式手动、脚本、配置化引入 superpowers 技能的方式我试过三种。第一种是手动引入就是把技能定义文件复制到项目的特定目录下然后在对话里显式告诉 AI “加载某某技能”。这种方式最直接适合刚开始尝试、想先看看效果的人。第二种是脚本引入写一个初始化脚本在启动 Claude Code 或 Codex CLI 时自动把技能目录挂载进去。这种方式适合固定项目一次配置长期使用。第三种是配置化引入把技能配置写进项目的配置文件里AI 启动时自动读取并按需加载。这种方式最灵活但配置项也最多需要花点时间理解。我个人的建议是先从手动引入开始跑通一两个技能确认效果符合预期之后再逐步过渡到脚本或配置化。一上来就搞全套配置很容易因为某个细节没配对而卡住反而打击积极性。4.3 技能加载的触发机制什么时候该用哪个技能技能加载的触发机制是 superpowers 的核心之一。通常有两种触发方式显式触发和隐式触发。显式触发就是你在对话里直接说“用某某技能来做这件事”AI 会加载对应技能。隐式触发则是 AI 根据任务类型自动判断该用哪个技能。隐式触发更省心但对技能描述的准确性要求很高——如果技能描述写得模糊AI 可能该用的时候不用不该用的时候乱用。我自己的做法是关键流程用显式触发确保不会漏辅助流程用隐式触发减少手动干预。比如“写测试”和“跑测试”这两个技能我会显式触发因为漏掉测试的代价比较大。而“写提交信息”这种隐式触发就够了AI 判断该写的时候自然会写。5. 实操过程从零搭建一个带技能框架的开发流5.1 第一步确定你的项目需要哪些技能不是所有项目都需要全套技能。我的经验是先列出你日常开发里最重复、最容易出错、最耗时间的环节这些环节就是最该技能化的。比如一个后端 API 项目最重复的可能是“写接口”“写测试”“跑测试”“写文档”一个前端项目最重复的可能是“改组件”“调样式”“跑构建”。把这些环节列出来再去 superpowers 的技能库里找对应的技能或者自己写一个。这里有个坑要注意不要一开始就追求大而全。我见过有人一上来就配了二十多个技能结果 AI 每次启动都要花时间判断该用哪个反而变慢了。先从三到五个核心技能开始跑顺了再逐步加。5.2 第二步配置技能目录和加载路径技能目录的配置方式取决于你用的工具。Claude Code 通常会在项目根目录下找特定的配置目录Codex CLI 则可能通过环境变量或命令行参数指定。我一般会在项目根目录建一个.skills目录把技能定义文件放进去然后在启动命令里加上路径参数。这样技能文件跟项目代码在一起版本管理也方便。配置的时候要注意路径的写法Windows 和 Unix 系统的路径分隔符不一样写错了会导致技能加载失败。另外如果技能文件里有引用其他文件比如模板、示例要确保相对路径是对的不然 AI 加载技能时会报“找不到文件”。5.3 第三步跑一个完整任务观察技能调用链配置好之后找一个真实的小任务跑一遍比如“给现有函数加一个参数校验”。跑的时候注意观察 AI 的调用链它先用了哪个技能、中间有没有跳过该用的技能、验证环节有没有执行。我第一次跑的时候发现 AI 跳过了“读上下文”技能直接开始改代码结果改出来的风格跟项目不一致。后来我把“读上下文”技能的触发条件写得更明确这个问题就解决了。观察调用链还有一个好处就是能发现技能之间的衔接问题。比如“写实现”技能完成之后应该自动触发“写测试”技能但如果触发条件没配好可能就断了。这种衔接问题在单个技能测试时看不出来只有跑完整任务才会暴露。5.4 第四步根据实际效果调整技能定义技能定义不是一次写好的需要根据实际效果反复调。我一般会关注三个指标任务完成率、返工率、人工干预次数。如果某个技能经常导致返工说明它的步骤定义有问题如果人工干预次数多说明技能的自动化程度不够。调整的时候优先改技能的执行步骤和触发条件而不是改技能的名字或描述——名字和描述影响的是 AI 的判断步骤影响的是 AI 的执行。我自己的经验是技能定义里的“失败处理”部分最值得花时间打磨。比如测试失败时AI 是该重试、该回退、还是该报告给人这个逻辑写清楚了整个流程的稳定性会提升一大截。6. 常见问题与排查技巧实录6.1 技能加载失败路径、权限、格式三大排查方向技能加载失败是最常见的问题排查顺序一般是先看路径对不对再看权限够不够最后看格式有没有问题。路径问题最常见的是相对路径写错尤其是在不同操作系统之间切换时。权限问题通常出现在技能文件放在系统目录下、当前用户没有读权限的情况。格式问题则多是 YAML 或 JSON 的缩进、引号、逗号写错了这种错误往往有明确的报错信息照着改就行。我遇到过一次比较隐蔽的加载失败技能文件本身没问题但文件编码是 GBK 而不是 UTF-8导致 AI 读出来是乱码加载就失败了。这种问题没有明显报错只能靠检查文件编码来发现。所以我现在养成了一个习惯所有技能文件统一用 UTF-8 编码保存。6.2 技能不触发描述模糊和触发条件冲突技能不触发的原因通常有两个一是技能描述太模糊AI 判断不出该不该用二是多个技能的触发条件有冲突AI 不知道该用哪个。解决第一个问题的办法是把描述写具体包含“什么时候用”“解决什么问题”“输入输出是什么”。解决第二个问题的办法是给技能排优先级或者在触发条件里加上更明确的区分条件。我踩过的一个坑是两个技能都写了“当需要修改代码时触发”结果 AI 每次改代码都要纠结用哪个。后来我把其中一个改成“当需要修改已有代码时触发”另一个改成“当需要新增代码时触发”冲突就解决了。6.3 技能执行中断上下文超限和命令超时技能执行到一半中断最常见的原因是上下文超限或命令超时。上下文超限通常发生在长任务里技能加载太多、对话历史太长把上下文撑爆了。解决办法是用/compact压缩上下文或者把大任务拆成小任务分批执行。命令超时则多发生在跑测试或构建的时候尤其是项目比较大的情况。解决办法是调整超时时间或者把耗时的命令放到后台执行。我自己的做法是对于超过两分钟的命令一律不放在技能里同步执行而是让 AI 启动命令后先继续做别的事过一会儿再回来检查结果。这样既能避免超时又能提高整体效率。6.4 技能效果不稳定模型差异和温度参数同一个技能在不同模型上效果可能差很多。比如 Claude 系列模型在“读上下文”和“写测试”上表现比较稳而一些开源模型在“任务拆解”上可能更强。如果你用第三方 API 接入其他模型比如通过 cc switch 接入 deepseek、qwen、glm 等需要针对模型特点调整技能定义。温度参数也有影响温度高的时候 AI 更发散适合规划类技能温度低的时候更收敛适合编码和验证类技能。我一般会在配置里给不同类型的技能设不同的温度规划类设 0.7 左右编码类设 0.2 左右验证类设 0.1 左右。这个不是绝对标准但实测下来比统一温度效果好不少。6.5 常见问题速查表问题现象可能原因排查方法解决建议技能加载失败路径错误、权限不足、格式错误检查路径、权限、文件格式统一用 UTF-8路径用绝对路径技能不触发描述模糊、触发条件冲突检查技能描述和触发条件描述写具体触发条件加区分执行中断上下文超限、命令超时查看上下文用量和命令耗时压缩上下文拆分任务调整超时效果不稳定模型差异、温度参数不当对比不同模型和温度下的表现按技能类型设温度针对性调定义验证环节被跳过触发条件没配好观察调用链看验证技能是否执行显式触发验证技能或加强触发条件7. 我踩过的坑和几条实在建议第一个坑是技能定义写得太理想化。我一开始写的技能定义步骤特别细恨不得把每一步的操作都写死。结果 AI 执行的时候反而束手束脚遇到定义里没覆盖的情况就卡住了。后来我把定义改成“目标 约束 验收标准”的结构给 AI 留出判断空间效果反而更好。技能定义不是越细越好关键是说清楚“要什么”和“不要什么”。第二个坑是忽略技能的维护成本。技能写多了之后改一个流程可能要动好几个技能文件改完还得重新测试。我现在的做法是把技能按“核心”和“辅助”分级核心技能严格维护辅助技能允许一定程度的粗糙。这样既保证了关键流程的稳定又不会在次要技能上花太多时间。第三个坑是过度依赖隐式触发。隐式触发确实省心但一旦 AI 判断错了排查起来很麻烦。我现在对关键技能一律用显式触发虽然多打几个字但心里踏实。隐式触发只用在那些“用了更好、不用也行”的技能上。最后分享一个小技巧给技能加版本号。技能定义改来改去有时候改坏了想回退没有版本号就很难受。我现在每个技能文件里都写一个版本号改之前先备份改完记录改了什么。这个习惯看起来麻烦但真出问题的时候能省很多时间。这个框架后续还可以往几个方向扩展一是把技能和项目的 CI/CD 流程打通让 AI 提交代码后自动触发流水线二是把技能和团队的知识库结合让 AI 在写代码时能参考团队的历史决策三是把技能做成可分享的包团队之间互相复用。这些方向我自己也在摸索有进展了再跟大家分享。