npm-upgrade
Skill25 starsChanged 9 months agoMITView on GitHub
Guides Node.js project upgrades using npm, yarn, or pnpm. Use when helping users upgrade npm packages, check for security vulnerabilities with `npm audit`, prioritize which packages to upgrade first, understand dependency conflicts, interpret `npm outdated` output, use `npm explain` to trace who requires a package, plan safe upgrade paths, resolve package version conflicts in package.json, or resolve merge conflicts in package-lock.json / yarn.lock / pnpm-lock.yaml. Trigger this skill whenever the user mentions npm packages, Node.js dependencies, outdated packages, CVEs in JavaScript or TypeScript projects, yarn or pnpm upgrades, or security advisories in package.json.
- Installs packages
1 other project uses a version of this.
Adopted by
Most recently taken up by
- mono0926/skillstheir own version, first seen Mar 10, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- mono0926/skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- composer-upgradeSkill
- gritqlSkill
- laravel-advanced-conceptsSkill
- packagistSkill
- phpstan-developerSkill
- php-type-safetySkill
- rector-developerSkill
- remotion-3d-background-developerSkill
- serpapiSkill
- slidewire-developerSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
When you have enough information to recommend a path, recommend it confidently.
- Distinctive: line 18
Check which lock file exists before running commands:
- Very specific: line 26
All examples below use npm.
- Very specific: line 30
Follow this sequence when upgrading a Node.js project:
- Very specific: line 48
Never edit conflict markers in package-lock.json by hand, and avoid blunt rm package-lock.json && npm install — that throws away both …
- Distinctive: line 128
Run these first, then give a direct recommendation: update the constraining package, relax your own range, or use an override.
- Distinctive: line 143
Prefer updating direct dependencies one at a time, running tests between each.
- Very specific: line 147
When npm explain reveals the constraint is in your own package.json:
- Very specific: line 159
After a successful major upgrade, tighten package.json ranges to prevent accidental downgrades on fresh installs:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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 Upgrade
Approach
Stay focused on commands and their output. Your job is to run the right diagnostic commands, interpret what they show, and give a clear upgrade sequence.
Do not describe API changes, new syntax, migration steps, or breaking change details for specific packages — no createRoot examples, no flat config explanations, no import path changes. That belongs in the package's own migration guide, not here. Stop at "upgrade this package" and let the user read the relevant docs if they need to migrate code.
When you have enough information to recommend a path, recommend it confidently. Don't hedge with a list of options unless the situation genuinely requires a decision from the user.
Detecting the Package Manager
Check which lock file exists before running commands:
| Lock file | Package manager |
package-lock.json | npm |
yarn.lock | yarn |
pnpm-lock.yaml | pnpm |
All examples below use npm. See references/commands.md for yarn and pnpm equivalents.
Upgrade Workflow
Follow this sequence when upgrading a Node.js project:
- Check for security issues →
npm audit— fixes here are highest priority - Try auto-fix →
npm audit fix— resolves compatible vulnerabilities automatically - Identify what's outdated →
npm outdated - Prioritize — packages with CVEs AND outdated go first; see references/audit.md
- Trace dependencies →
npm explain <package>— who requires it and why - Update packages →
npm update <package>ornpm install <package>@latest - Test
- Tighten constraints → update
package.jsonranges if needed (applications only) - Re-audit →
npm auditto confirm all advisories are resolved
See references/commands.md for full flag reference. See references/upgrade-workflow.md for detailed strategies, including merge conflict resolution. See references/audit.md for security audit details, severity tiers, and how to build a prioritized fix list.
Resolving package-lock.json Merge Conflicts
Never edit conflict markers in package-lock.json by hand, and avoid blunt rm package-lock.json && npm install — that throws away both sides' changes indiscriminately. Instead, use diff_lock.py to generate precise npm commands that apply exactly what the other branch changed.
Preferred approach — apply the other side's changes with npm commands:
# 1. Accept one side's package.json as the base (usually your branch)
git checkout --ours package.json
# 2. See what the other branch changed in the lock file
python3 scripts/diff_lock.py --conflict --format=summary
# 3. Get the exact npm commands to apply those changes
python3 scripts/diff_lock.py --conflict
# 4. Run the generated commands (e.g.)
npm install axios@1.7.7
npm install zod@3.23.8
npm uninstall some-removed-package
# 5. Commit
git add package-lock.json package.json
git commitThe --conflict flag reads both sides of the lock file directly from git — no need to extract markers manually. The default output (without --format=summary) produces ready-to-run npm install/uninstall commands for every change.
See references/upgrade-workflow.md — "Workflow: Merge Conflict in package-lock.json" — for the full step-by-step process.
Core Commands
See references/commands.md for the full flag reference.
npm outdated
npm outdated # tabular view
npm outdated --json # JSON output for parsing (fewer tokens)Three version columns: Current (installed), Wanted (latest satisfying package.json range), Latest (latest on the registry). A gap between Wanted and Latest means a major bump is available.
npm explain / npm ls
npm explain <package> # who in the tree requires this package
npm explain <package>@1.2.3 # who requires a specific version
npm ls <package> # show installed versions in the dependency treenpm update / npm install
npm update <package> # update to latest satisfying package.json range
npm install <package>@latest # install latest (rewrites package.json entry)
npm install <package>@^2.0.0 # install a specific range
npm install <package>@latest --save-exact # pin to exact version in package.jsonnpm audit
npm audit # show all vulnerabilities
npm audit fix # auto-fix compatible vulnerabilities
npm audit fix --force # also fix via breaking-change upgrades (test carefully)
npm audit --json # JSON output for scriptingCommon Patterns
"Why can't I update X?"
# See who requires the package and what version they constrain it to
npm explain <package>
npm ls <package>
# Check what versions exist on the registry
npm view <package> versions --jsonRun these first, then give a direct recommendation: update the constraining package, relax your own range, or use an override. Pick the right path based on what the output shows — don't list all three as equal options.
"Safe incremental upgrade"
# See what would change (no install)
npm outdated
# Patch and minor: update within existing package.json constraints
npm update <package>
# Major: install explicitly, which also rewrites package.json
npm install <package>@latestPrefer updating direct dependencies one at a time, running tests between each. For major version bumps, recommend doing each on its own branch with its own commit — this makes it easy to isolate breakage and revert if needed.
Relaxing constraints in package.json
When npm explain reveals the constraint is in your own package.json:
"dependencies": {
"some-package": "^3.0.0"
}Edit package.json then run npm install to resolve and update the lock file.
Pinning constraints after upgrading (applications)
After a successful major upgrade, tighten package.json ranges to prevent accidental downgrades on fresh installs:
# Pin to exact installed version
npm install <package>@latest --save-exact
# Review all direct dep versions before deciding what to pin
npm ls --depth=0Applications only: exact pins (
1.2.3without^) in a library'spackage.jsoncreate conflicts for downstream consumers. Libraries should use ranges.
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.

