技能管理 · skills · 验证于 2026-08-27 ✓ 实测验证

superpowers

已验证 2026-08-27技能安装实测通过；14 个可组合技能 + 软件开发方法论。

Agent 技能框架 + 软件开发方法论（14 个可组合技能），适合用 AI 结对开发、想要结构化工作流的开发者

详细版 → 所属问题域：技能管理 遇到问题？去问题空间 →

你会遇到什么

这个工具解决什么问题：让 Agent 按软件工程方法论干活——先设计后编码、测试驱动、系统化调试、子代理驱动开发。Superpowers 是 14 个可组合技能的方法论框架：Agent 依据 SKILL.md 的 description 自动触发（如写代码前自动 brainstorming + TDD）。 什么时候用：

  • 你要让 Agent 的编码行为从「直接写」变成「先想清楚再写」；
  • 你要 brainstorming / test-driven-development / systematic-debugging / subagent-driven-development 这套方法论；
  • 你在 Codex 环境（官方 Codex 形态 = 复制 skills/ 到 ~/.codex/skills/superpowers，本环境实测）。

什么时候别用：你只想要工具、不想要方法论约束时——它会改变 Agent 的工作方式（这是设计目的）。 注意事项：纯技能包——无 CLI/daemon/端口；安装 = 复制 skills 目录；技能由 Agent 自动触发，无需手动命令。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：官方 Codex 形态 = 把仓库 skills/ 复制到 ~/.codex/skills/superpowers（纯文件复制，14 个技能目录 + SKILL.md）。安装后技能由 Agent 依据 description 自动触发。方式 B：Claude Code 官方插件市场（/plugin install superpowers，未实测——未登录）。 关键概念：

  • 自动触发：Agent 读 SKILL.md 的 description，任务匹配时自动装载；
  • 方法论技能：brainstorming / TDD / systematic-debugging / subagent-driven-development 等 14 个；
  • 同目录写面：技能子目录名唯一，与其他技能集同名则后装覆盖。

装完它动哪里：~/.codex/skills/superpowers/（Codex 形态）；Claude 形态写 ~/.claude/skills/ 或插件注册。

快速修复（不想看讲解，直接跑）

note: 官方 Codex 形态（本环境实测）；国内/国外均可直连 GitHub（codeload 1.7s，探针 2026-08-27）
curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0
rm -rf /tmp/superpowers-src && mkdir -p /tmp/superpowers-src
tar xzf /tmp/superpowers.tar.gz -C /tmp/superpowers-src --strip-components=1
mkdir -p ~/.codex/skills && cp -r /tmp/superpowers-src/skills ~/.codex/skills/superpowers
test -f ~/.codex/skills/superpowers/brainstorming/SKILL.md && echo "superpowers installed: OK"

预期输出: superpowers installed: OK

一步步来

第 1 步：复制技能目录（为什么直接复制：纯文件技能包，无依赖无注册）

讲解：下载 tag 为 v6.3.0 的 tarball（固定 tag 不漂移），解压后把 skills/ 复制到 ~/.codex/skills/superpowers。重复安装覆盖同名目录。安装 = 纯文件复制，无依赖、无注册、无后台进程。

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0
rm -rf /tmp/superpowers-src && mkdir -p /tmp/superpowers-src
tar xzf /tmp/superpowers.tar.gz -C /tmp/superpowers-src --strip-components=1
mkdir -p ~/.codex/skills && cp -r /tmp/superpowers-src/skills ~/.codex/skills/superpowers
test -f ~/.codex/skills/superpowers/brainstorming/SKILL.md && echo "superpowers installed: OK"

预期输出: superpowers installed: OK

装好确认：

  • 输出 superpowers installed: OK；
  • ls ~/.codex/skills/superpowers 有 14 个技能目录。

卡住怎么办：

  • codeload 下载失败 → 换网络重试（codeload 直连实测 1.7s，一般可达）；
  • 技能没生效 → 确认复制到了 Agent 实际读取的技能目录（Codex 是 ~/.codex/skills/）。

