agentleFS
warsabwarsab/ai-skills/skills/upgrade-dependency/SKILL.md

upgrade-dependency

Skill0 starsChanged 3 months agoMITView on GitHub

Upgrade a third-party dependency safely by reading the changelog for breaking changes, finding every affected call site, updating the code, and verifying against a known-good baseline. Use when bumping a package version, applying a security or CVE patch, resolving a Dependabot or Renovate pull request, unpinning a version, or when the user mentions upgrading, updating or bumping a library, package, lockfile or requirements file.

  • Installs packages

4 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. ModelEngine-Group/fit-framework★ 2.1ksame name
    2. fitlab-ai/agent-infra★ 88same name
    3. malinskibeniamin/skills★ 4same name
    4. awcameron/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 repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the baseline is red, stop and say so.

    line 26
  2. Distinctive:

    Read the version numbers as the maintainer intended them:

    line 36
  3. Very specific:

    Write down each breaking change as a concrete question about this codebase: "they renamed Client.fetch() to Client.request() — do we call …

    line 54
  4. Distinctive:

    Do not guess from the changelog which parts matter.

    line 59
  5. Distinctive:

    Every import of the package

    line 62
  6. Distinctive:

    Every symbol imported from it

    line 63
  7. Distinctive:

    One dependency per change: If the upgrade drags in a transitive bump that breaks something, a single-package diff tells you which one did …

    line 82
  8. Distinctive:

    If the new version deprecates something without removing it yet, migrate anyway while the context is loaded.

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.

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

Upgrade a dependency

A dependency upgrade fails in one of three ways: it does not install, it installs but the code no longer compiles, or — the expensive one — it installs, compiles, passes tests, and behaves differently in production. This procedure is built to catch the third.

Before you start

Establish that the build is green now. If tests already fail, you cannot tell what the upgrade broke.

<test command>        # must pass before anything changes

If the baseline is red, stop and say so. Fixing an unrelated failure first is a separate piece of work.

Record what you are moving between — the exact installed version, not the range in the manifest. The manifest may say ^2.1.0 while the lockfile has 2.4.7.

Steps

1. Size the jump

Read the version numbers as the maintainer intended them:

JumpExpectationEffort
Patch (2.4.7 → 2.4.8)Bug fixes onlyRead the diff if it is a security fix
Minor (2.4.7 → 2.5.0)New features, no breaksSkim the changelog for deprecations
Major (2.4.7 → 3.0.0)Breaking changes expectedRead the migration guide in full

A maintainer who does not follow semver makes all three rows unreliable. Check the changelog regardless of what the numbers imply.

2. Read the changelog, not the release title

Find the actual list of changes — CHANGELOG.md in the repository, the GitHub releases page, or the project's migration guide. Read every entry between the installed version and the target, not just the newest one. A three-version jump carries three sets of breaking changes.

Write down each breaking change as a concrete question about this codebase: "they renamed Client.fetch() to Client.request() — do we call fetch?"

3. Inventory the actual usage

Do not guess from the changelog which parts matter. Search the codebase for what it genuinely uses:

  • Every import of the package
  • Every symbol imported from it
  • Configuration files, environment variables and CLI flags the package reads

Cross-reference that inventory against the breaking changes. The intersection is your real work list; everything else in the changelog is noise for this repo.

4. Apply the upgrade

Change the version in the manifest, then regenerate the lockfile with the ecosystem's own tooling. Never hand-edit a lockfile.

EcosystemUpgradeRegenerate lock
npm / pnpm / yarnnpm install pkg@3.0.0automatic
pip + requirementsedit requirements.inpip-compile
Poetry / uvpoetry add pkg@^3.0.0 / uv addautomatic
Cargocargo update -p pkg --precise 3.0.0automatic
Gogo get pkg@v3.0.0go mod tidy

One dependency per change. If the upgrade drags in a transitive bump that breaks something, a single-package diff tells you which one did it. A batch of twelve does not.

5. Fix what broke, at the source

Work through the compiler or test failures. For each one, apply the migration the changelog prescribes rather than the smallest change that makes the error stop.

If the new version deprecates something without removing it yet, migrate anyway while the context is loaded. Deprecation warnings become the next upgrade's breaking changes.

6. Verify

In order, stopping at the first failure:

  1. It installs from a clean lockfile
  2. It builds or type-checks
  3. The full test suite passes
  4. The application starts and serves a real request
  5. Behaviour that the changelog said changed actually behaves as documented

Step 5 is the one that catches silent breakage. If a changelog entry says default timeouts changed from 30s to 5s, assert the new timeout somewhere — do not assume the tests cover it.

7. Report

State plainly:

  • Package, from-version, to-version
  • Breaking changes that applied to this codebase, and what you changed for each
  • Breaking changes that did not apply, and why
  • Anything you could not verify locally
  • How to roll back

Do not

  • Force the install. --force, --legacy-peer-deps and --ignore-platform-reqs silence a real incompatibility rather than resolving it. If a peer dependency conflicts, resolve the conflict or stop.
  • Widen a version range to make resolution succeed. Changing ~2.4.0 to >=2.0.0 does not fix anything; it moves the failure to whoever installs next.
  • Upgrade everything at once because the tool offers to. Batched upgrades are unbisectable.
  • Skip the changelog because tests pass. Tests cover what someone thought to test. Changed defaults, altered error types and new network behaviour routinely slip through a green suite.
  • Leave a lockfile out of the commit. The lockfile is the upgrade; the manifest is only an intention.

When to stop and ask

  • The upgrade requires a runtime bump (Node 18 → 20, Python 3.9 → 3.11) that affects deployment
  • The package changed licence
  • The package is unmaintained or the repository is archived, and the real answer is to replace it
  • More than a handful of call sites need rewriting — that is a migration with its own plan, not a version bump

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.