Superpowers 深度指南

Superpowers 是一套面向 Coding Agent 的软件开发方法论，它通过可组合的 Skill 让 Agent 按照更严格的工程流程工作。

是什么

Superpowers 的核心不是“多几个提示词”，而是让 Agent 在合适的场景自动调用合适的技能。例如：

做功能前先用 brainstorming 澄清目标。
排错时先用 systematic-debugging 找根因。
写代码时用 test-driven-development 强制红绿重构。
完成前用 verification-before-completion 要求真实验证。

它的目标是让 Agent 不再凭感觉直接改代码，而是遵守一套可复用、可审查、可迭代的工程流程。

官方地址

类型	地址
官方 GitHub	https://github.com/obra/superpowers
Claude 插件页	https://claude.com/plugins/superpowers
Codex 安装说明	https://github.com/obra/superpowers/blob/main/docs/README.codex.md

适用场景

场景	是否推荐
想让 Agent 少猜、多验证	推荐
想把团队工程习惯写成可复用流程	推荐
经常让 Agent 修 bug、写测试、做 code review	推荐
只想临时问几个问题	不必安装
不能接受 Agent 被强流程约束	可能不适合

安装准备

环境	说明
Claude Code / Codex / Gemini CLI / Cursor / OpenCode 等宿主	Superpowers 需要宿主 Agent 加载 skills 或插件
Git	手动安装和更新需要
能访问官方仓库	推荐只从 `obra/superpowers` 安装
项目测试命令	TDD 和验证类技能需要

安装方式

Claude Code 官方插件市场

在 Claude Code 中执行：

text

/plugin install superpowers@claude-plugins-official

Claude Code Superpowers Marketplace

也可以先添加 Superpowers marketplace：

text

/plugin marketplace add obra/superpowers-marketplace

然后安装：

text

/plugin install superpowers@superpowers-marketplace

Codex CLI

Codex 可以通过原生 skill discovery 使用 Superpowers。官方手动安装方式是克隆仓库并建立 skill 目录链接：

bash

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

然后重启 Codex。

Windows PowerShell 可以用 junction：

powershell

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

如果要使用并行 subagent 相关能力，Codex 侧可能需要启用 multi-agent 功能：

toml

[features]
multi_agent = true

Gemini CLI

Gemini CLI 可以用 extensions 安装：

bash

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

更新：

bash

gemini extensions update superpowers

OpenCode

官方推荐让 OpenCode 获取安装说明：

text

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

核心目录和机制

Superpowers 的基本单位是 Skill。每个 Skill 通常是一个目录，里面有 SKILL.md：

text

skills/
  using-superpowers/
    SKILL.md
  systematic-debugging/
    SKILL.md
  test-driven-development/
    SKILL.md

SKILL.md 的 frontmatter 会描述技能名称和触发条件：

markdown

---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior
---

Agent 根据用户请求和 description 判断是否需要加载对应技能。

核心 Skill

Skill	作用	使用场景
`using-superpowers`	要求 Agent 在任务开始前检查相关技能	所有会话入口
`brainstorming`	需求澄清、方案比较、设计确认	新功能、行为变更
`writing-plans`	把设计拆成可执行计划	多步骤实现前
`executing-plans`	按计划执行实现	已有实现计划
`test-driven-development`	强制先写失败测试再实现	功能、bugfix、重构
`systematic-debugging`	四阶段根因排查	bug、测试失败、异常行为
`verification-before-completion`	完成前必须真实验证	声称完成前
`requesting-code-review`	请求代码审查	合并或交付前
`receiving-code-review`	严谨处理 review 反馈	收到审查意见后
`using-git-worktrees`	使用隔离工作树开发	并行分支和复杂任务
`dispatching-parallel-agents`	并行调度子 Agent	独立任务并行
`subagent-driven-development`	子 Agent 驱动开发	大任务拆分执行
`finishing-a-development-branch`	完成分支后的合并/PR/清理决策	开发完成后
`writing-skills`	编写和测试新 Skill	扩展技能库

命令和操作参考

Superpowers 的很多能力不是传统 CLI 子命令，而是被宿主 Agent 自动发现和调用。常见操作如下：