第 2 步：确认技能就位（本环境实测）

讲解：列出技能目录确认 14 个技能；技能由 Agent 自动触发，无需手动命令。

ls ~/.codex/skills/superpowers

预期输出: 14 个技能目录（brainstorming / test-driven-development / systematic-debugging / subagent-driven-development 等）

装好确认：

  • 输出包含 brainstorming、test-driven-development 等目录。

卡住怎么办：

  • 目录不齐 → 重新执行第 1 步的复制。

第 3 步：更新到最新版（重新下载覆盖）或装 Claude 形态（按需）

讲解：更新 = 重新下载覆盖（固定 tag，不会漂移）；Claude Code 形态用官方插件市场（未实测——未登录）；也可手动复制到 ~/.claude/skills/superpowers。

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 && rm -rf /tmp/superpowers-src && mkdir -p /tmp/superpowers-src && tar xzf /tmp/superpowers.tar.gz -C /tmp/superpowers-src --strip-components=1 && cp -r /tmp/superpowers-src/skills ~/.codex/skills/superpowers && echo "updated: OK"

预期输出: updated: OK

Claude 形态检查：

ls ~/.claude/skills/superpowers 2>/dev/null || echo "未安装 Claude 形态"

预期输出: 目录列表或未安装提示

卡住怎么办：

  • 下载失败 → 换网络重试（codeload 直连实测 1.7s）；
  • Claude 插件形态装不上 → 确认 Claude Code 登录（本环境未实测）。

怎么确认修好了

第 1 步：确认技能目录就位

讲解：安装是纯文件复制，确认文件落地即安装完成——test -f 标记文件存在 + 目录列表包含核心技能目录。

test -f ~/.codex/skills/superpowers/brainstorming/SKILL.md && echo "installed: OK" || echo "installed: MISSING"
ls ~/.codex/skills/superpowers

预期输出: installed: OK + 14 个技能目录（brainstorming / test-driven-development / systematic-debugging / subagent-driven-development 等）

卡住怎么办：

  • 目录不齐 → 重新执行「一步步来」第 1 步的复制；
  • 技能没生效 → 确认复制到了 Agent 实际读取的技能目录（Codex 是 ~/.codex/skills/）。

第 2 步：确认 Agent 能触发（可选）

讲解：技能由 Agent 自动触发，无需手动命令；新建会话后让 Agent 处理一个匹配技能的场景（如调试任务），能引用 brainstorming/systematic-debugging 即链路确认。

# 无命令：新建会话让 Agent 触发技能即可

预期输出: Agent 会话中技能被自动引用（无需手动调用）

卡住怎么办：

  • Agent 不引用 → 确认技能目录在 Agent 实际读取路径（~/.codex/skills/），必要时重启会话。

其它环境的表现（常见变体）

  • 更新：重新下载覆盖固定 tag（v6.3.0，不漂移）；重复安装覆盖同名目录。
  • Claude 形态：官方插件市场（未实测——未登录）或手动复制到 ~/.claude/skills/superpowers；与 ruflo 判定 possible-conflict（Claude 形态共享 ~/.claude/skills 写面，未实测），装 ruflo 时建议用 Codex 形态。
  • 网络：codeload 直连实测 1.7s（国内/国外均可直连），一般不需要镜像。
  • 写面：~/.codex/skills/superpowers/（纯文件复制；无依赖、无注册、无后台进程）。

日常使用

启动与入口

无启动；技能由 Agent 按需自动触发（SKILL.md 的 description 决定）。

常用操作

操作一：确认已装技能

ls ~/.codex/skills/superpowers

预期输出: 14 个技能目录（brainstorming / test-driven-development / systematic-debugging / subagent-driven-development 等）

操作二：更新到最新版（重新下载覆盖）

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 && rm -rf /tmp/superpowers-src && mkdir -p /tmp/superpowers-src && tar xzf /tmp/superpowers.tar.gz -C /tmp/superpowers-src --strip-components=1 && cp -r /tmp/superpowers-src/skills ~/.codex/skills/superpowers && echo "updated: OK"

