Skip to main content
Agent skill

Dependency Upgrade

Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing breaking changes in libraries.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Dependency Upgrade when an AI agent needs a reusable SKILL.md workflow for this job: Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing breaking changes in libraries.

When not to use it

Skip Dependency Upgrade when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/dependency-upgrade
# Save SKILL.md to ~/.claude/skills/dependency-upgrade/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/dependency-upgrade/SKILL.md. For a shared project, commit the folder at .claude/skills/dependency-upgrade/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Dependency Upgrade skill for this task: Upgrading major framework versions. Confirm any required inputs or files before making changes.

What supports this recommendation?

84/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
92/100
Practical detail
92/100
Source evidence
63/100
Source signals
80/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Dependency Upgrade

Master major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing approaches.

## When to Use This Skill

- Upgrading major framework versions - Updating security-vulnerable dependencies - Modernizing legacy dependencies - Resolving dependency conflicts - Planning incremental upgrade paths - Testing compatibility matrices - Automating dependency updates

## Semantic Versioning Review

``` MAJOR.MINOR.PATCH (e.g., 2.3.1)

MAJOR: Breaking changes MINOR: New features, backward compatible PATCH: Bug fixes, backward compatible

^2.3.1 = >=2.3.1 <3.0.0 (minor updates) ~2.3.1 = >=2.3.1 <2.4.0 (patch updates) 2.3.1 = exact version ```

## Dependency Analysis

### Audit Dependencies

```bash # npm npm outdated npm audit npm audit fix

# yarn yarn outdated yarn audit

# Check for major updates npx npm-check-updates npx npm-check-updates -u # Update package.json ```

### Analyze Dependency Tree

```bash # See why a package is installed npm ls package-name yarn why package-name

# Find duplicate packages npm dedupe yarn dedupe

# Visualize dependencies npx madge --image graph.png src/ ```

## Compatibility Matrix

```javascript // compatibility-matrix.js const compatibilityMatrix = { react: { "16.x": { "react-dom": "^16.0.0", "react-router-dom": "^5.0.0", "@testing-library/react": "^11.0.0", }, "17.x": { "react-dom": "^17.0.0", "react-router-dom": "^5.0.0 || ^6.0.0", "@testing-library/react": "^12.0.0", }, "18.x": { "react-dom": "^18.0.0", "react-router-dom": "^6.0.0", "@testing-library/react": "^13.0.0", }, }, };

function checkCompatibility(packages) { // Validate package versions against matrix } ```

## Staged Upgrade Strategy

### Phase 1: Planning

```bash # 1. Identify current versions npm list --depth=0

# 2. Check for breaking changes # Read CHANGELOG.md and MIGRATION.md

# 3. Create upgrade plan echo "Upgrade order: 1. TypeScript 2. React 3. React Router 4. Testing libraries 5. Build tools" > UPGRADE_PLAN.md ```

### Phase 2: Incremental Updates

```bash # Don't upgrade everything at once!

# Step 1: Update TypeScript npm install typescript@latest

# Test npm run test npm run build

# Step 2: Update React (one major version at a time) npm install react@17 react-dom@17

# Test again npm run test

# Step 3: Continue with other packages npm install react-router-dom@6

# And so on... ```

### Phase 3: Validation

```javascript // tests/compatibility.test.js describe("Dependency Compatibility", () => { it("should have compatible React versions", () => { const reactVersion = require("react/package.json").version; const reactDomVersion = require("react-dom/package.json").version;

expect(reactVersion).toBe(reactDomVersion); });

it("should not have peer dependency warnings", () => { // Run npm ls and check for warnings }); }); ```

## Breaking Change Handling

### Identifying Breaking Changes

```bash # Check the changelog directly curl https://raw.githubusercontent.com/facebook/react/master/CHANGELOG.md ```

### Codemod for Automated Fixes

```bash # Run jscodeshift with transform URL npx jscodeshift -t <transform-url> <path>

# Example: Rename unsafe lifecycle methods npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js src/

# For TypeScript files npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --parser=tsx src/

# Dry run to preview changes npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --dry src/ ```

### Custom Migration Script

```javascript // migration-script.js const fs = require("fs"); const glob = require("glob");

glob("src/**/*.tsx", (err, files) => { files.forEach((file) => { let content = fs.readFileSync(file, "utf8");

// Replace old API with new API content = content.replace( /componentWillMount/g, "UNSAFE_componentWillMount", );

// Update imports content = content.replace( /import { Component } from 'react'/g, "import React, { Component } from 'react'", );

fs.writeFileSync(file, content); }); }); ```

## Testing Strategy

### Unit Tests

```javascript // Ensure tests pass before and after upgrade npm run test

// Update test utilities if needed npm install @testing-library/react@latest ```

### Integration Tests

```javascript // tests/integration/app.test.js describe("App Integration", () => { it("should render without crashing", () => { render(<App />); });

it("should handle navigation", () => { const { getByText } = render(<App />); fireEvent.click(getByText("Navigate")); expect(screen.getByText("New Page")).toBeInTheDocument(); }); }); ```

### Visual Regression Tests

```javascript // visual-regression.test.js describe("Visual Regression", () => { it("should match snapshot", () => { const { container } = render(<App />); expect(container.firstChild).toMatchSnapshot(); }); }); ```

### E2E Tests

```javascript // cypress/e2e/app.cy.js describe("E2E Tests", () => { it("should complete user flow", () => { cy.visit("/"); cy.get('[data-testid="login"]').click(); cy.get('input[name="email"]').type("[email protected]"); cy.get('button[type="submit"]').click(); cy.url().should("include", "/dashboard"); }); }); ```

## Automated Dependency Updates

### Renovate Configuration

```json // renovate.json { "extends": ["config:base"], "packageRules": [ { "matchUpdateTypes": ["minor", "patch"], "automerge": true }, { "matchUpdateTypes": ["major"], "automerge": false, "labels": ["major-update"] } ], "schedule": ["before 3am on Monday"], "timezone": "America/New_York" } ```

### Dependabot Configuration

```yaml # .github/dependabot.yml version: 2 updates: - package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" open-pull-requests-limit: 5 reviewers: - "team-leads" commit-message: prefix: "chore" include: "scope" ```

## Rollback Plan

```javascript // rollback.sh #!/bin/bash

# Save current state git stash git checkout -b upgrade-branch

# Attempt upgrade npm install package@latest

# Run tests if npm run test; then echo "Upgrade successful" git add package.json package-lock.json git commit -m "chore: upgrade package" else echo "Upgrade failed, rolling back" git checkout main git branch -D upgrade-branch npm install # Restore from package-lock.json fi ```

## Common Upgrade Patterns

### Lock File Management

```bash # npm npm install --package-lock-only # Update lock file only npm ci # Clean install from lock file

# yarn yarn install --frozen-lockfile # CI mode yarn upgrade-interactive # Interactive upgrades ```

### Peer Dependency Resolution

```bash # npm 7+: strict peer dependencies npm install --legacy-peer-deps # Ignore peer deps

# npm 8+: override peer dependencies npm install --force ```

### Workspace Upgrades

```bash # Update all workspace packages npm install --workspaces

# Update specific workspace npm install package@latest --workspace=packages/app ```

Intended uses

  • Upgrading major framework versions
  • Updating security-vulnerable dependencies
  • Modernizing legacy dependencies
  • Resolving dependency conflicts
  • Planning incremental upgrade paths
  • Testing compatibility matrices
  • Automating dependency updates

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.