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 a lean, well-structured instruction skill with an explicit one-question-at-a-time interview protocol and a validation-looped wrapper workflow. Its decisive defect is that the entire supporting bundle it points to — three scripts, three references, and two format files — is absent, breaking both actionability and navigation in practice.
Suggestions
Ship the referenced bundle files: scripts/context_md_linter.py, scripts/adr_scanner.py, scripts/glossary_code_consistency.py, the three references/*.md files, CONTEXT-FORMAT.md, and ADR-FORMAT.md — every link in the body currently dangles.
Inline a minimal CONTEXT.md entry template (a 3-4 line example of one glossary term) so "Use the format in CONTEXT-FORMAT.md" is followable even before that file is opened.
State the expected output of each validator (e.g., "PASS/WARN/FAIL per rule" exit codes or summary lines) so the re-run feedback loops are interpretable without reading the script source.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core guidance earns its tokens: "Ask the questions one at a time, waiting for feedback", the three-part ADR criteria, and quoted challenge examples ("Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?") are all actionable, not explanatory filler. Minor trimmable padding: the provenance blockquote's "3 in-depth references each citing 7+ authoritative sources" and the author name-dropping in the reference list. Not 5 because of that meta-commentary; not 3 because nothing explains concepts Claude already knows. | 4 / 5 |
Actionability | Commands are concrete and copy-paste-shaped ("scripts/context_md_linter.py CONTEXT.md", "glossary_code_consistency.py --context CONTEXT.md --code src/") and the interview rules include example dialogue, but the load-bearing artifacts are missing from the bundle: CONTEXT-FORMAT.md, ADR-FORMAT.md, and all three scripts are referenced yet absent, so "Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md)" cannot actually be followed. Not 4 because the gaps are key details, not minor; not 2 because the written guidance itself is precise and specific. | 3 / 5 |
Workflow Clarity | The wrapper workflow is clearly sequenced (Pre-flight → During the session → Closing) with explicit validation checkpoints and feedback loops ("re-run adr_scanner.py to confirm numbering", "Final glossary_code_consistency.py run to confirm no new orphan terms"). Not 5 because the validators those checkpoints depend on are absent from the bundle, so the loops cannot actually execute as shipped; not 3 because sequence and checkpoints are explicit, not merely implied. | 4 / 5 |
Progressive Disclosure | References are well-signaled and one level deep — a tool table with one-line roles, per-reference summaries ("why a glossary belongs in source control"), and inline links at point of use — but verification of the bundle shows none of the referenced files exist (no references/, scripts/, CONTEXT-FORMAT.md, or ADR-FORMAT.md), so every navigation path dead-ends. Not 4 because all links dangling is more than a minor organization gap; not 2 because the in-body structure is well designed and nothing that belongs in separate files is inlined. | 3 / 5 |
Total | 14 / 20 Passed |