通过 Superpowers 理解各平台的插件支持机制

Superpowers 是一个适合用来观察“AI 编码平台如何支持插件”的真实样本。它并不是一个要被业务代码直接 import 的开发库，而是一套围绕 AI 编码助手构建的技能工作流系统。仓库中同时包含技能定义、启动脚本、命令封装、子代理提示词，以及面向不同平台的适配文件。也正因为如此，Superpowers 可以帮助我们把“插件支持”这件事拆开来看：平台究竟如何识别插件、发现技能、注入上下文，以及最终如何把这些能力交给模型使用。

本文聚焦仓库中可直接观察到配置文件的平台适配：Claude Code、Cursor、Codex、OpenCode 和 Gemini CLI，并以 Superpowers 的真实文件为例，说明其运行机制与平台差异。

一、Superpowers 是什么

从工程结构上看，Superpowers 更准确的定义是：

一套面向 AI 编码助手的技能工作流核心，以及围绕不同平台实现的插件适配层。

它所解决的问题，不是“给模型增加一个命令”，而是“为模型提供一套稳定的工作流程”。这套流程在 README 中有明确描述，核心包括：

• 在写代码之前先进行需求梳理和设计讨论
• 在设计确认之后生成实施计划
• 在实施阶段遵循测试、审查与分阶段推进
• 在任务结束后完成验证和收尾

对应的基础流程可以概括为：

brainstorming → writing-plans → executing-plans / subagent-driven-development
→ test-driven-development → requesting-code-review → finishing-a-development-branch

因此，Superpowers 的重点不是单个命令，而是由一组 skills 共同定义的工作方式。平台安装这个插件之后，实际获得的是一套可被自动触发和按需调用的工程流程。

二、Superpowers 中的主要文件分别负责什么

为了便于从整体上理解仓库结构，下面给出一级目录文件树示意：

superpowers/
├── .claude-plugin/        Claude Code 插件声明与 marketplace 配置
├── .codex/               Codex 安装与接入说明
├── .cursor-plugin/       Cursor 插件 manifest
├── .opencode/            OpenCode 插件实现与安装配置
├── agents/               子代理角色与提示词
├── commands/             常用流程命令封装
├── docs/                 平台文档、设计稿与规划文档
├── hooks/                会话启动与平台 hook 配置
├── skills/               核心技能库
├── tests/                技能与平台适配测试
├── CHANGELOG.md          版本更新记录
├── CLAUDE.md             Claude 侧上下文与协作说明
├── GEMINI.md             Gemini 侧上下文入口文件
├── README.md             项目总览与安装说明
├── gemini-extension.json Gemini CLI 扩展描述文件
└── package.json          项目基础元信息

理解 Superpowers，最好的方式不是先看某个平台，而是先看仓库本身。这个仓库中的关键目录，大致可以分为四类。

1. 能力核心

• skills/：核心技能库。每个子目录代表一个 skill，入口通常为 SKILL.md。例如 skills/brainstorming/SKILL.md、skills/using-superpowers/SKILL.md、skills/test-driven-development/SKILL.md。
• commands/：对常见流程的命令封装，例如 brainstorm.md、write-plan.md、execute-plan.md。
• agents/：子代理提示词与协作角色定义，例如 agents/code-reviewer.md。
• hooks/session-start：跨平台复用的启动脚本，是插件在会话开始时注入引导上下文的核心入口。

2. 平台适配层

• .claude-plugin/：Claude Code 的插件元信息与 marketplace 描述。
• .cursor-plugin/：Cursor 的插件 manifest，显式声明 skills、agents、commands 与 hooks 的入口。
• .codex/：Codex 的安装说明，强调通过固定 skills 目录完成发现。
• .opencode/：OpenCode 的插件实现与安装说明。
• gemini-extension.json：Gemini CLI 的扩展描述文件。
• GEMINI.md：Gemini CLI 的上下文入口文件。

3. 文档与设计记录

