Skip to content

Add extension skills, server instructions, and CLAUDE.md generation#4

Merged
phillip-kruger merged 1 commit intoquarkusio:mainfrom
phillip-kruger:skills-and-instructions
Mar 26, 2026
Merged

Add extension skills, server instructions, and CLAUDE.md generation#4
phillip-kruger merged 1 commit intoquarkusio:mainfrom
phillip-kruger:skills-and-instructions

Conversation

@phillip-kruger
Copy link
Copy Markdown
Member

@phillip-kruger phillip-kruger commented Mar 25, 2026

Summary

Adds extension skill support, MCP server instructions, project-level CLAUDE.md generation, and a quarkus/update tool to improve how AI coding agents work with Quarkus projects.

Extension Skills (SkillReader)

  • Reads extension skills from the new aggregated quarkus-extension-skills JAR (one JAR per Quarkus version containing all composed SKILL.md files)
  • Auto-downloads the JAR from Maven repos if not in local .m2
  • Respects Maven mirror configuration from:
    • .mvn/maven.config (project-level custom settings file via -s)
    • ~/.m2/settings.xml (user-level mirrors)
    • ${MAVEN_HOME}/conf/settings.xml (global mirrors)
  • Handles mirrorOf patterns: central, *, external:*, comma-separated, !central exclusions
  • Skips download for SNAPSHOT versions (not on release repos)

Update Tool (quarkus/update)

New tool that checks if a Quarkus project is up-to-date and provides a unified upgrade report:

  • Detects build tool (Maven, Gradle, Gradle Kotlin DSL) and current Quarkus version
  • Fetches the latest available version from code-with-quarkus-compare tags
  • Compares build files against reference projects, highlighting meaningful differences
  • Runs quarkus update --dry-run (if CLI is available) to preview automated migrations and patches
  • Provides a link to the full structural diff between versions
  • Returns a unified report with recommended actions

Based on the quarkus-update skill.

MCP Server Instructions

Configures quarkus.mcp.server.server-info.instructions to direct AI agents to:

  • Use quarkus/update (via subagent) when starting work on existing projects
  • Use quarkus/skills before writing any code (extension-specific patterns and pitfalls)
  • Use quarkus/searchDocs over generic documentation tools (Context7, web search)
  • Use quarkus/callTool for testing via subagents
  • Follow the correct workflow: update → start → skills → docs → code → test

CLAUDE.md Generation

quarkus/create now generates a CLAUDE.md in every new project with:

  • Required workflow (update → skills → docs → searchTools → callTool)
  • Rules (extension-first, always test, keep README updated)
  • Testing instructions using subagents for non-blocking test execution

Other Improvements

  • Shortened tool descriptions for better readability
  • Auto-enables Dev MCP (-Dquarkus.dev-mcp.enabled=true) when starting apps
  • Updated dependency versions

Depends on (Quarkus core PRs)

@phillip-kruger phillip-kruger force-pushed the skills-and-instructions branch from 4058541 to 047ed7d Compare March 25, 2026 06:56
- SkillReader: reads extension skills from the aggregated
  quarkus-extension-skills JAR instead of per-extension deployment JARs.
  Auto-downloads from Maven repos if not in local .m2, respecting
  mirrors from ~/.m2/settings.xml, ${MAVEN_HOME}/conf/settings.xml,
  and .mvn/maven.config.

- Server instructions: configures quarkus.mcp.server.server-info.instructions
  to direct AI agents to use quarkus-agent tools (skills, searchDocs,
  callTool) over generic alternatives like Context7.

- CLAUDE.md generation: quarkus/create now generates a CLAUDE.md in every
  new project with Quarkus-specific workflow rules, including running
  tests via subagents for non-blocking test execution.

- DevMcpProxyTools: quarkus/skills tool updated to use the new
  SkillReader that reads from the single aggregated JAR.

Depends on:
- quarkusio/quarkus#53195 (aggregate-skills mechanism)
- quarkusio/quarkus#53196 (extension skill files)
- quarkusio/quarkus#53182 (one-shot testing)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@phillip-kruger phillip-kruger force-pushed the skills-and-instructions branch from 047ed7d to 3ee521b Compare March 25, 2026 08:50
@phillip-kruger phillip-kruger merged commit 314d30c into quarkusio:main Mar 26, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant