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 contract skill: lean, mostly executable guidance with a clean split between the inline core conventions and a verified one-level-deep reference file. The main gaps are minor — clig quotes of common knowledge that could be trimmed, a missing executable test snippet for the determinism convention, and no single-pass checklist sequencing all conventions for a new flag or command.
Suggestions
Trim the clig block quotes that restate common knowledge (zero/non-zero exit codes, stdout vs stderr) to one-line citations like "Per clig: exit codes 0/non-zero", keeping full quotes only for non-obvious guidance such as the --plain recommendation.
Add an executable bats snippet for Convention 4 to match the pattern quality of Conventions 1-3, e.g. a sorted `--plain` golden-file comparison (run mycli list --plain, then diff the sorted output against a golden file).
Add a short 'Adding a new flag or command' checklist that sequences the conventions in one pass (exit code -> stdout/stderr -> --json/--plain -> determinism -> color/TTY -> --help/--version), so the contract can be applied as a workflow rather than looked up convention-by-convention.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly dense tables, CLI transcripts, and bats test patterns, but the clig block quotes restate knowledge Claude already has ("Return zero exit code on success, non-zero on failure", "Send output to `stdout`", "Send messaging to `stderr`"). Not 5: those quotes could be trimmed to one-line citations; not 3: the over-explanation is minor relative to the lean whole. | 4 / 5 |
Actionability | Copy-paste-ready bats patterns for conventions 1-3 (`run --separate-stderr mycli list`, `echo "$output" | jq -e '.[0] | has("name") and has("status")'`), a concrete exit-code table, and good/bad output transcripts. Not 5: Convention 4's 'Test pattern: golden-file comparison with sorted output' is prose with no executable example, and conventions 5-8's patterns are delegated to the reference file. | 4 / 5 |
Workflow Clarity | Conventions are numbered and consistently structured (rule, example, test pattern), with a clear diagnostic directive ('Fix the output, not the assertion') and an anti-patterns table cross-referenced by convention number. Not 5: there is no consolidated sequence (e.g., a single checklist for adding a new flag that walks conventions 1-8); not 3: each convention's application steps are unambiguous and the skill involves no destructive or batch operations that would require validation checkpoints. | 4 / 5 |
Progressive Disclosure | The body is a clear overview keeping the four core conventions inline and delegates the rest via a clearly signaled, one-level-deep reference ('The remaining four conventions and their bats test patterns are in references/conventions-5-8.md'). The referenced file exists in the bundle, delivers exactly what is promised, and adds no further nesting. | 5 / 5 |
Total | 17 / 20 Passed |