180 Java rules your AI coding agent can use to write better code.
Works with Claude Code, Cursor, Windsurf, Copilot, Codex, Aider, Zed, Amp, Cline, and pretty much any other agent that supports skills.
npx add-skill java-skillsThat's it. The CLI figures out which agents you have and installs the skill to the right place.
After installing, just ask your agent:
/java-skills review this class
/java-skills is my exception handling correct?
/java-skills check for concurrency issues
The agent loads the relevant rules and applies them to your code.
180 rules split into 14 categories:
| Category | Rules | What it covers |
|---|---|---|
| Exception Handling | 12 | Checked vs unchecked, try-with-resources, Optional |
| Concurrency | 15 | Thread safety, locks, ExecutorService, virtual threads |
| Collections | 14 | Right collection choice, unmodifiable, generics |
| OOP Design | 15 | Builder pattern, composition, records, sealed classes |
| Stream API | 12 | Streams, collectors, parallel streams, Optional |
| JVM Optimization | 12 | GC tuning, JIT, profiling with JFR |
| Naming | 14 | Following Java naming conventions |
| Type Safety | 12 | Generics, pattern matching, enums |
| Testing | 14 | JUnit 5, Mockito, AssertJ, Testcontainers |
| Docs | 11 | Javadoc best practices |
| Performance | 13 | StringBuilder, boxing, caching |
| Project Structure | 10 | Maven/Gradle, package structure, modules |
| Code Quality | 11 | Static analysis, Checkstyle, SonarQube |
| Anti-patterns | 15 | Common mistakes and how to fix them |
Each rule has:
- Why it matters
- Bad code example
- Good code example
- Links to official docs when relevant
If add-skill doesn't work for your setup, here's how to install manually:
Claude Code
Global (applies to all projects):
git clone https://github.com/mzdz/java-skills.git ~/.claude/skills/java-skillsOr just for one project:
git clone https://github.com/mzdz/java-skills.git .claude/skills/java-skillsCursor
git clone https://github.com/mzdz/java-skills.git .cursor/skills/java-skillsOr just grab the skill file:
curl -o .cursorrules https://raw.githubusercontent.com/mzdz/java-skills/master/SKILL.mdWindsurf
mkdir -p .windsurf/rules
curl -o .windsurf/rules/java-skills.md https://raw.githubusercontent.com/mzdz/java-skills/master/SKILL.mdOpenAI Codex
git clone https://github.com/mzdz/java-skills.git .codex/skills/java-skillsOr use the AGENTS.md standard:
curl -o AGENTS.md https://raw.githubusercontent.com/mzdz/java-skills/master/SKILL.mdGitHub Copilot
mkdir -p .github
curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/mzdz/java-skills/master/SKILL.mdAider
Add to .aider.conf.yml:
read: path/to/java-skills/SKILL.mdOr pass it directly:
aider --read path/to/java-skills/SKILL.mdOther agents (AGENTS.md)
If your agent supports the AGENTS.md standard:
curl -o AGENTS.md https://raw.githubusercontent.com/mzdz/java-skills/master/SKILL.mdSee SKILL.md for the full list with links to each rule file.
- Effective Java, 3rd Edition (Joshua Bloch)
- Java Concurrency in Practice
- Google Java Style Guide
- Oracle Java Documentation
- Real code from Spring, Hibernate, Quarkus, Micronaut
- SpotBugs, PMD, SonarQube rule documentation
PRs welcome. Just follow the format of existing rules.
MIT