spring-boot-skills

Production-grade Spring Boot skills for Claude Code and Codex. Drop a skill into your project and your AI coding agent instantly understands your architecture, patterns, and conventions.

Quick Start · Skills Catalog · Before / After · Skill Anatomy · Contributing

---

Why this exists

AI coding agents are great at Python. They hallucinate in Spring Boot.

They generate @Autowired field injection instead of constructor injection. They use ResponseEntity<?> where you have a standard response wrapper. They ignore your existing exception hierarchy and invent a new one. They don't know your project uses Flyway, so they generate schema SQL by hand. They emit pre-GA Spring AI artifact names that no longer exist in Maven Central.

Skills fix this. A skill is a markdown file your agent reads before touching your code. It tells the agent your conventions, your stack, your gotchas — not generic Spring Boot from 2020.

flowchart LR
    A["💬 You ask:<br/>&quot;add an orders endpoint&quot;"] --> B{Agent matches<br/>skill triggers}
    B -->|"REST code?"| C["📜 rest-api-conventions"]
    B -->|"persistence?"| D["📜 spring-data-jpa"]
    C --> E["🤖 Agent codes with<br/>YOUR envelope, YOUR<br/>status mapping, YOUR<br/>pagination contract"]
    D --> E
    E --> F["✅ Code that looks like<br/>your team wrote it"]

    style A fill:#0f172a,stroke:#38bdf8,color:#e2e8f0
    style B fill:#1e293b,stroke:#94a3b8,color:#e2e8f0
    style C fill:#10241a,stroke:#6DB33F,color:#a7f3d0
    style D fill:#10241a,stroke:#6DB33F,color:#a7f3d0
    style E fill:#0f172a,stroke:#d97757,color:#e2e8f0
    style F fill:#10241a,stroke:#6DB33F,color:#a7f3d0

This repo is a collection of battle-tested skills. Copy, adapt, drop in.

---

🧠 Concepts

Concept	Description
Skills	Markdown files loaded into Claude Code or Codex context — tell the agent how to work in your codebase
CLAUDE.md / AGENTS.md	Project-level persistent memory — your agent's onboarding doc
MCP Java SDK	Official Java SDK for building MCP servers — connect your Spring Boot app to any AI agent
Marketplace plugins	Versioned Claude Code and Codex packages for all Boot 3 or Boot 4 skills
Project templates	Ready-to-adapt CLAUDE.md and AGENTS.md guidance for Boot 3 and Boot 4 projects
Planned workflows	Repeatable commands such as /generate-endpoint, /write-test, and /db-migrate are listed in the roadmap

---

📦 Skills

The catalog ships in two version trees — pick the folder that matches your stack. Shared topics normally have both flavors; genuinely version-specific topics may live only in the relevant tree.

Folder	Target stack	Compatibility baseline
skills/spring-boot-4/	Spring Boot 4.x · Spring Framework 7 · Spring Security 7 · Spring Batch 6 · Jackson 3 · Spring AI 2.0	Java 17+; examples use Java 21; Boot 4.0.x and 4.1.x
skills/spring-boot-3/	Spring Boot 3.x · Spring Framework 6 · Spring Security 6 · Spring Batch 5 · Jackson 2 · Spring AI 1.x	Java 17+; examples use Java 21

Drop any skill folder into your agent's skills directory. Claude Code users can copy them to .claude/skills/; Codex users can adapt the same SKILL.md folders for .codex/skills/. The catalog below links to the Spring Boot 4 versions — swap spring-boot-4 for spring-boot-3 in any path if you're still on Boot 3.

The version guidance follows the Spring Boot 4 system requirements, the Spring Boot 4 migration guide, and Spring AI's compatibility guidance. Check the official release notes before upgrading a project.

Fast-moving integrations were last verified in August 2026 against Spring Boot 4.1, Spring AI 2.0, MCP Java SDK 2.0, Spring Cloud 2025.1, and Spring Cloud Gateway 5.0. Keep BOM-managed dependency versions together and recheck the linked official sources before adopting a newer release line.

