# Npm Safety

> >

- **Type:** Skill
- **Install:** `agentstack add skill-lifedever-skills-plugin-npm-safety`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lifedever](https://agentstack.voostack.com/s/lifedever)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lifedever](https://github.com/lifedever)
- **Source:** https://github.com/lifedever/skills-plugin/tree/main/skills/npm-safety

## Install

```sh
agentstack add skill-lifedever-skills-plugin-npm-safety
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# npm-safety

Vet npm-ecosystem packages with [socket.dev](https://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
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:

```bash
socket package score npm  --markdown
```

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

```bash
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:

```bash
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](https://github.com/lifedever)
- **Source:** [lifedever/skills-plugin](https://github.com/lifedever/skills-plugin)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lifedever-skills-plugin-npm-safety
- Seller: https://agentstack.voostack.com/s/lifedever
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.