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 well-structured, largely actionable skill body with genuine progressive disclosure into a real, verified bundle. Main weaknesses are minor redundancy between the process steps and the requirements/signal-mode sections, and a missing explicit fix-and-retry loop for failed validation.
Suggestions
Merge 'Expert Structure Requirements' into step 2 and the 'Signal Mode' section into step 6 to eliminate duplicated structure and commands.
Add explicit error recovery after validation, e.g. 'If validation fails, fix the reported issues and re-run until it passes before registering'.
Include one short worked example of a synthesized reference file or run_signal.sh snippet to make steps 3-4 fully concrete.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean, using compact tables (domain/signal mapping, quick commands) and templates without explaining concepts Claude already knows. It earns a 4 rather than 5 because the 'Expert Structure Requirements' section repeats the directory structure already shown in step 2, and the 'Signal Mode' section re-states the validate/register commands from step 6. | 4 / 5 |
Actionability | Concrete, executable commands are given ('scripts/validate_expert.sh /path/to/expert-{name}', 'scripts/register_expert.sh /path/to/expert-{name}') along with a copy-paste example prompt, a directory template, and a frontmatter template. It falls short of level 5 because steps 3-4 rely on placeholder templates ('{topic-1}.md', '{helper}.sh') and delegate script content to reference files without showing even one worked example inline. | 4 / 5 |
Workflow Clarity | Seven clearly numbered steps run from input analysis to reporting, with an explicit validation checkpoint ('Run validation... If valid, register') backed by a Validation Checks list, so no destructive/batch cap applies. It is not level 5 because the error-recovery loop is one-sided: it never states what to do when validation fails (fix and re-run), and registration reporting of line numbers is mentioned without a re-check step. | 4 / 5 |
Progressive Disclosure | The SKILL.md is a clear overview that splits detail into well-signaled, one-level-deep references ('See references/expert-structure.md', 'references/catalog-formats.md', 'references/signal-patterns.md'), all of which exist in the bundle alongside the referenced scripts (validate_expert.sh, register_expert.sh). This matches the anchor for a clear overview with well-signaled one-level-deep references and easy navigation. | 5 / 5 |
Total | 17 / 20 Passed |