企业官网建设流程全解析

Superpowers 安装指南：5 分钟修好 Claude Code 技能库报错

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

插件显示装好了，AI 却一个技能都不加载，安装时还报Plugin not found？这篇文章带你按「确认环境 → 安装 → 排错 → 升级 → 验证」的顺序，把 Superpowers 这个技能库插件的常见安装报错逐个过一遍。每个报错都给出原因和解法，不用对着英文文档猜。

装之前 · 30 秒确认你的环境

这节解决：为什么你复制的安装命令不生效？因为不同客户端，装法不一样。

Claude Code：两个安装入口

Claude Code 自带插件系统，不用你手动摆弄文件。你有两个入口可选：官方市场，直接一条命令安装；Superpowers 自建市场，需要先注册再安装（命令见下文「装的时候」一节）。

✅ 自检：在对话里输入/plugin，确认能打开插件管理界面。

Codex、OpenCode 等其他客户端：各自装一份

在 A 客户端装好，不等于 B 客户端也有。Superpowers 要在每个客户端里单独安装。比如 OpenCode 走自己的插件管理器：在opencode.json的plugin数组里登记一行 superpowers 的 git 包，然后重启。这一行具体怎么写，见 OpenCode 安装说明。Codex 则可以直接在它的插件市场里搜索 Superpowers 安装。

Windows：终端差异先看一眼

Windows 上钩子的执行依赖 Git Bash——它是 Git for Windows 附带的一套小型命令行环境，没装它，安装会「看似成功、实际没生效」。另外 cmd.exe、PowerShell、Git Bash 三个终端的行为各有差别，项目已为每种终端准备了差异说明，安装前先确认你用的是哪个终端。

✅ 自检：运行git --version能出结果，且确认机器上有 Git Bash。

装的时候 · 一条命令与高频报错

这节解决：该敲哪条命令，以及最常碰到的两个错误。

最常见的路径是走 Superpowers 自建市场，两行搞定：

/plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace

⚠️ 看到Plugin not found，意思是客户端在已注册的市场里找不到这个包。原因通常是只敲了 install、漏了前面那行 add。解法：补跑 add 那行再装一次。

看到脚本里有^M之类的怪字符、或者脚本干脆不执行，多半是 Windows 的 CRLF 行尾在捣乱。仓库已强制 LF 行尾，本地克隆若被污染，删掉重新克隆即可：

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

✅ 自检：重新克隆后重启客户端，启动日志里不再出现 CRLF 相关报错。

装完了却不好使 · 按报错对症查

这节解决：安装成功、技能却不生效的三个高频症状。先看报错，再对号入座。

Plugin hook error：钩子执行失败

现象：会话启动时报Plugin hook error，AI 像没装过技能库一样。

原因：hook（钩子）就是在特定时机自动运行的一小段脚本。这里指hooks/目录里的 session-start 脚本，负责在每个新会话开始时把「技能库使用手册」塞进 AI 的上下文。这一步失败，AI 就是「装了但不知道自己有技能」。

解法：把 Superpowers 升到最新版——旧版本在部分终端环境下的钩子执行问题已在后续版本逐一修复，更新日志里有完整记录。

✅ 自检：重启客户端、新开一个会话，启动日志里没有 hook 报错。

Bad substitution：默认的 sh 是 dash

现象：Ubuntu/Debian 用户会在会话启动日志里看到Bad substitution。

原因：这类系统默认的/bin/sh是 dash，不认 bash 的专属语法；老版本的钩子脚本恰好用了这类写法。

解法：官方脚本已改写为 POSIX 兼容写法，升级到最新版本即可。

✅ 自检：升级后新开一个会话，日志中不再出现该报错。

技能未找到：查路径和注册

现象：AI 表示找不到指定技能，或技能列表是空的。

原因：通常是两处之一——技能文件没落到客户端会读取的路径，或插件注册不完整。当前版本首次运行会把技能包自动克隆到~/.config/superpowers/skills/，不需要手工复制；老版本留下的手工软链接要按官方文档清理，否则会互相干扰。

解法：重启客户端；仍不生效，就跳到下面「验证安装」一节，跑一遍自带的结构校验脚本定位。

✅ 自检：直接问 AI「列出你已加载的技能」，输出非空即正常。

从旧版本升级 · 不丢数据的迁移步骤

这节解决：从老安装切到新版本，怎么保住已有的技能文件。

三步走：

1. 先手动备份旧技能目录，一条命令几秒钟：

cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup

2. 在客户端的插件管理器里执行插件更新。下次会话启动时，当前版本会自己完成技能包的克隆与更新，旧目录还会被自动备份成.bak文件，无需手工跑任何初始化脚本。
3. 如果你用的是 OpenCode 老的「克隆仓库 + 软链接」装法：先删掉旧软链接和旧目录，再按 OpenCode 安装说明 改用插件管理器登记。老文档里提到的 setup-personal-superpowers 钩子已被内置初始化机制取代，遇到也不用管。

📦 自检：升级完成后看一眼~/.config/superpowers/下的.bak备份和你的手动备份目录都在。

验证安装 · 跑一遍项目自带的测试脚本

这节解决：如何确认「真的装好了」，而不是靠感觉。

项目的 测试脚本目录 按客户端分好了验证脚本。以 OpenCode 为例，标准流程是先执行环境初始化脚本，再跑整套用例：

source tests/opencode/setup.sh bash tests/opencode/run-tests.sh

初始化脚本会用临时目录搭一个隔离的测试环境，不碰你的真实配置；整套用例里的插件加载校验会检查安装结构是否完整。Claude Code 用户则用 claude-code 测试套件，它需要本机已装 claude 命令行。

🧪 自检：跑完看末尾汇总，出现STATUS: PASSED且没有 FAILED。

还没解决？三条求助路径

这节解决：按上面步骤走通后仍有问题，往哪里找答案。

1. 查官方文档：docs/ 里有各客户端的安装与使用说明；更新日志记录了历史 bug 和修复方式，可以确认你的问题是否已被修掉。
2. 提交 issue：把客户端类型、Superpowers 版本、完整报错原文写进项目的 issue 跟踪系统，信息越全，回复越快。
3. 让 AI 自己查：Superpowers 内置了系统化调试技能（见 技能目录），在对话里直接说「帮我排查技能为什么没加载」，它会按步骤检查并给出结论。

保持 Superpowers 在最新版本，遇到问题时把报错原文保存下来——下次排查，就不用对着模糊的记忆猜了。

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers