Problem: Install troubleshooting: Node version / pnpm / npm cache —— Trove problem library

What you will run into

The skills CLI or the install process reports an unsupported Node version, pnpm-related errors, or an npx download that hangs/fails. Installing one skill package and the prerequisite environment blocks you three times.

Why this happens

npx is a "download-then-execute" chain: fetch the package from a registry (network layer) -> check the engines-declared Node version after unpacking (runtime layer) -> run the CLI (execution layer).

Any broken layer looks like "install failed", but each layer fails at a different spot: a Node-version error comes from the engines check, so the network is fine and the runtime is the problem;

a stuck/timed-out download is a fetch-layer issue, usually the official registry on a direct CN connection; pnpm/cache errors happen while unpacking or writing the cache, meaning the package downloaded but the local state is corrupted.

That is why the diagnostic order is fixed: node --version first (rule out the runtime), then a per-command registry switch via env var (only affects the current command, no global pollution), and only then cache cleanup — reversed order makes you keep hitting the same wall (e.g.

ten cache cleans won't help when the network is down).

Step by step

1. Confirm the Node version — Required

node --version

If < 18, upgrade with nvm to 18+.

2. Switch the registry to a CN mirror — Required

npm_config_registry=https://registry.npmmirror.com npx -y skills ...

The env-var form only applies to the current command and does not pollute global config.

3. Clear the cache and retry — Required

npm cache clean --force

Or retry with an isolated HOME (measured in this marketplace with /tmp/agsk-home).

How to confirm it works

The npx download and CLI execution work (measured shape):

npm_config_registry=https://registry.npmmirror.com npx -y skills ...
→ CLI downloads and executes normally, install flow reaches the clone/copy stage

node --version outputs >= 18 (v22.22.1 measured working).

Other environments

Symptom

The skills CLI or install process reports an unsupported Node version, pnpm-related errors, or an npx download that hangs/fails.

Cause

The CLI requires Node >= 18 (v22.22.1 measured working in this environment); the npm official registry is unstable on direct CN connections; corrupted cache / permission issues interrupt the npx download.

Solution

1. Confirm the version: node --version (upgrade with nvm if < 18).
2. Switch the registry to a CN mirror: npm_config_registry=https://registry.npmmirror.com npx -y skills ... (measured: npmmirror PONG 0.32s in this environment).
3. Clear the cache and retry: npm cache clean --force or use an isolated HOME.