Superpowers 智能体技能框架排错指南6 个高频问题的 10 分钟修复法【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是一套给编码智能体Claude Code、OpenCode、Codex、Kimi 等用的技能框架装好后智能体会自动走头脑风暴、TDD、代码审查这套开发流程。新手最常栽跟头的不是它的能力而是装完之后的各种小毛病一启动报 Bad substitution、插件加载了却像没装一样、更新半天不生效。这篇文章挑 6 个真实高频问题每个都给你最短的修复路径。先想清楚问题卡在哪一层排查时先做个三选一的分诊是宿主环境shell、Node、平台的问题还是插件安装marketplace 注册、插件行配置的问题还是运行时行为会话没刷新、缓存没清的问题。九成问题都卡在后两层——装好了但会话还是旧的这是新手最容易忽略的一点。Bad substitution 报错的三步处理症状在 Ubuntu/Debian 上启动终端直接弹出Bad substitution流程没跑起来。原因Ubuntu/Debian 的/bin/sh默认是 dash不支持 bash 专属语法如${BASH_SOURCE[0]:-...}。老版本的hooks/session-start钩子里恰好用了这种写法dash 一执行就报这个错。修复这是官方已修的老 bugv3.6.2 和 v5.0.3 都修了钩子脚本升级到新版即可# 在 Claude Code 里执行拉取最新 Superpowers /plugin update superpowers如果你现在被卡住等不及先手动用 bash 跑钩子绕过bash hooks/session-start先恢复工作再说。确认新开会话后启动不再弹Bad substitution智能体正常进入技能流程就算修好了。顺带一提所有脚本的 shebang 也统一成了#!/usr/bin/env bashNixOS、FreeBSD 这类 bash 位置不寻常的系统不再报错升级一次全解决了。macOS 启动钩子卡死的解法症状macOS 上用 Homebrew bash会话启动时钩子无限挂起转圈等不出结果。原因bash 5.3 有个回归 bugheredoc 里展开超大变量会死等。钩子原来用 heredoc 输出注入内容变量一大就触发这个坑官方 issue #571、#572。修复同样靠升级新版把 heredoc 换成了printf输出# 确认你的 bash 版本5.3 及以上才受影响 bash --version确认升级后重新clear会话启动钩子秒级返回、不再卡死。OpenCode 装完插件不加载的排查路径症状opencode.json加了插件行重启后问你有哪些 superpowers智能体一脸茫然。原因要么插件行写错要么 OpenCode 版本太老不支持。官方给的标准排查顺序是先看日志再核对配置行。修复按 OpenCode 文档 的 Troubleshooting 一节来# 过滤插件加载日志确认有没有 superpowers 相关报错 opencode run --print-logs hello 21 | grep -i superpowers日志干净但就是不生效核对opencode.json里plugin数组那一行并升级到较新的 OpenCode 版本。确认让 OpenCode 用 skill 工具列出技能清单brainstorming、writing-plans等技能能列出来就通了。技能未找到或装了不生效的常见根因症状提示找不到某技能或者 Kimi 里装完插件、新对话还是老样子。原因两条主线。一是技能本身每个都靠SKILL.md里的 YAML frontmatter 被发现文件缺失或 frontmatter 坏了技能就不存在二是很多宿主如 Kimi只对新会话应用插件变更旧会话里装了等于没装。修复Kimi 用户装完直接开新会话# Kimi Code 中开启全新会话插件变更才会生效 /new其他宿主先确认插件已加载见上一章再检查对应技能目录下SKILL.md是否完整。确认用 Kimi 文档给的验收句Lets make a react todo list装对了的话智能体应先触发brainstorming而不是直接写代码。更新半天不生效清 OpenCode 缓存症状明明升级了 Superpowers行为却停留在旧版本。原因OpenCode 通过 git 地址装插件部分 OpenCode/Bun 版本会把解析到的 git 依赖钉在 lockfile 或缓存里重启也拉不到最新提交。修复清掉 OpenCode 的包缓存或卸载重装插件。想锁版本的话插件行直接钉 tag例如{ plugin: [superpowersgithttps://github.com/obra/superpowers.git#v5.0.3] }确认清缓存重启后问智能体它的 Superpowers 版本或观察新特性出现即更新成功。Windows 上 brainstorm 可视化伴侣悄悄挂了症状brainstorming 流程里可视化伴侣页面出不来没有任何报错。原因老版脚本在 Windows 上用nohup/disown挂后台Git Bash 环境会把这种进程直接收走服务器没起来也不会提示。修复v5.0.3 起脚本会自动识别 Windows/Git Bash 并改走前台模式升级即可。确认脚本版本# 看 start-server.sh 是否带 Windows 自动检测OSTYPE/MSYSTEM 判断 grep -n msys skills/brainstorming/scripts/start-server.sh确认能 grep 到msys相关判断重启流程后伴侣页面正常弹出。全部问题速查表症状最可能原因一句话修复启动弹Bad substitutiondash 不支持 bash 语法钩子是老版本升级 Superpowersv3.6.2/v5.0.3 已修macOS 启动钩子卡死bash 5.3 heredoc 回归 bug升级新版改用printf输出OpenCode 装完插件不加载插件行写错 / OpenCode 太老opencode run --print-logs查日志核对opencode.json技能未找到 / Kimi 装了没反应SKILL.md损坏或插件变更未进新会话修好 SKILL.mdKimi 里执行/new开新会话更新后行为仍是旧版git 依赖被 lockfile/缓存钉住清 OpenCode 包缓存或重装插件Windows 上可视化伴侣无响应nohup后台进程被 Git Bash 回收升级到 v5.0.3自动切前台模式日常习惯少踩坑的 4 件事宿主Claude Code / OpenCode / Kimi 等和 Superpowers 都保持较新版本本文一半的坑升级就消失。升级前扫一眼 RELEASE-NOTES.md平台相关的修复都写在里面。改完任何插件配置一律开新会话再验证别在旧会话里反复试。跑不通时先跑项目自带的测试脚本定位层级比如 tests/ 下的run-*.sh以及 docs/testing.md 里的说明。卡住了就去项目 Discord 社区提问或在 issue 区开一个带完整日志的工单——附上日志的问题响应快得多。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Superpowers 智能体技能框架排错指南：6 个高频问题的 10 分钟修复法
Superpowers 智能体技能框架排错指南6 个高频问题的 10 分钟修复法【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是一套给编码智能体Claude Code、OpenCode、Codex、Kimi 等用的技能框架装好后智能体会自动走头脑风暴、TDD、代码审查这套开发流程。新手最常栽跟头的不是它的能力而是装完之后的各种小毛病一启动报 Bad substitution、插件加载了却像没装一样、更新半天不生效。这篇文章挑 6 个真实高频问题每个都给你最短的修复路径。先想清楚问题卡在哪一层排查时先做个三选一的分诊是宿主环境shell、Node、平台的问题还是插件安装marketplace 注册、插件行配置的问题还是运行时行为会话没刷新、缓存没清的问题。九成问题都卡在后两层——装好了但会话还是旧的这是新手最容易忽略的一点。Bad substitution 报错的三步处理症状在 Ubuntu/Debian 上启动终端直接弹出Bad substitution流程没跑起来。原因Ubuntu/Debian 的/bin/sh默认是 dash不支持 bash 专属语法如${BASH_SOURCE[0]:-...}。老版本的hooks/session-start钩子里恰好用了这种写法dash 一执行就报这个错。修复这是官方已修的老 bugv3.6.2 和 v5.0.3 都修了钩子脚本升级到新版即可# 在 Claude Code 里执行拉取最新 Superpowers /plugin update superpowers如果你现在被卡住等不及先手动用 bash 跑钩子绕过bash hooks/session-start先恢复工作再说。确认新开会话后启动不再弹Bad substitution智能体正常进入技能流程就算修好了。顺带一提所有脚本的 shebang 也统一成了#!/usr/bin/env bashNixOS、FreeBSD 这类 bash 位置不寻常的系统不再报错升级一次全解决了。macOS 启动钩子卡死的解法症状macOS 上用 Homebrew bash会话启动时钩子无限挂起转圈等不出结果。原因bash 5.3 有个回归 bugheredoc 里展开超大变量会死等。钩子原来用 heredoc 输出注入内容变量一大就触发这个坑官方 issue #571、#572。修复同样靠升级新版把 heredoc 换成了printf输出# 确认你的 bash 版本5.3 及以上才受影响 bash --version确认升级后重新clear会话启动钩子秒级返回、不再卡死。OpenCode 装完插件不加载的排查路径症状opencode.json加了插件行重启后问你有哪些 superpowers智能体一脸茫然。原因要么插件行写错要么 OpenCode 版本太老不支持。官方给的标准排查顺序是先看日志再核对配置行。修复按 OpenCode 文档 的 Troubleshooting 一节来# 过滤插件加载日志确认有没有 superpowers 相关报错 opencode run --print-logs hello 21 | grep -i superpowers日志干净但就是不生效核对opencode.json里plugin数组那一行并升级到较新的 OpenCode 版本。确认让 OpenCode 用 skill 工具列出技能清单brainstorming、writing-plans等技能能列出来就通了。技能未找到或装了不生效的常见根因症状提示找不到某技能或者 Kimi 里装完插件、新对话还是老样子。原因两条主线。一是技能本身每个都靠SKILL.md里的 YAML frontmatter 被发现文件缺失或 frontmatter 坏了技能就不存在二是很多宿主如 Kimi只对新会话应用插件变更旧会话里装了等于没装。修复Kimi 用户装完直接开新会话# Kimi Code 中开启全新会话插件变更才会生效 /new其他宿主先确认插件已加载见上一章再检查对应技能目录下SKILL.md是否完整。确认用 Kimi 文档给的验收句Lets make a react todo list装对了的话智能体应先触发brainstorming而不是直接写代码。更新半天不生效清 OpenCode 缓存症状明明升级了 Superpowers行为却停留在旧版本。原因OpenCode 通过 git 地址装插件部分 OpenCode/Bun 版本会把解析到的 git 依赖钉在 lockfile 或缓存里重启也拉不到最新提交。修复清掉 OpenCode 的包缓存或卸载重装插件。想锁版本的话插件行直接钉 tag例如{ plugin: [superpowersgithttps://github.com/obra/superpowers.git#v5.0.3] }确认清缓存重启后问智能体它的 Superpowers 版本或观察新特性出现即更新成功。Windows 上 brainstorm 可视化伴侣悄悄挂了症状brainstorming 流程里可视化伴侣页面出不来没有任何报错。原因老版脚本在 Windows 上用nohup/disown挂后台Git Bash 环境会把这种进程直接收走服务器没起来也不会提示。修复v5.0.3 起脚本会自动识别 Windows/Git Bash 并改走前台模式升级即可。确认脚本版本# 看 start-server.sh 是否带 Windows 自动检测OSTYPE/MSYSTEM 判断 grep -n msys skills/brainstorming/scripts/start-server.sh确认能 grep 到msys相关判断重启流程后伴侣页面正常弹出。全部问题速查表症状最可能原因一句话修复启动弹Bad substitutiondash 不支持 bash 语法钩子是老版本升级 Superpowersv3.6.2/v5.0.3 已修macOS 启动钩子卡死bash 5.3 heredoc 回归 bug升级新版改用printf输出OpenCode 装完插件不加载插件行写错 / OpenCode 太老opencode run --print-logs查日志核对opencode.json技能未找到 / Kimi 装了没反应SKILL.md损坏或插件变更未进新会话修好 SKILL.mdKimi 里执行/new开新会话更新后行为仍是旧版git 依赖被 lockfile/缓存钉住清 OpenCode 包缓存或重装插件Windows 上可视化伴侣无响应nohup后台进程被 Git Bash 回收升级到 v5.0.3自动切前台模式日常习惯少踩坑的 4 件事宿主Claude Code / OpenCode / Kimi 等和 Superpowers 都保持较新版本本文一半的坑升级就消失。升级前扫一眼 RELEASE-NOTES.md平台相关的修复都写在里面。改完任何插件配置一律开新会话再验证别在旧会话里反复试。跑不通时先跑项目自带的测试脚本定位层级比如 tests/ 下的run-*.sh以及 docs/testing.md 里的说明。卡住了就去项目 Discord 社区提问或在 issue 区开一个带完整日志的工单——附上日志的问题响应快得多。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考