预期输出: updated: OK

操作三：检查是否装过 Claude 形态

ls ~/.claude/skills/superpowers 2>/dev/null || echo "未安装 Claude 形态"

预期输出: 目录列表或未安装提示

数据与目录

  • 技能目录：~/.codex/skills/superpowers/（Codex 形态）；
  • Claude 形态：~/.claude/skills/superpowers 或插件注册。

卸载与清理

note: 纯文件技能包，删除技能目录即零残留；本市场一键卸载自动执行
rm -rf ~/.codex/skills/superpowers
test ! -d ~/.codex/skills/superpowers && echo "superpowers removed: OK" || echo "残留: superpowers 仍存在"

预期输出: superpowers removed: OK

手动确认清单（若装过其他形态）：

  • ~/.claude/skills/superpowers（Claude Code 手动复制形态）
  • Claude Code /plugins 安装的插件（用 /plugin uninstall superpowers）
  • 其他 harness（Cursor/Gemini/Copilot 等）：对应平台插件管理删除

依赖警告

  • 版本：[6.3.0, 6.3.0] 锁定（收录实测版本；安装命令固定 tag 不漂移）。
  • 环境：无运行时要求；Codex 形态需 ~/.codex/skills 可写。
  • 网络：codeload 直连实测 1.7s（国内/国外均可直连）。
  • 写面：~/.codex/skills/superpowers/（纯文件复制；重复安装覆盖同名目录）。
  • 共装：与 omc/agt/deepcode 判定 possible-compatible（无共享写面）；与 ruflo 判定 possible-conflict（Claude 形态共享 ~/.claude/skills 写面，未实测），装 ruflo 时建议用 Codex 形态。

FAQ（常见问题）

  • 问：安装后需要配置什么吗？答：不需要。技能由 Agent 按需自动触发（SKILL.md 的 description 决定），无配置文件。
  • 问：会不会影响我现有的其他技能？答：superpowers 技能子目录名唯一（如 brainstorming）；若其他技能集有同名技能，后装者覆盖（同目录写面），先检查 ~/.codex/skills 下已有技能名。
  • 问：为什么我的 Agent 行为变了？答：这是预期的——superpowers 是方法论框架（先设计后编码、TDD、子代理驱动），会改变 Agent 的工作方式。
  • 问：更新快，版本怎么锁定？答：本条目锁定 6.3.0（manifest version_range 单版本）；安装命令固定 tag，不会漂移。
  • 问：和其他插件能一起装吗？答：与 omc/agt/deepcode 判定 possible-compatible（无共享写面）；与 ruflo 判定 possible-conflict（Claude 形态共享 ~/.claude/skills 写面，未实测），装 ruflo 时建议用 Codex 形态。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。
验证证据
  • 实测：实测记录（本地留存）（2026-08-27，codeload 下载 + 复制 + 技能就位冒烟）。
  • 未实测：Claude Code 插件形态（未登录）；技能自动触发效果（需真实 Agent 会话观察）。

引用：superpowers · 验证于 2026-08-27 · v6.3.0~6.3.0

相关问题（问题域）

出问题了？排障方案

排障手册：superpowers（L34 批次 1）

症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：L33 分源记录（CSDN/掘金/知乎/B站）+ 匿名网页采集（CSDN 2 篇全文 + 掘金 1 篇全文）+ 本市场实测（2026-08-27/28）。
采集纪律：零账号匿名检索；不破解反爬；未碰 GitHub。check-words HARD 0。

基本信息

  • 条目名称：superpowers（obra/superpowers，MIT，v6.3.0 收录）
  • L33 分源信号：CSDN=5 / 掘金=5 / 知乎=4 / B站=5（强）
  • §14 角色：core；分类：skills
  • 定位：Agent 技能框架 + 软件开发方法论（14 个可组合技能）
  • 本市场安装路径：tarball 直装（站内文档 + 站内文档）
  • 主要安装形态：Codex CLI（~/.codex/skills/superpowers）/ Claude Code 插件市场（上游市场 git clone 路径）/ 通用 skills 目录

