agentleFS
Sign inStart free
KhaledSaeed18KhaledSaeed18/dotclaude/skills/engineering/dependency-upgrade/SKILL.md

dependency-upgrade

Skill5 starsChanged 4 months agoMITView on GitHub

Upgrade dependencies without breaking the project: audit what is outdated and why it matters (security, EOL, features), read the changelogs and migration guides for each major, upgrade in ordered small batches with the test suite and typecheck run after each, apply codemods where they exist, handle lockfile and peer-dependency conflicts, and leave a record of what changed and what was deferred. Use when a security advisory lands, when a runtime or framework reaches end of life, when a dependabot queue has piled up, or when an upgrade attempt broke the build.

  • Installs packages

We split this skill into the rules it gives an agent

9 rules. 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write the plan as a table before touching anything.

    line 15
  2. Distinctive:

    Read, for each major: the release notes for every skipped major, the migration guide, the codemods offered, and the peer dependency changes.

    line 21
  3. Very specific:

    Update them together (pnpm update within ranges, pip install -U for the batch), run the gate, commit as one change.

    line 25
  4. Very specific:

    Run codemods if the project offers them (npx @next/codemod, npx react-codemod, django-upgrade, pyupgrade, cargo fix --edition).

    line 32
  5. Distinctive:

    Run the tests; fix behaviour changes the guide predicted.

    line 35
  6. Distinctive:

    Run the app or the smoke path once by hand where tests are thin.

    line 36
  7. Distinctive:

    Commit with the version range and the changes made in the body.

    line 37
  8. Distinctive:

    Never upgrade and refactor in the same commit.

    line 55
  9. Distinctive:

    Never silence a type error or a deprecation warning to make an upgrade pass.

    line 56

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Upgrades fail when they are done all at once and diagnosed all at once. The discipline is: know what changed, change one thing, run the tests, commit, repeat. A day of small green steps beats a week of bisecting a red branch.

Step 1: inventory

  • npm outdated / pnpm outdated / pip list --outdated / cargo outdated / go list -m -u all, plus the audit: npm audit, pip-audit, cargo audit, govulncheck.
  • For each candidate: current, latest, is it a major bump, does an advisory apply, is the current version EOL, does it block another upgrade (e.g. the test runner must move before the framework can).
  • Classify: security (do first, minimal version that fixes), blocking (needed for another upgrade), major (needs reading), minor/patch (batchable).

Write the plan as a table before touching anything; get agreement if the list is long or a major touches the framework.

Step 2: prepare

  • Green baseline: full test suite, typecheck, lint, and build pass on the current commit; record timings.
  • A branch per major upgrade; one branch for the minor/patch batch.
  • Read, for each major: the release notes for every skipped major, the migration guide, the codemods offered, and the peer dependency changes. Note breaking changes that touch this codebase (grep for the removed APIs).

Step 3: minor and patch batch

Update them together (pnpm update within ranges, pip install -U for the batch), run the gate, commit as one change. If it goes red, bisect the batch by halving.

Step 4: majors, one at a time

For each, in dependency order (tooling first: TypeScript, test runner, bundler; then libraries; then the framework):

  1. Bump the one package (and its peers that must move with it).
  2. Run codemods if the project offers them (npx @next/codemod, npx react-codemod, django-upgrade, pyupgrade, cargo fix --edition).
  3. Typecheck first: it lists the removed and changed APIs faster than tests do.
  4. Fix compile errors by following the migration guide, not by casting or suppressing.
  5. Run the tests; fix behaviour changes the guide predicted; investigate any it did not.
  6. Run the app or the smoke path once by hand where tests are thin.
  7. Commit with the version range and the changes made in the body.

Lockfile conflicts: regenerate from the manifest (pnpm install --no-frozen-lockfile on the branch, then commit) rather than hand-merging. Peer warnings: satisfy them or pin with a documented override (pnpm.overrides, resolutions), with a comment naming the reason and the removal condition.

Step 5: runtime and language upgrades

Node, Python, Java, Go versions: update the engine field, .nvmrc/.tool-versions/pyproject requires-python, the Dockerfile base, and CI matrices together; run the full suite on the new version; check native modules and C extensions rebuild. Keep the old version in the CI matrix for one release when consumers may lag.

Step 6: record

In the PR body or docs/upgrades/<date>.md: the table from step 1 with the outcome per row (upgraded to X, deferred because Y, blocked by Z), the codemods run, the behaviour changes noticed, and the overrides added with their removal condition. Deferred items become issues.

Automation afterwards

Dependabot or Renovate with grouped minor/patch updates weekly, majors as separate PRs, security updates immediately, and the lockfile maintained. A queue that is merged weekly never becomes a migration project.

Rules

  • Never upgrade and refactor in the same commit.
  • Never silence a type error or a deprecation warning to make an upgrade pass; the warning is the migration guide pointing at the line.
  • A failed major upgrade is reverted cleanly (git revert or drop the branch), the blocker written down, and the rest of the plan continues.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free