• README.md：总体介绍、安装方式、工作流概览。
• docs/README.codex.md、docs/README.opencode.md：平台专用文档。
• docs/plans/、docs/superpowers/specs/：设计与规划文档。

4. 测试与验证

• tests/：包含针对 Claude Code、OpenCode、技能触发与子代理流程的测试脚本。

从这里就可以自然引出“插件”的概念。对于 Superpowers 来说，skills/ 和 hooks/ 才是能力本体；而 .claude-plugin/、.cursor-plugin/、.opencode/、gemini-extension.json 等文件，负责把这些能力接到具体平台上。换句话说，插件文件的主要职责是声明、注册和适配；技能文件的主要职责是定义行为。

三、插件的通用运行机制

虽然各个平台的接入方式不同，但从运行链路上看，Superpowers 的机制具有高度一致性：先让平台识别插件或技能包，再让平台发现能力目录，最后在会话启动时为模型注入一段引导上下文，使模型知道自己应该如何使用这些技能。

整体流程如下图所示：

flowchart TD
    A[安装或注册 Superpowers] --> B[平台识别插件/扩展]
    B --> C[发现 skills commands agents hooks]
    C --> D[触发 Session Start 或等价启动机制]
    D --> E[读取 using-superpowers 与相关映射文件]
    E --> F[将引导内容注入模型上下文]
    F --> G[模型优先检查相关技能]
    G --> H[按技能工作流执行任务]

这个过程中有两个关键点。

1. 技能发现

平台必须先知道 skills/ 在哪里。不同平台的实现方式不同：

• 有的平台在 manifest 中显式声明 skills 目录
• 有的平台通过固定目录扫描技能
• 有的平台在运行时动态修改配置，把 skills 路径注入平台配置中

2. 启动引导

Superpowers 不只是让平台“找到技能”，还需要让模型在新会话开始时就知道这些技能应当如何使用。这正是 skills/using-superpowers/SKILL.md 的作用。

该文件定义了一条核心规则：如果某个 skill 有可能适用，就应当优先调用 skill，而不是直接回答问题或直接开始编码。也就是说，Superpowers 的目标不是增加若干可选工具，而是改变代理的默认工作方式。

在仓库中，跨平台共用的 hooks/session-start 脚本会读取 skills/using-superpowers/SKILL.md，将其拼装为一段额外上下文，再按不同平台要求的格式输出。平台一旦接受了这段内容，模型从第一轮对话开始就会按这套规则工作。

四、以 Superpowers 为例，各平台下插件是如何运作的

4.1 Claude Code

Claude Code 的接入模式可以概括为：插件市场安装 + 插件元信息声明 + 会话启动 Hook 注入上下文。

安装入口

README 中给出的安装方式包括：

/plugin install superpowers@claude-plugins-official

或者：

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

这表明 Claude Code 本身提供插件市场和插件安装能力。

关键配置文件

• .claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• hooks/hooks.json
• hooks/session-start

其中，.claude-plugin/plugin.json 主要描述插件名称、版本、作者、仓库地址等元信息。.claude-plugin/marketplace.json 则面向 marketplace 场景，描述某个 marketplace 中可提供哪些插件。

真正影响运行时行为的是 hooks/hooks.json。该文件声明了 SessionStart 时需要执行的 hook，并最终调用 hooks/run-hook.cmd session-start。后续再由 hooks/session-start 读取 using-superpowers 的内容，并以 Claude Code 需要的 hookSpecificOutput.additionalContext 格式输出。

运行机制

Claude Code 下的运行链路可以概括为：

安装插件 → Claude Code 识别插件元信息 → SessionStart 触发 hook
→ 执行 session-start → 读取 using-superpowers → 注入 additionalContext
→ 模型优先按 skill 规则工作

说明

在这个模型中，.claude-plugin/ 更接近“插件声明层”；真正决定模型如何工作的，是 hooks/ 与 skills/。Claude Code 的优势是平台集成度高、安装路径清晰；限制在于插件作者需要遵循 Claude Code 的 hook 协议与输出格式。

