An agent skill that helps developers upgrade Java code from older idioms to modern equivalents. Built on the comprehensive pattern database from java.evolved by Bruno Borges (source).

This skill enables AI coding agents to:

• Detect legacy Java patterns in codebases and suggest modern replacements
• Provide before/after code examples for 113 patterns across 11 categories
• Guide enterprise migrations from Java EE to Jakarta EE, Spring XML to annotations
• Filter by JDK version to only suggest patterns compatible with the project's target
• Prioritize upgrades by difficulty (beginner, intermediate, advanced)

Install using skills.sh — works with Claude Code, GitHub Copilot, Cursor, Cline, Windsurf, and 15+ other agents:

npx skills add darshitpp/java-code-upgrade

This auto-detects the agent and installs the skill in the correct location. No manual setup needed.

There are two installation scopes:

Global (available in all projects):

git clone https://github.com/darshitpp/java-code-upgrade.git ~/.claude/skills/java-code-upgrade

Per-project (available only in that project):

cd /path/to/your/project
mkdir -p .claude/skills
git clone https://github.com/darshitpp/java-code-upgrade.git .claude/skills/java-code-upgrade

After installation, the skill appears automatically in Claude Code's available skills list. It triggers when asking to modernize Java code, review for outdated patterns, or upgrade JDK idioms. It can also be invoked explicitly with /java-code-upgrade.

To update the skill later:

cd ~/.claude/skills/java-code-upgrade   # or .claude/skills/java-code-upgrade
git pull

This skill follows the agentskills.io open standard and works with any compatible agent. See Usage with Different Agents below for agent-specific setup.

java-code-upgrade/
  SKILL.md                          # Core skill instructions
  scripts/
    find-pattern.py                 # CLI tool for searching patterns
    generate-references.py          # Regenerates references from upstream YAML
    sync-from-source.sh             # Pulls upstream and regenerates
  references/
    detection-patterns.md           # Code signatures for detecting legacy patterns
    pattern-index.md                # Quick lookup table of all 113 patterns
    language.md                     # Language feature patterns (23)
    collections.md                  # Collection patterns (11)
    strings.md                      # String patterns (7)
    streams.md                      # Stream patterns (12)
    concurrency.md                  # Concurrency patterns (11)
    io.md                           # I/O patterns (11)
    errors.md                       # Error handling patterns (7)
    datetime.md                     # Date/time patterns (6)
    security.md                     # Security patterns (5)
    tooling.md                      # Tooling patterns (8)
    enterprise.md                   # Enterprise migration patterns (16)
  assets/
    upgrade-report-template.md      # Template for upgrade reports

This skill follows the agentskills.io open standard. It auto-activates when relevant to Java modernization tasks, or can be invoked explicitly.

Invoke: Ask naturally ("modernize this Java code") or explicitly with /java-code-upgrade. Claude loads the skill automatically when relevant.

Claude Code skills docs

Invoke: Ask naturally or use /java-code-upgrade in chat. Cursor auto-discovers skills at startup. You can also install from GitHub via Settings > Rules > Add Rule > Remote Rule (Github).

Cursor skills docs

Invoke: Copilot auto-discovers and loads skills when relevant to the task.

Copilot skills docs

Invoke: Reference with /skills or $ mention syntax, or let Codex auto-select based on task context.

Codex skills docs

Invoke: Ask "Use the java-code-upgrade skill" or let Goose auto-activate when relevant.

Goose skills docs

Invoke: Roo indexes all skills at startup and auto-activates when your request matches. No manual registration needed.

Roo Code skills docs

Amp skills docs

Junie skills docs

Gemini CLI skills docs

For any other agentskills.io-compatible agent, place the skill directory where the agent discovers skills (typically ~/.agents/skills/ globally or .agents/skills/ per-project). The SKILL.md file is the entry point. The agent loads references and scripts on demand via progressive disclosure.

python3 scripts/find-pattern.py --category concurrency --format brief

python3 scripts/find-pattern.py --min-jdk 17 --max-jdk 21 --format brief

python3 scripts/find-pattern.py --keyword "virtual thread" --format full

python3 scripts/find-pattern.py --detect 'Collections.unmodifiableList(Arrays.asList("a"))' --format brief

All files in references/ are auto-generated from upstream YAML data. No manual editing needed.

The reference files can be automatically synced from the upstream javaevolved repository.

./scripts/sync-from-source.sh

The included .github/workflows/sync-upstream.yml runs weekly and opens a pull request if patterns changed.

Setup:

1. No extra tokens needed — the default GITHUB_TOKEN handles everything.
2. The schedule runs weekly on Monday at 06:00 UTC. Adjust the cron in the workflow file if needed.
3. Trigger manually anytime from Actions > Sync from upstream java.evolved > Run workflow.

The included .gitlab-ci.yml defines a sync-upstream job with the same behavior, opening a merge request on changes.

Setup:

1. Go to Settings > CI/CD > Variables and add GITLAB_TOKEN — a project access token with write_repository and api scopes.
2. Go to CI/CD > Schedules and create a new schedule with cron 0 6 * * 1 (weekly Monday 06:00 UTC) or any frequency you prefer.
3. Trigger manually anytime from CI/CD > Pipelines > Run pipeline.

Both CI options create a PR/MR for review rather than pushing directly, so you can inspect changes before merging.

All pattern data is sourced from the java.evolved project, created by Bruno Borges. The original YAML content files have been consolidated into markdown reference files for efficient agent consumption with progressive disclosure.

• Source repository: javaevolved/javaevolved.github.io
• Original license: MIT License - Copyright (c) 2026 Bruno Borges

MIT License.

• Pattern data (references/ content) — Copyright (c) 2026 Bruno Borges, from javaevolved.github.io
• Skill tooling (SKILL.md, scripts, assets, CI pipelines) — Copyright (c) 2026 Darshit Patel

Both components are licensed under the MIT License. See LICENSE for the full text.