Superpowers 插件

参考来源：https://github.com/obra/superpowersopen in new window、https://github.com/obra/superpowers/blob/main/docs/README.opencode.mdopen in new window、https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.mdopen in new window

1. 它是什么

Superpowers 是一个面向 AI 编码 Agent 的完整软件开发工作流框架，由 Jesse Vincent 创建并维护。它通过一套可组合的 "技能（Skills）" 系统，强制 AI Agent 遵循软件工程最佳实践。

核心定位：

• 不是简单的命令集合，而是一套强制性工作流
• 不是可选的建议，而是自动触发的规则
• 不是单一工具，而是覆盖完整软件开发生命周期的方法论即代码

与 Oh-My-OpenCode 的关系：

• Superpowers 是技能框架，提供 TDD、调试、规划等核心工作流
• Oh-My-OpenCode 是编排层，提供多 Agent 协作、MCP、Hook 等基础设施
• 两者可以叠加使用，在 Reddit 社区中被推荐为最佳组合

2. 核心设计理念

Superpowers 基于四大核心原则：

关键洞察： 技能自动触发，无需手动干预。AI Agent 在执行任何任务前必须检查并调用适用的技能。

2.1 三大核心价值

从实际使用者视角看，Superpowers 最重要的价值不是“多了一堆技能名字”，而是它在持续阻止 AI 走偏。你可以把它理解成给 Agent 加了一层强制性的工程护栏。

可以把它概括成一句话：Superpowers 的重点不是“帮 AI 更快写代码”，而是“防止 AI 以错误方式写代码”。

2.2 高质量工作流（流程保障）

Superpowers 强调的是一个带入口条件和退出条件的完整流程，而不是零散技巧。

想法
  -> brainstorming（设计/批准）
  -> writing-plans（拆成可执行小步骤）
  -> using-git-worktrees（隔离环境）
  -> subagent-driven-development（分任务执行 + 审查）
  -> verification-before-completion（验收）
  -> finishing-a-development-branch（合并 / PR / 清理）

这条链路的价值在于：

• 每个环节都有明确边界，不能随意跳过
• 从“想法”到“交付”是连续闭环，而不是临时拼接
• 失败时会把你拉回前置步骤，而不是继续带病推进

3. 技能（Skills）系统详解

3.0.1 六大核心技能信息图

下面这张图是我重新整理后的原创流程地图版，不再沿用参考图那种“三栏上下卡片”的排布，而是改成：

• 中轴：主流程推进顺序
• 左侧：把想法讲清楚、把方案拆清楚
• 右侧：把验证、协作与交付做扎实

六大核心技能总览表：

如果把它压缩成一句话，就是：

先把想法讲清楚，再把问题验证清楚，最后把任务协作完成并安全交付。

3.0.2 六大核心技能分组速览

3.0.3 从图上应该怎么读

这张图建议按“先看中轴，再看左右节点”的方式阅读：

1. 先看中轴编号：理解整个流程是串起来的，不是六个孤立技能
2. 再看左侧：brainstorming、writing-plans 负责把输入整理成可执行方案
3. 再看右侧：systematic-debugging、test-driven-development、subagent-driven-development 负责验证与实现
4. 最后看底部收尾节点：finishing-a-development-branch 负责把工作真正变成可交付结果

它想表达的核心不是“六个技能彼此独立”，而是：

• 前面的技能给后面的技能提供输入
• 后面的技能把前面的设计与验证真正落地
• 整套链路最终输出的是一个更像资深工程师的工作过程

3.1 什么是 Skill

Skill 是一个 Markdown 文件（SKILL.md），定义特定工作流，包含：

• 常见错误警告（Red Flags） - 识别危险信号
• 快速参考表 - 关键要点速查
• 流程图 - DOT/GraphViz 可视化流程
• 强制性规则 - 不可绕过的约束

3.2 技能库（14个核心技能）

核心工作流技能

开发实践技能

协作技能

元技能

3.3 具体 Skills 的一句话作用

如果你不想一开始就记完整套系统，可以先用下面这张速查表建立直觉：

3.4 子 agent 协作模式

Superpowers 不只是“单 Agent 守纪律”，它也强调一种更清晰的协作分工。

这种模式的优点是：

• 每个子 agent 有独立上下文，不容易互相污染
• 任务可以并行推进
• 审查和实现被明确拆开，减少“自己写自己夸”的情况

4. 基本工作流程

用户请求 → brainstorming（设计细化）→ using-git-worktrees（隔离环境）
    → writing-plans（制定计划）→ subagent-driven-development（子 Agent 执行）
    → test-driven-development（TDD 实现）→ requesting-code-review（代码审查）
    → finishing-a-development-branch（完成分支）

关键约束：

• 在呈现设计并获得用户批准之前，不得调用任何实现技能、编写代码或搭建项目
• 每个技能都有 <HARD-GATE> 或 <EXTREMELY-IMPORTANT> 块强制执行

