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
- fitlab-ai/agent-infratheir own version, first seen Oct 27, 2026
- malinskibeniamin/skillstheir own version, first seen Oct 17, 2026
- ModelEngine-Group/fit-frameworktheir own version, first seen Oct 8, 2026
- awcameron/skillstheir own version, first seen Sep 30, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- ModelEngine-Group/fit-framework★ 2.1ksame name
- fitlab-ai/agent-infra★ 88same name
- malinskibeniamin/skills★ 4same name
- 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
- Distinctive: line 26
If the baseline is red, stop and say so.
- Distinctive: line 36
Read the version numbers as the maintainer intended them:
- Very specific: line 54
Write down each breaking change as a concrete question about this codebase: "they renamed Client.fetch() to Client.request() — do we call …
- Distinctive: line 59
Do not guess from the changelog which parts matter.
- Distinctive: line 62
Every import of the package
- Distinctive: line 63
Every symbol imported from it
- Distinctive: line 82
One dependency per change: If the upgrade drags in a transitive bump that breaks something, a single-package diff tells you which one did …
- Distinctive: line 91
If the new version deprecates something without removing it yet, migrate anyway while the context is loaded.
≈ “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.
Files
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 changesIf 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:
| Jump | Expectation | Effort |
Patch (2.4.7 → 2.4.8) | Bug fixes only | Read the diff if it is a security fix |
Minor (2.4.7 → 2.5.0) | New features, no breaks | Skim the changelog for deprecations |
Major (2.4.7 → 3.0.0) | Breaking changes expected | Read 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.
| Ecosystem | Upgrade | Regenerate lock |
| npm / pnpm / yarn | npm install pkg@3.0.0 | automatic |
| pip + requirements | edit requirements.in | pip-compile |
| Poetry / uv | poetry add pkg@^3.0.0 / uv add | automatic |
| Cargo | cargo update -p pkg --precise 3.0.0 | automatic |
| Go | go get pkg@v3.0.0 | go 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:
- It installs from a clean lockfile
- It builds or type-checks
- The full test suite passes
- The application starts and serves a real request
- 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-depsand--ignore-platform-reqssilence 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.0to>=2.0.0does 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
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
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.

