---
name: upgrade-dependencies
description: |
  Use this skill to upgrade every dependency in a
  repository end-to-end: read the repo README and
  CLAUDE.md, sync master, confirm the baseline build
  is green, branch for the upgrade, lift every runtime
  and development dependency to its latest stable
  release, lift every CI plugin and GitHub Action to
  its latest version too, stabilize the build, commit,
  push, open a pull request whose description talks
  like a human, and wait until every CI job is green.
  One repository per run, one branch per run, one pull
  request per run — then stop.
---

Run `git status` first; if the working directory has
  any uncommitted changes, untracked files, or staged
  hunks, stop immediately and do not continue.

This skill must start from a clean tree so that
  nothing it does can mix with, overwrite, or
  accidentally commit unrelated work in progress.

Read the `README.md` file at the root of the
  repository before doing anything else; it names the
  build command, the test layout, the branch and
  commit conventions, and any project-specific rules
  this skill must respect.

Read the `CLAUDE.md` file at the root of the
  repository too, if it exists; it carries
  instructions written specifically for the agent —
  coding conventions, build shortcuts, files to
  avoid, and project-specific rules that override
  generic defaults.

Check out the `master` branch and run `git pull` to
  sync with the remote, so the work starts from the
  latest known state and not from a stale local copy.

Run the full build — every test, every linter, every
  static check — and confirm it is green before
  touching anything; a failure later must be
  attributable to the upgrade alone.

If the baseline build fails on `master`, repair it
  first inside this same run: read the failure, fix
  the source by hand, re-run the full build, and
  repeat until the tree is green; only then start
  the upgrade work.

Do not suppress baseline failures with
  `eslint-disable`, `noqa`, `.skip`, `--no-verify`,
  lowered thresholds, or commented-out tests; fix
  the source instead.

Create a new branch named `upgrade-deps` — or, if
  that name is already taken on the remote, append a
  short ISO date suffix such as `upgrade-deps-20260511`;
  do not bundle this branch with any other unrelated
  change.

Identify every dependency manifest in the
  repository — `package.json`, `pom.xml`, `Gemfile`,
  `requirements.txt`, `pyproject.toml`, `go.mod`,
  `Cargo.toml`, `build.gradle`, `composer.json`,
  `*.csproj`, `Pipfile`, and any other file that
  pins runtime or development versions — and treat
  every one of them as in scope for this run.

Lift every runtime dependency, every development
  dependency, and every transitive lock entry to its
  latest stable release published on the matching
  registry, ignoring pre-releases, release
  candidates, alpha and beta tags, and snapshot
  builds.

Lift every CI plugin too: the GitHub Actions used in
  `.github/workflows/*.yml`, the Maven, Gradle, npm,
  pip, or other build-tool plugins declared in the
  project manifests, and any pinned tool versions
  referenced from the CI configuration — actions
  pinned by tag or by commit SHA must be raised to
  the latest stable tag, then re-pinned by the
  matching SHA if the project uses SHA pinning.

Do not loosen version ranges, do not replace exact
  pins with floating ranges, and do not introduce
  new wildcards; raise the lower bound and keep the
  pinning style the project already uses.

Regenerate every lockfile the project owns —
  `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`,
  `Gemfile.lock`, `poetry.lock`, `go.sum`,
  `Cargo.lock`, `composer.lock`, and the like — using
  the tool the project itself prescribes, so the lock
  state matches the new manifest exactly.

Run the full build again — every test, every
  linter, every static check — and read the output
  end to end before reacting.

If the build fails, fix the source by hand, one
  file at a time, addressing the single most
  critical issue first, and re-run the full build
  after every edit.

Repeat the fix-and-rebuild loop until the build is
  clean, then run the full build one more time to
  confirm the green state is stable.

Do not pin a dependency back to an older version to
  silence a failure unless the newer release has a
  documented regression that the upstream project
  has acknowledged; in that case, pin to the latest
  known-good version, leave a one-line note in the
  pull request body, and open an upstream issue
  separately.

Do not suppress upgrade failures with
  `eslint-disable`, `noqa`, `.skip`, `--no-verify`,
  lowered thresholds, or commented-out tests; fix
  the code instead.

Do not batch-fix with `sed`, `awk`, codemods, or
  scripts; walk file by file, edit by hand, and read
  each change before saving it.

Commit the upgrade as one coherent change — or as a
  small ordered series if the project's commit
  convention demands it — with a short imperative
  subject such as `chore(deps): upgrade all
  dependencies` and a body that lists the notable
  version jumps in plain prose.

Push the branch to the remote and open a pull
  request against `master`; the title states the
  upgrade in one short imperative line, and the
  description talks like a human — plain prose,
  first person, no headings, no bullet lists, no
  tables, no checkboxes, no AI-disclosure banner.

In the pull request description, explain what was
  upgraded and why it matters: which manifests were
  touched, which major versions moved, which CI
  plugins were lifted, and what had to change in
  the source to keep the build green — written as
  if a teammate were summarizing the work over
  coffee.

Check the status of the CI jobs on GitHub for the
  pull request (for example with `gh pr checks
  --watch`) and wait for every one of them to
  finish; do not consider the work done while any
  check is still running.

If any CI job fails — for any reason, including
  flakes, environment issues, unrelated linters, or
  checks the local build did not run — diagnose the
  failure from the job logs, fix the code base,
  commit, and push again; repeat this loop until
  every check on the pull request is green.

Do not mark a failure as "not my problem" and do
  not ask a maintainer to re-run a red job to make
  it green by chance.

Stop only after every CI job on the pull request is
  green.

Do not bundle unrelated refactors, feature work, or
  cosmetic cleanups into this branch; if a second
  concern surfaces during the upgrade, note it and
  run the appropriate skill for it separately.

Do not merge the pull request, do not rebase it
  onto master, and do not force-push once it is
  open unless review explicitly asks for it; hand
  off to review with a clean green pipeline.