Superpowers 插件使用教程

发表于：2026-03-02 18:04:56浏览：5次TAG： #AI #Superpowers #skills

Superpowers 插件使用教程

一、Superpowers 插件概述

1.1 什么是 Superpowers 插件

Superpowers 是一款为代码智能助手（Claude Code、Codex、OpenCode.ai 等）打造的增强型插件体系，核心目标是为代码代理赋予「超能力」—— 摆脱简单的代码编写响应模式，实现自主化、流程化、标准化的软件开发全流程管理。

不同于传统的代码补全或指令响应工具，Superpowers 基于「技能（Skill）」体系设计：将软件开发中的通用流程（需求分析、方案设计、编码实现、测试验证、文档编写等）拆解为可复用、可组合的技能模块，代码代理可根据场景自动调用对应技能，遵循预设的最佳实践完成复杂任务。例如，面对一个认证系统开发需求，Superpowers 会先调用「writing-plans」技能生成详细的实现计划，再通过「subagent-driven-development」技能启动子代理分工完成编码、测试、文档等环节，全程遵循 TDD（测试驱动开发）、YAGNI（你不会需要它）、DRY（不要重复自己）等工程原则。

1.2 支持的平台

Superpowers 针对不同代码智能助手的架构特性提供适配支持，核心兼容以下平台：

Claude Code：通过原生插件市场集成，开箱即用；
Codex：无原生插件系统，通过 Bootstrap 脚本 + CLI 工具实现；
OpenCode.ai：基于 JavaScript/TypeScript 原生插件体系开发，共享核心技能逻辑，支持自定义工具与会话钩子。

1.3 核心优势

流程标准化：将资深工程师的最佳实践固化为技能模板，确保代码代理输出符合工程规范；
自主化执行：支持子代理驱动开发（Subagent-driven-development），代理可自主拆解任务、检查成果、迭代优化，最长可自主运行数小时；
技能可扩展：支持自定义个人技能，且个人技能可覆盖同名的官方技能，适配团队/个人的定制化流程；
跨平台兼容：核心技能逻辑（技能发现、解析、调用）抽象为共享模块，一次开发可在多平台复用；
渐进式披露：技能文档采用分层设计，代理仅在需要时加载详细内容，兼顾性能与功能完整性。

二、环境准备

2.1 通用前置条件

无论使用哪个平台的 Superpowers 插件，需先满足以下基础环境要求：

Git：用于克隆 Superpowers 仓库及版本管理，要求 2.30.0 及以上版本（验证：git --version）；
Node.js：核心技能逻辑基于 Node.js 开发，要求 16.x 及以上 LTS 版本（验证：node --version）；
对应代码助手：已安装并配置好 Claude Code/Codex/OpenCode.ai，且能正常运行基础指令。

2.2 平台专属准备

2.2.1 Claude Code

确保 Claude Code CLI 已安装并加入系统 PATH（验证：claude --version）；
登录 Claude Code 并完成基础配置，确保能访问插件市场。

2.2.2 OpenCode.ai

已安装 OpenCode.ai 客户端，且完成项目初始化（opencode init）；
确保用户目录下可创建配置文件夹（~/.config/opencode/，Windows 为 %USERPROFILE%\.config\opencode\）。

2.2.3 Codex

配置 Codex 运行环境，确保能执行自定义 CLI 脚本；
提前创建 Codex 配置目录（~/.config/codex/）。

三、安装部署

3.1 安装方式总览

Superpowers 的安装方式因平台而异，核心分为「插件市场安装（Claude Code）」「手动克隆配置（OpenCode/Codex）」两类，以下分平台详细说明。

3.2 Claude Code 安装（最简方式）

Claude Code 支持通过原生插件市场一键安装，步骤如下：

启动 Claude Code CLI，进入会话模式；

/plugin marketplace add obra/superpowers-marketplace

从插件市场安装 Superpowers 插件：

/plugin install superpowers@superpowers-marketplace

验证安装：执行 /plugin list，若输出中包含 superpowers 则说明安装成功。

3.3 OpenCode.ai 安装（手动配置）

OpenCode.ai 需手动克隆仓库并配置插件链接，步骤如下：

步骤 1：克隆 Superpowers 仓库

# 创建配置目录并克隆仓库
mkdir -p ~/.config/opencode/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

步骤 2：安装插件

Superpowers 插件文件已包含在仓库中，需将其链接到 OpenCode 项目目录（推荐项目级链接，避免全局污染）：

# 进入你的 OpenCode 项目目录
cd /path/to/your/opencode-project
# 创建插件目录
mkdir -p .opencode/plugin
# 软链接插件文件
ln -s ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js

