Content
85%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 well-structured instruction-only triage skill: concrete commands, a sequenced workflow with fail-fast validation and recovery guidance, and clean one-level-deep reference signaling to real bundle files. The one notable cost is token padding — the Table of Contents, Overview, and Philosophy sections restate other content and could be cut without losing anything.
Suggestions
Remove the 11-line Table of Contents and the Philosophy section; both restate the section list and the Workflow/Constraints content, trimming the body by roughly 15-20%.
Drop or merge the Overview section into 'When to use', since it duplicates the frontmatter description and the taxonomy summary already covered by references/failure-taxonomy.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The operational sections are lean, but roughly a fifth of the body could be trimmed: the 11-line Table of Contents adds navigation tokens with no new information, the Overview restates the frontmatter description, and the Philosophy section ('Separate symptom from cause', 'Preserve operator trust by avoiding speculative config edits') repeats the Workflow and Constraints sections. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the minor-trimmings anchor at 4. | 3 / 5 |
Actionability | The guidance is fully executable and copy-paste ready: exact commands ('bash scripts/codex-preflight.sh --repo-fragment local-memory --mode optional', 'codex mcp list', 'lsof -nP -iTCP:3002'), exact error strings to match ('connection closed: initialize response', 'No version is set for shim'), a concrete default repo root, and real referenced files (failure-taxonomy.md, contract.yaml, evals.yaml all exist). The Examples cover the common requests, matching the anchor for fully executable coverage rather than the minor-gaps anchor at 4. | 5 / 5 |
Workflow Clarity | The five-step Workflow is clearly sequenced, the Validation section adds an explicit fail-fast feedback loop ('stop at the first failed gate and fix it before continuing') with three concrete gate commands, and the Failure mode section gives error-recovery behavior when classification is ambiguous (report competing hypotheses instead of speculative edits). This matches the anchor for explicit validation steps plus feedback loops; nothing is missing that would drop it to 4. | 5 / 5 |
Progressive Disclosure | The body is a concise overview that delegates detail to three real, one-level-deep bundle files, each well-signaled with a 'Read when:' condition (failure-taxonomy.md for classification, contract.yaml for the machine-checkable contract, evals.yaml for routing/pressure-test cases), and the taxonomy file is also linked inline at the point of use. Verified bundle files contain no nested second-level references, matching the anchor for a clear overview with well-signaled one-level-deep references. | 5 / 5 |
Total | 18 / 20 Passed |