claude-code-java: Agent Skills for Java Projects, Reviewed

What claude-code-java actually ships

The repository is not a Java library and not a plugin that hooks into a build. It is a workspace of markdown skills, plus the scripts and templates that place them into a Java project. The README describes skills as "structured markdown files that give an AI agent domain knowledge and workflows", and states that they follow the Agent Skills specification, an open format read by a growing number of agents. Development and testing target Claude Code, and the repository carries an explicit note that it is not affiliated with Anthropic.

The audience is narrow and stated plainly: Java developers who want consistent AI assistance for code reviews, testing, commits and architecture decisions. Eighteen skills are grouped into workflow (git-commit, changelog-generator, issue-triage), code quality (java-code-review, api-contract-review, concurrency-review, performance-smell-detection, test-quality, maven-dependency-audit, security-audit), architecture and design (architecture-review, solid-principles, design-patterns, clean-code), and framework and data (spring-boot-patterns, java-migration, jpa-patterns, logging-patterns).

The stated design goals are token efficiency, reproducible patterns, Java and Maven tailoring, and incremental adoption. That last one matters more than it sounds: you can install a single skill and stop there, which is unusual for tooling that usually demands a full configuration pass before it does anything.

Routing is the real engineering problem here

An agent selects a skill from its name and description. Nothing else. With eighteen descriptions in one namespace, they compete, and the README is candid about the consequence: the wrong skill loads and answers plausibly anyway, so nobody notices. That is a quiet failure mode, and it is the most useful thing in this repository.

The project ships scripts/eval-routing.sh, which runs a set of prompts against the same list an agent receives and reports where a prompt lands somewhere other than expected. The README states the check found a real defect the first time it ran: the prompt "this class does too much, split it" reached clean-code rather than solid-principles. Sharpening three descriptions moved the set from 17 of 18 prompts routed correctly to 20 of 20. scripts/validate-skills.sh enforces that every skill has at least one case, so the cases cannot fall behind the skills. The check runs against any OpenAI-compatible endpoint, including a local model, per docs/SCRIPTS.md.

Treat the routing numbers as a property of that fixed prompt set, not as a general accuracy score. A 20 of 20 result on a curated set says the descriptions are separable for those prompts. It says nothing about the phrasing your team uses. The valuable artifact is the harness, because you can extend it with your own prompts.

Install and first run

There are two paths. The lightest installs skills only, with no clone and no setup script:

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

The README lists four flags for that command: --list to see the skills before installing, --skill <name> to install only some, --global to install at user level instead of the current project, and --copy to get files instead of symlinks. If you only want code review and commit help, --skill is the flag to reach for.

The heavier path clones the workspace and runs a setup script against your project. This is what you want if you also need CLAUDE.md generation, MCP configuration and project settings:

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

The setup script creates a .claude/ directory in the target project with symlinked skills, generates CLAUDE.md, and configures settings. If you would rather not run it, the README documents a manual route: create .claude/skills and either copy individual skill directories or symlink the whole set.

mkdir -p your-project/.claude/skills
cp -r ~/projects/claude-code-java/skills/java-code-review your-project/.claude/skills/
ln -s ~/projects/claude-code-java/skills/* your-project/.claude/skills/

After that, start Claude Code inside the Java project. Skills load from context, or you invoke them directly with slash commands such as /git-commit and /java-code-review. The README gives no example of what a skill's output looks like, so expect to judge the first run yourself.

Where the skill model breaks down

Skill selection is probabilistic. The README says so directly: an agent picks by name and description, and a wrong pick produces a plausible answer rather than an error. If your team needs a guaranteed sequence for a release process, this is the wrong layer to enforce it. Skills shape what the model knows and how it approaches a task; they do not gate it.

There is a second constraint in the structure. The eighteen skills are Java and Maven oriented, and several are framework specific: spring-boot-patterns, jpa-patterns, java-migration. On a Gradle Kotlin project, or a Java service that does not use Spring, those skills have little to say. The workflow skills (git-commit, changelog-generator, issue-triage) are the least Java-coupled, which makes them the sensible entry point for a mixed repository.

A third point the README does not address: symlinking skills from a shared clone means every project on the machine reads the same files. Updating the clone changes behaviour in every project at once. The README does not document rollback, so if you need per-project pinning, use --copy or copy individual skill directories instead of symlinks.

How this differs from a plain CLAUDE.md or a linter

The obvious alternative is a hand-written CLAUDE.md in the repository root, plus whatever static analysis your build already runs. The difference is scope and reuse. A CLAUDE.md is project-specific prose that you maintain yourself; these skills are packaged, versioned, and validated in CI against the Agent Skills specification, with a release history (v1.0.0, dated 2026-08-28) and a routing test suite attached.

Against a linter, the split is clearer. Checkstyle or SpotBugs decides pass or fail on rules you can read. A skill like concurrency-review or performance-smell-detection produces commentary, and its value depends on the model and the context it receives. One enforces; the other advises. Teams that need an auditable gate should keep the linter and treat skills as a second opinion.

The other real alternative is doing nothing and prompting Claude Code directly. That works until you have several developers and want the same review shape from each of them. The skills are a packaging format for that consistency, not a capability the model lacks on its own.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-09-06, and the repository is not archived. The single release listed is v1.0.0 from 2026-08-28, so the project is early in its version history. There is no published cadence for skill changes, and because skills are markdown, an upstream edit can change agent behaviour without any dependency resolver telling you.

Licensing is MIT, per the LICENSE file and the README badge. That is permissive and places no obligation on the skills you copy into a project, but it also means no warranty. Nothing here is legal advice; check the LICENSE text yourself if you redistribute the skills.

The upgrade cost is mostly human. Because installs default to symlinks, pulling the clone forward updates every project that links to it. The scripts/validate-skills.sh check is the fastest way to confirm a clone is still internally consistent after a pull, and the routing cases in evals/ are what you would extend when your own prompts start landing on the wrong skill.

Editorial conclusion

Adopt claude-code-java if you already run Claude Code on a Java or Maven codebase and want repeatable review, commit and migration behaviour instead of ad hoc prompting. Skip it if your project is not Java, or if you cannot accept that skill selection is a description-matching problem rather than a deterministic dispatch. Before committing, run scripts/validate-skills.sh in the cloned workspace and read the routing cases under evals/ to see whether the prompts you actually type land on the skill you expect.

Frequently asked questions

Official sources

1. decebals/claude-code-java on GitHub
2. Issues
3. License: MIT
4. README
5. Releases