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 tightly written, well-structured workflow skill: explicit phase gating, a genuine error-recovery loop, verified one-level-deep references, and no filler explanations. The gaps are localized — broken list numbering in Phase 3, an anemic single-item checklist, vague store locations in the persist phase, and comment-only usage examples.
Suggestions
Fix Phase 3's list numbering (two steps both labeled '1.') and expand the completion checklist beyond its single 'Artifact written' item — e.g. verify root cause located at a specific file:line and fix reproduced as passing.
Replace the comment-only 'Usage Examples' blocks with a real example exchange (user symptom → skill's search query → qualify questions → output format) or delete the section; it currently adds tokens without executable content.
Name the concrete mechanism for the thinking store and learnings store (the actual environment variable or default path) instead of 'an environment variable pointing to a notes directory' and 'a known location'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The prose is telegraphic and assumes competence ('Search-first diagnostic workflow. Human executes commands.', '80% of bugs solved online.') with zero explanation of concepts Claude already knows, and detail is pushed to references. Not anchor 5 because of real redundancy: 'Philosophy' ('Reproduce before you theorize') restates Anti-Patterns ('NEVER jump to a fix without reproducing the issue'), nine anti-patterns restate workflow rules already stated inline, and 'When to Use' duplicates the frontmatter triggers. Not anchor 3 because each section still serves a distinct function and the padding is trimmable rather than pervasive. | 4 / 5 |
Actionability | Mostly executable guidance: a copy-paste 'git bisect' block, a concrete example search query ("Type 'string | undefined' is not assignable to type 'string'" typescript), three specific qualify questions, and a step-by-step fallback procedure for the AskUserQuestion bug. Not anchor 5: the persist phase hedges with 'an environment variable pointing to a notes directory' without naming the variable or path ('or a known location' is similarly vague), and the three 'Usage Examples' bash blocks contain only comments — nothing a reader can execute or imitate concretely. | 4 / 5 |
Workflow Clarity | The sequence '0.Load → 1.Search → 2.Qualify → 3.Diagnose → 4.Investigate → 5.Persist → 6.Learn' has explicit gating ('Only if diagnosis inconclusive', 'Solution found → skip to 5.Learn', 'Exit when root cause confirmed and fix verified'), an error-recovery feedback loop (empty AskUserQuestion answers → numbered text list → wait), and a completion checklist. Not anchor 5: Phase 3's step numbering is broken (two steps are both labeled '1.' and the 'Pattern matches → suggest fix, skip OODA' line floats outside the list), and the 'Completion Checklist' verifies only one of the workflow's seven phases. | 4 / 5 |
Progressive Disclosure | All four referenced files exist and are relevant, references are one level deep, and navigation is well signaled: Phase 3 points inline at the point of use ('See references/protocols/diagnose.md for details') and a closing table lists each reference with a 'When to Use' column. The body keeps only overview-level content (the git bisect snippet is a single minimal example), matching the anchor 'Clear overview with well-signaled one-level-deep references; content appropriately split; easy navigation'. | 5 / 5 |
Total | 17 / 20 Passed |