步骤 3：重启 OpenCode

关闭并重新启动 OpenCode 客户端，启动新会话时若看到「You have superpowers.」提示，则插件加载成功。

3.4 Codex 安装（手动配置）

克隆仓库到 Codex 配置目录：

mkdir -p ~/.config/codex/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/codex/superpowers

添加 CLI 脚本到 PATH（可选，方便全局调用）：

ln -s ~/.config/codex/superpowers/.codex/superpowers-codex /usr/local/bin/superpowers-codex

验证：执行 superpowers-codex bootstrap，若输出引导内容则配置成功。

3.5 后续更新

Superpowers 会持续迭代技能与功能，更新方式如下：

cd ~/.config/opencode/superpowers # 对应平台的配置目录
git pull # 拉取最新代码

OpenCode/Codex 需重启客户端使更新生效，Claude Code 会自动同步插件更新。

四、核心概念与目录结构

4.1 核心概念

4.1.1 技能（Skill）

技能是 Superpowers 的核心单元，是针对特定场景的标准化流程/知识集合。每个技能包含：

元数据：名称（name）、描述（description），用于代理识别何时调用该技能；
核心内容：标准化的流程、指令、模板，指导代理完成任务；
附属文件：技能依赖的脚本、文档、示例等，遵循「渐进式披露」原则，仅在需要时加载。

技能分为两类：

官方技能：仓库自带的通用技能（如 brainstorming、writing-plans、systematic-debugging），存储在 ~/.config/opencode/superpowers/skills/；
个人技能：自定义技能，存储在 ~/.config/opencode/skills/，可覆盖同名官方技能。

4.1.2 工具（Tool）

Superpowers 为平台提供自定义工具，核心工具包括：

use_skill：加载并读取指定技能的详细内容；
find_skills：列出所有可用技能（含官方+个人）；
平台适配工具：如 OpenCode 的 update_plan（替代 Claude 的 TodoWrite）、子代理调用（@mention 语法）等。

4.1.3 会话钩子（Session Hook）

以 OpenCode 为例，session.started 钩子会在会话启动时自动执行：

注入「using-superpowers」技能内容，指导代理使用 Superpowers；
自动执行 find_skills 列出可用技能；
注入工具映射说明（不同平台的工具替代方案）；
检查更新并提示。

4.2 目录结构

Superpowers 的核心目录结构如下（以 OpenCode 为例）：

superpowers/
├── lib/
│   └── skills-core.js           # 共享技能逻辑（发现、解析、加载）
├── .codex/
│   ├── superpowers-codex        # Codex 适配脚本（CLI 工具）
│   ├── superpowers-bootstrap.md # Codex 引导文档
│   └── INSTALL.md               # Codex 安装说明
├── .opencode/
│   ├── plugin/
│   │   └── superpowers.js       # OpenCode 插件入口
│   └── INSTALL.md               # OpenCode 安装指南
├── skills/                      # 官方技能库
│   ├── brainstorming/           # 头脑风暴技能
│   ├── writing-plans/           # 计划编写技能
│   ├── systematic-debugging/    # 系统化调试技能
│   └── writing-skills/          # 技能编写最佳实践
└── docs/                        # 文档与测试说明
    ├── testing.md               # 技能测试指南
    └── plans/                   # 功能实现计划

五、基础使用流程

5.1 通用操作：技能的发现与调用

无论哪个平台，Superpowers 的核心操作围绕「发现技能」和「调用技能」展开。

5.1.1 发现可用技能

Claude Code：在会话中执行 /tool find_skills；
OpenCode.ai：在会话中输入 use find_skills tool；
Codex：执行 superpowers-codex find-skills。

执行后会输出所有可用技能，格式如下：

Available skills:

superpowers:brainstorming
  将创意转化为结构化设计，生成详细的设计文档并准备实现计划。
  Directory: ~/.config/opencode/superpowers/skills/brainstorming

superpowers:writing-plans
  为多步骤任务编写详细的实现计划，假设工程师无项目上下文。
  Directory: ~/.config/opencode/superpowers/skills/writing-plans

my-custom-skill (个人技能)
  自定义的业务逻辑处理技能。
  Directory: ~/.config/opencode/skills/my-custom-skill

5.1.2 调用指定技能

调用技能的核心语法为「指定技能名称 + 任务描述」，不同平台的调用方式如下：

Claude Code：/tool use_skill --skill_name superpowers:writing-plans；
OpenCode.ai：use use_skill tool with skill_name: "superpowers:writing-plans"；
Codex：superpowers-codex use-skill superpowers:writing-plans。

