Spring Boot Plugin for Claude Code (v1.2.1)

A Claude Code plugin with production-ready skills and agents for building Spring Boot 4.x / Java 21+ applications. Install the plugin and start generating your app — the skills and agents guide Claude to follow best practices for REST APIs with Problem Details errors, JPA, Flyway database migrations, security, testing, cloud-native deployment, and Kubernetes.

Installation

Install from Anthropic marketplace

claude plugin install spring-boot-template@piomin

Or install directly from repository

claude plugin marketplace add piomin/claude-ai-spring-boot
claude plugin install spring-boot-template@piomin

Then run Claude Code and type:

/plugin

To test locally during development:

claude --plugin-dir /path/to/claude-ai-spring-boot

Using the skills with Codex

The skills in skills/ use the open SKILL.md format (frontmatter with name and description, optional references/ folder), so OpenAI Codex can load them without changes. The repo is also a Codex plugin (.codex-plugin/plugin.json) with a marketplace file (.agents/plugins/marketplace.json).

As a plugin (skills only, no agents):

codex plugin marketplace add piomin/claude-ai-spring-boot

Then restart Codex, open the Plugins Directory, choose the piomin marketplace and install spring-boot-template. Update later with codex plugin marketplace upgrade piomin.

Or as plain skills. Codex discovers skills in .agents/skills (per repository) and $HOME/.agents/skills (per user):

git clone https://github.com/piomin/claude-ai-spring-boot.git

# for all your projects
mkdir -p ~/.agents/skills
cp -r claude-ai-spring-boot/skills/* ~/.agents/skills/

# or for a single project
mkdir -p my-project/.agents/skills
cp -r claude-ai-spring-boot/skills/* my-project/.agents/skills/

Codex follows symlinks, so you can ln -s each skill folder instead of copying to get updates with git pull. Restart Codex if the skills do not show up, then run /skills or type $ to pick one, or just describe the task and Codex selects a matching skill.

The agents/ folder uses the Claude Code subagent format and is Claude Code only. Skills mention the code-reviewer and security-engineer agents as hand-offs; in Codex, ignore those references and apply the skill directly.

What’s Included

Agents (agents/)

Specialized agents that Claude Code can invoke for specific tasks:

Skills (skills/)

Reusable knowledge that Claude loads contextually:

Key Conventions

The plugin enforces these rules via the conventions skill:

• No Lombok — explicit constructors, getters/setters, LoggerFactory.getLogger()
• Constructor injection — no @Autowired on fields
• RestClient over RestTemplate/WebClient for blocking HTTP calls
• RestTestClient with @AutoConfigureRestTestClient for integration tests
• Testcontainers with @ServiceConnection (not @DynamicPropertySource)
• Jakarta Persistence (not javax.persistence)
• Problem Details (RFC 9457) for every error; paged lists as PagedModel; optimistic locking with @Version and 409
• OpenAPI contract rules, only when the API is built for a UI (see below)
• Flyway owns the schema (ddl-auto: validate) when the API persists to a Flyway-supported relational database; skipped for APIs without persistence, NoSQL-only APIs, or projects already using Liquibase
• Maven with pl.piomin.services group ID
• CI pipeline — auto-detected from existing project config
• Docker Compose for local dependencies

Cloud-Native Coverage

The cloud.md reference covers:

• Spring Cloud (Config Server, Eureka, Gateway, Resilience4j, LoadBalancer)
• Distributed tracing with OpenTelemetry (OTLP) and Micrometer Observation API
• Virtual Threads, HTTP Interface Clients (@HttpExchange), GraalVM Native Image
• Kubernetes: ConfigMap/Secret with envFrom, Prometheus annotations, startup/liveness/readiness probes, preStop hook, graceful shutdown
• TLS: cert-manager (Ingress TLS + pod-level mTLS), SSL Bundles with hot reload
• Config Tree for reading mounted secrets from files
• Paketo Buildpacks via spring-boot:build-image
• Skaffold for local K8s development loop

Usage

After installing, describe what you want to build — Claude will use the skills and agents automatically:

cd my-project
claude
> "Build a REST API for managing orders with PostgreSQL"

For a relational database like PostgreSQL, the generated app includes Flyway migrations in src/main/resources/db/migration, ddl-auto: validate, and Testcontainers tests that verify all migrations were applied. APIs without persistence or with NoSQL stores get no Flyway configuration.

APIs built for a UI

Some rules are required only when the API is built for a UI (or another client generated from its OpenAPI contract), for example a UI made from crud-ui-blueprint. Say so in your prompt (“the API backs a web UI generated from its OpenAPI contract”) or in the project’s CLAUDE.md. The conventions skill then loads skills/spring-boot/references/ui-contract.md, the single source of these rules:

• /api base path, same origin (no CORS), operationIds the UI’s generated client relies on
• an OpenAPI contract generated by springdoc 3, exported to contract/openapi.json by a test and checked in CI, with info.version from the build
• Problem Details field errors with a fixed set of codes the UI translates, PUT with a required version
• typed list filters, relations as {id, label} summaries, 409 in-use instead of cascading deletes
• the Keycloak realm layout the UI logs in with, public /actuator/health and /actuator/info, and a README “Connect a UI” section

Without a UI, none of this is required: the generated API keeps Problem Details, paging and optimistic locking, and skips the contract export.

You can also invoke skills and agents directly:

# Invoke a skill
> /spring-boot-template:jpa-patterns

# Use an agent
> @agent-spring-boot-template:code-reviewer

Directory Structure

.
├── .agents/plugins/
│   └── marketplace.json
├── .claude-plugin/
│   └── plugin.json
├── .codex-plugin/
│   └── plugin.json
├── agents/
│   ├── code-reviewer.md
│   ├── devops-engineer.md
│   ├── docker-expert.md
│   ├── kubernetes-specialist.md
│   ├── security-engineer.md
│   └── spring-boot-engineer.md
├── skills/
│   ├── conventions/SKILL.md
│   ├── code-quality/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── api-contract.md
│   │       ├── correctness.md
│   │       ├── performance.md
│   │       ├── security.md
│   │       ├── smells.md
│   │       └── spring-conventions.md
│   ├── design-patterns/SKILL.md
│   ├── java-modern/SKILL.md
│   ├── jpa-patterns/SKILL.md
│   ├── logging-patterns/SKILL.md
│   ├── spring-boot/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── ai.md
│   │       ├── cloud.md
│   │       ├── data.md
│   │       ├── ui-contract.md
│   │       ├── security.md
│   │       ├── testing.md
│   │       └── web.md
│   └── testing-patterns/SKILL.md
├── README.md
└── LICENSE

Blog Post

You can find a detailed explanation of this plugin in the post: Claude Code Template for Spring Boot.

License

Apache License 2.0