Superpowers技能库跨平台部署与应用指南

1. 基础认知：Superpowers技能库概述

Superpowers是一套面向AI编程助手的技能扩展系统，旨在标准化开发流程并提升代码质量。该系统通过预定义的技能模块，将专业开发方法论编码为可执行的AI指令，实现从需求分析到代码交付的全流程支持。技能库采用模块化设计，可适配Claude Code、OpenCode和Codex三大主流AI编程平台，确保不同开发环境下的一致体验。

2. 环境准备：系统要求与兼容性检查

2.1 系统要求验证

在开始部署前，需确认开发环境满足以下基本要求：

1. 操作系统：Linux/macOS/Windows（WSL2）
2. Node.js环境：v14.0.0或更高版本
3. Git版本控制工具
4. 网络连接（用于获取技能库资源）

执行以下命令验证环境：

# 检查Node.js版本
node --version

# 检查Git安装情况
git --version

# 验证网络连通性
ping -c 3 gitcode.com

2.2 版本兼容性矩阵

平台	最低版本要求	支持的技能模块	扩展能力
Claude Code	v1.2.0	全部	插件市场集成
OpenCode	v0.8.0	核心技能集	自定义脚本扩展
Codex	v1.0.0	基础开发技能	有限的子代理支持

3. 分平台部署：安装与配置流程

3.1 Claude Code平台部署

Claude Code提供插件化安装方式，步骤如下：

1. 打开Claude Code终端，添加技能市场源：

/plugin marketplace add obra/superpowers-marketplace

2. 安装核心技能库：

/plugin install superpowers@superpowers-marketplace

3. 验证安装结果：

# 查看已安装插件列表
/plugin list

# 验证技能加载情况
/skill list

注意事项：Claude Code会自动处理依赖关系，但需确保网络连接稳定以完成插件下载。

3.2 OpenCode平台部署

OpenCode需要手动配置目录结构和符号链接：

1. 创建必要目录：

mkdir -p ~/.config/opencode/superpowers
mkdir -p ~/.config/opencode/plugin

2. 克隆技能库代码：

git clone https://gitcode.com/GitHub_Trending/su/superpowers ~/.config/opencode/superpowers

3. 创建插件链接：

ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js

4. 重启OpenCode生效配置。

注意事项：符号链接需使用绝对路径，避免相对路径导致的引用错误。

3.3 Codex平台部署

Codex采用轻量级目录部署方式：

1. 创建安装目录：

mkdir -p ~/.codex/superpowers

2. 克隆技能库资源：

git clone https://gitcode.com/GitHub_Trending/su/superpowers ~/.codex/superpowers

3. 在Codex配置中添加技能路径：

# 编辑Codex配置文件
nano ~/.codex/config.json

# 添加以下配置项
"skillPaths": ["~/.codex/superpowers/skills"]

注意事项：Codex需要手动指定技能路径，修改配置后需重启应用。

4. 核心功能：技能库分类与应用场景

4.1 设计阶段技能

• brainstorming：结构化需求分析工具，通过引导式提问将模糊需求转化为可执行任务。适用于项目初始阶段的需求梳理和方案设计。

• writing-plans：开发计划生成器，将项目分解为2-5分钟可完成的独立任务单元。适用于迭代开发中的任务规划和时间估算。

4.2 开发阶段技能

• subagent-driven-development：双阶段代码质量保障机制，先验证规范符合性，再进行代码质量审查。适用于需要严格质量控制的开发场景。

• test-driven-development：自动化测试驱动流程，严格执行RED-GREEN-REFACTOR开发循环。适用于对代码可靠性要求较高的核心模块开发。

4.3 调试协作技能

• systematic-debugging：四阶段根本原因分析流程，包括症状识别、假设验证、原因定位和解决方案实施。适用于复杂问题的诊断与修复。

• requesting-code-review：代码审查准备工具，生成包含关键检查点的预审查清单。适用于协作开发中的代码质量控制环节。

5. 实践案例：完整开发周期应用

以下展示Superpowers技能在典型开发流程中的应用：

1. 需求分析阶段： 使用brainstorming技能梳理用户需求：

   /skill brainstorming "设计一个任务管理应用，支持用户创建、分配和跟踪任务状态"
   

2. 开发规划阶段： 生成详细实施计划：

   /skill writing-plans "任务管理应用开发"
   

3. 代码开发阶段： 启动子代理驱动开发流程：

   /skill subagent-driven-development "任务数据模型实现"
   

4. 测试验证阶段： 执行测试驱动开发流程：

   /skill test-driven-development "用户认证模块"
   

5. 质量保障阶段： 请求代码审查：

   /skill requesting-code-review "任务分配功能"
   

6. 常见问题诊断：部署与运行故障排除

6.1 部署相关问题

问题：Claude Code插件安装失败 方案：检查网络连接，执行以下命令清理缓存后重试：

/plugin cache clear
/plugin marketplace update

问题：OpenCode符号链接创建失败 方案：确认目标路径存在，使用绝对路径重新创建：

# 检查目标文件是否存在
ls -l ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js

# 重新创建符号链接
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js

6.2 运行相关问题

问题：技能命令无响应 方案：验证技能库加载状态，检查日志文件：

# Claude Code查看日志
/logs show plugin:superpowers

# OpenCode查看日志
cat ~/.config/opencode/logs/plugin-superpowers.log

问题：子代理任务执行失败 方案：检查Node.js版本兼容性，确认版本不低于v14：

node --version

7. 进阶技巧：技能库定制与维护

7.1 技能优先级配置

Superpowers采用三级技能优先级体系：

1. 项目技能（项目根目录下的skills目录）
2. 个人技能（用户主目录下的.superpowers/skills）
3. 系统技能（技能库默认技能）

可通过以下命令查看当前技能优先级：

/skill priority list

7.2 技能库更新维护

所有平台均支持通过Git更新技能库：

# Claude Code平台
/plugin update superpowers

# OpenCode平台
cd ~/.config/opencode/superpowers && git pull

# Codex平台
cd ~/.codex/superpowers && git pull

更新完成后需重启对应平台以加载新技能。

7.3 自定义技能开发

创建个人技能扩展：

1. 创建技能目录：

mkdir -p ~/.superpowers/skills/my-custom-skill

2. 编写技能定义文件（SKILL.md），遵循现有技能格式规范

3. 加载自定义技能：

/skill reload

8. 架构解析：技能库核心模块

Superpowers技能库采用模块化架构，核心组件包括：

• 技能核心引擎：位于lib/skills-core.js，负责技能解析、加载和执行调度
• 技能定义规范：每个技能包含SKILL.md定义文件和相关实现脚本
• 平台适配层：处理不同AI平台的API差异，提供统一调用接口

模块间通过事件驱动机制交互，当触发特定开发场景时，技能引擎自动匹配并激活相关技能，确保开发流程的标准化执行。

官方文档：docs/README.opencode.md 技能定义示例：skills/writing-plans/SKILL.md 核心引擎源码：lib/skills-core.js