1. 从“superpowers”说起一个让 AI 编码助手真正长出“技能树”的框架第一次看到 “superpowers” 这个词是在几个做 AI 辅助开发的群里。有人甩了一张截图里面 Claude Code 在终端里连续执行了七八个步骤先读项目结构再跑测试发现失败后自己定位到某个文件改完代码又跑了一遍测试最后还顺手更新了文档。底下有人问“这是怎么做到的”答曰“装了个叫 superpowers 的东西。”这就是 superpowers 最直观的价值——它不是一个新模型也不是一个 IDE 插件而是一套agentic skills framework翻译过来就是“智能体技能框架”。你可以把它理解成给 Claude Code、Codex CLI 这类命令行 AI 编码助手装上一套“技能包”和“工作方法论”。原本这些工具也能写代码、改文件但它们的行动往往比较零散缺乏一套稳定的、可复用的做事流程。superpowers 做的事情就是把这些流程固化下来变成一个个可调用的 skill让 AI 在遇到特定任务时知道该按什么步骤走、该检查哪些东西、该在什么时候停下来确认。它解决的核心问题很具体AI 编码助手在真实项目里“不靠谱”。你让它改个 bug它可能只改了表面没跑测试你让它加个功能它可能把不相关的文件也动了你让它重构它可能改到一半就停了。superpowers 通过引入结构化的技能定义让 AI 的行为变得可预期、可复现。适合谁来参考如果你已经在用 Claude Code 或 Codex CLI但总觉得它们“差点意思”或者你刚开始接触这类工具想直接站在一个更高的起点上那这套框架值得花时间研究。我自己的体会是superpowers 最吸引人的地方不在于它有多“智能”而在于它把软件工程里那些老生常谈的实践——比如先写测试、小步提交、改完必须验证——变成了 AI 能理解和执行的指令。这比单纯换一个更强的模型对日常开发效率的提升要实在得多。2. 核心思路拆解为什么是“技能框架”而不是“提示词合集”2.1 从“一次性提示”到“可复用技能”的转变大多数人用 Claude Code 或 Codex CLI 的方式是在终端里敲一段自然语言指令比如“帮我修复登录页面的 bug”。AI 收到后开始工作改完就结束。下次遇到类似问题你又得重新描述一遍。这种模式的问题在于每次都是从头开始经验无法沉淀。superpowers 的思路完全不同。它把常见的开发任务抽象成一个个 skill每个 skill 本质上是一份结构化的 Markdown 文件里面定义了这个技能解决什么问题触发条件是什么比如“当用户要求修复 bug 时”执行步骤有哪些读代码、定位、修改、测试、验证每一步的注意事项和检查点完成后需要输出什么当你在 Claude Code 里启用 superpowers 后AI 在接到任务时会先匹配有没有对应的 skill。如果有它就按照 skill 里定义的流程走而不是自由发挥。这就像给一个聪明但随性的实习生配了一本《标准作业手册》他依然聪明但做事有了章法。2.2 为什么选择 Markdown 作为技能载体superpowers 的技能定义用的是 Markdown而不是 JSON、YAML 或某种 DSL。这个选择很值得琢磨。Markdown 的好处是人和 AI 都能轻松读写。你可以直接用文本编辑器打开一个 skill 文件看懂它在说什么也可以自己复制一份改吧改吧就变成新技能。AI 在读取时Markdown 的标题层级和列表结构天然就是很好的语义提示。相比之下如果用 JSON 来定义虽然机器解析更精确但人写起来痛苦改起来也容易出错。superpowers 走的是“人机共读”的路线降低参与门槛让每个开发者都能贡献自己的技能。我试过自己写一个简单的 skill大概二十分钟就能跑通这个上手速度在同类框架里算是很友好的。2.3 与 Claude Code、Codex CLI 的协作关系需要明确一点superpowers 本身不是编码助手它依附于 Claude Code 或 Codex CLI 这类宿主工具。你可以把它理解成“技能插件”。Claude Code 提供了终端交互、文件读写、命令执行的能力superpowers 则提供了“什么时候该做什么”的决策逻辑。这种分层设计的好处是解耦。宿主工具升级了superpowers 不用大改你想换一个宿主比如从 Claude Code 换到 Codex CLI技能定义大部分还能复用。实际使用中Claude Code 的 skill 调用机制比较成熟Codex CLI 也在逐步跟进。如果你两个都在用可以共享同一套技能库只是触发方式略有差异。注意superpowers 的技能触发依赖于宿主工具对 skill 机制的支持程度。Claude Code 目前对 skill 的支持比较完善Codex CLI 需要确认版本是否包含相关功能。建议先在一个宿主上跑通再考虑跨工具复用。3. 核心细节解析superpowers 里到底有哪些技能3.1 技能分类与典型代表superpowers 的技能库覆盖了软件开发的多个环节。根据我实际浏览和使用的经验大致可以分为以下几类技能类别典型技能解决什么问题代码理解项目结构分析、依赖梳理让 AI 快速摸清一个陌生项目缺陷修复Bug 定位、根因分析、修复验证避免改表面不治本功能开发需求拆解、增量实现、测试驱动防止一次性改太多导致失控重构优化安全重构、性能剖析在保证行为不变的前提下改进代码文档维护自动更新 README、API 文档减少文档与代码脱节版本控制提交信息生成、变更摘要让 commit 记录更有意义每个技能都不是孤立的它们可以组合使用。比如你先用“项目结构分析”摸清情况再用“缺陷修复”处理具体问题最后用“提交信息生成”收尾。这种组合性让 superpowers 能应对比单个技能复杂得多的场景。3.2 一个技能文件的内部结构我拿一个实际的“Bug 修复”技能来拆解。打开对应的 Markdown 文件大致会看到这样的结构# Bug Fix Skill ## 触发条件 当用户报告一个可复现的 bug并要求修复时。 ## 前置检查 - 确认 bug 是否可复现 - 确认当前分支是否干净 - 确认是否有相关测试用例 ## 执行步骤 1. 阅读相关代码理解预期行为 2. 编写一个失败的测试用例来复现 bug 3. 定位根因记录分析过程 4. 实施最小化修复 5. 运行测试确认修复有效且未破坏其他功能 6. 如果测试通过提交变更 ## 注意事项 - 不要在没有测试的情况下直接改代码 - 修复范围要最小化避免顺带重构 - 如果根因涉及多个模块先停下来与用户确认 ## 输出要求 - 修复说明 - 测试结果 - 变更文件列表这个结构的关键在于步骤明确、检查点清晰。AI 在执行时每一步都有明确的输入和输出不容易跑偏。而且“注意事项”部分实际上是在给 AI 划边界告诉它什么情况下应该停下来问人而不是自作主张。3.3 技能之间的依赖与编排单个技能能解决的问题有限superpowers 真正的威力在于技能编排。比如一个完整的“功能开发”流程可能涉及需求分析技能把模糊的需求拆成可执行的任务列表测试先行技能先写测试用例增量实现技能每次只实现一个测试用例重构技能在测试保护下优化代码文档更新技能同步更新相关文档这些技能按顺序执行每个技能完成后把结果传递给下一个。这种编排能力让 AI 能够处理需要多步骤协作的复杂任务而不是只能做单点操作。提示技能编排的复杂度取决于宿主工具的支持。Claude Code 目前可以通过在对话中逐步调用不同技能来实现编排但自动串联多个技能还需要一些手动引导。Codex CLI 的情况类似。4. 实操过程从零开始把 superpowers 跑起来4.1 环境准备与前置条件在开始之前你需要确保几件事已经安装并配置好 Claude Code 或 Codex CLI有一个可以正常工作的终端环境macOS、Linux 或 Windows 的 WSL对基本的命令行操作不陌生如果你还没装 Claude Code最简单的安装方式是通过 npmnpm install -g anthropic-ai/claude-code安装完成后在终端输入claude应该能看到交互界面。Codex CLI 的安装类似具体命令可以参考官方文档。这里不展开讲安装细节因为不同平台的步骤差异较大而且官方文档更新频繁直接看最新的更靠谱。4.2 获取 superpowers 技能库superpowers 的技能库通常以 Git 仓库的形式分发。你可以直接克隆到本地git clone https://github.com/your-org/superpowers.git ~/.superpowers克隆完成后你会看到skills目录下有一堆 Markdown 文件每个文件就是一个技能。有些版本还会包含一个config目录里面是技能启用配置。注意仓库地址和目录结构可能随版本变化建议以你获取到的实际内容为准。如果克隆不下来也可以手动下载 ZIP 包解压。4.3 在 Claude Code 中引入技能Claude Code 对 skill 的支持方式是在项目根目录或用户目录下放置技能文件然后在对话中通过特定指令触发。具体操作把 superpowers 的技能文件复制到~/.claude/skills/目录下如果目录不存在就新建启动 Claude Code输入/skills查看已加载的技能列表当你想使用某个技能时在对话中直接描述任务Claude Code 会自动匹配相关技能比如你说“帮我修复登录页面的 bug”Claude Code 会检测到“Bug Fix”技能并按照其流程执行。你也可以显式指定“使用 bug-fix 技能来修复这个问题”。4.4 在 Codex CLI 中引入技能Codex CLI 的技能引入方式略有不同。它通常通过配置文件来指定技能目录# ~/.codex/config.toml [skills] paths [~/.superpowers/skills]配置完成后重启 Codex CLI它会在启动时加载技能。使用时你可以在命令前加上技能名称比如codex run bug-fix 修复登录问题具体语法以你使用的版本为准。4.5 验证技能是否生效一个简单的验证方法是创建一个测试项目故意引入一个明显的 bug然后让 AI 去修。如果技能生效你应该能看到 AI 按照“先写测试、再修复、再验证”的流程走而不是直接改代码。如果它跳过了测试步骤说明技能可能没被正确加载。我自己的经验是第一次配置时最容易出问题的地方是路径不对。Claude Code 和 Codex CLI 对技能目录的查找逻辑不一样有的从当前项目目录找有的从用户主目录找。建议先用绝对路径配置确认生效后再改成相对路径。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最常见的问题。你明明把技能文件放好了但 AI 就是不用。排查顺序如下确认技能文件格式正确Markdown 的标题层级要清晰触发条件要明确。如果触发条件写得太模糊AI 可能匹配不上。确认技能目录被正确加载在 Claude Code 里输入/skills看列表里有没有你的技能。没有的话检查路径配置。确认任务描述能匹配触发条件如果你说“帮我看看这段代码”而技能触发条件是“当用户要求修复 bug 时”那可能匹配不上。试着用更明确的描述。检查宿主工具版本有些旧版本不支持 skill 机制升级到最新版再试。5.2 技能执行到一半停了有时候 AI 会按照技能流程走到某一步就停住比如写完测试后不继续修复。这通常是因为技能定义里设置了检查点要求 AI 在继续之前确认某些条件。你可以直接回复“继续”或“测试已确认请继续修复”来推动它。如果它频繁停下来可能是技能定义过于保守。你可以编辑技能文件把一些非关键的检查点去掉或者改成“自动继续”。5.3 多个技能冲突当你同时启用多个技能时可能会出现冲突。比如“快速修复”技能和“测试驱动修复”技能都匹配当前任务AI 不知道该用哪个。解决办法是在对话中显式指定技能名称或者在技能定义里设置优先级。5.4 常见问题速查表问题现象可能原因解决方法技能列表为空路径配置错误检查技能目录路径用绝对路径重试技能不触发触发条件不匹配修改任务描述或调整技能触发条件执行中断检查点等待确认回复“继续”或修改技能定义多个技能冲突触发条件重叠显式指定技能名称或设置优先级技能执行结果不符合预期技能定义有误打开技能文件检查步骤和注意事项提示修改技能文件后记得重启宿主工具或重新加载技能否则改动不会生效。6. 我踩过的坑和几条实在建议第一个坑是贪多。一开始我把所有技能都启用了结果 AI 每次做点什么都想走完整流程改一行代码也要先写测试、再验证、再更新文档效率反而低了。后来我只保留最常用的三四个技能其他按需临时启用体验好很多。第二个坑是技能定义写得太细。我试过把一个技能写成二十多步的详细清单结果 AI 执行时经常卡在某个步骤上反复确认。后来我把步骤压缩到七步以内只保留关键检查点流畅度明显提升。第三个坑是忽略宿主工具的差异。同样的技能文件在 Claude Code 里跑得好好的换到 Codex CLI 就可能不触发。后来我养成了习惯换工具时先拿一个最简单的技能做验证确认机制通了再批量迁移。如果你刚开始用 superpowers我的建议是先从一两个技能入手比如“Bug 修复”和“提交信息生成”这两个最容易看到效果。跑通之后再逐步扩展。另外技能文件不是圣旨你觉得哪一步不合理就直接改改成适合自己工作习惯的样子。这套框架的价值在于可定制而不是让你去适应它。最后分享一个小技巧你可以把自己常用的操作流程写成技能文件哪怕很简单。比如“每次改完代码后自动运行格式化命令”写成一个技能以后就不用每次都提醒 AI 了。积少成多你的 AI 助手会越来越懂你。