Npm Safety

npm-safety

Vet npm-ecosystem packages with socket.dev before they enter the project. The skill is the orchestrator: it runs the safety checks, surfaces capability / supply-chain signals, and only then runs the project's own package manager for the actual install.

The skill is package-manager-aware. It detects whether the project uses npm, yarn, or pnpm from the lockfile and uses that one — it does not force npm install.

When to use which command

| Situation | Command | |---|---| | User asks to add 1+ packages | socket package shallow npm ... (batch) or socket package score npm (deep, single) | | User asks for project-wide audit | socket scan create in the project root | | User asks "is package X safe?" without intent to install yet | socket package score npm --markdown | | User asks to fix CVEs | socket fix (npm projects only — see [Caveats](#caveats)) |

Workflow: pre-install vetting

This is the most common path. Follow it whenever the user asks to add a new dependency, regardless of the package manager they mention.

Step 1 — Preflight

Run the preflight script from the project root the user is working in:

bash "${CLAUDE_SKILL_DIR}/scripts/preflight.sh" ""

The script:

• Confirms socket CLI is installed (exit 2 with install hint if not)
• Confirms an API token is configured (exit 2 with setup hint if not)
• Detects package manager from lockfile (pnpm-lock.yaml > yarn.lock > package-lock.json), or from packageManager field in package.json as fallback
• Prints key=value pairs on stdout — parse package_manager and lockfile

If preflight exits non-zero, stop and show the user the stderr message verbatim. Do not attempt to install anything until they fix the prerequisite.

Step 2 — Query Socket for risk signals

For a single package, use socket package score — it includes transitive dependency scores, which matters because most supply-chain risk lives in transitives:

socket package score npm  --markdown

For multiple packages in one shot (cheaper, but shallow — own package only):

socket package shallow npm    --markdown

Pin a specific version when the user requested one: @. The CLI accepts purl syntax too (pkg:npm/@).

Step 3 — Read the signals

Socket reports six sub-scores out of 100 plus capabilities and alerts. What matters at install time:

• **Overall score @: overall /100
• vulnerability: supplyChain: quality:
• capabilities:
• alerts (critical/high only):

Then decide whether to ask the user before installing. Use `AskUserQuestion` if **any** of:

- Overall score ` (or `npm install -D ` for dev) |
| `yarn` | `yarn add ` (or `yarn add -D `) |
| `pnpm` | `pnpm add ` (or `pnpm add -D `) |

Preserve flags the user already gave (`-D`, `--save-exact`, version pin, workspace targeting like `pnpm add -F app-web`). Don't translate user intent across PMs — if they typed `pnpm add` but the lockfile is yarn, tell them about the mismatch instead of silently using yarn.

### Step 6 — Post-install audit (optional, only if user is onboarding a new project)

If this is the first time vetting this project, suggest one full project scan to baseline:

```bash
socket scan create

This uploads the manifest + lockfile to Socket and produces a report covering the whole dep tree. Don't run this every install — too noisy.

Workflow: project-wide audit

When the user says "audit my deps" / "扫一下依赖" / "is my project safe":

1. Run preflight to confirm tooling
2. From project root: socket scan create
3. Surface the report URL the CLI prints; summarize critical/high alerts if any
4. If the user wants to fix vulns and the project is npm: offer socket fix. For yarn/pnpm, see [Caveats](#caveats).

Workflow: standalone package check

User asks "is package X safe?" without intent to install:

socket package score npm  --markdown

Report the score + top alerts. Don't run preflight (no project context needed) — but if socket itself is missing, the command will fail with a clear error.

Caveats

• socket npm install wrapper only supports npm. There's no socket yarn / socket pnpm install wrapper. The strategy in this skill — query first via socket package score, then install via the project's actual PM — works for all three because the scoring API is package-manager-agnostic (it talks about packages in the npm registry, not how you install them).
• socket fix mutates npm projects only. Running it in a pnpm/yarn project may add a package-lock.json or otherwise confuse the lockfile state. For non-npm projects, surface the alerts from socket scan create and let the user decide on a per-vuln basis (upgrade, override, or accept).
• Private registries (corporate npm mirrors, internal packages): Socket has no data for these and will return "package not found". Treat as unknown rather than safe. Tell the user the package wasn't in Socket's database and ask whether to proceed.
• Quota costs. socket package score costs 100 units per call (deep scan); socket package shallow costs 100 per call but takes a batch. Prefer shallow when checking many packages at once.
• socket login is interactive only. It cannot run inside the Claude Code Bash tool (non-TTY). If the preflight fails on auth, point the user at the SOCKET_CLI_API_TOKEN env var path or have them run socket login themselves in their terminal with the ! prompt prefix.

Failure modes

• socket not in PATH → preflight exits 2 with install hint
• token not configured → preflight exits 2 with setup hint
• Not a Node project (no package.json) → preflight exits 3 — don't attempt to install
• Socket API rate-limit or transient failure → retry once, then tell the user and skip the safety check rather than blocking their install (with an explicit note that the check was skipped)
• Package not found in Socket → could be private/internal, very new, or removed. Treat as unknown; ask the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lifedever
• Source: lifedever/skills-plugin
• License: MIT

Install and usage instructions live in the source repository linked above.