调用后，代理会加载该技能的完整内容，并按照技能中的流程处理你的任务。例如调用 writing-plans 后，代理会要求你提供需求/规格说明，然后生成符合固定模板的实现计划。

5.2 典型场景：从需求到成品的全流程示例

以「开发一个 JWT 认证系统」为例，演示 Superpowers 的完整使用流程（基于 OpenCode.ai）。

步骤 1：启动会话，确认 Superpowers 加载

启动 OpenCode 会话，若看到以下提示，说明 Superpowers 已成功加载：

You have superpowers.

**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'use_skill' tool:**

[using-superpowers 技能内容]

**Tool Mapping for OpenCode:**
When skills reference tools you don't have, substitute OpenCode equivalents:
- `TodoWrite` → `update_plan` (your planning/task tracking tool)
- `Task` tool with subagents → Use OpenCode's subagent system (@mention syntax or automatic dispatch)
- `Skill` tool → `use_skill` custom tool (already available)
- `Read`, `Write`, `Edit`, `Bash` → Use your native tools

⚠️ **Updates available!** Run `cd ~/.config/opencode/superpowers && git pull` to update superpowers.

步骤 2：提供需求，调用头脑风暴技能

输入需求并调用 brainstorming 技能：

需求：开发一个基于 Node.js 的 JWT 认证系统，支持用户注册、登录、密码重置，令牌有效期 24 小时，受保护的路由需要验证令牌。
use use_skill tool with skill_name: "superpowers:brainstorming"

代理会按照 brainstorming 技能的流程，先拆解需求、分析核心模块（用户模型、认证路由、中间件、邮件服务），再生成结构化的设计文档，最终提示是否进入实现阶段。

步骤 3：调用编写计划技能，生成实现计划

确认进入实现阶段后，调用 writing-plans 技能：

进入实现阶段，请生成详细的实现计划。
use use_skill tool with skill_name: "superpowers:writing-plans"

代理会生成符合固定模板的实现计划，包含：

# JWT 认证系统 Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 开发基于 Node.js 的 JWT 认证系统，支持注册、登录、密码重置、令牌验证。

**Architecture:** 采用 Express 框架搭建 HTTP 服务，使用 bcrypt 加密密码，jsonwebtoken 生成/验证令牌，Nodemailer 处理密码重置邮件，遵循 RESTful 设计原则。

**Tech Stack:** Node.js, Express, bcrypt, jsonwebtoken, Nodemailer, Jest (测试)

---

## Tasks
### Task 1: 项目初始化
**Do:**
- 创建项目目录：mkdir jwt-auth && cd jwt-auth
- 初始化 npm：npm init -y
- 安装核心依赖：npm install express bcrypt jsonwebtoken nodemailer
- 安装开发依赖：npm install -D jest supertest nodemon

**Verify:**
- package.json 包含所有依赖
- 项目目录结构清晰

### Task 2: 用户模型设计
...（后续任务省略，包含路由、中间件、测试、文档等）

步骤 4：调用子代理驱动开发技能，执行计划

调用 subagent-driven-development 技能，让代理自主执行计划：

按照上述计划实现整个系统，遵循 TDD 原则，每完成一个任务提交一次代码。
use use_skill tool with skill_name: "superpowers:subagent-driven-development"

代理会启动子代理分工完成以下工作：

初始化项目，配置开发环境；
编写用户模型的测试用例（TDD 先行）；
实现用户模型，运行测试确保通过；
编写认证路由的测试用例，实现路由逻辑；
开发令牌验证中间件，测试受保护路由；
集成邮件服务，实现密码重置功能；
编写 README.md，记录使用方法；
全程提交代码，每完成一个任务生成提交记录。

步骤 5：测试与交付

代理完成开发后，会自动运行测试套件，验证所有功能符合需求，并输出最终的使用文档和测试报告。你只需确认成果是否符合预期，无需手动编写代码。

六、自定义技能开发

6.1 自定义技能的核心原则

Superpowers 允许开发符合个人/团队流程的自定义技能，核心需遵循以下原则：

简洁性：技能内容需简洁，仅包含代理「不知道」的信息，避免冗余（上下文窗口是公共资源）；
描述精准：技能的 description 字段需明确「做什么」和「何时用」，使用第三人称，包含关键触发词；
渐进式披露：核心内容控制在 500 行内，复杂内容拆分到附属文件，通过链接引用；
流程化：复杂任务拆分为清晰的步骤，可提供检查清单辅助代理跟踪进度。

6.2 自定义技能的目录结构

