claude-code-java

Agent Skills for Java projects, following the open Agent Skills specification

This project is not affiliated with Anthropic.

What is this?

A collection of reusable skills (structured markdown files that give an AI agent domain knowledge and workflows), plus project templates, MCP server configurations, and setup scripts.

The skills follow the Agent Skills specification, an open format read by a growing number of agents. They are developed and tested with Claude Code, and every skill is validated against the spec in CI.

Who is this for? Java developers who want consistent, high-quality AI assistance for common tasks like code reviews, testing, commits, and architecture decisions.

Routing is tested

An agent picks a skill from its name and description and nothing else. With eighteen of them the descriptions compete, and the failure is quiet: the wrong skill loads and answers plausibly anyway, so nobody notices.

scripts/eval-routing.sh runs a set of prompts against the same list an agent receives and reports where one lands somewhere other than expected. It found a real defect the first time it ran: "this class does too much, split it" reached clean-code rather than solid-principles. Sharpening three descriptions took the set from 17 of 18 prompts routed correctly to 20 of 20.

Every skill has at least one case, enforced by scripts/validate-skills.sh so the cases cannot fall behind the skills. The check runs against any OpenAI-compatible endpoint, including a local model. See docs/SCRIPTS.md.

Purpose

AI-powered development workflows with focus on:

• Token efficiency - Designed for fewer iterations and lower token usage
• Reproducible patterns - Reusable workflows across projects
• Java ecosystem - Tailored for Java/Maven development
• Incremental adoption - Start small, expand as needed

Quick Start

Skills only

npx skills@latest add decebals/claude-code-java

No clone, no setup script. Add --list to see the skills first, --skill <name> to install only some of them, --global to install at user level instead of the current project, or --copy to get files instead of symlinks.

For the skills plus CLAUDE.md generation, MCP configuration and project settings, continue below.

1. Clone this workspace

git clone https://github.com/decebals/claude-code-java.git ~/projects/claude-code-java
cd ~/projects/claude-code-java
chmod +x scripts/*.sh

2. Setup your Java project

./scripts/setup-project.sh ~/projects/your-java-project

This creates .claude/ with symlinked skills, generates CLAUDE.md, and configures settings.

Prefer manual setup? Just copy or symlink the skills you want:

mkdir -p your-project/.claude/skills

# Copy specific skills
cp -r ~/projects/claude-code-java/skills/java-code-review your-project/.claude/skills/

# Or symlink all skills
ln -s ~/projects/claude-code-java/skills/* your-project/.claude/skills/

3. Use with Claude Code

cd ~/projects/your-java-project
claude

# Skills load automatically based on context, or invoke directly:
> /git-commit
> /java-code-review

Available Skills (18)

Skills are automatically loaded by Claude Code based on context.

Workflow

Skill	Trigger Examples
git-commit	"commit these changes", "create commit"
changelog-generator	"generate changelog", "what changed since release"
issue-triage	"triage issues", "check open issues"

Code Quality

Skill	Trigger Examples
java-code-review	"review this code", "check this PR"
api-contract-review	"review API", "check REST endpoints"
concurrency-review	"check thread safety", "review async code"
performance-smell-detection	"check performance", "find slow code"
test-quality	"add tests", "improve coverage"
maven-dependency-audit	"check dependencies", "audit deps"
security-audit	"security review", "check OWASP", "vulnerabilities"

Architecture & Design

Skill	Trigger Examples
architecture-review	"review architecture", "check package structure"
solid-principles	"check SOLID", "single responsibility"
design-patterns	"use factory pattern", "implement strategy"
clean-code	"clean this code", "refactor"

Framework & Data

Skill	Trigger Examples
spring-boot-patterns	"create controller", "Spring Boot help"
java-migration	"upgrade to Java 21", "migrate from Java 8"
jpa-patterns	"N+1 problem", "LazyInitializationException"
logging-patterns	"add logging", "debug this flow", "analyze logs"

See skills/README.md for full documentation and docs/SCRIPTS.md for setup script options.

Project Structure

claude-code-java/
├── README.md                    # This file
├── LICENSE                      # MIT license
├── .gitignore                   # Git ignore rules
├── .claude/
│   └── skills/                  # 18 reusable skills (see Available Skills above)
├── docs/                        # Guidelines and best practices
│   ├── DESIGN_PRINCIPLES.md     # Core philosophy
│   ├── RE