Configuration

Skill	Description	Tags
configuration-properties	Typed binding, startup validation, duration units and secret handling.	configuration validation

🏗️ Architecture

Skill	Description	Tags
layered-architecture	Enforces Controller → Service → Repository separation. Prevents business logic leaking into controllers or repositories.	architecture
hexagonal-architecture	Ports and adapters pattern for Spring Boot. Keeps domain clean of framework dependencies.	architecture ddd
domain-driven-design	Aggregates, value objects, domain events with commit-safe publication. Includes JPA mapping conventions.	ddd jpa
multi-module-maven	Parent POM conventions, shared BOM, inter-module dependency rules. Prevents circular deps.	maven architecture
spring-modulith	Module boundaries, verification and durable event publication.	architecture modulith
multi-tenancy	Tenant resolution, database/schema isolation, tenant-aware persistence, caches, jobs, and migrations.	architecture security data

🔌 API Design

Skill	Description	Tags
rest-api-conventions	Your project's response envelope, error codes, pagination contract, versioning strategy. Fill in the template.	rest api
openapi-first	Generate controllers and DTOs from OpenAPI spec. Uses openapi-generator-maven-plugin.	openapi codegen
problem-details-rfc9457	RFC 9457 compliant error responses with Spring's ProblemDetail. Replaces ad-hoc error envelopes.	error-handling rest
idempotency-patterns	Concurrent retries, scoped request keys, replay and transaction boundaries.	api transactions
hateoas	Spring HATEOAS link building conventions. Teaches agent when and how to add hypermedia links.	hateoas rest

🌐 Edge & Reactive

Skill	Description	Tags
spring-cloud-gateway	Secure route design, header hygiene, timeouts, rate limits, retries, and release-train compatibility.	gateway spring-cloud security
webflux-reactive-patterns	Non-blocking WebFlux, Reactor context, R2DBC, backpressure, cancellation, and reactive tests.	webflux reactor r2dbc

🗄️ Data & Persistence

Skill	Description	Tags
spring-data-jpa	Boot 4 JPA with Hibernate 7: entity modeling, Jakarta imports, relationships, projections, N+1 prevention, keyset pagination, and batch writes.	jpa hibernate
flyway-migrations	Migration naming convention, safe multi-step schema changes, team workflow for concurrent migrations.	flyway migrations
spring-data-redis	Cache-aside pattern, key naming, TTL strategy, stampede protection, serialization config.	redis caching
transactional-patterns	@Transactional propagation rules, self-invocation pitfall, after-commit side effects, saga pattern.	transactions

📨 Messaging

Skill	Description	Tags
event-driven-messaging	Kafka/RabbitMQ/Pulsar/JMS contracts, idempotent consumers, outbox delivery, retries, and dead letters.	messaging kafka rabbitmq

⚙️ Batch & Jobs

Skill	Description	Tags
spring-batch	Spring Batch 6 chunk jobs, JDBC versus resourceless repositories, JobOperator, restartability, reader sort/thread-safety, and transaction boundaries.	batch etl

🚀 Migration & Deployment

Skill	Description	Tags
spring-boot-migration	Staged Boot 3.5 → 4 migration covering modular starters, Jackson 3, tests, servers, and verification.	migration spring-boot-4
container-native-deployment	Buildpacks, layered OCI images, JVM containers, GraalVM native images, AOT hints, and probes.	containers graalvm aot

🧰 Framework 7 Core

Skill	Description	Tags
api-versioning	Spring Framework 7 built-in API versioning: mapping versions, central request resolution, defaults, supported versions, and deprecation headers.	rest api versioning
http-interface-clients	Boot 4 declarative HTTP clients with @ImportHttpServices, grouped base URLs/timeouts, and RestClient versus WebClient selection.	http clients
null-safety	JSpecify nullability for Framework 7: @NullMarked, @Nullable, generic and array positions, Kotlin interop, and NullAway.	null-safety jspecify