The SKILL.md format this repo uses was released by Anthropic as an open standard, and it now has a neutral home at agentskills.io with a written specification and a growing list of hosts that read it: Cursor, GitHub Copilot and VS Code, Gemini CLI, Codex, OpenCode, Goose, JetBrains Junie, Spring AI, and others.
The skills here already conform. I checked all 18 against the hard requirements (name 1-64 characters, lowercase alphanumeric and hyphens, matching the parent directory, non-empty description under 1024 characters) and all 18 pass. Only 2 of the 18 mention Claude in the body of SKILL.md. So this is less a migration than a matter of stating what is already true, plus a check so it stays true.
Two hosts on that list matter more than the rest for a Java skills collection: Junie is IntelliJ-native, and Spring AI is Spring. Those are Java developers who are unlikely to arrive here through Claude Code.
Scope
- Add
license: MIT to the frontmatter of all 18 skills. Skills get copied out of this repo one folder at a time, and the license should travel with the file.
- Add
scripts/validate-skills.sh implementing the spec's hard requirements, wired into test-all.sh.
- Run it in CI.
docs/TESTING.md already lists this as a planned option.
- Drop the "Structure" section from the skill-review workflow prompt, since a deterministic check replaces it.
- Update
README.md, .claude/skills/README.md, docs/SKILL_GUIDELINES.md, docs/SCRIPTS.md and docs/TESTING.md.
Out of scope
No rename. The repo keeps the name claude-code-java. The name is doing real discovery work at this size, and renaming breaks every local symlink and every third-party README that copied a path from ours. That decision can be revisited later on its own merits, and it is not a prerequisite for spec compliance.
No compatibility claims I have not tested. The README will say the skills follow the Agent Skills specification, which is verifiable. It will not claim "works with Cursor and Copilot" until someone has actually run a skill there.
No content restructuring. Eight skills exceed the 500-line body the spec recommends: design-patterns (739), jpa-patterns (657), solid-principles (648), test-quality (575), java-migration (569), clean-code (560), security-audit (556), logging-patterns (522). Splitting those into references/ is worth doing, since progressive disclosure is the point of the format and token efficiency is a stated goal here, but it changes what an agent actually reads and can degrade a skill. That gets its own issue and one PR per skill. The validator will report the 500-line limit as a warning rather than an error, so CI does not go red on day one.
On tooling
I looked at three options for the CI check and picked none of them:
skills-ref, the reference implementation, states in its own README that it is for demonstration purposes only.npx skills from Vercel Labs is well adopted but has no validate command.- The "Validate Skill" marketplace action runs the right checks, but it is a v1.0.0 from an unfamiliar publisher, and pulling an unvetted third-party action into CI is a poor look for a repo that ships a security-audit skill.
The spec's hard rules are short enough to check in about 40 lines of bash, with no dependencies, runnable locally by contributors. That is what I plan to write.
Open to input
If you use these skills on a host other than Claude Code, say so here. That is the one thing I cannot verify on my own, and it is what would let the README make a stronger claim than "follows the spec".
The SKILL.md format this repo uses was released by Anthropic as an open standard, and it now has a neutral home at agentskills.io with a written specification and a growing list of hosts that read it: Cursor, GitHub Copilot and VS Code, Gemini CLI, Codex, OpenCode, Goose, JetBrains Junie, Spring AI, and others.
The skills here already conform. I checked all 18 against the hard requirements (name 1-64 characters, lowercase alphanumeric and hyphens, matching the parent directory, non-empty description under 1024 characters) and all 18 pass. Only 2 of the 18 mention Claude in the body of SKILL.md. So this is less a migration than a matter of stating what is already true, plus a check so it stays true.
Two hosts on that list matter more than the rest for a Java skills collection: Junie is IntelliJ-native, and Spring AI is Spring. Those are Java developers who are unlikely to arrive here through Claude Code.
Scope
license: MITto the frontmatter of all 18 skills. Skills get copied out of this repo one folder at a time, and the license should travel with the file.scripts/validate-skills.shimplementing the spec's hard requirements, wired intotest-all.sh.docs/TESTING.mdalready lists this as a planned option.README.md,.claude/skills/README.md,docs/SKILL_GUIDELINES.md,docs/SCRIPTS.mdanddocs/TESTING.md.Out of scope
No rename. The repo keeps the name
claude-code-java. The name is doing real discovery work at this size, and renaming breaks every local symlink and every third-party README that copied a path from ours. That decision can be revisited later on its own merits, and it is not a prerequisite for spec compliance.No compatibility claims I have not tested. The README will say the skills follow the Agent Skills specification, which is verifiable. It will not claim "works with Cursor and Copilot" until someone has actually run a skill there.
No content restructuring. Eight skills exceed the 500-line body the spec recommends: design-patterns (739), jpa-patterns (657), solid-principles (648), test-quality (575), java-migration (569), clean-code (560), security-audit (556), logging-patterns (522). Splitting those into
references/is worth doing, since progressive disclosure is the point of the format and token efficiency is a stated goal here, but it changes what an agent actually reads and can degrade a skill. That gets its own issue and one PR per skill. The validator will report the 500-line limit as a warning rather than an error, so CI does not go red on day one.On tooling
I looked at three options for the CI check and picked none of them:
skills-ref, the reference implementation, states in its own README that it is for demonstration purposes only.npx skillsfrom Vercel Labs is well adopted but has no validate command.The spec's hard rules are short enough to check in about 40 lines of bash, with no dependencies, runnable locally by contributors. That is what I plan to write.
Open to input
If you use these skills on a host other than Claude Code, say so here. That is the one thing I cannot verify on my own, and it is what would let the README make a stronger claim than "follows the spec".