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，最简单的安装方式是通过 npm：
npm 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 助手会越来越懂你。
