Content
78%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.
A lean, highly actionable conventions document whose only structural weakness is its reliance on files outside the bundle: the body defers to references/ui-contract.md and references/data.md in a spring-boot skill that is not part of this skill's bundle, leaving the disclosed detail unreachable on its own. Workflow gating via decision tables is a strength, though no ordered multi-step procedure or feedback loop is provided.
Suggestions
Progressive disclosure: either ship references/ui-contract.md and references/data.md in this skill's own references/ directory or inline the genuinely needed details — the bundle contains no references/ folder, so both citations dead-end unless the separate spring-boot skill happens to be installed.
Progressive disclosure: the single long sentence summarizing ui-contract.md (base path, operationIds, FieldError codes, Keycloak layout, etc.) compresses another file's contents into the body; make the body a pure pointer and let the reference carry that list, or move the list into a local file.
Workflow clarity: add a short ordered procedure for the most common multi-step change (e.g., new entity: write V<n> migration → map entity → expose DTO/controller → positive and negative Testcontainers tests asserting migrations applied), with the migration assertion as an explicit validation checkpoint.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a dense imperative rule list with no concept explanations and no padding — every section adds project-specific standards Claude could not infer. Minor trimmable instances remain: the time-sensitive version pin "Use latest Spring Boot 4.x and Java 21+" (not placed in a deprecated/old-patterns section) and a few long rationale sentences (e.g., the Actuator probe rule, the ui-contract.md summary) that could be tightened. | 4 / 5 |
Actionability | For an instruction-only conventions skill the guidance is fully concrete and copy-paste ready: exact property keys ("spring.threads.virtual.enabled: true", "management.endpoint.health.group.readiness.include: readinessState,db"), exact paths ("src/main/resources/db/migration", "contract/openapi.json"), naming patterns ("V<n>__<description>.sql", "pk_/uk_/ck_/fk_/ix_" prefixes), and exact DDL forms per database. Per the rubric's code-vs-instruction note, absence of code is not penalized when guidance is this actionable. | 5 / 5 |
Workflow Clarity | The two applicability decisions are well gated with explicit situation/action tables and an "Unsure | Ask once" fallback, and the Flyway section includes a validation checkpoint ("Integration tests use Testcontainers... assert that all migrations were applied"). It falls short of anchor 5 because there is no ordered end-to-end procedure (e.g., entity → migration → tests) and no explicit validate-fix-retry loop; it stays above anchor 3 because checkpoints are present, not merely implied. | 4 / 5 |
Progressive Disclosure | Sections are well organized and the external references are clearly signaled ("references/ui-contract.md is the single source of these rules", with an inline summary of its contents), but the referenced files do not exist in this skill's bundle — there is no references/ directory, and both ui-contract.md and data.md are said to live in a separate "spring-boot" skill. Scored against the actual bundle structure, navigation dead-ends whenever that other skill is unavailable, which is the anchor-3 defect of references that cannot reliably be followed. | 3 / 5 |
Total | 16 / 20 Passed |