文章目录

• Pre
• 一、为什么需要 Superpowers：从“聪明模型”到“有方法论的工程师”
• 二、整体架构：技能发现与会话注入的双引擎
  • 2.1 两个核心职责
  • 2.2 session-start：跨平台的枢纽脚本
  • 2.3 支持的平台一览
• 三、平台对比：如何选择最适合你的落地路径
• 四、Claude Code：官方插件市场的“首选体验”
  • 4.1 安装：官方 vs 社区市场
  • 4.2 更新与运行原理
  • 4.3 实战示例：在 Claude Code 中验证安装
• 五、Cursor：面向 VS Code 用户的轻量路径
  • 5.1 一条命令安装
  • 5.2 钩子机制与 JSON 适配
• 六、GitHub Copilot CLI：与 GitHub 工作流深度融合
  • 6.1 安装：注册市场 + 安装插件
  • 6.2 运行原理与工具映射
• 七、Gemini CLI：扩展系统中的原生接入
  • 7.1 安装与更新
  • 7.2 GEMINI.md：上下文注入的入口
• 八、Codex：手工党与高级用户的乐园
  • 8.1 标准安装流程（类 Unix）
  • 8.2 Windows：使用 Junction 代替符号链接
  • 8.3 启用多 Agent 支持
  • 8.4 更新与卸载
• 九、OpenCode：用配置文件管理插件与优先级
  • 9.1 安装：编辑 opencode.json
  • 9.2 验证安装
  • 9.3 从旧版安装迁移
  • 9.4 锁定版本与运行原理
• 十、统一的验证流程：如何判断“真的装好了”
  • 10.1 通用验证步骤
• 十一、常见问题排查指南（按平台分类）
  • 11.1 Claude Code / Cursor / Copilot CLI
  • 11.2 Codex
  • 11.3 OpenCode
  • 11.4 Gemini CLI
• 十二、下一步：从“装好了”到“用得顺手”
• 十三、写给工程团队的落地建议

Pre

Superpowers - 01 让 AI 真正“懂工程”：Superpowers 软件开发工作流深度解析

Superpowers - 02 用 15 个技能给你的 AI 装上「工程大脑」：Superpowers 快速开始深度解析

一、为什么需要 Superpowers：从“聪明模型”到“有方法论的工程师”

过去两年，AI 编码助手从“能写代码”逐步进化到“能协助工程实践”。但很多人的实际体验仍然是这样：

• 模型会写代码，但不会遵守你的开发流程；
• 会修 bug，却不系统化地调试；
• 能审查代码，但输出零散，难以直接执行。

Superpowers 的目标，就是在主流 AI 编码平台之上，提供一套统一的工程方法论技能库。

这样，Agent 不只是“会写代码的聊天机器人”，而更像一位懂流程、讲规范、能协作的高级工程师。

在这套系统里，“技能”是第一等公民，覆盖内容包括：

• 头脑风暴、设计规范、计划拆解；
• 子 Agent 协同开发、测试驱动、系统化调试；
• 代码审查、Git 工作流管理等。

要让这些技能在不同平台稳定发挥作用，安装与注入机制就成了核心问题。这也是本文要重点展开的部分。

二、整体架构：技能发现与会话注入的双引擎

在谈具体平台之前，先看一下 Superpowers 的通用架构设计。

2.1 两个核心职责

Superpowers 在任何平台上，最终都要完成两件事：

• 技能发现
  让 Agent 能“看见”技能目录中的所有技能（skills/ 下 15+ 个可组合技能），并理解每个技能的能力与使用方式。
• 会话注入
  在每次新对话启动时，把 using-superpowers 这个“主技能执行器”的内容，注入到当前会话中，作为 Agent 的“作战手册”和入口。

只要这两件事完成，无论平台插件机制如何差异，Agent 在体验上都是一致的。

2.2 session-start：跨平台的枢纽脚本

Superpowers 通过一个统一的 hooks/session-start 脚本，把多平台差异统一封装。

