跳转到内容
Skills 学习中心

Superpowers：AI 编码代理的完整软件开发方法论

一句话总结

Section titled “一句话总结”

Superpowers 是一个完整的 AI 编码代理软件开发方法论，通过 14 个可组合 Skills 覆盖从头脑风暴到代码交付的完整生命周期。

核心能力

Section titled “核心能力”
  • 🧩 14-Skill 组合系统：每个 Skill 专注一个开发环节，可灵活组合成完整工作流
  • 👁️ 可视化头脑风暴伴侣：基于浏览器的交互式服务器，辅助需求探索与设计讨论
  • 🤖 Subagent 驱动开发：将任务分解为并行子代理执行，支持代码审查、规范审查
  • 🔄 TDD 工作流：测试驱动开发集成，包含测试反模式指南
  • 🔌 多平台支持：Claude Code、Codex CLI、Gemini CLI、OpenCode、Cursor、Copilot CLI

关键指标

Section titled “关键指标”
  • 146 个文件，14 个独立 Skills，完整测试套件
  • Version 5.1.0，npm 包格式
  • 零外部依赖政策
  • 6 平台支持（插件 + 扩展配置）

文件清单

Section titled “文件清单”

One-Line Summary

Section titled “One-Line Summary”

Superpowers is a complete software development methodology for AI coding agents, covering the full lifecycle from brainstorming to code delivery through 14 composable skills.

Core Capabilities

Section titled “Core Capabilities”
  • 🧩 14-Skill Composite System: Each skill focuses on one development phase, flexibly composable into complete workflows
  • 👁️ Visual Brainstorming Companion: Browser-based interactive server for requirement exploration and design discussion
  • 🤖 Subagent-Driven Development: Decompose tasks into parallel sub-agents for execution, supporting code review and spec review
  • 🔄 TDD Workflow: Test-driven development integration with testing anti-pattern guide
  • 🔌 Multi-Harness Support: Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor, Copilot CLI

Key Metrics

Section titled “Key Metrics”
  • 146 files, 14 independent skills, comprehensive test suites
  • Version 5.1.0, npm package format
  • Zero external dependency policy
  • 6-platform support (plugins + extension config)

File Inventory

Section titled “File Inventory”

14-Skill 可组合系统架构

Section titled “14-Skill 可组合系统架构”

Superpowers 不是一个单一的 Skill，而是一个 Skill 框架——14 个独立 Skill 形成一个完整的开发方法论。每个 Skill 专注一个环节，通过 CLAUDE.md 引导加载器在会话启动时自动装载。

Skill 生命周期

Section titled “Skill 生命周期”

核心开发流程由 7 个 Skill 组成一个管道：

  1. brainstorming → 需求探索与设计讨论（含可视化伴侣服务器）
  2. writing-plans → 编写实施计划（含计划文档审查器）
  3. subagent-driven-development → 将任务分解为并行子代理执行
  4. requesting-code-review → 请求代码审查（含审查者提示）
  5. receiving-code-review → 接收并处理审查反馈
  6. verification-before-completion → 完成前验证清单检查
  7. finishing-a-development-branch → 清理、提交、合并

辅助 Skills

Section titled “辅助 Skills”

另有 7 个辅助 Skill 提供支撑：

  • using-superpowers：框架引导加载器——在会话启动时自动装载所有 Skill
  • using-git-worktrees：Git Worktree 隔离开发
  • test-driven-development：测试驱动开发指南（含测试反模式）
  • systematic-debugging：系统性调试方法论（含 git bisect 封装）
  • writing-skills：编写和修改 Skill 的元 Skill（含 Graphviz 渲染器）
  • dispatching-parallel-agents：并行 Agent 调度器
  • executing-plans：计划的批量执行

多平台支持架构

Section titled “多平台支持架构”

