npm-bump-packages
A Claude Code Agent Skill that upgrades a project's npm dependencies the boring, recoverable way — minor/patch bumps first, then major bumps one major version at a time, each staged as a reviewable git patch and validated against the project's own lint/test/build commands before the next one lands.
Updating everything at once is dangerous: if thirty packages move and the build breaks, you have no idea which one did it. This skill separates planning from execution so that a bad bump is always attributable to a single change and trivially reverted.
Installation
skills CLI
Vercel's skills CLI pulls the skill straight from the repo into your project's .claude/skills/:
npx skills add ladamczyk-it/qoq --skill npm-bump-packages
Add --global to install it to your user directory instead, or --agent claude-code to target Claude Code explicitly.
agent-skills-cli
agent-skills-cli is a universal installer that targets Claude Code and many other agents. Both CLIs expose a skills binary, so invoke this one through its agent-skills bin to avoid the name clash:
npx -p agent-skills-cli agent-skills add ladamczyk-it/qoq@npm-bump-packages -a claude
Add -g to install globally to ~/.claude/skills/.
Claude Code plugin marketplace
The skill ships in the qoq-agent-skills plugin marketplace. Add the marketplace and install the packages-skills plugin from within Claude Code:
/plugin marketplace add ladamczyk-it/qoq
/plugin install packages-skills@qoq-agent-skills
Once installed, Claude loads the skill automatically — no further setup. The /plugin menu lists it under packages-skills, where you can enable or disable it per project.
When it triggers
Claude reaches for this skill whenever you want to update, upgrade, or bump dependencies — including phrasings like "get on the latest versions", "my deps are stale", "modernize the project", or a mention of npm outdated. You don't have to say the word "safely".
How it works
The workflow is a plan-then-execute flow built around two failure modes — silent breakage (a bump that compiles but changes behavior) and unattributable breakage (applying many changes together). The antidotes are running the project's real validation after every step, and applying one patch at a time.
| Phase | What happens |
|---|---|
| 0 · Safety net | Confirm a clean tree, discover the lint/test/build commands, install, and verify the baseline is already green. |
| 1 · Discovery | Run npm outdated --json, split findings into minor/patch vs. major, and confirm scope with you. |
| 2 · Plan safe bumps | Stage minor/patch upgrades as safe_dev.patch and safe.patch, editing only version ranges. |
| 3 · Plan major bumps | One major step at a time, with changelog research and the minimal code edits each breaking change requires. |
| 4 · Present the plan | Summarize every patch and code change for sign-off before anything is applied. |
| 5 · Execution | Apply patches sequentially — npm i and validate after each, stopping the moment something goes red. |
| 6 · Clean up | On a fully green run, remove the .npm-bump/ scratch directory and offer to commit. |
Every change is staged in a .npm-bump/ scratch directory as a git patch — generated without dirtying the tree (edit → git diff > patch → git checkout --) — so the working tree stays clean until you approve execution.
QoQ integration
The skill is QoQ-aware. During Phase 0 it profiles the toolchain to build a fast validation menu, so each patch can be checked with the smallest trustworthy command instead of the whole suite:
- Selective execution —
qoq eslint --checklints without touching Prettier, JSCPD, or Knip, so a patch whose blast radius is a single ESLint plugin is validated by that tool alone. - Structured output —
qoq --check --json --output <dir>writes each tool's result as JSON, which is cheaper and more reliable to parse than scraping console text.
When a patch's blast radius is wide or unclear — a runtime dependency, a TypeScript- or Node-level change — the skill falls back to the full validation suite. A final full pass runs as a backstop once the last patch lands.
Allowed tools
The skill is sandboxed to the commands it actually needs:
Bash(npm outdated *)
Bash(npm run:*)
Bash(npm i *)
Bash(mkdir -p .npm-bump)
Bash(git checkout:*)
Bash(git apply *)
Coupled packages
Some packages must move together or installs break — peer-coupled sets (react + react-dom, @typescript-eslint/parser + @typescript-eslint/eslint-plugin) and same-namespace releases (all @ladamczyk/qoq-* to one version). The skill keeps these in a single patch rather than splitting them, and treats an npm i peer warning as a signal it split a coupled set.