How to use the Java Architect agent skill (java-architect)

What does the java-architect skill make the agent do?

An agent skill is a folder with a SKILL.md file that the agent reads when a task matches the skill's description. This one is triggered by work on enterprise Java applications with Spring Boot 3.x, microservices, or reactive programming. Once loaded, it shapes the agent's output toward reactive WebFlux endpoints, tuned JPA queries (for example avoiding N+1 fetches), Spring Security with OAuth2/JWT, and tests with JUnit 5 and Testcontainers aiming for 85%+ coverage.

The skill also includes reference notes the agent loads on demand for Spring Boot setup, reactive code, data access, security, and testing.

• Project structure and modern pom.xml guidance for Spring Boot 3.2
• WebFlux controllers that return Mono and Flux
• JPA entity design, JOIN FETCH queries, and projections
• OAuth2/JWT resource server configuration with a SecurityFilterChain
• JUnit 5, Testcontainers and Mockito test patterns

How do you install the java-architect skill?

Download the ZIP for this skill from this page and unzip it. You can install it in one of two places: your personal skills folder, or a single project's skills folder.

For a personal install, unzip into ~/.claude/skills/. For a project-only install, unzip into the project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with a natural request?

You do not need a special command. Describe a Java or Spring task in plain language and mention Spring Boot, JPA, WebFlux, Spring Security, or microservices. The skill's description matches requests like these, so the agent is more likely to load it.

Be specific about the project. The skill works best when the agent can see your pom.xml or build.gradle and the module you want changed.

• "Add a WebFlux endpoint that returns an order by ID in our Spring Boot 3 service."
• "This JPA query on orders is slow. Find the N+1 problem and fix it."
• "Configure OAuth2 JWT resource server security for our API and keep /actuator/health public."
• "Why is my Spring Security filter chain rejecting valid tokens?"

What do you need before using it?

The skill expects a Java 21 environment with Maven or Gradle, an existing Spring Boot 3.x project, and an agent that can run shell commands. Its workflow depends on running the build: ./mvnw verify -pl <module> for data-layer checks, ./mvnw verify for security and full checks, or ./gradlew check for Gradle projects.

The skill's workflow asks the agent to check JaCoCo coverage at target/site/jacoco/index.html when coverage is below 85%.

• Java 21 and Maven or Gradle
• A Spring Boot 3.x project
• An agent that can run shell commands

What are the safety notes for scripts and network use?

The skill runs scripts, so it can execute build commands in your project. It does not use the network, according to its listing. Review what the agent runs before approving it, especially in shared or production repositories.

The generated security configuration is a starting point, not a finished decision. The example disables CSRF and uses stateless JWT sessions. A qualified engineer should review these choices before production use.

• Runs scripts: yes. Uses network: no.
• Check generated SecurityFilterChain code, especially CSRF and session settings.
• Never hardcode secrets; the skill's own rules say to externalize configuration.

What does a typical session look like?

Start with a clear request and let the agent analyze the project first. The skill's workflow begins with architecture analysis, then domain design, implementation, data layer, security, and quality checks. For a JPA problem, expect the agent to inspect the entity and repository, propose a JOIN FETCH or projection query, and then run the module build to confirm the query.

If tests fail, the skill tells the agent to review Hibernate SQL logs for data-layer issues, and to check SecurityFilterChain bean order and token validation config for security issues. Re-run the build after each fix.

What tips help you get better results?

Give the agent your Spring Boot version and module layout. Keep requests to one concern, such as one endpoint or one slow query. Ask for tests along with the code, since the skill's output format includes test classes and an explanation of architectural decisions.

• Name the module with -pl so the agent runs a focused build.
• Ask for the JpaRepository query and a test together.
• Ask the agent to explain why it chose a fetch strategy or security setting.