Content
86%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.
An exemplary instruction-type skill body: lean, specific, and sequenced, with a strong validation step and truthful-reference discipline (declared-but-missing paths, provenance labels). The only gaps are an explicit fix-and-revalidate loop and unnamed build/lint/test commands.
Suggestions
In step 6, add an explicit error-recovery loop, e.g. "If validate_pair.py or any test fails: fix the pair and re-run before proceeding to the browser check" — this closes the feedback-loop gap for workflow_clarity.
Name the actual commands for step 6's "Run build, lint, full tests" (e.g. the repo's npm/pnpm scripts or CI entry points) so the whole workflow is copy-paste executable and lifts actionability to 5.
Consider adding one short card-PNG vs. inspector example snippet under step 4 (or moving one to the reference) to make the pairing rule concrete for the common cases.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and imperative with zero padding of concepts Claude already knows; every line carries a project-specific constraint Claude could not infer, e.g. "Never relabel imported geometry as img2threejs", "Do not claim a GLB or texture exists because code declares a future URL", and "Ground from foot/contact geometry, not the lowest weapon tip". Not 4 because there is no over-explanation anywhere to trim — every token earns its place. | 5 / 5 |
Actionability | Concrete, executable guidance dominates: "Run `scripts/validate_pair.py <png> <model-source>`", "Store project-bound output under `public/asset-catalog/<category>/`", "Normalize catalog copies to 512×512 RGBA", "Attach equipment to named sockets". Not 5 because step 6 says "Run build, lint, full tests" without naming the actual commands, and much of the guidance is constraints rather than copy-paste-ready code — minor gaps, not missing steps. | 4 / 5 |
Workflow Clarity | Seven clearly ordered steps with a dedicated validation step (6) covering the validation script, inventory tests, deterministic motion testing, build, lint, full tests, `git diff --check`, and browser verification, plus a handoff contract in step 7 ("Commit the narrow task and hand off its exact SHA"). Not 5 because there is no explicit error-recovery loop — nothing like "if validation fails, fix and re-validate" — even though step 6 is otherwise a thorough checkpoint; not 3 because validation checkpoints are very much present and explicit. | 4 / 5 |
Progressive Disclosure | The body is a compact overview that keeps exactly one clearly signaled, one-level-deep reference: "Read [references/catalog-contract.md](references/catalog-contract.md) when changing catalog types, provenance language, or review-route behavior" — the referenced file exists and covers precisely those topics (surface mapping, provenance language, grounding, browser proof), and `scripts/validate_pair.py` exists at the cited path. Not 4 because there are no organization gaps: navigation is trivial, the split is appropriate, and no content that belongs in the reference is inlined. | 5 / 5 |
Total | 18 / 20 Passed |