5. 安装前提与安装方法

5.1 安装前提

开始前，建议先确认以下条件：

• 已安装可正常运行的 OpenCode CLI
• 当前 OpenCode 版本支持插件与技能加载
• 本机已经配置好至少一个可用模型来源
• 你知道当前项目使用的是全局配置还是项目级配置

如果你本身已经在使用 Oh-My-OpenCode，通常再接入 Superpowers 的门槛会更低，因为很多技能与工作流已经能直接复用。

5.2 OpenCode 安装（推荐）

在 OpenCode 配置中添加插件即可。常见做法是在项目级 opencode.json 或对应配置文件中加入：

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

重启 OpenCode 后，插件会自动安装并注册技能目录。

如果你们团队希望项目内统一启用 Superpowers，建议把这段配置放到项目级配置里；如果只是个人全局偏好，再放到用户级配置。

验证安装：

Tell me about your superpowers

如果插件已生效，Agent 通常会识别并说明当前已加载的 Superpowers 能力或技能规则。

5.3 其他平台安装

5.4 版本固定

如需固定特定版本：

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

5.5 安装示例

下面给几个更贴近日常使用的例子。

示例 1：给当前项目启用 Superpowers

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

适合团队项目，希望所有人在这个仓库里都使用同样的技能纪律。

示例 2：和 Oh-My-OpenCode 一起用

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

工作流上再配合 oh-my-opencode 的 Agent / Category / Skill 体系即可。

适合已经在用多 Agent 编排、希望再补一层工程纪律约束的用户。

示例 3：锁定版本，避免团队环境漂移

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

适合稳定性优先的项目，避免插件升级后触发工作流变化。

6. 使用方法

6.1 列出可用技能

use skill tool to list skills

6.2 加载特定技能

use skill tool to load superpowers/brainstorming

6.3 自动触发

Superpowers 的核心价值在于自动触发。当你说：

• "帮我规划这个功能" → 自动触发 brainstorming
• "修复这个 Bug" → 自动触发 systematic-debugging
• "实现这个需求" → 自动触发 test-driven-development

6.4 在 OpenCode / Oh-My-OpenCode 里的实际用法

Superpowers 更像“隐形工作流层”，而不是单独敲一个命令后才会生效的插件。它的典型使用方式是：

1. 你正常向 Agent 提需求
2. Agent 根据任务类型判断哪个技能适用
3. 先调用对应技能，再进入实现、调试、规划或验证流程

例如：

• 你说“帮我设计一个新功能”时，优先走 brainstorming
• 你说“修复这个线上 Bug”时，优先走 systematic-debugging
• 你说“实现这个需求”时，优先走 test-driven-development
• 你说“任务做完了”时，优先走 verification-before-completion

如果你叠加使用 Oh-My-OpenCode，那么常见协作方式会变成：

• Oh-My-OpenCode 负责把任务分派给合适的 Agent / Category
• Superpowers 负责强制这些 Agent 先走正确的软件工程流程

也就是说：前者更偏编排，后者更偏纪律。

6.5 常见工作流对照表

如果只记一句话：

• Superpowers 决定“应该按什么流程做”
• Oh-My-OpenCode 决定“由谁来做、怎么编排来做”

7. 自定义技能与优先级

7.1 个人技能

创建目录：

mkdir -p ~/.config/opencode/skills/my-skill

创建 SKILL.md：

---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill content here]

7.2 项目技能

在项目内创建 .opencode/skills/ 目录，技能优先级通常是：

项目技能 > 个人技能 > Superpowers 技能

7.3 Skill 文件结构

skills/
  skill-name/
    SKILL.md              # 主文件（必需）
    supporting-file.*     # 辅助文件（可选）

7.4 SKILL.md 格式规范

Frontmatter（YAML）：

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

关键规则：

• name：仅使用字母、数字和连字符
• description：必须以 "Use when..." 开头，描述触发条件，不要总结工作流程
• 最大 1024 字符

8. 工具映射

Superpowers 技能使用 Claude Code 工具名，在 OpenCode 中自动映射：

8.1 什么时候应该自定义技能

以下场景适合自己补充技能：

• 团队有固定研发流程，希望强制 Agent 遵守
• 某类任务总在重复出现，值得沉淀成模板化工作流
• 你希望把仓库约束、测试约束、发布约束写成可复用规则

如果只是一次性需求，没必要为了“看起来高级”而新建技能；只有当某个流程值得长期复用时，技能化才有意义。

9. 工作原理

Superpowers 插件做两件事：

1. 注入引导上下文 - 通过 experimental.chat.system.transform Hook，为每次对话添加 Superpowers 意识
2. 注册技能目录 - 通过 config Hook，让 OpenCode 自动发现所有 Superpowers 技能

9.1 指令优先级

Superpowers 技能覆盖默认系统提示行为，但用户指令始终优先：

