What I’d like us to agree is whether the results look ok to all or if you think we should change things.
For sure it’s better than what was there before (just a FIXME ;)) but are we ok to apply this style elsewhere? In practice I don’t see how we could not agree since it’s based on our proposed/voted rules but as you know it’s not an exact science and maybe we need to slant it a bit differently in the skill, to get some different feel.
The skill seems a bit verbose, in particular regarding older branches. Wouldn’t it be much simpler to just backport the Checkstyle changes? Feels weird to me to use the older style on older branches - and it’s not going to break anything to accept the new syntax also on older branches.
Also, I wonder if this is really something to have as a skill or if it shouldn’t be part of AGENTS.md, maybe in a condensed form? At least when writing code, Claude Code almost always adds or edit JavaDoc comments.
It’s a bit more work but I agree it would be better.
I think it’s ok to add have it as a skill for the use case when you want to improve javadoc. But that’s debatable and we could move it to the OKF fully (ie without the skill) too.
Note that right now, the skill should be triggered automatically (I need to check this) thanks to the skill description:
description: Write clear, genuinely useful Javadoc for XWiki Java code, following the XWiki Java Code Style and the Oracle “How to Write Doc Comments” conventions. Use when adding or improving Javadoc on classes, interfaces, methods, fields or parameters in an XWiki repo — especially public/protected APIs, REST resources, component roles — or when Checkstyle reports MissingJavadocType / MissingJavadocMethod. For the build/Checkstyle commands use xwiki-build; for the @since / @Deprecated(since) version string use the versioning rules (xwiki-knowledge); for opening the PR use xwiki-pull-request.