操作	命令或写法	作用	注意事项
Claude 插件安装	`/plugin install superpowers@claude-plugins-official`	安装官方插件	在 Claude Code 内执行
添加 marketplace	`/plugin marketplace add obra/superpowers-marketplace`	添加 Superpowers marketplace	之后才能从该 marketplace 安装
Codex 手动安装	`ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers`	让 Codex 发现 skills	重启 Codex 才会扫描
Gemini 安装	`gemini extensions install https://github.com/obra/superpowers`	作为 Gemini extension 使用	以 Gemini 当前扩展机制为准
更新 Codex 版	`cd ~/.codex/superpowers && git pull`	拉取最新 skills	symlink 模式会即时生效
卸载 Codex 版	`rm ~/.agents/skills/superpowers`	移除 skill 入口	可选删除 clone
指名使用技能	`请使用 systematic-debugging 排查这个问题`	手动触发特定 Skill	适合自动触发不明显时

与 gstack、OpenSpec 的关系

工具	关注点
Superpowers	单个任务该怎么严谨执行
gstack	一次开发从需求到发布怎么组织
OpenSpec	需求和变更规格如何沉淀

可以组合使用：OpenSpec 负责规格，gstack 负责交付流程，Superpowers 负责每一步的执行纪律。

安全建议

只从官方仓库或官方 marketplace 安装。
不要把生产密钥写进 Skill。
自定义 Skill 要明确何时触发，避免过宽的 description。
不要跳过验证类 Skill，尤其是 verification-before-completion。
并行 Agent 只处理独立文件或独立模块，避免互相覆盖。

排错

Codex 中没有发现技能

检查 symlink：

bash

ls -la ~/.agents/skills/superpowers
ls ~/.codex/superpowers/skills

确认后重启 Codex。

技能没有自动触发

可能是任务描述和 description 不匹配。可以直接点名：

text

请使用 test-driven-development 来实现这个 bugfix。

更新后行为变化

查看 Superpowers 仓库的 release notes，或者回看具体 Skill 的 SKILL.md。Skill 是流程定义，更新可能会改变 Agent 的工作顺序。

总结

Superpowers 适合已经开始严肃使用 Coding Agent 的开发者。它不会替你选择需求，也不会保证 Agent 永远正确，但它能显著减少“凭感觉改代码、没验证就说完成、遇到 bug 乱猜”的问题。

如果你只安装一个增强工具，Superpowers 更像是给 Agent 加上工程纪律。

Superpowers 深度指南

是什么

官方地址

适用场景

安装准备

安装方式

Claude Code 官方插件市场

Claude Code Superpowers Marketplace

Codex CLI

Gemini CLI

OpenCode

核心目录和机制

核心 Skill

命令和操作参考

推荐工作流

新功能

Bug 修复

创建团队自己的 Skill

与 gstack、OpenSpec 的关系

安全建议

排错

Codex 中没有发现技能

技能没有自动触发

更新后行为变化

总结

Superpowers 深度指南 ​

是什么 ​

官方地址 ​

适用场景 ​

安装准备 ​

安装方式 ​

Claude Code 官方插件市场 ​

Claude Code Superpowers Marketplace ​

Codex CLI ​

Gemini CLI ​

OpenCode ​

核心目录和机制 ​

核心 Skill ​

命令和操作参考 ​

推荐工作流 ​

新功能 ​

Bug 修复 ​

创建团队自己的 Skill ​

与 gstack、OpenSpec 的关系 ​

安全建议 ​

排错 ​

Codex 中没有发现技能 ​

技能没有自动触发 ​

更新后行为变化 ​

总结 ​

Superpowers 深度指南

是什么

官方地址

适用场景

安装准备

安装方式

Claude Code 官方插件市场

Claude Code Superpowers Marketplace

Codex CLI

Gemini CLI

OpenCode

核心目录和机制

核心 Skill

命令和操作参考

推荐工作流

新功能

Bug 修复

创建团队自己的 Skill

与 gstack、OpenSpec 的关系

安全建议

排错

Codex 中没有发现技能

技能没有自动触发

更新后行为变化

总结