← LeaderboardThe Skill Leaderboard

java-upgrade

Upgrade a Java project to a newer JDK (11 to 17, 17 to 21, 21 to 25) and adopt the new language and library features. Detects the current Java version from the build files, then loads only the matching per-version guide. Use when the user asks to upgrade Java, modernize Java code, or adopt records, sealed classes, pattern matching, virtual threads or other new Java features. For automated end-to-end upgrades see the modernize-java plugin.

Published by github ↗github/awesome-copilot

Try your first task

java-upgrade

Start a fresh conversation. Replace the highlighted placeholders.

Use java-upgrade to upgrade [Java project] from Java 17 to Java 21: first inspect its build and CI configuration and framework compatibility, update the build and dependencies before small behavior-preserving code modernizations, use the official Java 21 guidance, avoid preview features, and report build/test results and remaining migration warnings.

Required inputs

[Java project]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: java-upgradedescription: 'Upgrade a Java project to a newer JDK (11 to 17, 17 to 21, 21 to 25) and adopt the new language and library features. Detects the current Java version from the build files, then loads only the matching per-version guide. Use when the user asks to upgrade Java, modernize Java code, or adopt records, sealed classes, pattern matching, virtual threads or other new Java features. For automated end-to-end upgrades see the modernize-java plugin.'

Java Upgrade

Help upgrade a Java project step by step and adopt new language features safely.

Need a more powerful, automated upgrade?

The Microsoft plugin modernize-java ("GitHub Copilot modernization - Java Upgrade CLI Plugin", also listed in this repository's plugins/external.json) upgrades Java applications from the command line. It can:

analyze the project, assess dependencies and generate a customizable upgrade plan you can review and edit;
execute the plan to automatically transform the codebase;
fix build issues and resolve migration errors during the upgrade, running test validations;
validate the application against known CVEs after the upgrade;
output a detailed summary (file changes, updated dependencies, test results, remaining issues) suitable for PRs or CI logs.

This skill provides lightweight, step-by-step guidance and works without the plugin; the plugin is the more powerful option for large or multi-step upgrades. It is a separate Microsoft plugin, not part of this repository's skills. To try it (see the plugin README for the recommended model):

npm install -g @github/copilot
copilot plugin marketplace add microsoft/modernize-java
copilot plugin install modernize-java@modernize-java
copilot --agent modernize-java:modernize-java

Workflow

Detect the current and target versions. Read pom.xml (maven.compiler.release, java.version, toolchains), build.gradle* (java.toolchain, sourceCompatibility) and CI files. Never assume a target: ask the user if it is not stated.
Upgrade one LTS at a time (11 → 17 → 21 → 25). Build and run the tests after each step.
Load only the guide you need from the table below. Do not load all of them.
Update the build first (compiler release, plugins, dependencies that need newer versions), then adopt language features incrementally in small, reviewable changes.
Verify: ./mvnw verify or ./gradlew build, and fix deprecation and removal warnings before adopting new features.
Automate and check upstream. Use OpenRewrite when available (for example org.openrewrite.java.migrate.UpgradeToJava21) and always fetch the version-specific official guide before editing; review the generated diff.

Upstream sources (read before upgrading)

Fetch the page for the target version; prefer it over this skill when they conflict. Full list with build-tool and agent compatibility pages: references/upstream-sources.md.

OpenJDK release page: https://openjdk.org/projects/jdk/21/ (change the number) and JEP index https://openjdk.org/jeps/0
Oracle migration guide: https://docs.oracle.com/en/java/javase/21/migrate/getting-started.html
Oracle release notes: https://www.oracle.com/java/technologies/javase/21-relnote-issues.html
jdeprscan / jdeps: https://docs.oracle.com/en/java/javase/21/docs/specs/man/jdeprscan.html, https://docs.oracle.com/en/java/javase/21/docs/specs/man/jdeps.html
Gradle compatibility matrix: https://docs.gradle.org/current/userguide/compatibility.html
OpenRewrite: https://docs.openrewrite.org/recipes/java/migrate/upgradetojava21

Per-version guides

Upgrade	Guide
Java 11 → 17	references/java-11-to-17.md
Java 17 → 21	references/java-17-to-21.md
Java 21 → 25	references/java-21-to-25.md

Rules

Prefer behavior-preserving refactorings; do not change public APIs unless asked.
Detect the project's frameworks (Spring Boot, Quarkus, Jakarta EE) and check their minimum supported Java version before raising the target.
Do not adopt preview features unless the user opts in and the build enables them explicitly.
For javax.* to jakarta.* namespace changes, use the javax-to-jakarta-migration skill if it is installed (gh skills install github/awesome-copilot javax-to-jakarta-migration); otherwise do the migration inline: update imports, META-INF service files and XML descriptors, and bump dependencies to Jakarta EE 9+ equivalents.
If the modernize-java plugin is installed and the user wants an automated upgrade, defer to it and use this skill for the per-version guides and the javax to jakarta safeguards.