spring-boot-skills

Production-grade Claude Code skills for Spring Boot developers

Drop a skill into your project. Your AI coding agent instantly understands your Spring Boot codebase — architecture, patterns, conventions — and codes like a senior engineer who's been on your team for years.

This is a practical collection of Claude Code skills that teach AI coding agents how to work inside real Spring Boot projects: architecture rules, REST conventions, persistence patterns, security, testing, Spring AI, and MCP server development.

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.

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.

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

GitHub description suggestion: Production-grade Claude Code skills for Spring Boot, Java, JPA, Flyway, Security, Spring AI, and MCP development.

🧠 CONCEPTS

📦 SKILLS

Drop any skill folder into .claude/skills/ in your project. Claude Code auto-discovers them.

🏗️ Architecture

🔌 API Design

🗄️ Data & Persistence

🔒 Security

🤖 AI & MCP

🧪 Testing

⚡ QUICK START

1. Install Claude Code (if not already)

npm install -g @anthropic-ai/claude-code

2. Drop a skill into your project

mkdir -p .claude/skills
cp -r spring-boot-skills/skills/rest-api-conventions .claude/skills/
cp -r spring-boot-skills/skills/spring-data-jpa .claude/skills/

3. Tell Claude to use it

claude
> Generate a CRUD endpoint for the Order entity following our REST conventions

That's it. Claude 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.

Without a skill

@RestController
public class OrderController {
    @Autowired
    private OrderRepository repository;

    @PostMapping("/orders")
    public ResponseEntity<?> create(@RequestBody Order order) {
        return ResponseEntity.ok(repository.save(order));
    }
}

Problems:

• Business logic leaks into the controller.
• No request DTO or validation boundary.
• Repository is called directly from the web layer.
• Response shape does not follow project conventions.
• Errors and status codes are left to framework defaults.

With layered-architecture + rest-api-conventions

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

The agent now follows the intended design: controller as HTTP adapter, service for business rules, DTO validation at the boundary, and consistent response contracts.

📐 SKILL ANATOMY

Every skill in this repo follows the same structure:

skills/rest-api-conventions/
├── SKILL.md          ← agent reads this (description + trigger conditions)
├── conventions.md    ← your actual conventions
├── examples/         ← good and bad examples
│   ├── good-response.java
│   └── bad-response.java
└── templates/        ← copy-paste starting points
    └── ResponseWrapper.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.

💡 TIPS (from the trenches)

Gotchas section is the most valuable — add every time the agent does something wrong. Your future self will thank you.

Don't describe what Spring Boot already knows. Skills should push Claude 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 .claude/ 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 using the official Java SDK — the same protocol used by Claude, Cursor, VS Code, and every major AI coding tool.

// What the agent generates with the skill loaded:
@Bean
public McpServer orderMcpServer(OrderService orderService) {
    return McpServer.sync(McpServerTransports.stdio())
        .serverInfo("order-service-mcp", "1.0.0")
        .tool(McpServerFeatures.SyncToolSpecification.builder()
            .tool(Tool.builder()
                .name("get_order")
                .description("Retrieve order by ID with full line items")
                .inputSchema(SchemaUtils.infer(GetOrderRequest.class))
                .build())
            .callHandler((exchange, args) -> {
                var req = ObjectMappers.map(args, GetOrderRequest.class);
                return new CallToolResult(orderService.findById(req.orderId()));
            })
            .build())
        .build();
}

Without the skill: the agent guesses the API, uses deprecated methods, or writes Python MCP code instead.

🗺️ ROADMAP

• Skills for Spring Batch
• 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.

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

OTHER REPOS

About

Skills for Spring Boot AI coding agents · Java 21 · Spring Boot 3.x · Claude Code · MCP Java SDK

Topics: spring-boot java ai-coding-agent claude-code mcp skills spring-ai developer-tools vibe-coding agentic-engineering

LinkedIn summary:

Built spring-boot-skills, a collection of production-grade Claude Code skills that help AI coding agents work more reliably in real Spring Boot projects, covering REST APIs, architecture, JPA/Hibernate, Flyway, security, testing, Spring AI, and MCP server development.

*Built by @rrezartprebreza · Pristina, Kosovo