Skip to main content

Using Moderne skills with AI coding agents

The Moderne CLI can install agent tools (skills and MCP servers) that teach AI coding agents how to work with OpenRewrite recipes. With a single command, you can install these tools for all detected agents, giving them guidance through the full recipe workflow: creating recipes, running them at scale, and analyzing the impact of what changed.

Why use Moderne skills​

Building OpenRewrite recipes requires understanding visitor patterns, LST structures, and testing idioms that AI coding agents don't know out of the box.

Moderne skills teach agents about:

  • Recipe creation - choosing the right type of recipe (Declarative, Refaster, or Imperative) and following OpenRewrite conventions
  • Testing workflows - setting up working sets, running recipes against real code, and diagnosing why recipes match or don't match certain pieces of code
  • Impact analysis - turning recipe run data into executive reports and visualizations

The skills are bundled with the CLI and stay current when you update.

Supported agents​

The CLI auto-detects installed coding agents and installs skills to each one:

AgentDetectionInstall location
Claude Code~/.claude/ (or CLAUDE_CONFIG_DIR)~/.claude/marketplaces/moderne/moderne/skills/<skill>/SKILL.md
Windsurf~/.codeium/~/.codeium/windsurf/skills/<skill>/SKILL.md
Sourcegraph Amp~/.config/agents/~/.config/agents/skills/<skill>/SKILL.md
OpenAI Codex~/.agents/~/.agents/skills/<skill>/SKILL.md
Cursor~/.cursor/.cursor/rules/moderne-<skill>.mdc
GitHub Copilot.github/ in current directory or ~/.copilot/.github/instructions/moderne-<skill>.instructions.md
note

Cursor and GitHub Copilot skills are installed per-project (into .cursor/rules/ and .github/instructions/ respectively). Unlike the other agents which install skills globally, these require running the install command from each project root where you want the skills available.

In addition to installing skills, the command also registers a Moderne MCP server for each agent, providing tools for semantic code search, navigation, and refactoring.

Installation​

The following command scans for installed coding agents and installs agent tools (skills and MCP servers) to each one. If no agents are detected, it displays a message listing the supported agents and their detection paths.

mod config agent-tools install

To remove all installed agent tools:

mod config agent-tools uninstall

Per-agent installation​

You can install agent tools for a single coding agent instead of all detected agents:

mod config agent-tools claude install
mod config agent-tools cursor install
mod config agent-tools copilot install

Each per-agent command installs both skills and the MCP server for that agent only. If the agent is not detected on your system, the command displays a message and exits without making changes.

The available per-agent subcommands are: claude, windsurf, cursor, copilot, amp, and codex.

Skills-only installation​

To install only skills (without the MCP server) for all detected agents:

mod config agent-tools skills install

To remove only skills:

mod config agent-tools skills uninstall

Invoking skills​

How you invoke skills depends on your coding agent:

Claude Code - Use slash commands with the /moderne: prefix:

/moderne:create-recipe

Create a recipe that replaces all calls to Logger.info() with Logger.debug()

Windsurf, Sourcegraph Amp - Reference skills by name in your prompt:

Using the run-recipe skill, test my recipe against the Default organization.

Cursor - Skills are loaded automatically as rules. Reference them in context:

@moderne-create-recipe Create a recipe that migrates deprecated API calls.

GitHub Copilot - Skills are loaded as instructions. Reference them in your prompt:

Following the moderne-run-recipe instructions, help me debug why my recipe isn't matching.

Available skills​

The following skills are installed:

  • create-organization - build a working set of repositories to test against
  • create-recipe - create new OpenRewrite recipes with proper patterns
  • run-recipe - test and debug recipes against real repositories
  • analyze-impact - create reports and visualizations from recipe run data

create-organization​

Use this skill when you want to create a custom set of repositories to run recipes against.

This skill helps you:

  • Find repositories by language, technology (Spring Boot, JPA, Kafka, etc.), or by listing all accessible repos
  • Search across platforms - GitHub, GitLab, Bitbucket, and other sources like Sourcegraph and Libraries.io
  • Generate repos.csv files with proper format and organizational hierarchy
  • Sync repositories using mod git sync csv
  • Organize repositories by team, technology, or business domain for focused testing

create-recipe​

Use this skill when you want to create a new OpenRewrite recipe or modify an existing one.

When not to use: Testing or debugging a recipe you've written (use run-recipe instead) or general Java programming unrelated to OpenRewrite.

This skill helps you with:

  • Recipe type selection - Choosing between declarative YAML (for composing existing recipes), Refaster templates (for simple expression replacements), or imperative Java recipes (for complex logic)
  • Critical patterns - LST immutability, visitor traversal, type matching with MethodMatcher, and proper import handling
  • Testing - Writing tests with the RewriteTest framework, including before/after assertions and no-change cases
  • Data tables - Emitting structured data for analysis

run-recipe​

Use this skill to discover, configure, and run OpenRewrite recipes against real repositories. This skill is especially useful for AI coding agents as they can use it to run recipes as part of automated workflows. With it, they can browse the recipe catalog, configure complex recipe options, and interpret results.

note

If you just want to run an existing recipe without iterative debugging, you can use the CLI directly (mod run).

The skill supports two modes:

  • Existing recipe mode - For pre-built recipes from the catalog or Maven coordinates (uses mod config recipes jar install)
  • Development mode - For recipes you're actively editing (uses mod config recipes active set)

When developing a new recipe, the skill guides you through an iterative loop:

  1. Working set setup - Syncing repositories from a Moderne organization or custom CSV
  2. Pre-analysis - Searching source code to predict which files should be affected
  3. Recipe execution - Running with appropriate parallelism and monitoring progress
  4. Results comparison - Comparing predictions vs actual results to diagnose mismatches
  5. Diagnosis - Investigating why expected changes are missing (e.g., checking matchers, reviewing visitor logic)
  6. Iteration - Fixing the recipe and re-running until results match expectations

analyze-impact​

Use this skill when you want to create reports and visualizations from recipe run data.

This skill helps you with:

  • Discovering data - Finding existing recipe runs with mod audit runs list
  • Data aggregation - Extracting data tables with mod study
  • Analysis - Identifying patterns in vulnerability, migration, or code quality data
  • Visualization - Creating Sankey diagrams, bar charts, treemaps, and tables
  • Report generation - Building markdown-based slide decks with Marp

The skill knows which recipes produce useful data tables for impact analysis, including DependencyVulnerabilityCheck for security, UpgradeToJava25 for migration scope, and CommonStaticAnalysis for code quality.

Workflow example​

The skills work together to support the full recipe lifecycle:

  1. Create a working set with create-organization to find Spring Boot repositories
  2. Write a recipe with create-recipe to migrate a deprecated API
  3. Test iteratively with run-recipe until the recipe matches expected files
  4. Generate a report with analyze-impact showing migration scope across teams

Keeping skills up to date​

The skills are bundled with the CLI. When you upgrade the CLI, run the install command again to sync:

mod config agent-tools install

This ensures the agent tools stay current as CLI capabilities evolve.

Next steps​