4.2 Cursor

Cursor 的接入模式与 Claude Code 接近，但 manifest 更集中，入口声明也更直接。

安装入口

README 中给出的安装方式为：

/add-plugin superpowers

关键配置文件

• .cursor-plugin/plugin.json
• hooks/hooks-cursor.json
• hooks/session-start

Cursor 的 .cursor-plugin/plugin.json 不只包含元信息，还显式声明了以下内容：

• skills: "./skills/"
• agents: "./agents/"
• commands: "./commands/"
• hooks: "./hooks/hooks-cursor.json"

相比之下，Cursor 的 manifest 更像“总入口清单”，平台可以直接从中得知所有核心目录的位置。

运行机制

hooks/hooks-cursor.json 声明 sessionStart 时执行 ./hooks/session-start。随后，同一个跨平台脚本会根据环境变量识别当前平台是 Cursor，并输出 Cursor 需要的 additional_context 字段。

因此，Cursor 下的流程为：

安装插件 → Cursor 读取 manifest 中的 skills/agents/commands/hooks
→ sessionStart 触发 → 执行 session-start
→ 注入 additional_context → 模型按技能规则工作

说明

Cursor 的优势在于结构清晰、入口集中，适合理解一个插件“把哪些能力暴露给平台”。其限制主要在于，插件作者需要在 manifest 中显式维护这些目录入口，并适配 Cursor 的 hook 约定。

4.3 Codex

Codex 的接入思路与前两者明显不同。它更接近“技能目录发现”，而不是“完整插件包加载”。

安装入口

.codex/INSTALL.md 给出的安装方式为：

git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

关键配置文件

• .codex/INSTALL.md
• docs/README.codex.md
• skills/

运行机制

Codex 的关键步骤是把 skills/ 挂到 ~/.agents/skills/。这意味着平台的核心能力是“原生技能发现”：

clone 仓库 → 将 skills 挂载到固定发现目录
→ Codex 启动时扫描 ~/.agents/skills/
→ 读取各 skill 的 SKILL.md frontmatter
→ 在任务匹配时自动触发或按需加载

这里并没有像 Claude Code 或 Cursor 那样的 manifest 入口文件。平台不需要先识别一个复杂插件包，而是直接识别技能目录。

说明

Codex 的优势是机制直接、目录约定清晰，适合把技能作为一等公民来管理；限制是用户或安装脚本通常需要显式处理软链接或目录挂载，插件包装能力相对较弱。

4.4 OpenCode

OpenCode 的实现体现了另一种思路：在运行时通过插件脚本直接修改平台配置，并注入上下文。

安装入口

.opencode/INSTALL.md 给出的方式是在 opencode.json 中加入：

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

关键配置文件

• .opencode/INSTALL.md
• .opencode/plugins/superpowers.js
• skills/using-superpowers/SKILL.md

运行机制

.opencode/plugins/superpowers.js 主要完成两项工作：

第一，动态注册技能路径。脚本会把 Superpowers 的 skills 目录写入 config.skills.paths，从而让 OpenCode 在运行时发现这些技能，而不要求用户手动创建软链接或移动目录。

第二，动态注入引导内容。脚本会读取 using-superpowers/SKILL.md，移除 frontmatter 后形成 bootstrap 文本，并通过 experimental.chat.messages.transform 插入到每个会话的第一条用户消息之前。

整体链路如下：

在 opencode.json 中声明插件 → OpenCode 加载 superpowers.js
→ 运行时把 ../../skills 注册到 config.skills.paths
→ 对话启动时注入 using-superpowers bootstrap
→ 模型按技能规则执行

说明

OpenCode 的优势是自动化程度高，安装完成后通常不需要用户再手工管理技能目录；限制在于对平台运行时接口依赖更强，插件脚本本身需要跟随平台 API 演进而维护。

4.5 Gemini CLI

Gemini CLI 的接入方式最轻量，重点在于“扩展描述文件 + 上下文入口文件”。

安装入口

