Agent skills: comment and Javadoc conventions, record captures, writing style #57818

Description

Two points came up in reviews this week. The agent skills under .agents/skills/ do not cover them.

Comments and Javadoc. The coding-style skill only says to prefer descriptive names over comments. #57535 had no Javadoc on its new types and members. #57806 added it to every type and member, including accessors, record components and enum constants. The skill should say where Javadoc and block comments belong, and that single statements get no comment.

Records instead of parallel lists. #57535 captured three parallel lists for a service, because the runtime carrier was a mutable class. #57806 replaced them with a list of records. #57536 received the same remark. The converting-recorders-to-services skill lists records as capturable but does not say to prefer them over parallel lists.

Null elements in captured collections. Stream#toList() accepts a null element. The capture is re-created with List.of() at runtime, see SerializedCaptureEmitter.emitCollSer for CollSer tag 4, and List.of() throws on startup. This caused the NPE that #57806 fixed for a function without @Named. The skill does not mention it.

Implementation ideas

• coding-style: add a "Comments and Javadoc" section. Javadoc on new types and on public or package-private members. One // comment per block in a long method, none on a single statement. A TODO names its issue, and tests get no Javadoc. Add one line to AGENTS.md.
• converting-recorders-to-services: in the lambda capture rules, say to capture a List<Record> and not parallel lists. Under "Not capturable", add collections that contain null.