npm-check-updates skill

A reusable agent skill that turns npm-check-updates (ncu) into a safe dependency-upgrade workflow. Works with npm, pnpm, yarn, and bun projects, monorepos included, and with any agent that reads SKILL.md — Claude Code, Codex, GitHub Copilot CLI, Gemini CLI, Cursor, and the rest.

Instead of blindly running ncu -u, the skill instructs the agent to:

1. Detect the package manager from the lockfile and use the matching commands throughout.
2. List what's outdated, splitting majors from patch/minor.
3. Categorize each update (patch / minor / major / 0.x — pre-1.0 minors are treated as breaking).
4. Research breaking changes for every major/0.x bump via GitHub releases, the compare view, migration guides, the npm page, and open/recent issues — never from memory.
5. Check whether our code actually uses the changed APIs and verify peer-dependency compatibility (ncu --peer).
6. Upgrade safe-first in batches (majors one at a time, or ncu --doctor -u to auto-isolate breakage), leaving framework-pinned packages (e.g. Expo) to the framework's own updater.
7. Verify with install + build + tests after every batch — with the plain install, never the frozen CI one.
8. Report a per-package verdict (✅ Safe / ⚠️ Needs code change / ⛔ Hold) with the exact code changes required and the build/test result.

It also covers the package-manager gotchas that trip upgrades: pnpm's minimumReleaseAge, blocked build scripts, and catalogs; yarn Berry vs classic; bun's bun.lock; and stale-lockfile failures.

Install

With the skills CLI (recommended)

One command, no clone. Auto-detects your agent and works across Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor, and 20+ others. Use whichever runner matches your package manager:

# Global — available in every project
npx skills add MrErikCodes/npm-check-updates-skill -g        # npm
pnpm dlx skills add MrErikCodes/npm-check-updates-skill -g   # pnpm
yarn dlx skills add MrErikCodes/npm-check-updates-skill -g   # yarn (Berry)
bunx skills add MrErikCodes/npm-check-updates-skill -g       # bun

# Project-scoped — just this repo
npx skills add MrErikCodes/npm-check-updates-skill
pnpm dlx skills add MrErikCodes/npm-check-updates-skill
yarn dlx skills add MrErikCodes/npm-check-updates-skill
bunx skills add MrErikCodes/npm-check-updates-skill

Manage it later with skills list and skills remove npm-check-updates via the same runner.

Manual install — pick your agent's skills directory

Drop SKILL.md into a folder named npm-check-updates inside the agent's skills directory.

Agent	Global (personal) skills directory	Project skills directory
Claude Code	~/.claude/skills/	.claude/skills/
Codex	~/.agents/skills/	.agents/skills/
GitHub Copilot CLI	~/.copilot/skills/ or ~/.agents/skills/	.github/skills/, .claude/skills/, or .agents/skills/
Gemini CLI	~/.gemini/skills/ or ~/.agents/skills/	.gemini/skills/ or .agents/skills/

~/.agents/skills/ is a shared path that Codex, Copilot CLI, and Gemini CLI all read — install there once to cover all three. Claude Code does not read it, so use ~/.claude/skills/ for Claude.

From git (clone & copy) — one-liner

macOS / Linux:

DEST=~/.claude/skills/npm-check-updates       # Claude Code
# DEST=~/.agents/skills/npm-check-updates      # Codex + Copilot CLI + Gemini CLI (shared)
# DEST=~/.copilot/skills/npm-check-updates     # Copilot CLI only
# DEST=~/.gemini/skills/npm-check-updates      # Gemini CLI only
git clone https://github.com/MrErikCodes/npm-check-updates-skill.git /tmp/ncu-skill && mkdir -p "$DEST" && cp /tmp/ncu-skill/SKILL.md "$DEST/" && rm -rf /tmp/ncu-skill

Windows (PowerShell):

$Dest = "$HOME\.claude\skills\npm-check-updates"      # Claude Code
# $Dest = "$HOME\.agents\skills\npm-check-updates"    # Codex + Copilot CLI + Gemini CLI (shared)
# $Dest = "$HOME\.copilot\skills\npm-check-updates"   # Copilot CLI only
# $Dest = "$HOME\.gemini\skills\npm-check-updates"    # Gemini CLI only
git clone https://github.com/MrErikCodes/npm-check-updates-skill.git "$env:TEMP\ncu-skill"; New-Item -ItemType Directory -Force $Dest > $null; Copy-Item "$env:TEMP\ncu-skill\SKILL.md" $Dest; Remove-Item -Recurse -Force "$env:TEMP\ncu-skill"

Download the file only (no clone) — one-liner

macOS / Linux:

DEST=~/.claude/skills/npm-check-updates       # or ~/.agents, ~/.copilot, ~/.gemini
mkdir -p "$DEST" && curl -fsSL https://raw.githubusercontent.com/MrErikCodes/npm-check-updates-skill/main/SKILL.md -o "$DEST/SKILL.md"

Windows (PowerShell):

$Dest = "$HOME\.claude\skills\npm-check-updates"      # or .agents, .copilot, .gemini
New-Item -ItemType Directory -Force $Dest > $null; Invoke-WebRequest https://raw.githubusercontent.com/MrErikCodes/npm-check-updates-skill/main/SKILL.md -OutFile "$Dest\SKILL.md"

Usage

Once installed, every agent auto-selects the skill when your request matches its description — so plain language works everywhere:

"Update our dependencies safely." "What's outdated in this pnpm workspace?" "Bump deps in the backend package, majors one at a time."

To invoke it explicitly:

Agent	Explicit invocation	List installed skills
Claude Code	/npm-check-updates	/skills
Codex	$npm-check-updates (type $ to mention a skill)	/skills
GitHub Copilot CLI	Use the /npm-check-updates skill to …	/skills list
Gemini CLI	auto-activated only (you'll see a confirmation prompt)	/skills

The agent then follows the workflow in SKILL.md: detects your package manager, lists and categorizes updates, researches the majors, applies safe batches, runs your install/build/tests, and reports a per-package verdict. If you don't want it to touch a package (say, framework-pinned Expo modules), just say so — the skill already tells the agent to exclude those by default.

The tool itself

npm install -g npm-check-updates   # enables the `ncu` shorthand

# or run without installing — only the LONG name resolves through a runner:
npx npm-check-updates              # npm
pnpm dlx npm-check-updates         # pnpm
yarn dlx npm-check-updates         # yarn (Berry)
bunx npm-check-updates             # bun

Tell ncu which manager you use with -p npm|pnpm|yarn|bun, and add --workspaces in a monorepo.

Changelog

• 2026-09 — Rewritten to be package-manager neutral: detection step, per-manager command table, and dedicated pnpm / yarn / bun / npm sections (pnpm minimumReleaseAge, blocked build scripts, catalogs; yarn Berry vs classic; bun bun.lock; stale-lockfile pitfalls). Skill body made agent-neutral (no vendor-specific tool names). Added --cooldown, corrected the workspaces flag to --workspaces / -w, added a framework-pinned-packages section and a monorepo worked example. README gains per-agent usage, pnpm dlx / yarn dlx / bunx install variants, and Codex's documented ~/.agents/skills/ path.
• 2026-06 — Initial release with multi-agent install one-liners.