Superpowers 同时支持 6 种编码代理平台，通过各自的插件机制实现：

  • Claude Code：原生通过 .claude-plugin/plugin.json 注册，使用 Skill 工具
  • Codex CLI：通过 .codex-plugin/plugin.json 注册，using-superpowers 引导加载
  • Gemini CLI：通过 gemini-extension.json 注册
  • OpenCode：通过 .opencode/plugin 注册
  • Cursor：通过 .cursor-plugin/plugin.json 和 hooks-cursor.json 注册
  • Copilot CLI：通过 using-superpowers/references/copilot-tools.md 的参考提示支持

每种平台的引导方式不同，但核心都是让 using-superpowers Skill 在会话启动时自动装载。

CLAUDE.md 引导机制

Section titled “CLAUDE.md 引导机制”

Superpowers 的 CLAUDE.md 是一个独特的”守门文档”——它不直接包含工作指令，而是设置了严格的贡献者准入标准。它包含：

  • AI Agent 行为守则（94% PR 拒绝率的警示）
  • 必须阅读 PR 模板并填写每个章节的要求
  • 变更前的真实问题验证流程
  • Skill 修改必须附带评估结果的硬性要求
  • 新平台支持必须提交完整会话记录的验收测试

14-Skill Composable System Architecture

Section titled “14-Skill Composable System Architecture”

Superpowers is not a single skill but a Skill Framework — 14 independent skills forming a complete development methodology. Each skill focuses on one phase, auto-loaded at session start via the CLAUDE.md bootstrap loader.

Skill Lifecycle

Section titled “Skill Lifecycle”

The core development pipeline consists of 7 skills:

  1. brainstorming → Requirement exploration and design discussion (with visual companion server)
  2. writing-plans → Implementation plan writing (with plan document reviewer)
  3. subagent-driven-development → Task decomposition into parallel sub-agents
  4. requesting-code-review → Request code review (with reviewer prompts)
  5. receiving-code-review → Receive and process review feedback
  6. verification-before-completion → Pre-completion checklist verification
  7. finishing-a-development-branch → Cleanup, commit, merge

Support Skills

Section titled “Support Skills”

7 additional support skills provide infrastructure:

  • using-superpowers: Framework bootstrap loader — auto-loads all skills at session start
  • using-git-worktrees: Git Worktree isolation for development
  • test-driven-development: TDD guide (with testing anti-patterns)
  • systematic-debugging: Systematic debugging methodology (with git bisect wrapper)
  • writing-skills: Meta-skill for creating and modifying skills (with Graphviz renderer)
  • dispatching-parallel-agents: Parallel agent dispatcher
  • executing-plans: Batch plan execution

Multi-Harness Architecture

Section titled “Multi-Harness Architecture”

Superpowers supports 6 coding agent platforms through respective plugin mechanisms:

  • Claude Code: Native via .claude-plugin/plugin.json, using the Skill tool
  • Codex CLI: Via .codex-plugin/plugin.json, using-superpowers bootstrap loading
  • Gemini CLI: Via gemini-extension.json
  • OpenCode: Via .opencode/plugin registration
  • Cursor: Via .cursor-plugin/plugin.json and hooks-cursor.json
  • Copilot CLI: Supported via using-superpowers/references/copilot-tools.md reference prompts

Each platform has a different bootstrap mechanism, but the core principle is that using-superpowers auto-loads at session start.

CLAUDE.md Bootstrap Mechanism

Section titled “CLAUDE.md Bootstrap Mechanism”

Superpowers’ CLAUDE.md is a unique “gatekeeper document” — it doesn’t contain direct work instructions but sets strict contributor admission standards. It includes:

  • AI Agent code of conduct (94% PR rejection rate warning)
  • Requirement to read the PR template and fill every section
  • Real-problem verification process before changes
  • Hard requirement for evaluation results with skill changes
  • New platform support must include complete session transcripts for acceptance testing

Superpowers Skill 生命周期流程