核心思想很简单，脚本本身只做三件事：

• 1）通过环境变量识别当前平台，
• 2）读取 using-superpowers 的内容，
• 3）按平台要求拼装 JSON 并输出。

平台识别主要依赖环境变量：

• CURSOR_PLUGIN_ROOT → Cursor
• CLAUDE_PLUGIN_ROOT → Claude Code
• COPILOT_CLI → GitHub Copilot CLI 等。

JSON 输出格式按平台做适配：

• Claude Code：hookSpecificOutput.additionalContext
• Cursor：additional_context（蛇形命名）
• Copilot CLI：additionalContext（驼峰命名）

在 Windows 上，又额外提供了一个多语言混合 .cmd 包装器。它通过 Git for Windows 把 CMD.exe 与 bash 桥起来，保证同一套逻辑跨平台运行。

2.3 支持的平台一览

当前正式支持的平台包括：

• Claude Code（官方/社区插件市场）
• Cursor（插件市场）
• GitHub Copilot CLI（插件市场）
• Gemini CLI（扩展系统）
• Codex（Git 克隆 + 符号链接 / Junction）
• OpenCode（opencode.json 插件配置）

它们在安装方式、更新机制、子 Agent 以及 Windows 支持方面略有差异，下面会逐一拆解。

三、平台对比：如何选择最适合你的落地路径

先看一张官方给出的对比表，帮助你快速选型：

平台	安装方式	更新方式	技能发现机制	子 Agent 支持	Windows 支持
Claude Code	插件市场，一条命令	/plugin update	插件自动发现 skills/	原生 Task 工具	多语言混合 .cmd 包装器
Cursor	插件市场，一条命令	插件自动更新	插件自动发现 skills/	原生 Task 工具	多语言混合 .cmd 包装器
Copilot CLI	插件市场，两条命令	/plugin update	插件自动发现技能	原生 task 工具	多语言混合 .cmd 包装器
Gemini CLI	extensions install 一条命令	extensions update	扩展自动发现（GEMINI.md）	工具映射	完全支持
Codex	Git 克隆 + 符号链接	git pull	扫描 ~/.agents/skills/	multi_agent	Junction（无需提权）
OpenCode	opencode.json 插件配置	重启自动更新	插件注册技能目录	@mention 系统	完全支持

简单理解：

• 想一条命令搞定 → 选 Claude Code / Cursor / Gemini CLI；
• 团队大量使用 GitHub 生态 → Copilot CLI 是天然入口；
• 喜欢掌控文件系统、配置细节 → Codex、OpenCode 更灵活。

四、Claude Code：官方插件市场的“首选体验”

Claude Code 是 Superpowers 官方强烈推荐的入口之一。

原因很简单：安装简单、更新方便、原生 Task 能力强。

4.1 安装：官方 vs 社区市场

Claude 提供两个插件市场来源：

官方插件市场（推荐）

只需一条命令：

/plugin install superpowers@claude-plugins-official

社区插件市场（更新更快）

需要先添加社区市场，再安装插件：

# 步骤 1：注册社区市场/plugin marketplace add obra/superpowers-marketplace
# 步骤 2：安装 Superpowers/plugin install superpowers@superpowers-marketplace

4.2 更新与运行原理

更新命令统一为：

/plugin update superpowers

运行流程如下：

• 1）会话一启动，就会按照 hooks/hooks.json 中的配置触发 SessionStart 钩子；
• 2）随后，这个钩子会调用 session-start 脚本，产出带有 using-superpowers 内容的 hookSpecificOutput.additionalContext；
• 3）接下来，Claude Code 会继续借助自身的插件能力扫描 skills/ 目录，整个过程不需要额外的符号链接，也不用再补充其他配置。

4.3 实战示例：在 Claude Code 中验证安装

安装完成后，可以直接在新会话中输入：

告诉我你的 superpowers

