Content
75%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 dense, well-structured instruction body: clear lane separation, a numbered workflow, and unusually strong validation tooling with real commands. It loses points on closed-loop error recovery (recovery actions per failure class are unspecified), a few abstract workflow steps without worked examples, and ornate phrasing that costs clarity without saving tokens.
Suggestions
For each validation failure class (stale source, environment/tooling blocker, hosted blocker, blocked unknown), state the concrete next action so the feedback loop closes the way the stop rules already do.
Replace metaphorical phrasing like 'bounded truth constellation' and 'documentation supply chain' with plain equivalent terms (e.g., 'the set of surfaces that own or constrain the claims').
Add one short worked example of a claim -> evidence, owner, status, citation record so step 4's prescribed output is concrete rather than only structural.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely terse, telegraphic prose with zero explanation of concepts Claude already knows; almost every line is instruction. Not a 5 because of minor non-earning tokens: ornate metaphors ("Inspect the bounded truth constellation", "Resolve the documentation supply chain") and a noise HTML comment ("Discovery-smoke compatibility marker") that plainer phrasing would replace. | 4 / 5 |
Actionability | The Validation section gives four concrete, executable commands (e.g., "./bin/ask skills audit <skill-path> --level strict --json --robot") and the workflow prescribes a concrete record structure ("claim -> evidence, owner, audience visibility, volatility, status, citation"). Not a 5 because several workflow steps remain abstract direction ("Preserve and classify checkout state", "Search the active glossary") with no worked example of the outputs they prescribe. | 4 / 5 |
Workflow Clarity | A clearly numbered 12-step sequence with a dedicated Validation section specifying exact commands, a failure-classification taxonomy, and explicit stop rules ("Stop on introduced defects and required owning-contract failures"). Not a 5 because recovery actions are only defined for a subset of failure classes — it says to classify stale source, tooling blockers, etc., but not what to do next for each, so the feedback loop is not fully closed. | 4 / 5 |
Progressive Disclosure | The body is a compact overview with a References section that one-line-annotates each file, and inline pointers load reference files exactly when needed (discovery-interview.md for underspecified requests, documentation-quality.md for rubric decisions); all referenced paths exist in the bundle. Not a 5 because knowledge-capsule-routing.md is a second-level index into knowledge-capsules/*.md (a 2-level hop from SKILL.md) and several bundle files are never signposted from the body. | 4 / 5 |
Total | 16 / 20 Passed |