README 中给出的安装方式为：

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

关键配置文件

• gemini-extension.json
• GEMINI.md
• skills/using-superpowers/SKILL.md
• skills/using-superpowers/references/gemini-tools.md

运行机制

gemini-extension.json 中最重要的字段是：

"contextFileName": "GEMINI.md"

而 GEMINI.md 本身并不重复定义完整规则，而是进一步引用：

@./skills/using-superpowers/SKILL.md
@./skills/using-superpowers/references/gemini-tools.md

也就是说，Gemini CLI 会先把 GEMINI.md 当作入口上下文文件，再由该文件把 using-superpowers 及 Gemini 平台的工具映射引入会话。

整体流程为：

安装扩展 → Gemini CLI 读取 gemini-extension.json
→ 载入 GEMINI.md 作为上下文入口
→ 引入 using-superpowers 与 Gemini 工具映射
→ 模型按技能规则工作

说明

Gemini CLI 的优势是结构轻量、入口单一、维护成本相对较低；限制是上下文组织更依赖文本入口文件，平台可见的结构化注册能力相对较少。

五、各平台特点与适用性汇总

从 Superpowers 的实现可以看出，各平台都支持“扩展”，但扩展模型并不相同。差异主要体现在以下几个维度：

• 平台如何识别一个插件或技能包
• 平台如何发现 skills 目录
• 会话引导内容由谁注入，以及通过什么格式注入
• 安装后的自动化程度如何

下表可以作为一个总结：

平台	主要机制	优点	局限
Claude Code	插件市场 + Hook 注入	官方安装链路清晰，平台集成度高，会话启动控制能力强	需要遵循特定 hook 协议与输出格式
Cursor	Manifest 显式声明 + Hook 注入	结构清晰，技能、命令、代理与 hook 的入口一目了然	适配层字段较多，需要显式维护
Codex	固定目录技能发现	模型与技能的关系直接，适合以 skills 为中心管理能力	通常需要手工处理目录或软链接
OpenCode	运行时插件脚本	自动化程度高，可动态注册技能目录并注入上下文	更依赖平台运行时接口，适配脚本需要维护
Gemini CLI	扩展描述 + 上下文入口文件	结构轻量，入口简单，适合文档驱动的扩展方式	平台层面的结构化注册能力相对较弱

如果进一步从工程设计角度总结，可以得到三点结论。

1. 插件文件不等于功能本体

Superpowers 的核心能力不在 .claude-plugin/ 或 .cursor-plugin/ 里，而在 skills/、commands/、agents/、hooks/session-start 中。平台适配文件负责“让平台看见它”，而不是“定义它能做什么”。

2. AI 平台的插件关键能力之一是上下文控制

传统插件更关注菜单、事件或 API 扩展；AI 编码平台的插件则多了一项关键能力：让模型在会话一开始就获得一套工作规则。Superpowers 的跨平台实现，几乎都围绕这件事展开。

3. 跨平台插件设计的关键是分层

Superpowers 的设计价值，不在于为每个平台写完全不同的一套逻辑，而在于保持一套统一的能力核心，再根据平台的插件模型提供不同的适配层。这样的设计既减少重复，又便于持续演进。

结语

Superpowers 提供了一个非常清晰的观察窗口。通过这个仓库可以看到，所谓“平台支持插件”，并不是一个抽象概念，而是由具体的工程机制组成：如何安装、如何发现技能、如何在会话启动时注入规则、如何把这些规则交给模型执行。

对于 Claude Code、Cursor、Codex、OpenCode 和 Gemini CLI 来说，它们都支持扩展，但支持的是不同形态的扩展能力。Superpowers 的价值，正在于它把这些能力放在同一个仓库中，以统一的技能核心，对接各自不同的平台机制。

如果需要用一句话概括本文的结论，可以表述为：

Superpowers 不是单一平台上的一个插件，而是一套跨平台的技能工作流系统；不同平台的差异，主要体现在它们如何识别、发现并驱动这套能力。