npm-safety
Skill14 starsChanged 6 months agoMITView on GitHub
Vet npm / yarn / pnpm packages with socket.dev before they enter the project, and audit an existing project's full dependency tree. Auto-detects the project's package manager (npm / yarn / pnpm) and uses it for the actual install — the safety check is the wrapper, not the installer. Use when the user wants to add a dependency ("install lodash", "add vue-router", "pnpm add zod", "yarn add axios"), audit existing deps ("is my project safe", "scan dependencies", "扫一下依赖", "检查依赖安全"), or check a single package ("is X safe to install", "X 这个包有问题吗", "vet this package"). Especially relevant when the package is unfamiliar, from a new author, or recently published.
- Installs packages
In this repository14 other files it gives its agents.
- app-icon-generatorSkill
- break-itSkill
- debug-modeSkill
- dev-launcherSkill
- diagram-proSkill
- image-uploadSkill
- localizeSkill
- mac-app-uninstallSkill
- mac-cleanup-diskSkill
- mac-cleanup-memorySkill
- mac-cleanup-processSkill
- macos-app-scaffoldSkill
- root-causeSkill
- skill-scanSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 37
Run the preflight script from the project root the user is working in:
- Distinctive: line 50
If preflight exits non-zero, stop and show the user the stderr message verbatim.
- Very specific: line 101
Use the package_manager value from preflight.
- Distinctive: line 113
If this is the first time vetting this project, suggest one full project scan to baseline:
- Distinctive: line 123
When the user says "audit my deps" / "扫一下依赖" / "is my project safe":
- Distinctive: line 125
Run preflight to confirm tooling
- Very specific: line 128
If the user wants to fix vulns and the project is npm: offer socket fix.
- Very specific: line 152
Not a Node project (no package.json) → preflight exits 3 — don't attempt to install
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 <a> <b> ... (batch) or socket package score npm <a> (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 <X> --markdown |
| User asks to fix CVEs | socket fix (npm projects only — see 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" "<project-dir>"The script:
- Confirms
socketCLI 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 frompackageManagerfield inpackage.jsonas fallback - Prints key=value pairs on stdout — parse
package_managerandlockfile
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 <package-name> --markdownFor multiple packages in one shot (cheaper, but shallow — own package only):
socket package shallow npm <pkg-a> <pkg-b> <pkg-c> --markdownPin a specific version when the user requested one: <name>@<version>. The CLI accepts purl syntax too (pkg:npm/<name>@<version>).
Step 3 — Read the signals
Socket reports six sub-scores out of 100 plus capabilities and alerts. What matters at install time:
- Overall score < 50 — strongly worth flagging. Treat as a hard stop unless the user has a specific reason.
vulnerability< 100 — a known CVE exists. Surface the alert.supplyChain< 70 — recently changed maintainer, install scripts, obfuscated code, or telemetry. The most common cause of modern npm investigations.- Capabilities containing
shell,network,filesystem,env,eval— the package can run shell commands / make network calls / read files / read env vars / useeval. Not automatically bad (eslint legitimately reads files), but worth telling the user. - Alerts with severity
criticalorhigh— surface every one.
Lower-severity signals (middle, low) like usesEval on lodash are common and rarely actionable; mention them only if asked.
Step 4 — Decision point
Summarize the findings to the user in this shape:
<package>@<version>: overall <N>/100
- vulnerability: <N> supplyChain: <N> quality: <N>
- capabilities: <list>
- alerts (critical/high only): <list, or "none">Then decide whether to ask the user before installing. Use AskUserQuestion if any of:
- Overall score < 70
- Any critical / high severity alert
- Any of these capabilities present:
shell,eval(network / filesystem alone don't trigger — most legit libs have them)
Otherwise proceed with the install and just include the score line in your summary. The goal is to interrupt only when there's a real signal — most small utility packages score 70-79 due to maintenance penalties even when they're fine, and prompting on every one of them makes the skill annoying instead of useful.
Step 5 — Install with the project's package manager
Use the package_manager value from preflight. Never substitute one PM for another.
| PM | Add command |
npm | npm install <name> (or npm install -D <name> for dev) |
yarn | yarn add <name> (or yarn add -D <name>) |
pnpm | pnpm add <name> (or pnpm add -D <name>) |
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:
socket scan createThis 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":
- Run preflight to confirm tooling
- From project root:
socket scan create - Surface the report URL the CLI prints; summarize critical/high alerts if any
- If the user wants to fix vulns and the project is npm: offer
socket fix. For yarn/pnpm, see Caveats.
Workflow: standalone package check
User asks "is package X safe?" without intent to install:
socket package score npm <X> --markdownReport 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 installwrapper only supports npm. There's nosocket yarn/socket pnpminstall wrapper. The strategy in this skill — query first viasocket 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 fixmutates npm projects only. Running it in a pnpm/yarn project may add apackage-lock.jsonor otherwise confuse the lockfile state. For non-npm projects, surface the alerts fromsocket scan createand 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 scorecosts 100 units per call (deep scan);socket package shallowcosts 100 per call but takes a batch. Prefershallowwhen checking many packages at once. socket loginis interactive only. It cannot run inside the Claude Code Bash tool (non-TTY). If the preflight fails on auth, point the user at theSOCKET_CLI_API_TOKENenv var path or have them runsocket loginthemselves in their terminal with the!prompt prefix.
Failure modes
socketnot 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

