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 reference skill: concrete, executable bats test patterns for most conventions, an unambiguous failure→fix mapping, and a clean one-level-deep split of conventions 5-8 into a real reference file. The two weaker spots are the trimmable clig blockquotes and the missing code example for Convention 4's golden-file test pattern.
Suggestions
Trim the five clig blockquotes to one-line citations (e.g., 'Per clig.dev: data on stdout, messages on stderr') — the quoted guidelines are concepts Claude already knows, and the anti-pattern table already restates the key rules.
Show a concrete bats example for Convention 4's golden-file comparison (e.g., comparing sorted --plain output against a checked-in fixture) so it matches the executable standard set by Conventions 1-3.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly tight tables, examples, and terse rules that assume competence (no basic-concept explanations), but the five clig blockquotes (e.g., "Send output to `stdout`... Send messaging to `stderr`") restate guidelines Claude broadly knows, and the anti-pattern table partially repeats the conventions. These are minor trimmable instances, fitting the efficient-with-minor-over-explanation anchor rather than the every-token-earns-its-place anchor. | 4 / 5 |
Actionability | Conventions 1-3 come with copy-paste-ready bats test patterns (e.g., "run --separate-stderr mycli list" and the jq assertion on --json output), but Convention 4's test pattern ("golden-file comparison with sorted output") names a technique without showing code — a minor gap versus the fully-executable anchor. | 4 / 5 |
Workflow Clarity | This is a single-purpose reference/contract skill with no multi-step process, and per the simple-skill guidance it scores 5 when the action is unambiguous: each convention pairs rule → example → test pattern, the anti-pattern table maps failure → why → fix → convention, and "Fix the output, not the assertion" gives an explicit decision rule. No destructive or batch operations are involved, so no validation cap applies. | 5 / 5 |
Progressive Disclosure | Scored against the actual bundle: references/conventions-5-8.md exists, is referenced from a clearly signaled dedicated section ("The remaining four conventions and their bats test patterns are in [references/conventions-5-8.md]"), and is one level deep. Core conventions 1-4 stay inline with the remainder appropriately split out, matching the well-signaled one-level-deep-references anchor. | 5 / 5 |
Total | 18 / 20 Passed |