rrezartprebreza/spring-boot-skills

---

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:"add an orders endpoint""] --> B{Agent matchesskill triggers}
    B -->|"REST code?"| C["📜 rest-api-conventions"]
    B -->|"persistence?"| D["📜 spring-data-jpa"]
    C --> E["🤖 Agent codes withYOUR envelope, YOURstatus mapping, YOURpagination contract"]
    D --> E
    E --> F["✅ Code that looks likeyour 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

---

📦 Skills

Every skill ships in two flavors — pick the folder that matches your stack:

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

🔌 API Design

🗄️ Data & Persistence

⚙️ Batch & Jobs

🧰 Framework 7 Core

🔒 Security

🤖 AI & MCP

🧪 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.

Install from the Claude Code marketplace

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.

Install as a Codex plugin

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.

---

⚔️ 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.

---

📐 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.

---

🔥 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

• [x] Skills for Spring Batch
• [x] Spring Boot 4 versions of all 23 skills (skills/spring-boot-4/)
• [ ] Skills for Spring Cloud Gateway
• [ ] Skills for Spring WebFlux / reactive patterns
• [ ] Skills for multi-tenancy
• [ ] CLAUDE.md template for Spring Boot projects
• [ ] /generate-endpoint command
• [ ] /write-test command
• [ ] /db-migrate command
• [ ] Integration with Hatch background job library
• [ ] Integration with SpringPulse observability

---

🤝 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

---