Draft of the Empower your AI migrations to Quarkus with Skills blog

_data/authors.yaml

@@ -353,6 +353,13 @@ aureamunoz:
   job_title: "Senior Software Engineer"
   twitter: "auritamh"
   bio: "Works on Quarkus and SmallRye at Red Hat"
+cmoulliard:
+  name: "Charles Moulliard"
+  email: "cmoulliard@ibm.com"
+  emailhash: "a13e1afd9920c8ae376d646061d1d8e2"
+  job_title: "Senior Principal Software Engineer"
+  twitter: "cmoulliard"
+  bio: "Open source contributor and technical leader working at IBM on Quarkus, Spring migration tooling, Kubernetes related projects."
 edeandrea:
   name: "Eric Deandrea"
   email: "eric.deandrea@ibm.com"

_posts/2026-05-26-ai-skills-migration.adoc

@@ -0,0 +1,199 @@
+---
+layout: post
+title: 'Empower your AI migrations to Quarkus with Skills'
+date: 2026-06-03
+tags: ai, skill, agent, migrate-spring-to-quarkus
+synopsis: 'Empower your AI migrations to Quarkus with Skills. Transform your AI agent into a framework domain: dependencies, jpa, web, etc expert capable of migrating Spring applications.'
+author: cmoulliard
+---
+:imagesdir: /assets/images/posts/ai-skills-migration
+
+== What are Skills?
+
+https://agentskills.io/specification[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 https://github.com/quarkusio/skills[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.
+
+== Why use AI Skills for migration?
+
+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.
+
+== How we designed the migration Skill
+
+The https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus[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:
+
+[cols="20%,80%",options="header"]
+|===
+| Module | Responsibility
+
+| `jdk`
+| Enforce JDK 21+ compatibility
+
+| `build`
+| Migrate `pom.xml` or `build.gradle` -- swap Spring starters for Quarkus extensions, update plugins, adjust the BOM
+
+| `code`
+| Convert Spring annotations to their CDI/JAX-RS/Quarkus equivalents (`@Component`, `@Autowired`, `@RestController`, `@Repository`, etc.)
+
+| `frontend`
+| Migrate Thymeleaf or JSP views to Quarkus-compatible alternatives and update static resource paths
+
+| `testing`
+| Convert `@SpringBootTest` to `@QuarkusTest`, replace `@MockBean` with Quarkus mocking utilities
+
+| `cleanup`
+| Remove leftover Spring artifacts, unused imports, and stale configuration
+|===
+
+Each https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus/modules[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 https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus/references[reference] files help the AI model to better understand the transformations to apply:
+
+- `dependency-map.md` -- maps Spring Boot starters to their Quarkus extension equivalents
+- `annotation-map.md` -- maps Spring annotations to JAX-RS, CDI, and Quarkus annotations
+- `config-map.md` -- maps `application.properties` / `application.yml` keys between frameworks
+
+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).
+
+== How to run a Spring-to-Quarkus migration
+
+=== Step 1: Install the Skill
+
+We use https://claude.ai/download[Claude Code] as our agent in this walkthrough, but you can use any agent that supports Skills (Cursor, Windsurf, Cline, OpenCode and https://agentskills.io/clients[many others]).
+
+Install the migration Skill using https://github.com/vercel-labs/skills[`npx skills`]:
+
+[source,bash]
+----
+npx skills add quarkusio/skills --skill migrate-spring-to-quarkus
+----
+
+This downloads the Skill files into your project's `.claude/skills/` directory (for Claude Code). To install it globally so it is available across all your projects, add the `-g` flag:
+
+[source,bash]
+----
+npx skills add quarkusio/skills --skill migrate-spring-to-quarkus -g
+----
+
+TIP: You can also install all available Quarkus Skills at once with the command: `npx skills add quarkusio/skills`.
+
+=== Step 2: Start the migration
+
+Open a terminal and navigate to your Spring Boot project (Petclinic, TODO, etc) to be migrated and launch your agent.
+
+image::01-project-to-migrate.png[alt=Application to migrate, align=left, width=60%]
+
+TIP: Don't forget to configure the agent authentication mode using the API Key and/or subscription according to the provider before to launch it !
+
+Then ask the agent to start the migration using the following tailored prompt:
+
+[source]
+----
+claude "Migrate this Spring Boot project to Quarkus using the full migration strategy.
+        Work entirely within this directory.
+        Do a full migration — convert all source files, build files, config, and tests.
+        After migration, verify the project compiles with ./mvnw compile and fix any errors.
+        Then run ./mvnw test and fix any test failures.
+        If you need to delete code or files, explain why you are deleting them and what you are replacing them with.
+        If anything could not be converted/migrated explain why - do not just delete/remove it without explaining.
+        Include a summary of the migration in the end of the output."
+----
+
+NOTE: The https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus[migrate-spring-to-quarkus] skill supports 2 migration strategies: full - Quarkus native or https://quarkus.io/guides/#q=spring[Spring Compatibility].
+
+The agent selects the correct installed skill by matching the phrase 'Migrate this Spring Boot' from the user's prompt with the skill's description.
+
+.Skill invocation
+image::03-skill-invocation.png[alt="skill invocation",align=left, width=80%]
+
+=== Step 3: Analysis and strategy selection
+
+The agent first scans the application using different tools executed locally and presents to the user a summary:
+
+.AI analysis overview
+image::04-analysis-overview.png[alt="analysis overview",align=left, width=80%]
+
+NOTE: The summary includes the strategy defined part of the user's prompt to be executed. This means that AI will replace all Spring annotations with JAX-RS/CDI/Panache equivalents using the instructions of the modules: code, web, etc.
+
+=== Step 4: Module selection and execution
+
+As preamble to execute the set of the instructions, AI will report that it will now read the different "references" files and load the https://github.com/quarkusio/skills/blob/main/skills/migrate-spring-to-quarkus/SKILL.md#step-3-execute-modules[modules] to get the instructions:
+
+.Skill load the modules
+image::05-skill-load-modules.png[alt="skill load modules",align=left, width=80%]
+
+As mentioned at the beginning of the blog, the module's instructions will be selected only if the condition declared part of the GATE CHECK is passing.
+
+TIP: By looking to the "Gate result", you can immediately see which module has been selected and is currently processed
+
+.Gate JDK check
+image::06-gate-check.png[alt="Gate JDK check",align=left, width=70%]
+
+The agent populates a list of "check boxes" corresponding to the list of the modules and will change the symbols during the migration process.
+
+.Module Build System
+image::08-module-build-executed.png[alt="Module Build system",align=left, width=85%]
+
+Here are the messages that we got by example during the execution of the module "Code" where Spring annotations have been discovered within the java source files.
+
+NOTE: The messages will depend on the model selected and tokens window size !
+
+.Module Code
+image::07-module-code-executed.png[alt="Module code executed",align=left, width=95%]
+
+NOTE: The module "web" is optional if the application to be migrated don't include, thymeleaf files, jsp and/or JavaScript assets
+
+=== Step 5: Verification
+
+After all modules complete, the agent runs the verification https://github.com/quarkusio/skills/blob/main/skills/migrate-spring-to-quarkus/SKILL.md#step-4-verify-the-migration[instructions].
+The checks we are doing allow to verify if the application has been migrated, that we have a Quarkus application and that the application can be launched using: `mvn quarkus:dev`.
+
+.Verification checks
+image::09-verification-checks.png[alt="Verification checks",align=left, width=95%]
+
+=== Step 6: Launch your Quarkus application
+
+Your application is now a Quarkus project. Start it in dev mode:
+
+[source,bash]
+----
+mvn compile quarkus:dev
+----
+
+You should see the familiar Quarkus banner and your application running with live reload enabled:
+
+[source]
+----
+ --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
+ -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
+--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
+2026-06-03 11:30:03,129 INFO  [io.quarkus] (Quarkus Main Thread) app 0.0.1-SNAPSHOT on JVM (powered by Quarkus 3.33.2) started in 9.058s. Listening on: http://localhost:8081
+
+2026-06-03 11:30:03,130 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
+2026-06-03 11:30:03,131 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [agroal, cdi, compose, hibernate-orm, hibernate-orm-panache, jdbc-mysql, narayana-jta, qute, rest, rest-jackson, rest-qute, smallrye-context-propagation, vertx]
+----
+
+== Conclusion
+
+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.
+
+== Resources
+
+- https://github.com/quarkusio/skills[Quarkus Skills repository] -- the collection of Skills maintained by the Quarkus project
+- https://agentskills.io/specification[Agent Skills specification] -- the open standard defining the Skills format
+- https://github.com/vercel-labs/skills[npx skills CLI] -- the CLI tool for discovering and installing Skills
+- https://claude.ai/download[Claude Code] -- the AI agent used in this walkthrough