At Moderne, we’re exploring how far coding agents can go toward becoming expert OpenRewrite recipe authors, capable of writing structured, testable, working recipes.
Writing OpenRewrite recipes turns out to be a great use case for generative AI. When they can be declarative, recipes are highly composable. When they need to be imperative, they’re deeply structured, built around known patterns like visitors and templates. And because every recipe can be backed by before-and-after tests, they’re easily testable, keeping AI as honest as possible. But as we discovered in our first attempts to write an OpenRewrite recipe with Claude Code, even the best models still need coaching.
It left us wondering: how much better could Claude be at writing OpenRewrite recipes if we had a way to teach it the right way to do things once, and reuse that knowledge across every session?
It turns out, there is a way. Claude Skills are reusable pieces of knowledge—text instructions, scripts, or reference files—that can be pulled in as needed.
Where AI falters in recipe writing
Even though OpenRewrite recipes are structured and testable, and we’ve seen that Claude can generate working versions, getting the model to actually produce high-quality output isn’t so straightforward. We saw that Claude Code didn’t follow all of our best practices, and it wasn’t aware of things like scanning recipes or language directives in tests. It also struggled with knowing when to use declarative YAML versus imperative Java.
Anthropic offers a few ways to “teach” Claude:
- Prompt with specific direction (like “be more idiomatic with OpenRewrite recipes”)
- Include a
CLAUDE.mdfile with a repo - Create subagents
- Build plugins and slash commands
- Use Claude Skills for reusable guidance
We’d already been using CLAUDE.md pretty regularly, but it’s typically tied to individual repositories, so it didn’t scale as well for cross-project use. We also tried building a recipe-authoring subagent, but that didn’t work as well as we’d hoped. Overloaded terms like “trait” confused Claude, and it continued to repeat the same common mistakes that humans do when first learning to build recipes, like forgetting to use preconditions or trying to directly mutate the LST.
Claude Skills looked like a better fit. Instead of repeating instructions every session or per repo, we could encode our conventions once and reuse them everywhere.
Claude Skills and progressive disclosure
What makes Claude Skills especially interesting is how they use progressive disclosure.
Despite good documentation and lots of examples, it can still be a lot for any model to hold in context. And that lack of retained knowledge often looked to be the source of the limitations we were running into. But with progressive disclosure, Claude reads only what it needs, when it needs it, instead of trying to cram everything into a prompt, meaning it can manage context much more efficiently. A Skill is just a bundle of text instructions, optionally supported by things like scripts and reference templates, that get loaded contextually as the task unfolds.
Skills are also easy to maintain. Because it’s just text, the skill can live alongside your codebase and documentation. You can version it, improve it, and share it across teams. For us, that meant we could start small and iterate, just like we do with recipes!
What we’ve learned since
Since originally publishing this post, we’ve taken everything we learned about guiding Claude and turned it into something more robust: skills built directly into the Moderne CLI. That means no more separate setup, and a much more accessible starting point for AI-assisted recipe authoring.
The skills now support key parts of the broader workflow too, like running recipes at scale, analyzing impact, and setting up target repositories for testing. Together, they streamline the full loop from authoring to execution.
And they’re not limited to Claude. Any agent that supports skill-based instruction can take advantage of these same workflows. The skills are implemented in plain Markdown, versioned alongside the CLI, and reusable by any agent capable of following structured instructions. They’re portable, inspectable, and composable—just like the OpenRewrite recipes they help build and run.
Here’s how it works now.
Moderne Skills, now built into the CLI
When we set out to integrate AI assistance into recipe development, we faced a classic challenge: how do you teach an AI to work with a specialized domain like OpenRewrite? The answer turned out to be surprisingly elegant—we built skills directly into the Moderne CLI that teach Claude Code and other coding agents exactly how to work with recipes.
The problem with generic AI assistance
OpenRewrite recipes are powerful but nuanced. They manipulate Lossless Semantic Trees (LSTs), follow specific visitor patterns, and require careful attention to immutability. Generic AI tools often stumble on these patterns, taking a while to figure them out or missing some subtleties.
We needed the agent to understand the specific idioms and patterns that make OpenRewrite recipes work correctly.
Four skills, one workflow
The Moderne plugin for Claude Code installs with a single command:
mod config moderne skills update
This gives agents four complementary skills that cover the complete recipe development lifecycle.
Creating recipes
The /moderne:create-recipe skill teaches Claude when to use declarative YAML composition versus Refaster templates versus full imperative Java recipes. It understands the trade-offs: YAML is simpler for combining existing recipes, Refaster provides type-safe pattern matching for expression replacements, and imperative recipes handle complex conditional logic.
When you're building a new recipe, Claude guides you through the decision tree. It knows that maybeAddImport() should pair with JavaTemplate, that visitors should always call super.visitX() to continue traversal, and that LST nodes are immutable.
The skill also covers testing with the RewriteTest framework, showing Claude how to structure before/after assertions and verify that recipes make no changes when they shouldn't.
Running recipes at scale
Once you have a recipe, the /moderne:run-recipe skill handles the mechanics of testing it against real code. It sets up a working set from a Moderne organization, manages the active recipe configuration, and parses the streaming output to show you exactly what changed.
The workflow is iterative by design. Make changes to your recipe, recompile, run again—the skill handles the loop while you focus on the transformation logic. For Moderne employees developing the CLI itself, it even detects when a local build is newer than the installed version and uses that instead.
Understanding impact
The /moderne:analyze-impact skill addresses a question that comes up after every large-scale migration: what actually happened? It starts by discovering what recipe runs are already available using mod audit runs list, so you don't need to re-run recipes just to analyze their results.
If no suitable data exists, the skill suggests impactful recipes to run—vulnerability checks, code quality scans, migration dry-runs—drawing from the Proof of Value recipes that demonstrate OpenRewrite's capabilities.
From there, it guides data aggregation with mod study, visualization choices (Sankey diagrams for change flow, treemaps for hierarchical data), and report generation. The result is executive-ready analysis that answers questions like "which teams own the most vulnerable code?" or "what's the realistic effort for this migration?"
Creating Organizations
Before running recipes at scale, it's helpful to target a specific set of repositories for testing or analysis. The /moderne:create-organization skill helps Claude define a custom set of repositories to run recipes against. It guides the process of searching for relevant repos by language, framework (like Spring Boot, Kafka, JPA), or platform across GitHub and other sources. The skill then generates a correctly structured repos.csv file and organizes it by team, technology, or business domain to support targeted testing. Once defined, the skill can sync the selected repositories and set the context for running recipes or analyzing impact.
Skills that stay current
The plugin version matches the CLI version. When we improve a workflow or add a new pattern, running mod config moderne skills update refreshes everything. The instructions the agent follows always correspond to the commands that actually exist, eliminating a whole category of "that flag doesn't exist anymore" errors.
Skills are also inspectable. You can read the Markdown files that the skills install to see exactly what the agent knows. If something seems wrong, you can see why.
Getting started
Install the Moderne CLI, then run:
mod config moderne skills update
From there, in Claude Code, try /moderne:create-recipe when you're building something new, /moderne:create-organizationand /moderne:run-recipe when you're ready to test it, and /moderne:analyze-impact when you need to understand what your recipes found or changed.
The skills build on each other, but each stands alone. You can jump straight to impact analysis on existing recipe runs, or run a catalog recipe without ever writing one yourself. The plugin adapts to wherever you are in the workflow.
Want to learn more about writing OpenRewrite recipes? Check out our training course about teaching AI to write OpenRewrite recipes.
