Problem: Offline install fails — /plugin list shows "!" unavailable after manual zip extract —— Trove problem library

What you will run into

After manually downloading the zip, extracting it to ~/.claude/plugins/local-superpowers, /plugin list shows an exclamation mark (unavailable); copying the repo directory directly also reports missing files. Offline install won't work.

Why this happens

Each harness directory in the tarball (.claude-plugin/.codex-plugin/.cursor-plugin) has plugin.json but no compiled dist/index.js — the local plugin form requires a complete plugin package;

a pure-SKILL repo wired in via the plugin path is missing pieces (CSDN case: missing plugin.json + dist/index.js → unavailable).

The same repo supports two integration forms with completely different loading mechanisms: the skills form is "directory scanning" — the client scans the skills directory at startup, every subdirectory containing a SKILL.md is a skill, pure files suffice, no compiled artifacts needed;

the plugin form is "code loading" — the client reads plugin.json and loads/executes the plugin code in dist/index.js; this is runtime code, and without it the plugin fails to load (exclamation mark).

The problem is "wiring a skills-form repo through the plugin form": the tarball's harness dirs carry plugin.json (declaring themselves plugins) but no compiled artifacts (the author only publishes the skills form), so the two sides don't match and you get missing-file errors.

That also gives the decision path: decide which form you want first, then wire in per that form's complete requirements — want skills? copy the skills/ dir (recommended; measured 14/14); insist on the plugin form?

go through the marketplace flow to get the complete package (with dist/).

Step by step

1. Use as skills (recommended) — Required

cp -r <repo>/skills ~/.claude/skills/superpowers

Enable in a new session; or fetch via the npx superpowers-zh method.

2. Use as a local plugin — Required

/plugin marketplace add <local-path>/.claude/plugins/superpowers/superpowers-main

Then /plugin install superpowers@superpowers-dev → /reload-plugins.

3. Codex CLI form (measured path here) — Required

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

No compiled artifacts needed; pure file form.

How to confirm it works

Skill directory structure and validity (measured shape):

ls ~/.codex/skills/superpowers
→ 14 skill dirs / 14 SKILL.md / frontmatter 14/14 valid 

/plugin list no longer shows the exclamation mark (local-plugin form), or /find-skills shows the skills (skills form).

Other environments

Symptom

After manually downloading and extracting the zip into ~/.claude/plugins/local-superpowers, /plugin list shows an exclamation mark (unavailable); copying the repo directory directly also reports missing files.

Cause

The harness dirs in the tarball (.claude-plugin/.codex-plugin/.cursor-plugin) carry plugin.json but no compiled dist/index.js — the local plugin form requires a complete plugin package; wiring a pure SKILL repo through the plugin path misses files.

Solution

1. Use it as skills (recommended): copy all skill dirs under skills/ into a skills dir Claude can read, enable in a new session; or pull via npx superpowers-zh.
2. As a local plugin: /plugin marketplace add <local path>/.claude/plugins/superpowers/superpowers-main -> /plugin install superpowers@superpowers-dev -> /reload-plugins.
3. Codex CLI form (this marketplace's verified path): download the tarball -> cp -r skills ~/.codex/skills/superpowers, no compiled artifacts needed.