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

你会遇到什么

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

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

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

同一个仓库可以有两种接入形态，它们的加载机制完全不同：技能形态是“目录扫描”——客户端在启动时扫描 skills 目录，每个含 SKILL.md 的子目录就是一个技能，纯文件即可，不需要任何编译产物；插件形态是“代码加载”——客户端读取 plugin.json，加载并执行 dist/index.js 里的插件代码，这是运行时代码，缺了它插件就加载失败（感叹号）。

问题出在“用插件形态去接一个技能形态的仓库”：tarball 里的 harness 目录带 plugin.json（声明自己是插件），但不带编译产物（作者只发布了技能形态），两头对不上就报缺文件。

这也给出了判断路径：先想清楚你要哪种形态，再按对应形态的完整要求接入——要技能就复制 skills/ 目录（推荐，实测 14/14）；非要插件形态就要走 marketplace 流程拿到完整包（含 dist/）。

一步步来

1. 当技能用（推荐） — 必做

cp -r <仓库>/skills ~/.claude/skills/superpowers

新会话启用；或 npx superpowers-zh 方式拉取。

2. 当本地插件用 — 必做

/plugin marketplace add <本地路径>/.claude/plugins/superpowers/superpowers-main

然后 /plugin install superpowers@superpowers-dev → /reload-plugins。

3. Codex CLI 形态（本市场实测路径） — 必做

cp -r skills ~/.codex/skills/superpowers

无需编译产物，纯文件形态。

怎么确认修好了

技能目录结构与有效性（实测形态）：

ls ~/.codex/skills/superpowers
→ 14 技能目录 / 14 SKILL.md / frontmatter 14/14 有效

/plugin list 不再显示感叹号（本地插件形态），或 /find-skills 可见技能（技能形态）。

其它环境的表现

症状

手动下载 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，无需编译产物。