个人技能需放在 ~/.config/opencode/skills/（OpenCode）或对应平台的技能目录下，每个技能为一个独立目录，核心文件为 SKILL.md：

~/.config/opencode/skills/
└── my-jwt-skill/           # 技能目录（名称与技能名一致）
    ├── SKILL.md            # 核心技能文件
    ├── EXAMPLES.md         # 示例文件（可选）
    └── TESTS.md            # 测试指南（可选）

6.3 编写 SKILL.md

SKILL.md 分为「前置元数据」和「核心内容」两部分，以下是自定义「my-jwt-skill」的示例：

6.3.1 元数据部分

元数据使用 YAML 格式，包裹在 --- 之间，核心字段为 name 和 description：

---
name: my-jwt-skill
description: 开发基于 Node.js 的 JWT 认证系统，支持注册、登录、密码重置和令牌验证。使用当用户提及 JWT、认证、登录、密码重置或 Node.js 身份验证时。
---

元数据编写技巧：

name：与技能目录名一致，个人技能无需加命名空间；
description：包含「功能」和「触发条件」，使用第三人称，避免模糊表述（如「处理认证」→「开发基于 Node.js 的 JWT 认证系统，支持注册、登录、密码重置和令牌验证」）。

6.3.2 核心内容部分

核心内容需按照「流程化、结构化」的原则编写，示例如下：

# my-jwt-skill
## 前置要求
- 确保已安装 Node.js 16+ 和 npm
- 熟悉 Express 框架和 RESTful API 设计
- 掌握 JWT 基本原理和 bcrypt 加密方式

## 实现流程（复制此清单并跟踪进度）

Research Progress:

[ ] Step 1: 项目初始化与依赖安装
[ ] Step 2: 用户模型设计与实现（TDD）
[ ] Step 3: 认证路由开发（注册、登录）
[ ] Step 4: JWT 令牌生成与验证中间件
[ ] Step 5: 密码重置功能（邮件发送）
[ ] Step 6: 测试与文档编写
```

Step 1: 项目初始化与依赖安装

执行命令

mkdir jwt-auth && cd jwt-auth
npm init -y
npm install express bcrypt jsonwebtoken nodemailer cors
npm install -D jest supertest nodemon

验证标准

package.json 中包含所有依赖
能正常运行 npm run dev（需配置 nodemon）

Step 2: 用户模型设计与实现（TDD）

第一步：编写测试用例（src/tests/user.test.js）

// 测试用例代码示例
const request = require('supertest');
const app = require('../app');

describe('User Model', () => {
  test('should hash password before saving', async () => {
    // 测试逻辑
  });
});

第二步：实现用户模型（src/models/user.js）

// 模型代码示例
const bcrypt = require(‘bcrypt’);

class User {
constructor(email, password) {
this.email = email;
this.password = bcrypt.hashSync(password, 10);
this.createdAt = new Date();
}
}

module.exports = User;

验证标准

测试用例执行通过
密码存储为加密后的哈希值，而非明文

Step 3: 认证路由开发（注册、登录）

…（后续步骤省略，需包含代码示例、验证标准）

测试与交付标准

所有测试用例通过率 100%；
代码提交记录清晰，每个任务对应一次提交；
生成 README.md，包含安装、使用、测试说明；
提供 Postman 集合或 curl 示例，演示 API 使用方式。
```

6.4 测试自定义技能

自定义技能编写完成后，需验证其能否被正确识别和调用：

执行 find_skills 工具，确认技能出现在列表中；
调用 use_skill 工具加载自定义技能，检查内容是否完整加载；
提供对应需求，验证代理是否按照技能中的流程执行任务。

七、故障排查

7.1 插件未加载

现象

OpenCode/Codex 启动后未看到「You have superpowers.」提示，Claude Code 执行 /plugin list 无 superpowers。

排查步骤

检查插件文件是否存在（OpenCode）：
```
ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js
```
若不存在，重新克隆仓库：git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers。
检查日志（OpenCode）：
查看 OpenCode 日志文件，寻找插件加载错误（如语法错误、依赖缺失）。
验证 Node.js 版本：
执行 node --version，确保版本 ≥ 16.x，低版本可能导致插件加载失败。

Claude Code 重新安装插件：

/plugin uninstall superpowers@superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

7.2 技能未找到

现象

调用 use_skill 时提示「Error: Skill “xxx” not found.」。

排查步骤

验证技能目录是否存在：

# 检查官方技能
ls ~/.config/opencode/superpowers/skills/xxx
# 检查个人技能
ls ~/.config/opencode/skills/xxx

