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/>"add an orders endpoint""] --> 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 |
| Planned workflows | Repeatable commands such as /generate-endpoint, /write-test, and /db-migrate are listed in the roadmap |
📦 Skills
Every skill ships in two flavors — pick the folder that matches your stack:
| 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.
🏗️ 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 |
🔌 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 |
| hateoas | Spring HATEOAS link building conventions. Teaches agent when and how to add hypermedia links. | hateoas rest |
🗄️ Data & Persistence
| Skill | Description | Tags |
|---|
| spring-data-jpa | Entity conventions, N+1 prevention, projections, keyset pagination, batch inserts. | 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 |
⚙️ Batch & Jobs
| Skill | Description | Tags |
|---|
| spring-batch | Spring Batch chunk jobs — builder API (no JobBuilderFactory), restartable & idempotent job parameters, reader sort/thread-safety, fault tolerance, chunk transaction boundaries. | batch etl |
🔒 Security
| Skill | Description | Tags |
|---|
| spring-security-jwt | JWT auth filter chain, access and refresh token validation, RBAC with method security. Opinionated starting point. | security jwt |
| oauth2-resource-server | OAuth2 resource server config, JWT claim extraction, scope-based authorization. | security oauth2 |
🤖 AI & MCP
| Skill | Description | Tags |
|---|
| spring-ai-integration | Spring AI ChatClient, chat memory, RAG pipeline, structured output. Real GA artifact names — no dead pre-GA coordinates. | spring-ai llm |
| mcp-server | Build MCP servers with the official Java SDK 1.0 + Spring AI starters. Tool registration, transports, stdio pitfalls. | mcp ai-agents |
| ai-observability | Token usage tracking, latency monitoring, prompt/response logging for Spring AI apps. | observability spring-ai |
🧪 Testing
| Skill | Description | Tags |
|---|
| testing-pyramid | Unit → Slice → Integration conventions. @WebMvcTest, @DataJpaTest, @MockitoBean, Testcontainers. | testing |
⚡ Quick Start
1. Prepare your coding agent
Install Claude Code if needed:
npm install -g @anthropic-ai/claude-code
If you use Codex, confirm the CLI or desktop app command is available:
codex --version
2. Drop a skill into your project
Claude Code:
PROJECT_DIR=/path/to/my-spring-app
mkdir -p "$PROJECT_DIR/.claude/skills"
# Spring Boot 4 project
cp -r skills/spring-boot-4/rest-api-conventions "$PROJECT_DIR/.claude/skills/"
cp -r skills/spring-boot-4/spring-data-jpa "$PROJECT_DIR/.claude/skills/"
# Spring Boot 3 project — same skills, Boot 3 flavor
cp -r skills/spring-boot-3/rest-api-conventions "$PROJECT_DIR/.claude/skills/"
Codex:
PROJECT_DIR=/path/to/my-spring-app
mkdir -p "$PROJECT_DIR/.codex/skills"
# Spring Boot 4 project
cp -r skills/spring-boot-4/rest-api-conventions "$PROJECT_DIR/.codex/skills/"
cp -r skills/spring-boot-4/spring-data-jpa "$PROJECT_DIR/.codex/skills/"
# Spring Boot 3 project — same skills, Boot 3 flavor
cp -r skills/spring-boot-3/rest-api-conventions "$PROJECT_DIR/.codex/skills/"
Run these commands from the root of this repository, or replace skills/ with the path to your
local clone.
3. Tell your agent what you want
claude
> Generate a CRUD endpoint for the Order entity following our REST conventions
or:
codex
> Generate a CRUD endpoint for the Order entity following our REST conventions
That's it. Your agent reads the skill before writing a single line.
⚔️ Before / After
The value of these skills is not generic Spring Boot advice. The value is preventing the small mistakes AI agents make when they do not know your backend conventions.
@RestController
public class OrderController {
@Autowired
private OrderRepository repository;
@PostMapping("/orders")
public ResponseEntity<?> create(
@RequestBody Order order) {
return ResponseEntity.ok(
repository.save(order));
}
}
@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor
class OrderController {
private final OrderService orderService;
@PostMapping
ResponseEntity<ApiResponse<OrderResponse>> create(
@Valid @RequestBody CreateOrderRequest request) {
OrderResponse response = orderService.create(request);
return ResponseEntity.status(HttpStatus.CREATED)
.body(ApiResponse.ok(response));
}
}
- Business logic leaks into the controller
- No request DTO or validation boundary
- Repository called directly from the web layer
- Response shape ignores project conventions
- Status codes left to framework defaults
- Controller as a pure HTTP adapter
- Service owns the business rules
- DTO validation at the boundary
- Consistent response envelope
- Correct
201 Created semantics
📐 Skill Anatomy
Every skill in this repo follows the same structure:
skills/spring-boot-4/rest-api-conventions/
├── SKILL.md ← the skill: trigger description + conventions + gotchas
├── examples/ ← good and bad examples, side by side
│ ├── good-controller.java
│ └── bad-controller.java
└── templates/ ← copy-paste starting points
├── ApiResponse.java
└── GlobalExceptionHandler.java
SKILL.md has two critical parts:
---
name: rest-api-conventions
description: >
Use when generating REST controllers, response objects, DTOs, or error handlers.
Defines the project's response envelope, HTTP status mapping, and error code conventions.
---
## Conventions
...
The description is a trigger — write it as "use when [condition]", not as a summary. This is what makes the agent actually load the skill.
The Gotchas section at the bottom of each skill is the secret weapon: a running list of the exact mistakes agents make in that domain, phrased as Agent does X — do Y instead.
💡 Tips from the trenches
The Gotchas section is the most valuable part — add to it every time the agent does something wrong. Your future self will thank you.
Don't describe what Spring Boot already knows. Skills should push your agent out of its default behavior, not repeat the docs.
Be opinionated about your project. Generic Spring Boot best practices belong in a blog post. Skills belong in your agent skills folder.
Fork this repo and customize. Every team's conventions are different. These are starting points, not gospel.
Combine with CLAUDE.md. CLAUDE.md is for project-level memory (build commands, test runner, key architecture decisions). Skills are for domain-specific coding patterns.
| Anti-pattern | Fix |
|---|
| Giant SKILL.md with everything | Split into focused skills, one concern each |
| "Always use constructor injection" | Already a strong agent default — skip it |
| No examples | Add a good.java and bad.java — the contrast is what teaches |
| Prescriptive step-by-step instructions | Give goals and constraints, let agent decide how |
| Never updating | Add a Gotchas section, update it when agent fails |
🔥 Hot: MCP Server Skill
The mcp-server skill is the most powerful one here.
It teaches your agent to build production-ready MCP servers on MCP Java SDK 1.0 and the Spring AI GA starters — the same protocol used by Claude, Cursor, VS Code, and every major AI coding tool.
The MCP skill distinguishes native MCP annotations such as @McpTool from Spring AI model
tool-calling annotations such as @Tool. Use the native MCP path when exposing server tools.
// What the agent generates with the skill loaded —
// real GA API: spring-ai-starter-mcp-server + annotation scanning
@Component
public class OrderMcpTools {
private final OrderService orderService;
@McpTool(name = "get_order",
description = "Get a single order by ID including all line items and status history")
public OrderResponse getOrder(
@McpToolParam(description = "UUID of the order", required = true) String orderId) {
return OrderResponse.from(orderService.findById(UUID.fromString(orderId)));
}
}
Without the skill, the agent guesses: dead pre-GA artifact names, SDK 0.9.0 APIs, System.out logging that corrupts the stdio transport — or it gives up and writes Python.
🗺️ Roadmap
🤝 Contributing
Skills get better with real-world use. If you find a gap — the agent did something stupid in your Spring Boot project — open a PR and add it to the Gotchas section of the relevant skill.
Before opening a PR, run:
bash scripts/validate-skills.sh
The validation script checks both version trees, front matter, README catalog paths, and required
skill sections.
1. Fork the repo
2. Copy an existing skill as a template
3. Fill in conventions, examples, gotchas
4. PR with a one-line description of what problem it solves
🛠️ More from the same workbench
| Repo | Description |
|---|
| Hatch | Multi-module background job library for Spring Boot — REST polling, retry, Redis/JDBC backends, SSE dashboard |
| SpringPulse | Runtime observability for @Scheduled methods — AOP interception, WebSocket dashboard |
| rest-api-generator | CLI that scaffolds Spring Boot REST APIs from plain English prompts |
If a skill saved your agent from writing @Autowired field injection today — ⭐ star the repo.
spring-boot · java · claude-code · codex · mcp · spring-ai · skills · developer-tools
Built by @rrezartprebreza · Pristina, Kosovo
LinkedIn
