Review npm dependencies for supply-chain risk with an audit SKILL.md
Cursor or Claude Code applies a SKILL.md to dependency PRs: new maintainers, suspicious postinstall scripts, lockfile-only changes without version bumps, typosquat package names, and a merge gate checklist.
An npm-audit skill in the repo, severity-tagged findings on every dependency PR, and a reviewed checklist before new transitive dependencies reach production builds.
- 1
Test on a Dependabot PR first
Run the skill on a real bot-generated update. The agent should verify all changes are expected transitive updates, not surprise additions.
- 2
Maintain an install-script allow-list
Some legitimate packages (e.g., Puppeteer, node-gyp deps) need postinstall. Commit the list beside the skill so reviewers know what is pre-approved.
- 3
Require the checklist in branch protection
Add a dependency review checklist to PR template for package.json or lockfile changes. The skill is worthless if humans merge without reading findings.
The prompt to paste
Write SKILL.md for reviewing npm (or pnpm/yarn) dependency changes for supply-chain risk before merge. The agent flags suspicious patterns, not routine updates.
Repository context:
[package manager: npm, pnpm, yarn — affects lockfile name]
[lockfile path: package-lock.json, pnpm-lock.yaml, yarn.lock]
[dependency policy: allowed registries, internal scoped packages, whether lockfile-only PRs need review]
[how to inspect packages: npm view, pnpm why, or registry API links to npmjs.com]
Dependency PR context (paste when using):
[PR title, changed files: package.json and/or lockfile, added/updated package names]
SKILL.md must include:
1. Purpose — catch malicious or risky dependencies before they run postinstall scripts or ship in production bundles.
2. When to use — any PR adding or updating dependencies, especially lockfile-only changes from bots, major version bumps, or new transitive deps. When not to use — docs-only, .nvmrc, or README changes without package.json/lockfile diffs.
3. Severity rubric the agent must use in findings:
- Block: new dependency with postinstall/preinstall script not in allow-list, typosquat name resembling popular package (edit distance ≤ 2), package published < 7 days ago with < 100 weekly downloads, maintainer account created same week as package publish, lockfile adds dependency not in package.json with no explanation.
- Warn: major version bump (breaking changes, review changelog), new maintainer added in latest version, package repo archived or deleted, transitive dep count spike (e.g. +20 packages), no repository field or broken repo link, dependency last published > 2 years ago (unmaintained).
- Note: minor/patch bumps, lockfile integrity hash changes, npm audit advisories that are not exploitable in this app context.
4. Required inputs: package.json diff, lockfile diff, PR description (especially for bot PRs like Dependabot/Renovate).
5. Review steps:
- Parse lockfile diff for added/updated packages (direct + transitive).
- For each new package:
a. Check npm registry: publish date, weekly downloads, maintainers, repository link.
b. Compare name against top 5000 npm packages for typosquat (Levenshtein distance).
c. Read package.json from tarball or registry API: look for install scripts (postinstall, preinstall, install).
d. Check maintainer accounts: creation date, other packages published (single-package new accounts are suspicious).
- For updated packages: note major vs minor/patch, check changelog link if available, flag if maintainer list changed.
- For lockfile-only changes: verify all changes are transitive updates from a declared dep update or resolution fix; flag orphan additions.
- Run npm audit (or pnpm audit) and cross-check with existing advisories; list only High/Critical not already in main.
- List findings as: [Block|Warn|Note] package@version — issue — evidence (one line).
6. PR comment template: Summary counts by severity, Findings table with package + evidence links (npmjs.com, repo, advisory), Merge recommendation (block / approve with warns / approve).
7. Two example prompts: Dependabot PR bumping minor versions vs manually adding a new utility package.
8. Pitfalls: approving postinstall scripts without reading the script source, missing transitive typosquats because you only checked direct deps, ignoring new maintainers on popular packages, allowing lockfile drift with "looks fine" because tests pass, skipping registry checks on scoped internal packages (still verify the scope matches your org).
9. Done means: every Block resolved (remove package or add to allow-list with justification), Warns reviewed and accepted with note in PR, lockfile integrity verified, npm audit run and new High/Critical issues addressed or documented as false positives.
Rules:
- Never run npm install or execute install scripts in the agent session — inspect static files and registry API only.
- Do not claim a package is safe solely because it has many downloads — popularity is not a security audit.
- Output only SKILL.md markdown.Lockfile-only PRs can add packages without touching package.json if a transitive dep updates. The skill must explain every new package, not just direct dependencies.
Sample case written by Hidden Logic Lab. Not affiliated with Cursor or Claude Code.
More in Coding
Get new cases in your inbox
Weekly notes on new use cases and agent workflows. No product pitches.