Empower your AI migrations to Quarkus with Skills

Skills are an open standard for packaging reusable instructions that teach AI coding agents how to perform specialized tasks. A Skill is simply a directory containing a SKILL.md file — a Markdown document with YAML header describing what it does and when to trigger it, followed by step-by-step instructions the agent must follow.

Skills follow a progressive disclosure model that optimizes context window usage across all installed skills: agents load only the metadata at startup, pull in the full instructions when the skill triggers, and fetch reference files on AI’s demand. This keeps context usage efficient while giving the agent deep domain knowledge exactly when it needs it.

The Quarkus project maintains its own collection of Skills in the quarkusio/skills repository. These Skills transform a general-purpose coding agent into a Quarkus expert, capable of creating projects, upgrading versions, and — as we will explore in this post — migrating entire Spring Boot applications to Quarkus.

Migrating an application from one framework to another is a task that is complex and require deep knowledge about the technology used. Consider a Spring Boot to Quarkus migration: you need to rewrite the maven or Gradle build file, swap annotations (@Autowired to @Inject, @RestController to JAX-RS resources), convert configuration properties, refactor the Web layer to move to Qute, and more. Each of these steps follows well-known mapping rules, but the sheer number of files and the subtle interactions between them make manual migration tedious and error-prone.

This is where AI agents shine — they can apply transformation rules across an entire codebase methodically. But a generic agent lacks the framework-specific knowledge to make the right choices. It might produce code that compiles but does not follow Quarkus development best practices, or it might miss a critical dependency swap.

Skills bridge that gap. By giving the agent a curated set of instructions, reference mappings, and gate checks, you get the best of both worlds: the tireless execution of an AI agent guided by the deep domain expertise encoded in the Skill. The result is a migration that is fast, consistent, and with few errors.

The migrate-spring-to-quarkus Skill uses a modular, domain-based approach with gate checks. Rather than one monolithic script, the migration is broken into independent modules, each responsible for a specific technical domain:

Each module follows the same disciplined cycle: Evaluate gate → Load reference files → Execute transformations → Compile → Verify. A module only runs if its gate condition is met.

For example, the frontend module is skipped entirely if the project has no Thymeleaf or JSP templates. If compilation fails after a module completes, the agent stops immediately — no cascading errors.

Different reference files help the AI model to better understand the transformations to apply:

This design ensures that the migration is transparent (every decision is documented), safe (the build is verified after each phase), and extensible (you can add new modules or override reference mappings for your specific project).

Skills turn your AI coding agent into a Java domain expert able to migrate Spring applications to Quarkus. Instead of relying on the general knowledge baked into a large language model (llm), using skills with reference files allows to give precise and curated instructions making the migration process straightforward even for more complex domains involving web parts.

For Spring-to-Quarkus migrations, this means every annotation swap, every dependency change, and every configuration mapping follows a verified playbook — with gate checks ensuring the build stays green at every step.

The modular, domain-based design also means you are not locked into a one-size-fits-all approach. You can customize reference mappings, add project-specific modules, or even write entirely new Skills for other migration scenarios.

We encourage you to try it on your own Spring Boot projects and share your feedback with the community.