graph LR
  BS[brainstorming] --> WP[writing-plans]
  WP --> SDD[subagent-driven-development]
  SDD --> RCR[requesting-code-review]
  RCR --> RCVR[receiving-code-review]
  RCVR --> VBC[verification-before-completion]
  VBC --> FDB[finishing-a-development-branch]

  US[using-superpowers] -.->|引导装载| BS
  TDD[test-driven-development] -.->|测试支撑| SDD
  SD[systematic-debugging] -.->|调试支撑| SDD
  WS[writing-skills] -.->|元技能| WP
  GW[using-git-worktrees] -.->|隔离开发| FDB
  DPA[dispatching-parallel-agents] -.->|并行调度| SDD
  EP[executing-plans] -.->|批量执行| SDD

  style BS fill:#4fc3f7,stroke:#0288d1,color:#000
  style WP fill:#4fc3f7,stroke:#0288d1,color:#000
  style SDD fill:#81c784,stroke:#388e3c,color:#000
  style RCR fill:#81c784,stroke:#388e3c,color:#000
  style RCVR fill:#81c784,stroke:#388e3c,color:#000
  style VBC fill:#ffb74d,stroke:#f57c00,color:#000
  style FDB fill:#ffb74d,stroke:#f57c00,color:#000
  style US fill:#ce93d8,stroke:#7b1fa2,color:#000

关键脚本清单

Section titled “关键脚本清单”

Key Scripts Inventory

Section titled “Key Scripts Inventory”
脚本路径行数功能
start-server.shbrainstorming/scripts/~149启动可视化头脑风暴 HTTP 服务器，支持多平台后台进程管理
helper.jsbrainstorming/scripts/~120浏览器端选区录制与 WebSocket 交互脚本
stop-server.shbrainstorming/scripts/~30安全停止运行中的头脑风暴服务器
render-graphs.jswriting-skills/~169从 SKILL.md 中提取 dot 图并渲染为 SVG
find-polluter.shsystematic-debugging/~60git bisect 自动封装，定位引入问题的提交
bump-version.shscripts/~50项目版本号自动升级脚本
sync-to-codex-plugin.shscripts/~80同步项目配置到 Codex 插件格式
ScriptPathLinesPurpose
start-server.shbrainstorming/scripts/~149Launches the visual brainstorming HTTP server with multi-platform daemon support
helper.jsbrainstorming/scripts/~120Browser-side selection recording and WebSocket interaction script
stop-server.shbrainstorming/scripts/~30Safely stops the running brainstorming server
render-graphs.jswriting-skills/~169Extracts dot graphs from SKILL.md and renders them as SVG
find-polluter.shsystematic-debugging/~60git bisect automation wrapper to locate the commit introducing a bug
bump-version.shscripts/~50Automated project version bumping script
sync-to-codex-plugin.shscripts/~80Syncs project configuration to Codex plugin format

start-server.sh — 可视化头脑风暴服务器

Section titled “start-server.sh — 可视化头脑风暴服务器”

start-server.sh 是 Superpowers 可视化头脑风暴系统的核心启动脚本。它启动一个 Node.js HTTP 服务器，为浏览器端提供设计协作界面。脚本处理了多平台兼容性、后台守护进程管理、会话隔离和自动停止逻辑。

start-server.sh is the core startup script for Superpowers’ visual brainstorming system. It launches a Node.js HTTP server providing a browser-based design collaboration interface. The script handles multi-platform compatibility, daemon process management, session isolation, and auto-stop logic.