症状 → 原因 → 解法 → 验证证据

1. /plugin install 报 fatal: Failed to connect to github.com port 443

症状

Claude Code 中执行 /plugin install superpowers@claude-plugins-official 或 @superpowers-marketplace 报：

# 来源: Trove 排障手册 · 验证于 2026-08-27
fatal: unable to access 'https://github.com/obra/superpowers.git/': Failed to connect to github.com port 443 after 2045 ms

应用内配了全局代理也不通（未开 TUN 时 git 子进程不走代理）。

原因

上游 Claude Code 插件市场的安装路径 = git clone GitHub 仓库（市场网站不提供 zip 下载）；国内网络直连 github.com:443 不稳定/被阻断；应用级代理不覆盖 git 子进程（除非 TUN/透明代理或给 git 显式配代理）。

解法

  1. 先探路再选路：curl -sI https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0——codeload 可达就走 tarball 直装（命令见「本市场实测」一节，本环境 1.7~1.9s）。
  2. 给 git 显式配代理后重试：git config --global http.proxy http://127.0.0.1:<端口>；或开 TUN/透明代理。
  3. 走加速：gh-proxy 类加速（2026-08-28 实测可用，7.8s），或用国内镜像站下载 zip 后离线安装（见症状 2）。
  4. 离线兜底：按「症状 6」的本地路径方式接入。

验证证据

  • 网页案例：CSDN m0_58528895/161265224（2026-05）——443 案例全文：@claude-plugins-official / @superpowers-marketplace 均失败，全局代理不通、未试 TUN。
  • 本市场实测 2026-08-28：GitHub 源码下载 200 / 1.91s（站内文档；2026-08-27 基线 1.73s）；raw.githubusercontent.com 超时（非安装路径，避免使用）。
  • 本市场实测安装：codeload tarball 544K / 2.1s → PASS（实测记录（本地留存））。

2. ZIP / tarball 下载超时或中断

症状

从 GitHub 下载 zip / tarball 反复超时、中断，无法拿到完整压缩包。

原因

到 GitHub 的下载链路（codeload/github.com）不稳定或带宽差；大文件传输中途断开。

解法

  1. 换通道：改用 git clone（浅克隆 git clone --depth 1 --branch v6.3.0 https://github.com/obra/superpowers.git）或反向互换。
  2. 换网络：切换网络环境 / 开代理后重试；错峰重试。
  3. 离线解压：换任意可达的镜像站下载 zip → 手动解压 → 按「症状 6」接入；不依赖 zip 完整性的替代 = 只取 skills 目录（tarball 内含）。

验证证据

  • 网页案例：CSDN Codex 桌面端安装（2026-06）——ZIP 下载超时 → git clone / 换网络 / 离线解压的社区解法。
  • 本市场实测：codeload tarball 544K 直连稳定（2.1s 完成，），证明该端点当前可用；探针 raw 端点超时，故手册统一避开 raw 路径。

3. Plugin not found

症状

/plugin install superpowers@... 报 plugin not found / 找不到插件。

原因

市场源未添加或名字写错：superpowers 不在当前已配置的市场源里（上游市场与社区市场源名字不同）。

解法

  1. 先加市场源：/plugin marketplace add obra/superpowers-marketplace（或 claude-plugins-official，取决于你要哪个渠道的版本）。
  2. 再装：/plugin install superpowers@superpowers-marketplace。
  3. 确认：/plugin marketplace list 检查源已生效；必要时 /plugin marketplace update 后重试。

验证证据

  • 网页案例：CSDN 问题排查指南（2026-01）——Plugin not found → 市场配置错误，加源后解决。
  • 掘金基础教程（2026）——标准三步：加源 → 安装 → 新会话 /find-skills 验证。
  • 未实测项（如实标注）：Claude Code 插件市场路径本机不可测（无登录态），以上为网页方案整合。

