Dev MCP: Add initial skill files for 11 core extensions

[phillip-kruger]

Adds quarkus-skill.md files and description fields in quarkus-extension.yaml
for 11 core extensions, providing AI coding agents with extension-specific patterns,
testing guidelines, and common pitfalls.

Extensions included: ArC, RESTEasy Reactive (REST), Hibernate ORM Panache,
REST Client, Hibernate ORM, OIDC, Hibernate Validator, Scheduler, Security,
SmallRye OpenAPI, Web Dependency Locator.

Each skill file contains:

• Key API patterns and annotations
• Testing approaches with @QuarkusTest and Dev Services
• Common pitfalls that agents (and developers) frequently hit

Each deployment module gets a META-INF/quarkus-skill.md source file. No pom.xml
changes needed — the aggregate-skills goal (#53195) discovers all skill files
automatically.

Depends on #53195.

[holly-cummins]

Should we add this an expectation to the extension maturity matrix? Maybe as an advanced one?

[phillip-kruger]

Should we add this an expectation to the extension maturity matrix?

Yes, I think this fits well in the Advanced tier of the extension maturity matrix. It's not required for an extension to function, but it's a meaningful quality signal — similar to having good documentation and test coverage.

Something like:

AI coding skill — Provide a quarkus-skill.md with extension-specific patterns, testing guidelines, and common pitfalls for AI coding agents.

It's low effort (just a markdown file in deployment/src/main/resources/META-INF/, no build config needed), and not every extension needs one — simple or internal extensions can skip it. But for widely-used extensions it makes a real difference in how well AI agents generate correct code.

I'll open a follow-up PR to add it to the maturity matrix once this lands.

[cescoffier]

I think you will need to ask every extension owner, as I spotted a few inconsistencies.

[phillip-kruger]

I think you will need to ask every extension owner, as I spotted a few inconsistencies.

Maybe I should do a PR per extension... Else this might never get merged ....

[brunobat]

I think we have a problem in defining the target user for the skills.
Are these skills directed to:

• Someone fixing a bug in Quarkus?
• Someone adding a new functionality in Quarkus?
• Someone implementing a new service and needs to know how the extension works? (probably the current intent)

Once we have these files in, how we create skills with other usage purposes in the same paths?

Let me give you an example. I'd like to have a skill explaining how the OTel extension is structured and were the integration tests are, but I would also like to have a skill explaining how to implement a new instrumentation on an extension. This last one might include where are the semantic conventions to use, among other things.

There can be many skills for each extension depending on intent, how should we organize this?

[phillip-kruger]

Hi @brunobat

This is NOT:

Someone fixing a bug in Quarkus?
Someone adding a new functionality in Quarkus?

For these ^^^ two, see #53038

This skill file is for users building applications with Quarkus. I would also add skill file only where needed. So we test build an app without the skills and see where the agent struggle. We use the skill to fill those gaps. Agents already have access to the documentation too.

Having said that, if there is a requirement to support multiple skill (for the user) file per extension, I need to add that feature.

If you still believe we need that please open an issue and I can have a look at that. (This will be part of the DevStar work group)

[brunobat]

If you still believe we need that please open an issue and I can have a look at that. (This will be part of the DevStar work group)

Thanks for your reply. I think I'm good now.

[phillip-kruger]

@maxandersen w.d.y.t ? Is this a good start ?

[cescoffier]

Looking good! I've made a few relatively minor comments.

I still have one question: Should we add links to the reference guide for each extension as a resource?

[phillip-kruger]

Looking good! I've made a few relatively minor comments.

I still have one question: Should we add links to the reference guide for each extension as a resource?

Thanks @cescoffier - i'll address your comments soon. W.r.t above, we automatically add all the metadata in the final skill, that will contain the reference guide. See https://quarkus.io/version/main/guides/dev-mcp#extension-skills

[marko-bekhta]

Thanks 🙂
Added a few ideas for the Hibernate Validator file 🤞🏻

[quarkus-bot]

Status for workflow Quarkus CI

This is the status report for running Quarkus CI on commit 1c813d1.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

---

Flaky tests - Develocity

⚙️ JVM Tests - JDK 25

📦 extensions/vertx-http/deployment

❌ io.quarkus.vertx.http.filters.GracefulShutdownFilterTest.test - History

• Timeout waiting for response - java.lang.RuntimeException

Details

java.lang.RuntimeException: Timeout waiting for response
	at io.quarkus.vertx.http.filters.GracefulShutdownFilterTest.testWithVertxHttpClientAndHttp2AfterShutdown(GracefulShutdownFilterTest.java:85)
	at io.quarkus.vertx.http.filters.GracefulShutdownFilterTest.test(GracefulShutdownFilterTest.java:59)

---

⚙️ JVM Integration Tests - JDK 25 Semeru

📦 integration-tests/reactive-messaging-hibernate-orm

❌ io.quarkus.it.kafka.KafkaConnectorTest.testPets - History

• 1 expectation failed. Expected status code is <204> but was <500>. - java.lang.AssertionError

Details

java.lang.AssertionError: 
1 expectation failed.
Expected status code is <204> but was <500>.

	at org.codehaus.groovy.vmplugin.v8.IndyInterface.fromCache(IndyInterface.java:344)
	at io.restassured.internal.ResponseSpecificationImpl$HamcrestAssertionClosure.validate(ResponseSpecificationImpl.groovy:516)
	at org.codehaus.groovy.vmplugin.v8.IndyInterface.fromCache(IndyInterface.java:344)
	at io.restassured.internal.ResponseSpecificationImpl.validateResponseIfRequired(ResponseSpecificationImpl.groovy:714)