rrezartprebreza/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

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.

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.

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.

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.

For persistent project guidance, start from the matching templates:

# Codex, Spring Boot 4
cp templates/spring-boot-4/AGENTS.md "$PROJECT_DIR/AGENTS.md"

# Claude Code, Spring Boot 4
cp templates/spring-boot-4/CLAUDE.md "$PROJECT_DIR/CLAUDE.md"

Boot 3 equivalents live under templates/spring-boot-3/. Adapt commands and conventions to the project rather than using the templates unchanged.

This repository also exposes two marketplace plugins without duplicating the skill files:

claude plugin marketplace add rrezartprebreza/spring-boot-skills
claude plugin install spring-boot-4-skills@spring-boot-skills
# or for a Boot 3 project:
claude plugin install spring-boot-3-skills@spring-boot-skills

The marketplace manifest is .claude-plugin/marketplace.json. Validate it locally with claude plugin validate .. The repository can be submitted to Anthropic's Claude Code community marketplace; approval is a separate review step. GitHub Marketplace is intended for GitHub Apps and Actions, so this skills repository should use GitHub releases and the Claude marketplace instead.

Codex uses its own plugin manifest and marketplace catalog. Add this repository and install the version that matches your application:

codex plugin marketplace add rrezartprebreza/spring-boot-skills
codex plugin add spring-boot-4-skills@spring-boot-skills
# or for a Boot 3 project:
codex plugin add spring-boot-3-skills@spring-boot-skills

The Codex package metadata lives in .agents/plugins/marketplace.json and the two plugin manifests under plugins/. Direct copying into .codex/skills/ remains supported for projects that do not use plugins.

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.

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));
    }
}

Every skill in this repo follows the same structure:

skills/spring-boot-4/rest-api-conventions/
├── SKILL.md          ← the skill: trigger description + conventions + gotchas
├── agents/
│   └── openai.yaml   ← Codex skill-list metadata and default prompt
├── 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.

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 or AGENTS.md. Project guidance stores build commands, verification, and architecture decisions. Skills provide reusable domain-specific workflows.

The mcp-server skill is the most powerful one here.

It teaches your agent to build production-ready MCP servers on MCP Java SDK 2.x and the Spring AI 2.0 starters - the same protocol used by Claude, Codex, Cursor, VS Code, and other major AI coding tools.

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, removed SDK constructors, @Tool instead of native @McpTool, or System.out logging that corrupts stdio transport.

• Skills for Spring Batch
• Spring Boot 4 versions of all 33 skills (skills/spring-boot-4/)
• Skills for Spring Cloud Gateway
• Skills for Spring WebFlux / reactive patterns
• Skills for multi-tenancy
• Spring Boot 3 → 4 migration skill
• Production observability skill
• Event-driven messaging skill
• Container and native deployment skill
• CLAUDE.md and AGENTS.md templates for Boot 3 and Boot 4
• /generate-endpoint command
• /write-test command
• /db-migrate command
• Integration with Hatch background job library
• Integration with SpringPulse observability

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, install the validator dependency in a virtual environment and run:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r scripts/requirements.txt
bash scripts/validate-skills.sh

The validator parses YAML safely, rejects duplicate keys, and checks both version trees, metadata, README links and marketplace packaging. There are 33 topics with Boot 3 and Boot 4 variants.

The behavior fixture compiles the shipped JWT, Problem Details, pagination and configuration templates. Its tests cover token/account rejection, HTTP error contracts, configuration startup validation, and JPA/Flyway against PostgreSQL. CI runs Boot 3.5 and Boot 4.1 with Java 17 and 21. The MCP compilation fixture remains separate. This is targeted coverage, not a claim that every example in the catalog has executable tests.

Agent evaluations provide repeatable prompts and review criteria for Claude Code and Codex. Transcript collection and human review are separate from CI validation; a successful model invocation is not a benchmark pass.

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