Content
73%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 operational skill with copy-paste entry templates, exact commands, and exceptionally well-sequenced workflows including human-approval gates, dry-runs, and verification steps. The main weaknesses are moderate verbosity (duplicated trigger lists and tables explaining concepts Claude already knows), a broken code fence inside the error-entry template, and an orphaned examples.md reference.
Suggestions
Consolidate the three overlapping trigger lists (Quick Reference, 'Detection Triggers', 'Multi-Agent Support') into the Quick Reference table, and drop or trim the 'Area Tags' and 'Priority Guidelines' tables — Claude can infer what 'frontend' and 'critical' mean.
Fix the nested code fence in the Error Entry template (use a four-backtick outer fence or an indented block for the '### Error' section) so the template renders and copies as one unit.
Link references/examples.md from the 'Logging Format' section (e.g., 'For fully worked entries, see references/examples.md') so the largest reference file is discoverable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core is efficient (copy-paste entry templates, ID format, exact grep commands), but several sections pad or duplicate: 'Area Tags' explains that frontend means 'UI, components, client-side code', the 'Priority Guidelines' table spells out obvious severity levels, and trigger guidance appears three times (Quick Reference, 'Detection Triggers', and 'Multi-Agent Support'). Matches anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened'); not 2 because the bulk of the body is genuinely operational rather than padded. | 3 / 5 |
Actionability | Highly executable throughout: full markdown entry templates, 'grep -r "keyword" .learnings/', './skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run', and a numbered promotion workflow with an explicit human-approval checkpoint. Falls short of 5 on two minor gaps: the error-entry template's nested triple-backtick fence is broken in the source (the inner ``` at the '### Error' block prematurely closes the outer ```markdown fence, so lines like 'Actual error message or output' render outside the template), and the extract-skill.sh path hardcodes one install layout. | 4 / 5 |
Workflow Clarity | Multi-step processes are explicitly sequenced with validation checkpoints: promotion requires 'Show the proposed diff for human approval before writing instructions' and 'Do not mark an unapplied proposal as promoted'; skill extraction runs '--dry-run' before the real run and ends with 'Verify: Read skill in fresh session to ensure it's self-contained'; there is a quality-gates checklist and a recurrence feedback loop (increment Recurrence-Count, bump priority, consider systemic fix). Matches anchor 5; anchor 4 would imply missing checkpoints, which is not the case. | 5 / 5 |
Progressive Disclosure | Good one-level-deep structure: 'For installation commands, see references/installation.md... Read these only when installing or configuring the skill', with hooks-setup.md, amp-setup.md, context-maintenance.md, assets/ templates, and scripts/extract-skill.sh all correctly signposted and all verified to exist in the bundle. Falls short of 5 because references/examples.md — the largest reference file (383 lines of worked entry examples) — is never linked from SKILL.md anywhere, leaving it undiscoverable. | 4 / 5 |
Total | 16 / 20 Passed |