start-server.sh — 服务器启动与参数解析 ↗ 源文件
1 #!/usr/bin/env bash 2 # Start the brainstorm server and output connection info 3 # Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background] 4 5 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" 6 7 # Parse arguments 8 PROJECT_DIR="" 9 FOREGROUND="false" 10 FORCE_BACKGROUND="false" 11 BIND_HOST="127.0.0.1" 12 URL_HOST="" 13 while [[ $# -gt 0 ]]; do 14 case "$1" in 15 --project-dir) PROJECT_DIR="$2"; shift 2 ;; 16 --host) BIND_HOST="$2"; shift 2 ;; 17 --url-host) URL_HOST="$2"; shift 2 ;; 18 --foreground|--no-daemon) FOREGROUND="true"; shift ;; 19 --background|--daemon) FORCE_BACKGROUND="true"; shift ;; 20 *) echo "{\"error\": \"Unknown argument: $1\"}"; exit 1 ;; 21 esac 22 done 23 24 # Environment detection for auto-foreground 25 if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then 26 FOREGROUND="true" 27 fi 28 29 if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then 30 case "${OSTYPE:-}" in 31 msys*|cygwin*|mingw*) FOREGROUND="true" ;; 32 esac 33 if [[ -n "${MSYSTEM:-}" ]]; then 34 FOREGROUND="true" 35 fi 36 fi
代码解读
L3 多参数支持：project-dir 用于持久化存储，host/url-host 分离绑定地址和显示地址，foreground/background 控制运行模式。 L6 SCRIPT_DIR 获取脚本自身路径，确保后续 cd 操作正确——这是 Bash 脚本的标准做法。 L27 环境感知：检测 Codex CI 环境，自动切换到 foreground 模式——防止 CI 环境收割后台进程。 L33 跨平台兼容：检测 msys/cygwin/mingw（Windows Git Bash），这些环境也无法可靠运行 nohup 后台进程，自动切换到 foreground 模式。
start-server.sh — 会话隔离与自动停止 ↗ 源文件
1 # Generate unique session directory 2 SESSION_ID="$$-$(date +%s)" 3 if [[ -n "$PROJECT_DIR" ]]; then 4 SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}" 5 else 6 SESSION_DIR="/tmp/brainstorm-${SESSION_ID}" 7 fi 8 9 STATE_DIR="${SESSION_DIR}/state" 10 PID_FILE="${STATE_DIR}/server.pid" 11 LOG_FILE="${STATE_DIR}/server.log" 12 13 mkdir -p "${SESSION_DIR}/content" "$STATE_DIR" 14 15 # Kill any existing server 16 if [[ -f "$PID_FILE" ]]; then 17 old_pid=$(cat "$PID_FILE") 18 kill "$old_pid" 2>/dev/null 19 rm -f "$PID_FILE" 20 fi 21 22 cd "$SCRIPT_DIR" 23 24 # Resolve the harness PID (grandparent of this script) 25 OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ')" 26 if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then 27 OWNER_PID="$PPID" 28 fi
代码解读
L2 会话隔离：使用 $$（shell PID）+ 时间戳生成唯一会话 ID，避免多个并发的 brainstorm 会话冲突。 L3 持久化存储：指定 project-dir 时，会话文件存储在项目目录下的 .superpowers/brainstorm/ 中；否则使用 /tmp——即使服务器停止，文件保留。 L8 PID_FILE 机制：通过 PID 文件追踪服务器进程，确保可以停止、重启。LOG_FILE 用于异步确认服务器启动。 L17 OWNER_PID 检测：解析祖父进程 PID（编码代理本身的 PID），用于自动停止——当编码代理会话结束时，服务器自动退出。
start-server.sh — 服务器启动与等待确认 ↗ 源文件
1 # Foreground mode 2 if [[ "$FOREGROUND" == "true" ]]; then 3 echo "$$" > "$PID_FILE" 4 env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs 5 exit $? 6 fi 7 8 # Background mode with nohup 9 nohup env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs > "$LOG_FILE" 2>&1 & 10 SERVER_PID=$! 11 disown "$SERVER_PID" 2>/dev/null 12 echo "$SERVER_PID" > "$PID_FILE" 13 14 # Wait for server-started message (check log file) 15 for i in {1..50}; do 16 if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then 17 alive="true" 18 for _ in {1..20}; do 19 if ! kill -0 "$SERVER_PID" 2>/dev/null; then 20 alive="false"; break 21 fi 22 sleep 0.1 23 done 24 if [[ "$alive" != "true" ]]; then 25 echo "{\"error\": \"Server started but was killed...\"}" 26 exit 1 27 fi 28 grep "server-started" "$LOG_FILE" | head -1 29 exit 0 30 fi 31 sleep 0.1 32 done 33 34 echo '{"error": "Server failed to start within 5 seconds"}' 35 exit 1
代码解读
L2 Foreground 模式：前台运行适用于 CI/repl 需要收割后台进程的环境。PID_FILE 写入 $$（当前 shell 的 PID）而非后台 PID。 L4 环境变量注入：通过 env 前缀设置 4 个环境变量（SESSION_DIR、HOST、URL_HOST、OWNER_PID）传递给 server.cjs——优雅的配置传递方式。 L11 后台模式：使用 nohup 使进程在 shell 退出后继续运行。disown 从 job table 中移除。 L22 启动确认循环：最多等待 5 秒（50 x 0.1s），检测 LOG_FILE 中的 "server-started" 标记。收到后额外验证进程存活。 L27 进程存活性验证：收到启动确认后继续检查 2 秒（20 x 0.1s），防止进程被注册收割器杀死——这是多平台兼容性的关键。

