跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

upgrade-dependencies

Use when upgrading a JS/TS dependency or toolchain to a new/latest version (e.g. "upgrade TypeScript to the latest", "bump Vite to v7", major-version bumps), or when a build/typecheck/lint/test/CI goes red after a version bump and peer-dependency incompatibilities need resolving.

AlemTuzlak · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add AlemTuzlak/skills --skill upgrade-dependencies

技能说明


name: upgrade-dependencies description: Use when upgrading a JS/TS dependency or toolchain to a new/latest version (e.g. "upgrade TypeScript to the latest", "bump Vite to v7", major-version bumps), or when a build/typecheck/lint/test/CI goes red after a version bump and peer-dependency incompatibilities need resolving.

Upgrade Dependencies

Drive a dependency upgrade from "bump X to latest" all the way to green — without hacking around the errors it causes.

Core principle: fix upward, never patch sideways. When a bump breaks something, the fix is to upgrade the thing that's incompatible to a version that supports the target — not to suppress the error, downgrade the target, or add // @ts-ignore. If nothing upstream supports the target yet, that's a blocker you report, not a workaround you invent.

JS/TS ecosystems only (npm / pnpm / yarn / bun, including workspace monorepos and nx/turbo).

The workflow

Work the phases in order. Scan the full impact (phase 2) before touching anything, and collect all breakage (phase 4) before fixing — otherwise you'll fix the same file three times and discover missed references halfway through.

1. Resolve the target version

  • Absolute latest stable by default: npm view <pkg> version (dist-tag latest). Ignore existing semver ranges — the user asked to upgrade.
  • Use a prerelease (next/rc/canary) only if the user asked for it, or if it's the only version that unblocks a phase-5 blocker (and say so).
  • Detect the package manager from the lockfile: pnpm-lock.yaml→pnpm, bun.lockb→bun, yarn.lock→yarn, package-lock.json→npm. Never substitute a different runner.
  • Detect monorepo layout: root workspaces, pnpm-workspace.yaml, nx.json, turbo.json.

2. Scan the impact (read-only — before touching anything)

Do NOT bump yet. First, in one read-only pass, build the impact map: everything the upgrade will touch. This map drives every later phase.

  • Every reference to bump. Grep the package name across all package.json — root and every workspace, dependencies/devDependencies/peerDependencies alike. Don't assume it lives in one place.
  • Config/usage sites the version affects. e.g. TypeScript → tsconfig*.json + everything compiled by tsc; Vite → vite.config.*; ESLint/Prettier → their config files. These are where a major bump's breaking changes land.
  • Checks that exercise it — don't guess. Read root+workspace package.json scripts (build, typecheck/tsc, lint, test…), .github/workflows/*.{yml,yaml} (what CI actually runs), and nx.json/turbo.json task graphs. Produce a concrete check list; include only checks the dep can affect. A TypeScript bump touches typecheck + build + anything running tsc; a Vite bump touches build + dev + test (if vitest); a linter bump touches lint.
  • Third-party deps in the blast radius. From the config/usage and peer requirements, note which other deps are likely to need their own upgrade to support the target (feeds phase 5).

Output of this phase: the list of files to bump, the check list to run, and the suspect deps — decided up front, not discovered mid-fix.

3. Bump everywhere

  • Using the impact map, update every referencing package.json to the target version.
  • Reinstall to regenerate the lockfile with the repo's package manager.

4. Collect ALL breakage first

Run every mapped check once and capture full output per check. Now you know the total damage before touching code. Record which checks are red and the leading errors of each.

If everything's green — done. Report and stop.

5. Triage failures — upstream first

For each failing third-party dependency (the thing whose incompatibility is causing the error, e.g. Vite failing under TS 7):

  1. Look up whether a newer release supports the target. Sources: npm view <dep> peerDependencies, npm view <dep> versions, the package's GitHub releases/CHANGELOG, and open issues/PRs referencing the target version.
  2. Compatible release exists → bump that dep too (rescan + rebump, phases 2–3, for it), then continue.
  3. No compatible release exists → STOP that thread and report it as a blocker. Include the evidence: the dep's latest version, its peer range, and the tracking issue/PR link if there is one. Do not downgrade the target, pin around it, or suppress the error to make the check pass.

Failures that are just your own code needing updates for the new version go straight to phase 6.

6. Fix, one check at a time, parallelized

Fix real code — new API usage, updated types, migrated config — never suppressions.

  • Dispatch one worktree-isolated subagent per independent check (a build agent, a typecheck agent, a lint agent, a test agent). Give each agent: the target bump, its single check's command, and that check's captured errors.
  • Use worktrees so parallel agents don't collide on the same working tree (see superpowers:using-git-worktrees / your blitz skill).
  • Serialize instead when checks share the same files or when there are only one or two — parallel worktrees aren't free.
  • Each agent's exit bar: its check passes on real fixes.

7. Verify and report

  • Merge the agents' branches, then re-run the full check set on the merged result. A fix that passed in isolation can fail once combined — loop phase 6/7 until the whole set is green.
  • Final report:
    • Bumped: target + any upstream deps you moved, with versions.
    • Fixed: which checks were red and what the real fix was.
    • Blocked: any deps held at their current version because upstream doesn't support the target yet, with evidence. These are the only things left un-upgraded, and the user decides what to do with them.

Quick reference

StepCommand / action
Latest stablenpm view <pkg> version
All versionsnpm view <pkg> versions --json
Peer requirementsnpm view <dep> peerDependencies
Fin
阅读完整来源 ↗