如果 Agent 能明确说明自己将使用哪些技能，如 brainstorming、systematic-debugging、requesting-code-review 等，并在后续对话中主动宣告“正在使用 某某 技能”，就说明注入链路工作正常。

五、Cursor：面向 VS Code 用户的轻量路径

对于更偏 IDE 一体化体验的开发者，Cursor 提供了极低上手门槛的选项。

5.1 一条命令安装

Cursor 在聊天面板直接输入：

/add-plugin superpowers

或者在插件市场中搜索 “superpowers” 安装。

5.2 钩子机制与 JSON 适配

Cursor 使用独立的钩子配置文件 hooks/hooks-cursor.json，但触发的仍然是同一份 session-start 脚本。

区别在于：

• Cursor 要求 JSON 字段为 additional_context（蛇形命名）；
• session-start 通过 CURSOR_PLUGIN_ROOT 环境变量判断当前平台，自动切换输出格式。

这意味着，同一份脚本可以同时兼容 Claude 与 Cursor，只是表现层字段略有差异。

六、GitHub Copilot CLI：与 GitHub 工作流深度融合

如果你的团队已经高度依赖 GitHub Copilot CLI，Superpowers 可以直接作为其插件生态的一部分。

6.1 安装：注册市场 + 安装插件

安装分两步进行：

# 步骤 1：注册插件市场copilot plugin marketplace add obra/superpowers-marketplace
# 步骤 2：安装 Superpowers 插件copilot plugin install superpowers@superpowers-marketplace

6.2 运行原理与工具映射

Copilot CLI 会设置环境变量 COPILOT_CLI=1。

session-start 发现后，会输出包含 additionalContext 字段的 JSON（驼峰命名）。

由于 Superpowers 技能内部是基于 Claude 工具命名设计的，Copilot CLI 在底层做了一层映射：

• Claude Read → Copilot view
• Write → create
• Task → task
• TodoWrite → 内置 todos 表上的 sql 查询。

在 CLI 侧，skill 工具会自动发现来自插件的技能。你可以：

• 让 Agent 使用 skill 列出所有技能；
• 直接下达指令：“使用 brainstorming 技能帮我设计这个功能”。

七、Gemini CLI：扩展系统中的原生接入

Gemini CLI 通过官方扩展机制集成 Superpowers，其安装方式同样保持一条命令体验。

7.1 安装与更新

安装：

gemini extensions install https://github.com/obra/superpowers

更新：

gemini extensions update superpowers

7.2 GEMINI.md：上下文注入的入口

在仓库根目录下，有一个专门为 Gemini 设计的 GEMINI.md 文件。

它的作用是：

• 使用 Gemini 支持的 @./path 语法，引用 using-superpowers 主技能；
• 再引用一份专门的“工具映射参考”文件，完成从 Claude 风格工具到 Gemini 原生工具的对应，例如用 activate_skill 替代 Claude 的 Skill 工具。

对用户来说，你只需要安装扩展。后续的上下文注入和工具映射，都会在扩展内部自动完成。

八、Codex：手工党与高级用户的乐园

Codex 没有插件市场，因此 Superpowers 在这里采用的是Git 克隆 + 文件系统符号链接的方式。

8.1 标准安装流程（类 Unix）

三条命令完成安装：

# 步骤 1：克隆仓库git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
# 步骤 2：创建技能符号链接mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
# 步骤 3：重启 Codex

启动时，Codex 会自动扫描 ~/.agents/skills/，读取每个技能目录下的 SKILL.md frontmatter，完成技能注册与加载。

8.2 Windows：使用 Junction 代替符号链接

在 Windows 上，推荐使用 Junction（连接点）而不是符号链接：

# 步骤 1：克隆仓库git clone https://github.com/obra/superpowers.git "$env:USERPROFILE.codexsuperpowers"
# 步骤 2：创建 JunctionNew-Item -ItemType Directory -Force -Path "$env:USERPROFILE.agentsskills"
cmd /c mklink /J "$env:USERPROFILE.agentsskillssuperpowers" "$env:USERPROFILE.codexsuperpowersskills"
# 步骤 3：重启 Codex

