claude-code-java: Agent Skills for Java Projects, With a Routing Test That Caught a Real Bug
Reusable AI development infrastructure for Java projects, optimized for Claude Code
At a glance
- What is it?
- A collection of eighteen Agent Skills markdown files, setup scripts and templates aimed at Java and Maven work in Claude Code. The interesting part is not the skill list but the routing evaluation harness that found a description collision between clean-code and solid-principles.
- Who is it for?
- Adopt it if your team already runs Claude Code on a Maven codebase and you want review, commit and migration workflows expressed as versioned markdown rather than as prompts pasted into chat. Skip it if your stack is Gradle-first, if you cannot point the routing check at an OpenAI-compatible endpoint, or if you need the skills to work identically across many agents, since the README only claims development and testing against Claude Code.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 9 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is skill selection, not skill content
An agent chooses a skill from its name and description. It does not read the body first. The README says this plainly: "An agent picks a skill from its name and description and nothing else." With eighteen skills installed, those descriptions compete for the same prompts. A request like "this class does too much, split it" sits between clean-code and solid-principles, and both descriptions could plausibly claim it. The failure is silent, because whichever skill loads will still produce a confident answer about refactoring. Nothing errors out. You just get advice shaped by the wrong set of rules.
So the project is not really selling eighteen markdown files. It is selling a way to keep those files honest. The skills themselves are ordinary domain knowledge for Java work: code review, concurrency, JPA, Spring Boot, Maven dependency auditing, logging, migration. Any experienced Java developer could write similar notes. What is harder is knowing whether the agent reaches for the right note at the right moment, and that is the part the repository actually instruments.
What each skill is, mechanically
A skill here is a directory under skills/ containing structured markdown that supplies an agent with domain knowledge and a workflow. The README describes them as following the Agent Skills specification, an open format it says is read by a growing number of agents, and states that every skill is validated against that spec in CI. The badge in the README points at a test workflow, and the repository ships scripts/validate-skills.sh, which the README says enforces that each skill has at least one routing case so the cases cannot fall behind the skills.
The eighteen skills are grouped into four buckets. Workflow covers git-commit, changelog-generator and issue-triage. Code quality covers java-code-review, api-contract-review, concurrency-review, performance-smell-detection, test-quality, maven-dependency-audit and security-audit. Architecture covers architecture-review, solid-principles, design-patterns and clean-code. Framework and data covers spring-boot-patterns, java-migration, jpa-patterns and logging-patterns. Each entry in the README lists trigger phrases, which is the surface an agent matches against: "check thread safety" for concurrency-review, "N+1 problem" for jpa-patterns, "upgrade to Java 21" for java-migration.
That trigger table is also the weak point. Trigger phrases written for humans to read and trigger phrases that discriminate well in a routing decision are not the same artifact, and the README's own anecdote shows the gap.
The routing eval and what it found
scripts/eval-routing.sh runs a set of prompts against the same list of names and descriptions an agent receives, then reports where a prompt lands somewhere other than expected. The README states that on its first run it surfaced a real defect: "this class does too much, split it" reached clean-code instead of solid-principles. Sharpening three descriptions moved the set from 17 of 18 prompts routed correctly to 20 of 20.
Two things about that number deserve attention. First, the prompt count and the skill count do not match. Eighteen skills, eighteen prompts in the failing run, twenty in the passing run. So the suite is not one prompt per skill in a strict bijection, and the README does not publish the prompt list. You cannot audit the coverage from the README alone. Second, a 20 of 20 result is a small sample. It demonstrates that the specific collisions the author cared about are resolved. It does not demonstrate that routing holds for your prompts, on your codebase, with your phrasing. The README is careful to present it as a defect that was found and fixed, not as a general accuracy claim, and that framing is the honest one.
The check runs against any OpenAI-compatible endpoint, including a local model, per the README. That matters for cost and for teams that cannot send prompts to a hosted API. It also means the eval measures the model you point it at, not routing in the abstract. A local model with weaker instruction following will produce different results than the model the descriptions were tuned against.
Getting it running: two paths
The fastest path installs skills only, with no clone and no setup script:
npx skills@latest add decebals/claude-code-java
The README lists four flags. --list shows the skills before installing. --skill <name> installs a subset. --global installs at user level rather than into the current project. --copy writes files instead of symlinks. That last flag is the one to think about. Symlinks keep the installed skills pointing back at the cloned repository, so a git pull updates every project at once. Copies freeze a snapshot per project. If you want reproducible agent behaviour across a team, copies are the safer default; if you want one place to fix a description, symlinks are.
The second path clones the workspace and runs the setup script:
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
According to the README, that creates .claude/ with symlinked skills, generates CLAUDE.md, and configures settings. There is also a manual route: create your-project/.claude/skills and either copy a single skill directory into it or symlink the whole skills/* glob. Once installed, skills load on context or can be invoked directly with slash commands such as /git-commit and /java-code-review. The repository also ships templates for CLAUDE.md, mcp-config.json and an MCP configuration doc, which is where the MCP server configuration mentioned in the README lives.
Where this is the wrong tool
The README states the skills are developed and tested with Claude Code, and the project is not affiliated with Anthropic. Spec compliance and Claude Code behaviour are two different guarantees. The Agent Skills format may be read by other agents, but nothing in the material shows the routing descriptions were tuned for anything except Claude Code. If your organisation standardises on a different agent, you are adopting an untested combination and should expect to redo the description-tuning work yourself.
The Java coverage is Maven-shaped. maven-dependency-audit is named for Maven, the README's purpose section says the project is tailored for Java and Maven development, and the setup script is described as generating project configuration without any mention of Gradle. On a Gradle build you can still use the review and design skills, but the dependency audit skill has no stated Gradle equivalent.
There is also a maintenance surface that is easy to underestimate. The skills encode advice about Java versions, Spring Boot conventions and JPA behaviour, and those conventions move. The routing cases are enforced by validate-skills.sh, so the suite cannot silently lose coverage, but nothing in the material describes how the advice inside a skill body is kept current. A skill that recommends a pattern your framework deprecated two releases ago will still route correctly and still be wrong.
Finally, the project is a Shell repository with a single v1.0.0 release dated 2026-08-28 and a last push about a week later. That is a young artifact. The scripts and skill descriptions are the load-bearing parts, and they are the parts most likely to change.
The alternative: prompts, or a linter
The obvious alternative is not another skill collection. It is the thing most Java teams already do: keep review standards in a wiki or a CONTRIBUTING file and paste the relevant section into the chat when you need it. That approach has no routing problem at all, because a human does the routing. You decide that this pull request needs the concurrency checklist and paste that. The cost is that the pasting is manual, inconsistent between engineers, and invisible to version control in the sense that nobody can tell which revision of the checklist was used for a given review.
claude-code-java trades that manual step for a description-matching step that can fail quietly, and then spends scripts/eval-routing.sh and validate-skills.sh to make the failure loud. That is the real difference in approach, and it is a genuine trade rather than a strict improvement. If your reviews are infrequent or highly varied, manual selection is fine and the routing machinery is overhead. If you run the same categories of review across many repositories and want the same rules applied each time, the automated path is worth the tuning.
A second alternative is deterministic tooling: Checkstyle, SpotBugs, Error Prone, OWASP dependency-check. Those produce findings you can gate a build on. They cannot discuss whether a class has too many responsibilities, and they will not write a changelog. The two approaches are complementary rather than competing, and the honest framing is that claude-code-java covers the judgement-shaped work that linters cannot, at the cost of non-determinism.
Licence, upgrade cost, and what to check first
The repository is MIT licensed, and the README carries an explicit note that the project is not affiliated with Anthropic. MIT is permissive, so copying skill directories into a private repository is straightforward. The thing to keep in mind is not the licence text but the provenance of the content: if you copy skills into your own repository and then edit the descriptions, your edits are yours to maintain and will diverge from upstream. Nothing here is legal advice, and the usual caveat applies that you should read the LICENSE file in the repository rather than a summary of it.
Upgrade cost depends on which install path you chose. With --copy, upgrading means re-copying and re-applying any local edits. With symlinks, a git pull in the cloned workspace updates every project at once, which is convenient until a description change alters routing in a project you were not thinking about. That is the specific risk of the symlink path: the routing eval in the repository tests the upstream description set, not the combination of skills present in your project after you have added your own.
Before adopting, run the validator on your own checkout and read the routing cases rather than the README summary. Then look at clean-code and solid-principles together, because that is the pair the README itself identifies as having collided. If you cannot tell from the two descriptions which one should handle "this class does too much, split it", an agent will not reliably tell either. Fixing that pair, or deciding you do not care because you invoke skills by slash command, is the concrete first step.
Editorial conclusion
Adopt it if your team already runs Claude Code on a Maven codebase and you want review, commit and migration workflows expressed as versioned markdown rather than as prompts pasted into chat. Skip it if your stack is Gradle-first, if you cannot point the routing check at an OpenAI-compatible endpoint, or if you need the skills to work identically across many agents, since the README only claims development and testing against Claude Code. Verify first that npx skills@latest add resolves the skills you actually want, run scripts/validate-skills.sh against your checkout, and read the description of solid-principles and clean-code side by side before trusting automatic routing on refactor requests.
Community notes