4. 安装后 hook error（Windows SessionStart hook fails）

症状

安装后 Claude Code 启动报 hook 错误（SessionStart hook 执行失败）。

原因

Claude Code 在 Windows 上的路径处理 bug（上游 Issue #420 属此场景）；或插件版本与 Claude Code 版本不匹配。

解法

  1. 升级 Claude Code 与插件版本后重试。
  2. 手动执行对应 hook 脚本（session-start.sh）看真实报错。
  3. Windows 场景可改走纯技能形态（不依赖 hook 的路径，见「症状 6」）。

验证证据

  • 网页案例：CSDN（2026-01）——Plugin hook error → 更新版本或手动跑 session-start.sh。
  • 国外信号（L32 窗口期匿名摘录）：上游 Issue #420 为 Windows SessionStart hook 路径处理 bug。

5. 装完看不到技能

症状

安装成功，但 /find-skills（或等价技能查看命令）看不到 brainstorming / systematic-debugging / test-driven-development 等技能。

原因

技能缓存未刷新；未完全退出重开新会话；技能被放到 Claude 读不到的目录（路径放错）。

解法

  1. /plugin list 确认插件状态（感叹号 = 不可用，见症状 6）。
  2. 完全退出（Ctrl+C 或 /exit）后重开新会话再查。
  3. 检查路径：Claude Code 读 ~/.claude/skills/（或插件安装目录），不要放在其他目录。
  4. 缓存不全时重跑安装命令（上游 Issue #818 场景：14 个技能只装了 7 个，重装补齐）。

验证证据

  • 网页案例：CSDN（2026-06）+ 掘金 FAQ（2026）——退出重启 + 路径检查为社区通用解法。
  • 国外信号（L32 匿名摘录）：上游 Issue #818 技能缓存不完整（7/14）。
  • 本市场实测：tarball 结构 14 技能目录 / 14 SKILL.md / frontmatter 14/14 有效——技能完整性可提前校验。

6. 本地/离线部署后插件显示不可用（感叹号）

症状

手动下载 zip 解压放到 ~/.claude/plugins/local-superpowers 后，/plugin list 显示感叹号不可用；直接复制仓库目录也报缺文件。

原因

tarball 内各 harness 目录（.claude-plugin/.codex-plugin/.cursor-plugin）带 plugin.json，但不含编译产物 dist/index.js——本地插件形态要求完整插件包；纯 SKILL 仓库按插件路径接入会缺件。

解法

  1. 当技能用（推荐）：把仓库内 skills/ 下全部技能目录复制到 Claude 能读的 skills 目录，新会话启用；或 npx superpowers-zh 方式拉取。
  2. 当本地插件用：/plugin marketplace add <本地路径>/.claude/plugins/superpowers/superpowers-main → /plugin install superpowers@superpowers-dev → /reload-plugins。
  3. Codex CLI 形态（本市场实测路径）：下载 tarball → cp -r skills ~/.codex/skills/superpowers，无需编译产物。

验证证据

  • 网页案例：CSDN m0_58528895/161265224（2026-05）——离线部署缺 plugin.json + dist/index.js 导致不可用（作者原仓库确实无编译产物）。
  • 网页案例：CSDN aicoding.csdn.net（2026）——本地路径 marketplace add → install → reload 的可行接入流程。
  • 本市场实测：tarball 含 .claude-plugin/plugin.json 但无 dist/（2026-08-28 解包核实）；skills 目录复制形态 14/14 有效。

7. 无本地文件读取权限 / 渠道不一致

症状

Codex 桌面端装完读不到技能（无本地文件读取权限）；CodeBuddy 等产品装 OpenSpec/Superpowers 渠道不一致报错。

原因

桌面端未授予本地文件读取权限；不同产品对「插件/技能」的格式与目录约定不同（Codex 桌面端、CodeBuddy、Claude Code 各一套）。

