Content
75%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 highly actionable, well-sequenced skill body with excellent concrete command examples and validation checkpoints at both ends of the workflow. Its main weakness is repetition — three core principles are each restated multiple times across Steps 3b/4 and the Guidelines section, inflating the token budget by roughly a third.
Suggestions
Consolidate the command-quality principle into one authoritative statement (keep the Step 3b falsifiability test and the good/bad examples) and drop its restatements in Guidelines — the 'add/remove commands' guidance repeats nearly verbatim.
Merge the behavioral-over-structural guidance from Steps 2 and 4 and the Guidelines into a single prioritized list, keeping the good/bad `facts add` examples once.
Add an explicit feedback loop to Step 6: if `facts check` fails after edits, revisit the commands added in Step 3b and fix or revert them before reporting.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and domain-specific, but three core principles are each restated ~3 times: command falsifiability (Step 3b blockquote, Guidelines "Command quality matters more than command count" and "Only add commands that would break"), behavioral-over-structural facts (Steps 2, 4, Guidelines), and domain vocabulary consistency (Steps 2b, 3, 4, Guidelines). This goes beyond minor trimming and the body could be tightened to ~200 lines without loss. | 3 / 5 |
Actionability | Fully executable throughout: exact CLI commands (`facts list`, `facts edit <id> --add-tag "implemented"`, `facts remove <id>`, `facts add "..." --section`), concrete good/bad shell command examples for both facts and validation commands, and a complete worked example session covering the common cases. | 5 / 5 |
Workflow Clarity | A clearly sequenced process (1, 2, 2b, 3, 3b, 4, 5, 6) with validation at both ends (`facts check` in Step 1 and Step 6) and per-case error handling (partial truths, obsolete facts, failed commands). Minor gap: no explicit recovery loop for the final validation — Step 6 says to confirm checks pass but not what to do if one fails. | 4 / 5 |
Progressive Disclosure | Good single-file structure with well-organized, clearly headed sections and no buried or nested references (no bundle files exist). The ~90 lines of good/bad command examples in Step 3b are central guidance rather than clearly-separable reference material, but at ~310 lines the body is on the large side for one file. | 4 / 5 |
Total | 16 / 20 Passed |