Content
90%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.
An exemplary instruction-only skill body: executable commands, a complete report schema, a severity-to-action table, and a fix workflow with consent and verification checkpoints. The only gaps are a missing explicit recovery branch when findings persist after a fix, and a body size just past what comfortably fits the single-file ideal.
Suggestions
Add one line to the Fix workflow for the failure case, e.g., "If findings remain after re-running, report the leftover evidence to the user instead of re-running fixes unprompted," to close the validation feedback loop.
If the skill grows further, move the full report JSON example into a reference file and keep only the key fields inline in SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section conveys bm-specific knowledge Claude cannot already have — severity semantics ("error | Will not go away without a fix"), background indexing behavior, cloud-project limitations, exit codes — with no padding or explanation of known concepts. This matches the 5 anchor: lean, assumes competence, every token earns its place. | 5 / 5 |
Actionability | Commands are copy-paste ready ("bm doctor --skip-self-test --json", "--project NAME"), the report's stable JSON shape is shown in full for parsing, and the severity table maps each level to a concrete action ("Offer the `command`; if it is null, explain the evidence"). This fully matches the 5 anchor. | 5 / 5 |
Workflow Clarity | The Fix section is a clearly sequenced four-step process — summarize findings, show commands and ask before running, run approved commands, then "Run bm doctor ... again and confirm the findings are gone" — with an explicit user-consent checkpoint and a final validation step. Not 5 because there is no explicit error-recovery branch for what to do when findings persist after the fix, which the 5 anchor expects as a feedback loop. | 4 / 5 |
Progressive Disclosure | The body is a single well-organized file with clear sections (When to Use, Run It, Read the Report, Fix, Exit Codes), no bundle files exist, and no content clearly belongs in a separate reference. Not 5 because the ~88-line body exceeds the under-50-line simple-skill exception, and the 20-line report JSON example is the kind of detail that could live in a reference file if the skill grew. | 4 / 5 |
Total | 18 / 20 Passed |