好处是：不需要启用开发者模式，也不强制管理员权限。

8.3 启用多 Agent 支持

很多高级技能依赖 Codex 的多 Agent 功能，如：

• dispatching-parallel-agents
• subagent-driven-development 等。

在配置文件中启用：

[features]
multi_agent = true

8.4 更新与卸载

更新：

cd ~/.codex/superpowers && git pull

由于技能目录通过符号链接挂载，更新会在下次重启 Codex 时立即生效。

卸载：

rm ~/.agents/skills/superpowers
# 如需完全清理
# rm -rf ~/.codex/superpowers

九、OpenCode：用配置文件管理插件与优先级

OpenCode 通过一个 JSON 配置文件管理插件依赖，Superpowers 在这里以“插件包”的形式出现。

9.1 安装：编辑 opencode.json

在以下任一位置添加配置文件：

• 全局：~/.config/opencode/opencode.json
• 项目级：/.opencode/opencode.json

添加插件字段：

{"plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]}

重启 OpenCode 后，Bun 会自动安装插件并注册所有技能。

9.2 验证安装

重启后可以这样验证：

• 直接问：“告诉我你的 superpowers”；
• 或使用原生的 skill 工具列出技能：use skill tool to list skills。

9.3 从旧版安装迁移

如果之前通过“Git 克隆 + 符号链接”方式安装，需要先清理旧文件：

rm -f ~/.config/opencode/plugins/superpowers.js
rm -rf ~/.config/opencode/skills/superpowers
rm -rf ~/.config/opencode/superpowers

再按前述方式配置 opencode.json 即可。

9.4 锁定版本与运行原理

锁定特定版本（常用于 CI 或团队统一环境）：

{"plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]}

运行时，.opencode/plugins/superpowers.js 主要会处理两件事：

• 1）在 config 钩子里，把 Superpowers 的技能目录直接注入到 OpenCode 的运行时配置中。这样一来，技能不需要再手动注册；
• 2）借助 experimental.chat.messages.transform 钩子，把 using-superpowers 的引导内容写入每个会话的第一条用户消息，而不是放进系统消息。这样做的目的很明确：尽量减少系统 prompt 反复注入造成的 token 膨胀，同时也能避开一部分兼容性问题。

技能优先级规则：

• 1）项目技能 .opencode/skills/
• 2）个人技能 ~/.config/opencode/skills/
• 3）Superpowers 自带技能

这使你可以在项目级覆盖任何 Superpowers 技能，而无需 fork 插件本身。

十、统一的验证流程：如何判断“真的装好了”

不论你在哪个平台安装 Superpowers，都可以用同一套“验收脚本”。

10.1 通用验证步骤

• 确保是“全新会话”
  因为技能发现与注入都是在会话启动时完成的，安装后必须重启 Agent。
• 给一个“应该触发技能”的任务
  例如：

输入内容	预期触发的技能
“帮我规划这个功能”	brainstorming
“我们来调试这个问题”	systematic-debugging
“审查我的代码”	requesting-code-review
“告诉我你的 superpowers”	using-superpowers

• 观察技能宣告行为
  安装成功时，Agent 通常会说类似：“我将使用某个技能来完成这项任务”。
• 如失败，先重启再排查
  最常见原因就是：“安装后没有重启 Agent”。重启平台或新建对话，往往可以解决大部分“技能未触发”的问题。

如果它直接开始编码而不提技能，多半说明注入链路存在问题。

十一、常见问题排查指南（按平台分类）

在实际团队落地过程中，排查路径非常关键。下面按平台整理官方给出的典型问题与解决方案。

11.1 Claude Code / Cursor / Copilot CLI

常见问题表：

症状	可能原因	建议解决方案
技能完全不触发	插件未安装	使用 /plugin list 检查是否存在 Superpowers
提示 “未找到 skill 工具”	Claude Code 版本过旧	升级到最新版本
Windows 上出现钩子执行错误	未安装 Git for Windows	从 git-scm.com 安装 Git for Windows
技能行为陈旧、缺少最新更新	插件缓存未刷新	执行 /plugin update superpowers 并重启

11.2 Codex

典型问题与排查：

症状	可能原因	建议解决方案
技能列表中看不到 Superpowers	符号链接损坏或不存在	ls -la ~/.agents/skills/superpowers 检查链接
Windows 提示 “bash not found”	Git Bash 未加入 PATH	确认已安装 Git for Windows，重启终端
Junction 创建失败	权限问题	以管理员身份运行 PowerShell
启动时加载的是旧版引导程序	~/.codex/AGENTS.md 中残留旧代码块	删除其中的 superpowers-codex bootstrap 相关内容

11.3 OpenCode

对于 OpenCode，更多问题集中在配置文件与版本兼容上：

症状	可能原因	建议解决方案
插件完全没有加载	opencode.json 语法错误	检查 JSON 格式，确保 plugin 是数组
无法发现任何 Superpowers 技能	插件配置钩子执行失败	使用 `opencode run --print-logs “hello” 2>&1
引导内容没有注入	OpenCode 版本过旧	升级到支持 experimental.chat.messages.transform 的版本

11.4 Gemini CLI

在 Gemini CLI 上的问题相对集中在扩展注册：

症状	可能原因	建议解决方案
CLI 无法识别 superpowers 扩展	扩展注册表或安装过程异常	gemini extensions remove superpowers 后重新执行 install 命令
技能看似安装但不能激活	上下文文件未被正确加载	确认扩展根目录存在 GEMINI.md，必要时重新安装

十二、下一步：从“装好了”到“用得顺手”

当你在任一平台成功安装并验证 Superpowers 之后，建议按以下路径逐步深入：

• 先走一遍官方“快速入门”工作流
  从“构思功能想法”到“完成带测试与代码审查的实现”，体验一次完整的技能组合使用。
• 理解底层技能机制
  通过“技能发现与激活”等文档，弄清楚 frontmatter、技能触发条件、子 Agent 协作等细节，方便你为团队定制自己的技能库。
• 看多平台兼容性设计
  如果你所在团队横跨多平台，例如前端用 Cursor，后端用 Claude Code，DevOps 用 Copilot CLI，建议阅读多平台兼容性内容，理解工具映射和行为一致性保障策略。

从工程实践的角度看，Superpowers 本身可以被视作一个“AI 开发流程的可移植标准库”。

一旦你在团队中规范了技能使用与工作流，就可以在不同平台间复用同一套方法论，而不是在每个 IDE 里重新训练 Agent 的习惯。

十三、写给工程团队的落地建议

• 在一个平台先打样，再推广到多平台
  建议选 Claude Code 或 Cursor 作为“样板环境”，把技能使用习惯沉淀清晰后，再迁移到 Copilot CLI、Gemini CLI、Codex、OpenCode 等环境。
• 定义团队级“技能使用规范”
  例如明确：
  • 新功能设计必须先使用 brainstorming 技能；
  • Bug 处理必须走 systematic-debugging；
  • PR 前必须走 requesting-code-review 等。
• 在 OpenCode / Codex 上做项目级扩展
  利用 OpenCode 的优先级规则，在项目技能中覆盖 Superpowers 的部分行为（如增加公司内部安全检查步骤）；在 Codex 中通过多 Agent 功能，把 Superpowers 技能与你自己的 Agent 工作流结合。
• 把“验证安装”做成团队自检脚本
  可以把文档中的验证提示词固化进一个“环境自检说明”里，要求每位开发者在本机完成一次验证，并把结果截图或录屏纳入入项 checklist。

通过这些实践，你可以把 Superpowers 从“一个工具仓库”升级为“团队级工程习惯载体”，这也是它真正的价值所在。