1. 用户显式指令（CLAUDE.md、AGENTS.md、直接请求）— 最高优先级
2. Superpowers 技能 — 覆盖默认系统行为
3. 默认系统提示 — 最低优先级

9.2 技能调用规则

铁律： 如果技能适用，AI Agent 没有选择权，必须调用。

用户消息收到 → 是否有技能适用？（即使 1% 可能）→ 调用 Skill 工具
    → 宣布："Using [skill] to [purpose]"
    → 有检查清单？→ 创建 TodoWrite 逐项完成
    → 严格遵循技能执行

10. 安装后建议做的 3 件事

1. 先验证插件是否真的加载成功
2. 再确认技能列表里能看到 Superpowers 相关技能
3. 最后用一个真实任务验证技能是否会自动触发

推荐先用这类低风险指令做试运行：

Explain what skills you would use before implementing a new feature in this repo.

如果返回里能明确提到 brainstorming、test-driven-development、verification-before-completion 等技能，说明插件已基本接通。

11. 故障排查

11.1 插件未加载

1. 检查 OpenCode 日志：

   opencode run --print-logs "hello" 2>&1 | grep -i superpowers
   
2. 验证 opencode.json 中的插件行是否正确
3. 确保使用较新版本的 OpenCode

11.2 技能未找到

1. 使用 skill 工具列出可用技能
2. 检查插件是否加载（见上）
3. 每个技能需要有效的 YAML frontmatter

11.3 引导未出现

1. 检查 OpenCode 版本是否支持 experimental.chat.system.transform Hook
2. 配置更改后重启 OpenCode

12. 更新

Superpowers 在重启 OpenCode 时自动更新（从 Git 仓库重新安装）。

手动更新：

/plugin update superpowers  # Claude Code
gemini extensions update superpowers  # Gemini CLI

13. 与 Oh-My-OpenCode 配合使用

根据社区反馈（Reddit r/ClaudeCode），Superpowers 与 Oh-My-OpenCode 是最佳组合：

• Oh-My-OpenCode 提供：多 Agent 编排、MCP、Hook、后台任务
• Superpowers 提供：TDD、系统化调试、设计先行等工作流纪律

使用建议：

1. 先安装 Oh-My-OpenCode 获得基础设施
2. 再安装 Superpowers 获得工作流纪律
3. 在提示词中包含 ultrawork 或 ulw 激活完整工作流

13.1 两者如何分工

如果你要向别人解释这两个插件的关系，可以直接用下面这套说法：

• Oh-My-OpenCode：解决 Agent 编排、模型路由、工具装载、并行任务、MCP、Hook、tmux 等“基础设施问题”
• Superpowers：解决设计先行、测试先行、系统化调试、验证闭环等“工程纪律问题”

所以它们不是互相替代，而是上下层关系：

• 没有 Oh-My-OpenCode，Superpowers 也能工作，但编排能力较弱
• 没有 Superpowers，Oh-My-OpenCode 也能工作，但更容易出现流程失控

14. 官方资源

15. 版本信息

• 当前版本： v5.0.5（2026-03-17）
• 许可证： MIT
• 作者： Jesse Vincent (@obra)
• 创建时间： 2025-10-09

16. 总结

Superpowers 不是又一个 AI 编码工具，而是一套强制软件工程纪律的框架。它解决的核心问题是：

"AI Agent 经常偏离轨道，跳过设计直接写代码，跳过测试直接交付。"

Superpowers 的解决方案：

• 不能跳过头脑风暴 — 设计先行
• 不能先写代码再补测试 — TDD 强制
• 不能未经审查就合并 — 两阶段代码审查

如果你希望 AI Agent 像经验丰富的软件工程师一样工作，Superpowers 是目前最成熟的解决方案。

16.1 本质是什么

更直白地说，Superpowers 可以理解为：

把资深工程师的工作习惯，写成 AI 必须遵守的规则。

它默认假设以下风险真实存在：

• AI 会偷懒，所以要强制验证
• AI 会跳步，所以要强制分阶段推进
• AI 会瞎猜，所以要强制找根因
• AI 会乱承诺，所以要强制用证据说话

它的最终目标不是让输出“更像 AI”，而是让输出更像一个有经验、守流程、负责任的工程师。

16.2 当前状态怎么理解

在不同 OpenCode 环境里，Superpowers 的体验可能不完全一样：

• 有些环境会把技能完整注册到 skill 工具中，能够显式列出和加载
• 有些环境虽然文件已经存在，但未必以完全相同的方式暴露给最终用户
• 即便没有完整的自动注册体验，你仍然可以按它的原则手动执行这些流程

所以阅读这篇文档时，建议把它分成两层来理解：

1. 理念层：哪些原则必须遵守
2. 集成层：当前平台把这些原则暴露成了哪些可用入口

只要你抓住这两层，就不会把 Superpowers 误解成“只是多了一些命令”。