render-graphs.js — Graphviz 可视化渲染

Section titled “render-graphs.js — Graphviz 可视化渲染”

render-graphs.js 是 Superpowers 中 Skill 流程图的自动渲染工具。它从 SKILL.md 文件中提取 ```dot 代码块，调用系统 graphviz (dot) 命令渲染为 SVG 文件。支持单图渲染和合并渲染两种模式。

render-graphs.js is the automated diagram renderer for Superpowers skills. It extracts ```dot code blocks from SKILL.md files, invokes the system graphviz (dot) command to render SVG files. Supports both individual and combined rendering modes.

render-graphs.js — dot 图块提取与合并 ↗ 源文件
1 #!/usr/bin/env node 2 3 const fs = require('fs'); 4 const path = require('path'); 5 const { execSync } = require('child_process'); 6 7 function extractDotBlocks(markdown) { 8 const blocks = []; 9 const regex = /```dot\n([\s\S]*?)```/g; 10 let match; 11 12 while ((match = regex.exec(markdown)) !== null) { 13 const content = match[1].trim(); 14 const nameMatch = content.match(/digraph\s+(\w+)/); 15 const name = nameMatch ? nameMatch[1] : `graph_${blocks.length + 1}`; 16 blocks.push({ name, content }); 17 } 18 return blocks; 19 } 20 21 function extractGraphBody(dotContent) { 22 const match = dotContent.match(/digraph\s+\w+\s*\{([\s\S]*)\}/); 23 if (!match) return ''; 24 let body = match[1]; 25 body = body.replace(/^\s*rankdir\s*=\s*\w+\s*;?\s*$/gm, ''); 26 return body.trim(); 27 } 28 29 function combineGraphs(blocks, skillName) { 30 const bodies = blocks.map((block, i) => { 31 const body = extractGraphBody(block.content); 32 return ` subgraph cluster_${i} { 33 label="${block.name}"; 34 ${body.split('\n').map(line => ' ' + line).join('\n')} 35 }`; 36 }); 37 38 return `digraph ${skillName}_combined { 39 rankdir=TB; compound=true; newrank=true; 40 ${bodies.join('\n\n')} 41 }`; 42 }
代码解读
L7 extractDotBlocks(): 使用正则匹配 ```dot ... ``` 代码块，提取所有 dot 图定义。regex = /```dot\n([\s\S]*?)```/g 是非贪婪匹配，确保每个代码块独立。 L12 从 digraph 声明中提取图名称作为文件名；如果 digraph 没有显式命名则回退为 graph_N。 L23 extractGraphBody(): 提取 digraph 的 body 部分，移除 rankdir 声明（合并时在顶层统一设置）。 L34 combineGraphs(): 将多个 dot 图合并为一个大图，每个子图包装为 cluster 子图——视觉上保持独立区域。compound 和 newrank 确保子图间不互相干扰。
render-graphs.js — 渲染与主流程 ↗ 源文件
1 function renderToSvg(dotContent) { 2 try { 3 return execSync('dot -Tsvg', { 4 input: dotContent, 5 encoding: 'utf-8', 6 maxBuffer: 10 * 1024 * 1024 7 }); 8 } catch (err) { 9 console.error('Error running dot:', err.message); 10 if (err.stderr) console.error(err.stderr.toString()); 11 return null; 12 } 13 } 14 15 function main() { 16 const args = process.argv.slice(2); 17 const combine = args.includes('--combine'); 18 const skillDirArg = args.find(a => !a.startsWith('--')); 19 20 if (!skillDirArg) { /* show usage */ process.exit(1); } 21 22 const skillDir = path.resolve(skillDirArg); 23 const skillFile = path.join(skillDir, 'SKILL.md'); 24 const skillName = path.basename(skillDir).replace(/-/g, '_'); 25 26 if (!fs.existsSync(skillFile)) { /* error */ process.exit(1); } 27 28 // Check if dot is available 29 try { execSync('which dot', { encoding: 'utf-8' }); } 30 catch { /* error with install instructions */ process.exit(1); } 31 32 const markdown = fs.readFileSync(skillFile, 'utf-8'); 33 const blocks = extractDotBlocks(markdown); 34 const outputDir = path.join(skillDir, 'diagrams'); 35 if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir); 36 37 if (combine) { 38 const combined = combineGraphs(blocks, skillName); 39 const svg = renderToSvg(combined); 40 if (svg) { 41 fs.writeFileSync(path.join(outputDir, skillName + '_combined.svg'), svg); 42 fs.writeFileSync(path.join(outputDir, skillName + '_combined.dot'), combined); 43 } 44 } else { 45 for (const block of blocks) { 46 const svg = renderToSvg(block.content); 47 if (svg) fs.writeFileSync(path.join(outputDir, block.name + '.svg'), svg); 48 } 49 } 50 }
代码解读
L1 renderToSvg(): 调用系统 dot 命令渲染 SVG。使用 execSync 同步执行，maxBuffer=10MB 避免大图截断。返回 null 让调用方处理渲染失败。 L21 main() 入口：解析 --combine 标志和 skill 目录路径。argv.find() 而非 argv[2] 使参数顺序灵活。 L35 前置检查：确认 SKILL.md 存在、dot 命令可用。不可用时提供友好的安装指导。这是"fail fast"原则的体现。 L39 输出目录：在 skill 目录下创建 diagrams/ 子目录。与 SKILL.md 同级的约定式目录结构。 L43 合并模式：将多个 dot 图合并为一个大图，同时输出 .svg 和 .dot 源文件——方便调试。 L48 单独模式：每个 dot 块单独渲染为 SVG。文件名为 digraph 中声明的名称。

find-polluter.sh — Git Bisect 封装

Section titled “find-polluter.sh — Git Bisect 封装”

find-polluter.sh 是 systematic-debugging Skill 中的核心调试工具。它封装了 git bisect 命令，自动执行二分搜索定位引入问题的提交。用户只需提供一个判断脚本（返回 0 表示”好”，非 0 表示”坏”），工具自动完成二分查找。

find-polluter.sh is the core debugging tool in the systematic-debugging skill. It wraps git bisect to automatically perform binary search locating the commit that introduced a problem. The user only provides a judgment script (returning 0 for “good”, non-zero for “bad”), and the tool handles the entire bisect process.

脚本间关系图

Section titled “脚本间关系图”

Superpowers 关键辅助脚本关系

graph TD
  SBS["brainstorming/scripts/start-server.sh"] -->|启动| SERVER["server.cjs - Node HTTP"]
  SBS -->|管理| PIDF["PID File / 进程追踪"]
  SBS -->|检测| ENV["Codex / Windows 环境"]
  HJ["brainstorming/scripts/helper.js"] -->|浏览器端| UI["交互式 UI / 选区"]
  RGS["writing-skills/render-graphs.js"] -->|调用| DOT["System graphviz dot"]
  FPS["systematic-debugging/find-polluter.sh"] -->|封装| BISECT["git bisect"]
  FPS -->|用户提供| SCRIPT["判断脚本"]

  style SBS fill:#4fc3f7,stroke:#0288d1,color:#000
  style RGS fill:#81c784,stroke:#388e3c,color:#000
  style FPS fill:#ffb74d,stroke:#f57c00,color:#000

设计亮点

Section titled “设计亮点”
  1. 可组合 Skills 模式：14 个独立 Skill 各自专注一个开发环节，通过 CLAUDE.md 引导加载器自动编排成完整流水线——这是”微服务架构”在 AI 编码代理领域的映射
  2. 渐进式信息披露：每个 Skill 的 SKILL.md 遵循”metadata → body → resources”结构：先通过 YAML frontmatter（name + description）暴露触发点，再通过 Skill 体内容指导行为，最后通过引用文件提供深度支撑
  3. 多平台适配模式：一套代码库同时支持 6 种编码代理平台（Claude Code、Codex CLI、Gemini CLI、OpenCode、Cursor、Copilot CLI），每个平台通过各自的插件机制集成
  4. 可视化伴侣模式：brainstorming Skill 附带一个基于浏览器的 HTTP 服务器，在开发过程中提供交互式可视化界面——这是”编码代理 + 浏览器”协同工作的典范
  5. Subagent 驱动开发：将复杂任务分解为可并行执行的子任务，每个子任务由独立 subagent 完成——这是一种新颖的 AI 编码执行模型
  6. 零依赖设计哲学：整个框架不依赖任何外部 npm 包或系统库（除了可选的 graphviz），安装即用
  7. CLAUDE.md 作为守门员：通过严格的 PR 验收标准和行为准则，确保贡献质量和项目方向可控

可复用模式

Section titled “可复用模式”

如何构建自己的 Skill 框架

Section titled “如何构建自己的 Skill 框架”

“如果你想为你的团队或领域构建一套类似的 Skill 框架…”

  1. 从 using-superpowers 开始：这是整个框架的入口点。创建一个引导 Skill，在会话启动时加载所有其他 Skill
  2. 定义你的开发阶段：识别你领域中的关键环节，为每个环节创建一个 Skill（如 brainstorming → planning → execution → review）
  3. 设计 Skill 关系图：明确每个 Skill 的输入/输出和前驱/后继关系
  4. 实现 Skill 内容：按”metadata → body → resources”结构编写每个 SKILL.md
  5. 添加辅助脚本：为 Skill 编写配套脚本（shell、Node.js、Python 等）
  6. 配置多平台支持：根据目标平台创建对应的插件配置文件（.claude-plugin、.codex-plugin 等）
  7. 构建测试体系：为每个 Skill 创建触发测试和功能测试
  8. 编写 CLAUDE.md 守则：建立贡献标准，确保 AI 代理遵守框架规范

常见坑

Section titled “常见坑”
  • ⚠️ 不要让 Skills 之间冲突：多个 Skill 可能对同一场景有不同指令，需要明确优先级规则（用户指令 > Superpowers Skills > 默认系统提示）
  • ⚠️ 引导加载器必须可靠：如果 using-superpowers 没有在会话启动时加载，所有 Skill 都不会自动触发
  • ⚠️ 不要过度设计 Skill 粒度：Skill 太多会让引导加载器变慢，Skill 太少又不够灵活——14 个是一个经过实践验证的平衡点
  • ⚠️ 多平台测试要完整：每个平台的插件机制不同，同一个 Skill 在不同平台上的触发行为可能不同，需要逐一验证
  • ⚠️ Skill 修改必须附带评估：Superpowers 要求任何行为修改必须附带 before/after eval 结果——这是确保质量的有效手段

Design Highlights

Section titled “Design Highlights”
  1. Composable Skills Pattern: 14 independent skills each focus on one development phase, automatically orchestrated into a complete pipeline by the CLAUDE.md bootstrap loader — a “microservices architecture” mapped to the AI coding agent domain
  2. Progressive Disclosure: Each skill’s SKILL.md follows “metadata → body → resources” structure: trigger points exposed first via YAML frontmatter (name + description), then behavioral guidance via skill body, then deep support via reference files
  3. Multi-Harness Pattern: Single codebase supporting 6 coding agent platforms (Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor, Copilot CLI), each integrated through their respective plugin mechanisms
  4. Visual Companion Pattern: The brainstorming skill includes a browser-based HTTP server providing interactive visual interfaces during development — a model for “coding agent + browser” collaboration
  5. Subagent-Driven Development: Complex tasks decomposed into parallel sub-tasks, each completed by an independent subagent — a novel AI coding execution model
  6. Zero-Dependency Philosophy: The entire framework depends on no external npm packages or system libraries (except optional graphviz) — install and use instantly
  7. CLAUDE.md as Gatekeeper: Strict PR acceptance standards and behavioral guidelines ensure contribution quality and project direction control

Reusable Patterns

Section titled “Reusable Patterns”

How to Build Your Own Skill Framework

Section titled “How to Build Your Own Skill Framework”

“If you want to build a similar Skill framework for your team or domain…”

  1. Start with using-superpowers: This is the framework entry point. Create a bootstrap skill that loads all other skills at session start
  2. Define your development phases: Identify key phases in your domain, create one skill per phase (e.g., brainstorming → planning → execution → review)
  3. Design skill relationship graph: Clarify each skill’s inputs/outputs and predecessor/successor relationships
  4. Implement skill content: Write each SKILL.md following “metadata → body → resources” structure
  5. Add supporting scripts: Write companion scripts for skills (shell, Node.js, Python, etc.)
  6. Configure multi-platform support: Create corresponding plugin config files per target platform (.claude-plugin, .codex-plugin, etc.)
  7. Build test infrastructure: Create trigger tests and functional tests for each skill
  8. Write CLAUDE.md rules: Establish contribution standards to ensure AI agents follow framework norms

Common Pitfalls

Section titled “Common Pitfalls”
  • ⚠️ Don’t let skills conflict: Multiple skills may have different instructions for the same scenario. Clear priority rules are needed (user instructions > Superpowers Skills > default system prompt)
  • ⚠️ Bootstrap loader must be reliable: If using-superpowers doesn’t load at session start, no skills will auto-trigger
  • ⚠️ Don’t over-design skill granularity: Too many skills slow the bootstrap loader, too few lacks flexibility — 14 is a proven balance point
  • ⚠️ Complete multi-platform testing required: Each platform has different plugin mechanisms; the same skill may trigger differently on different platforms
  • ⚠️ Skill changes must include evaluation: Superpowers requires any behavioral modification to include before/after eval results — an effective quality assurance measure
模式说明适用于...
可组合 Skills多个独立 Skill 形成开发流水线任何需要多阶段流程的 AI 编码场景
多平台适配一套代码支持 6 种编码代理需要跨平台分发的 Skill 框架
可视化伴侣浏览器端界面辅助开发过程需要交互式设计的 Skill
Subagent 驱动任务分解为并行子代理执行大规模、多模块的编码任务
CLAUDE.md 守门严格贡献标准确保质量开源项目或团队协作
PatternDescriptionApplies to...
Composable SkillsMultiple independent skills form a development pipelineAny AI coding scenario needing multi-phase workflow
Multi-HarnessSingle codebase supporting 6 coding agentsSkill frameworks needing cross-platform distribution
Visual CompanionBrowser-based interface assisting developmentSkills needing interactive design
Subagent-DrivenTask decomposition into parallel sub-agent executionLarge-scale, multi-module coding tasks
CLAUDE.md GatekeepingStrict contribution standards ensuring qualityOpen source projects or team collaboration