解法

  1. 在对应产品的设置里授予本地文件读取权限。
  2. 按产品形态安装：Codex 用 skills 目录；Claude Code 用插件市场或 skills 目录；CodeBuddy 用其自身渠道（先查该产品支持 Superpowers 的形态）。
  3. 渠道不一致报错时，以产品自带插件安装渠道为准，不要混用。

验证证据

  • 网页案例：CSDN Codex 桌面端（2026-06）——权限问题；CSDN CodeBuddy（2026-07）——渠道不一致。
  • 本市场形态边界：Codex 形态纯文件（无权限/端口/后台需求）；Claude Code 形态未实测（无登录态）。

本市场实测安装 / 卸载（2026-08-27/28）

安装（站内安装说明 superpowers，隔离 HOME 复现）：

# 来源: Trove 排障手册 · 验证于 2026-08-27
[install][WARN] 注意：superpowers 与以下条目存在未验证组合（可能冲突）: ruflo
[probe][PASS] github：GitHub 源码下载 / GitHub 网页 / GitHub API 可用
[install] 执行: curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 && ... && cp -r .../skills ~/.codex/skills/superpowers
superpowers installed: OK
[install] 已记录本地安装回执（匿名；~/.trove/receipts/）
[install][PASS] superpowers 安装完成

卸载（站内卸载说明 superpowers，green 档一键执行）：

# 来源: Trove 排障手册 · 验证于 2026-08-27
[uninstall] 执行: rm -rf ~/.codex/skills/superpowers
[uninstall] 验证: test ! -d ~/.codex/skills/superpowers
superpowers removed: OK
[uninstall][PASS] superpowers 卸载完成，零残留

完整日志：实测记录（本地留存）；连通性：实测记录（本地留存） + 站内文档。

冲突标注

  • possible-compatible：oh-my-claudecode / agent-governance-toolkit / deepcode（无共享写面，共装判定见冲突矩阵）
  • possible-conflict：ruflo（Claude 形态共享 ~/.claude/skills 写面，未实测）——同机装 ruflo 时建议用 Codex 形态
  • 形态维度：Codex 形态只写 ~/.codex/skills/superpowers，与其他条目共享面最小；Claude 插件市场形态写面在 Claude 插件目录，按形态分别评估

名称混淆

无同名高危条目（检索时注意 superpower 单复数拼写差异）。

判据（验证状态）

  • 症状清单：
  • [x] /plugin install 报 fatal: Failed to connect to github.com port 443（CSDN，2026-05；解包核实 + 探针证据）
  • [x] ZIP 下载超时 → git clone/换网络/离线解压（CSDN，2026-06）
  • [x] Plugin not found → 市场源配置错误（CSDN，2026-01；掘金教程整合）
  • [x] Plugin hook error → 更新版本或手动跑 session-start.sh（CSDN，2026-01；上游 Issue #420）
  • [x] 装完看不到技能 → 完全退出重启 + 路径检查（CSDN，2026-06；掘金 FAQ；上游 Issue #818）
  • [x] 无本地文件读取权限 / 渠道不一致（CSDN，2026-06/07）
  • [x] 本地插件缺 dist 产物显示不可用（CSDN 2026-05 + aicoding 案例；tarball 解包核实无 dist/）
  • 实测步骤：

本站实测记录

  • [x] 卸载验证（green 档一键卸载 → verify 零残留）
  • [x] 网络/镜像场景（network-probe full：codeload 1.91s / gh-proxy 7.8s / raw 超时）
  • [x] 未能实测项：Claude Code 插件市场场景本机不可测（无登录态）——网页方案整合，如实标注

验收

  • [x] 症状 → 原因 → 解法 → 验证证据 四段齐全（7 症状）
  • [x] 名称混淆已点名：无同名高危条目
  • [x] check-words HARD 0
  • [x] validate 通过
  • [x] 未碰 GitHub / 未用任何账号

所属组合包 （1）

矩阵暂无该工具对子。

← 返回工具货架 ｜ 遇到其它问题？去 问题空间 提交求助卡 ｜ 预检与证据记录由维护流程本地留存，仅公开结论与来源