Safe Dependency Upgrader
Upgrade dependencies with changelogs read, breakages found, and rollbacks ready.
An agent skill for dependency upgrades that goes beyond 'bump and pray': read the changelog between versions, grep the codebase for every documented breaking change, upgrade in risk order, and verify with the affected tests — one dependency per commit for clean rollbacks.
SKILL.md
--- name: dependency-upgrade description: Process for upgrading dependencies. Use when updating package versions or resolving security advisories. --- # Safe Dependency Upgrader ## Per-dependency process 1. **Read before bumping** — fetch the changelog/release notes between current and target version; list breaking changes and deprecations relevant to us 2. **Grep for impact** — search the codebase for every API the changelog says changed; list affected files 3. **Upgrade** — one dependency (or one tightly-coupled group like @babel/*) per commit 4. **Verify** — run the test suites covering the affected files, plus typecheck and build; for UI deps, load the affected screens 5. **Commit message** — include: old → new version, breaking changes handled, anything deferred ## Risk ordering (batch upgrades) Process in this order so failures bisect cleanly: 1. Patch bumps of dev-only tooling (lowest risk) 2. Patch/minor of runtime deps 3. Majors of runtime deps — each gets its own PR with the impact list ## Hard rules - Security advisories: check whether we're actually exposed (is the vulnerable path reachable?) — fix the exposed ones FIRST, and say so - Never upgrade a lockfile without its manifest, or vice versa - If the changelog is missing/unreadable, diff the package's types or source between versions — absence of a changelog is not absence of breaking changes - A test failure after upgrade is a finding to report, never a test to delete or skip - Peer-dependency warnings get resolved or explicitly documented, not silenced
How to use
- 1Save as .claude/skills/dependency-upgrade/SKILL.md.
- 2Point the agent at your dependabot/renovate queue and let it process in the skill's risk order.
- 3The 'actually exposed' rule for security advisories kills most of the alert-fatigue noise honestly.
Examples
Handling a major version bump
Input
Asked to upgrade axios 0.27 → 1.6.
Output
Changelog review: 1.0 changed default JSON serialization of params and removed `axios.Cancel`... Grep: 3 files use CancelToken (src/api/*.ts). Migrated to AbortController per migration guide, tests for api/ pass (41), typecheck clean. Committed separately from the 6 patch bumps.
Pro tips
- Run this monthly rather than letting upgrades pile into a scary quarterly big-bang.
Frequently asked questions
Is one-dependency-per-commit overkill for 30 patch bumps?+
The skill's risk ordering allows batching genuinely low-risk patch bumps of dev tooling into one commit. The rule protects runtime majors, where bisecting a broken batch costs hours.