Guide · Agent skill
How to use the Dependency Upgrade Planner agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Dependency Upgrade Planner is an agent skill, a folder of instructions that an AI agent such as Claude loads when your request matches its description. This one gives the agent a structured playbook for moving a JavaScript or TypeScript project to a new major version of a library or framework. After this guide you will know how to install it, how to ask for help with a real upgrade, and which safety checks to keep in place.
Dependency Upgrade Plannerwshobson/agents · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it so you have a folder containing SKILL.md.
- 2Place the folder in the right location. Copy it to ~/.claude/skills/ for all projects, or to .claude/skills/ inside one project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm your project has tests and a build. Make sure npm run test and npm run build work in your project before starting an upgrade, so you have a baseline.
- 4Commit or back up your work. Create a clean git commit or branch so you can recover if an upgrade goes wrong, since the rollback example can discard local changes.
- 5Ask for an audit and a plan. Ask the agent to audit outdated and vulnerable packages and write an upgrade order. Review the plan before any changes are made.
- 6Upgrade one package at a time. Approve one package upgrade, run the tests and build, then move to the next package in the plan.
- 7Review the changes before merging. Read the diff, check the test results, and merge only after a human has reviewed the upgrade.
What the skill makes the agent do
The skill's main file, SKILL.md, tells the agent to treat a major upgrade as a planned, staged process rather than one large install. It covers semantic versioning (what a major, minor and patch change means), auditing outdated and vulnerable packages, checking dependency trees for duplicates, and reading changelogs and migration notes before changing code.
- Audit outdated and vulnerable packages with npm outdated, npm audit and npx npm-check-updates
- Plan an upgrade order and write it to an UPGRADE_PLAN.md file
- Upgrade one package at a time, running tests and a build between steps
- Apply automated code fixes with jscodeshift codemods, with a dry-run option to preview changes
- Set up rollback steps in case an upgrade fails
Install the skill from the ZIP
Download the ZIP for this skill from this page and unzip it. The skill is a folder containing SKILL.md. To make it available to Claude Code for all your projects, place the folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill there.
- Personal (all projects): ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with a natural request
You do not need a special command. The skill's description says it applies when you are upgrading framework versions, updating major dependencies, or managing breaking changes in libraries. Describe your situation in plain terms and mention the packages involved, so the agent can match the request and pick the right steps.
Good requests name the project, the current versions and the goal. For example, ask the agent to plan moving a React app from version 17 to 18 while keeping React Router and the testing libraries working. Ask it to list the upgrade order before it edits anything.
- Plan an upgrade from React 17 to 18 for this project and list the order before changing files
- Audit my npm dependencies for outdated and vulnerable packages and suggest which major upgrades are safe to do first
- Help me upgrade TypeScript, then test and build after each step
- Show me a dry run of a jscodeshift codemod on src/ before applying it
What you need before you start
The skill's examples assume Node.js and npm (or yarn), a project with an npm run test script and an npm run build script, and git. The rollback example uses git, so a git repository is needed if you want that part to work as written. Optional tools include npx access to jscodeshift, npm-check-updates and madge, and a Renovate or Dependabot setup if you use those configurations.
The skill assumes you already know how package managers, test suites and git work. It does not teach those basics.
- Node.js and npm (or yarn)
- A test suite runnable with npm run test and a build script runnable with npm run build
- git, for the rollback example
- Optional: npx access to jscodeshift, npm-check-updates and madge
Safety notes: scripts and network access
This skill runs scripts and uses the network. The examples fetch codemods from raw GitHub URLs, fetch a changelog with curl, and run package installs. The rollback example runs git stash, creates branches, and can delete a branch with git branch -D. Those commands can discard local work.
Review every command the agent proposes before you approve it. Work on a clean git branch, commit or back up your changes first, and use the dry-run option for codemods. Do not run the upgrade unattended against production code.
- Commit or back up local work before starting, because the rollback script uses git stash and branch deletion
- Use the --dry flag on codemods to preview changes
- Check the codemod URL and the changelog source before you run them
- Keep a human review step before any commit or merge
Tips for getting useful results
Upgrade one major version at a time and keep the tests green between steps. The skill's own examples say not to upgrade everything at once. If your project uses Renovate or Dependabot, mention it, because the skill includes example configurations for both and major updates can be set to require manual merging.
The React examples and the compatibility matrix are specific to React. If your project uses another framework, ask the agent to build a similar matrix from that framework's own changelog and migration guide.
- Ask for a plan first, then approve each step
- Name the exact current and target versions
- Confirm your test and build scripts exist before starting
- For non-React projects, provide the migration guide so the agent works from real documentation
What people use it for
- Planning a staged move from React 17 to React 18 with matching react-dom, React Router and testing library versions
- Auditing an npm project for outdated and vulnerable packages and deciding which major upgrades to tackle first
- Previewing a jscodeshift codemod such as the React unsafe lifecycle rename with the --dry option before applying it
- Mapping which packages depend on a library with npm ls and finding duplicates with npm dedupe before an upgrade
- Drafting an UPGRADE_PLAN.md file that lists the upgrade order for a team to review
Frequently asked questions
How do I install the dependency-upgrade agent skill?
Download the ZIP from this page and unzip it. Place the dependency-upgrade folder in ~/.claude/skills/ for all your projects, or in a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
Is the dependency-upgrade skill free to use?
The skill is published under the MIT licence, as stated on this page. Check the licence file in the source repository for the full terms. Your agent platform may have its own pricing, which this page does not cover.
Does this skill work with Python, Java or Go projects?
The skill is written around npm, yarn and React examples, so it is aimed at JavaScript and TypeScript projects. The general approach of audit, staged upgrade, testing and rollback may still help in other ecosystems, but the commands will not apply directly.
What do I need installed to use it?
You need Node.js and npm (or yarn) for the commands shown, a project with npm run test and npm run build scripts, and git for the rollback example. Optional tools include npx access to jscodeshift, npm-check-updates and madge.
Why does the skill mention rollback scripts that delete branches?
The example rollback script uses git stash, creates a branch, and can delete it with git branch -D if tests fail. This can discard local work, so commit or back up your changes first and review each command before running it.
Can the agent run a major upgrade on its own?
It is not recommended. The examples include automatic installs and automatic commits, so keep a human reviewing each step and each commit, and avoid unattended upgrades on production code.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you maintain a JavaScript or TypeScript project and want an agent to plan a safe, staged major upgrade with tests between each step. Pick something else if you work in Python, Java or Go, or if you need an unattended tool, since the skill's examples are npm and React specific and assume git and testing experience.
Download the skill