Content
63%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is well-structured as a progressive-disclosure overview with strong validation checkpoints (compile-before, stop-on-fail, verify-after) and a properly signaled, real reference file. Its weaknesses are redundancy — the trigger list and capability list duplicate the frontmatter description — and thin in-body actionability, with the substantive guidance entirely delegated to the reference.
Suggestions
Remove the 'When to use this skill' section and the 'What is covered in this Skill?' bullet list — both duplicate the frontmatter description's capabilities and trigger phrases; a single sentence pointing to the reference suffices.
Add one short inline example of the highest-value pattern (e.g., a controller method with @Valid on a request DTO and the corresponding 400 error response) so the skill's core instruction is actionable before jumping to the reference file.
Replace vague step names like 'Gather scope and decide target improvements' and 'Apply framework-aligned changes' with concrete checkpoints (e.g., 'list the DTOs/controllers touched', 'apply the matching example from the reference'), and extend the SAFETY rule with a recovery step when post-change `mvn clean verify` fails.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean, but two sections are redundant: 'What is covered in this Skill?' and 'When to use this skill' restate the frontmatter description's capabilities and the identical trigger list ('Add validation support in Spring Boot'...), and 'Scope: Apply recommendations based on the reference rules and good/bad examples' is filler. Not 4 because an entire duplicated trigger-list section is more than a minor trim; not 2 because there is no concept-explainer padding and the Constraints/Workflow sections earn their tokens. | 3 / 5 |
Actionability | Concrete, copy-pasteable commands exist ('Run `./mvnw compile` or `mvn compile`', '`./mvnw clean verify` or `mvn clean verify`', 'Read references/303-frameworks-spring-boot-validation.md'), but the core how-to is deferred: steps like 'Gather scope and decide target improvements' and 'Implement or refactor validation-related configuration/code following the reference patterns' are high-level direction with no concrete annotation/code example inline. Not 4 because the only executable content is build commands while the skill's actual instructions live entirely in the reference; not 2 because the build/verify commands and named reference path are specific and executable. | 3 / 5 |
Workflow Clarity | The 4-step workflow (read reference/assess, gather scope, apply changes, verify/report) has explicit checkpoints: 'MANDATORY: Run `./mvnw compile`... before applying any change', 'SAFETY: If compilation fails, stop immediately', and 'VERIFY: Run `./mvnw clean verify`... after applying improvements'. Not 5 because 'stop immediately' is a halt rather than a fix-and-retry feedback loop and there is no guidance for handling a post-change verify failure; not 3 because compile-before/verify-after checkpoints are explicit, not merely implicit. | 4 / 5 |
Progressive Disclosure | The ~50-line body is a clean overview pointing to a single one-level-deep reference that exists and is substantive (references/303-frameworks-spring-boot-validation.md, 395 lines with Examples 1-7), signaled both in Constraints ('BEFORE APPLYING: Read the reference') and in a dedicated '## Reference' section with a markdown link. Matches the anchor-5 pattern of a concise overview with well-signaled references; no nested references or inlined bulk content. | 5 / 5 |
Total | 15 / 20 Passed |