检查技能文件结构：
确保技能目录下有 SKILL.md 文件，且元数据格式正确（无语法错误）。
使用 find_skills 工具：
执行 use find_skills tool，确认技能是否在可用列表中。

7.3 工具映射问题

现象

代理提示「找不到 TodoWrite/Task/Skill 工具」。

解决方法

Superpowers 已内置工具映射说明，代理会自动替换：

TodoWrite → update_plan（OpenCode 计划工具）；
Task（子代理）→ @mention 语法（OpenCode 子代理）；
Skill → use_skill（自定义工具）；
文件操作 → 平台原生工具（Read/Write/Edit/Bash）。

若仍有问题，可手动在会话中提示代理：「使用 update_plan 替代 TodoWrite，使用 @mention 调用子代理」。

八、高级技巧

8.1 技能覆盖

个人技能可覆盖同名的官方技能，只需将个人技能放在 ~/.config/opencode/skills/ 目录下，名称与官方技能一致即可。例如，自定义 writing-plans 技能后，代理会优先加载个人版本，适配团队的计划模板。

8.2 技能组合调用

复杂任务可组合多个技能，例如：

开发一个电商订单管理系统，先进行头脑风暴，再生成实现计划，最后执行开发。
use use_skill tool with skill_name: "superpowers:brainstorming"
use use_skill tool with skill_name: "superpowers:writing-plans"
use use_skill tool with skill_name: "superpowers:subagent-driven-development"

代理会按照技能调用顺序，依次完成设计、计划、开发全流程。

8.3 渐进式披露优化

对于复杂技能，将详细内容拆分到附属文件，例如：

# PDF 处理技能
## 快速开始
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

高级功能

Form filling: See FORMS.md for complete guide
API reference: See REFERENCE.md for all methods


代理会在需要时自动读取附属文件，避免初始加载过多内容占用上下文窗口。

### 8.4 测试技能有效性
参考 Superpowers 官方测试指南，验证技能的实际效果：
1. **清理环境**：使用 trap 清理临时目录，避免残留文件影响测试；
2. **解析会话日志**：不要仅依赖用户输出，需解析 `.jsonl` 会话文件验证代理行为；
3. **授予权限**：使用 `--permission-mode bypassPermissions` 确保代理能执行文件操作；
4. **验证实际行为**：检查代理是否创建了预期文件、测试是否通过、代码是否提交。

## 九、常见问题解答
### Q1：Superpowers 支持 Windows 系统吗？
A1：支持，但路径需调整：
- 配置目录：`%USERPROFILE%\.config\opencode\superpowers`（替代 `~/.config/opencode/superpowers`）；
- 软链接：Windows 需使用 `mklink` 替代 `ln -s`，且需管理员权限。

### Q2：个人技能的元数据有哪些必填字段？
A2：核心为 `name` 和 `description`，其他字段（如 `version`、`author`）可选，`description` 是技能发现的关键，务必精准。

### Q3：如何贡献官方技能？
A3：可提交 PR 到 [obra/superpowers](https://github.com/obra/superpowers) 仓库，需遵循技能编写最佳实践，包含测试用例和文档。

### Q4：Superpowers 会消耗更多的令牌/API 额度吗？
A4：因技能包含更多上下文，首次加载会增加少量消耗，但后续流程标准化可减少重复尝试，整体额度消耗更可控。

### Q5：如何禁用 Superpowers 的自动更新提示？
A5：修改 OpenCode 插件文件（`superpowers.js`），注释掉更新检查相关代码：
```javascript
// const hasUpdates = skillsCore.checkForUpdates(
//   path.join(homeDir, '.config/opencode/superpowers')
// );
// const updateNotice = hasUpdates ?
//   '\n\n⚠️ **Updates available!** Run `cd ~/.config/opencode/superpowers && git pull` to update superpowers.' :
//   '';

十、总结

Superpowers 并非简单的「代码助手增强插件」，而是一套「将软件工程最佳实践固化为可执行流程」的体系。通过标准化的技能设计、跨平台的兼容适配、可扩展的自定义能力，它能让代码智能助手从「被动响应指令」升级为「主动管理开发流程」，大幅提升复杂任务的交付质量和效率。

无论是个人开发者快速实现需求，还是团队标准化开发流程，Superpowers 都能提供核心支撑。掌握其使用方法和自定义技能开发技巧，能充分释放代码智能助手的潜力，让「AI 驱动的自主化开发」从概念变为现实。

如需获取更多帮助，可访问：

仓库地址：https://github.com/obra/superpowers
问题反馈：https://github.com/obra/superpowers/issues
官方文档：https://github.com/obra/superpowers

栏目分类全部>