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.
A strong, highly actionable body: every read command is presented with concrete syntax, flags, defaults, and output shape, and external detail is properly pushed to real one-level-deep reference files. The main weaknesses are redundancy — overlapping setup/error tables and a triplicated `opencli doctor` explanation — and a non-executable pseudo-syntax block in Step 1.
Suggestions
Merge the 'Common setup issues' table and the 'Error Reference' table into one, and fold the Step 5 Diagnostics section into Step 1 or the error table — `opencli doctor` and its failure modes are currently explained three separate times.
Replace the non-executable "!`(...)`" environment-status block in Step 1 with a plain bash snippet (e.g. `command -v opencli && opencli doctor`) so the check is copy-paste runnable.
Move the per-command "Output columns" listings into references/schema.md, keeping only one example inline, so that detail lives where the schema is documented.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly dense, useful signal — a command routing table, flag tables, and concrete examples — with no explaining of concepts Claude already knows. It falls short of the lean anchor because of trimmable redundancy: the "Common setup issues" and "Error Reference" tables repeat the same three rows (Extension not connected / No session / CSRF token missing), `opencli doctor` is explained three times (Step 1, setup, Step 5 Diagnostics), and the read-only caveat is restated three times in the body. | 4 / 5 |
Actionability | Guidance is fully executable and copy-paste ready: a routing table mapping each user request to a specific command with its flags ("opencli twitter search \"QUERY\"" with "--filter top|live", "--limit N"), worked examples ("opencli twitter search \"$AAPL earnings\" --filter live --limit 10 -f json"), and per-command output columns. It matches the top anchor — concrete commands covering the common cases — and exceeds the 4 anchor which allows minor gaps. | 5 / 5 |
Workflow Clarity | Steps 1–5 form a clear sequence with a real checkpoint (run `opencli doctor` before anything else if unsure; jump to Step 5 on failure). The gap versus the 5 anchor is that the Step 1 status check is a non-executable pseudo-block — "!`(command -v opencli && opencli doctor ...) || echo \"NOT_INSTALLED\"`" — with an unexplained `!`(...) syntax, and recovery guidance is duplicated across three sections rather than a single feedback loop. It sits above the 3 anchor since checkpoints are explicit, not merely implied. | 4 / 5 |
Progressive Disclosure | Structure is good: SKILL.md is a working overview, both referenced files (references/commands.md, references/schema.md) exist, are one level deep, contain no further nested references, and are clearly signaled ("Read the reference files when you need exact command syntax..."). It misses the top anchor because the detailed "Output columns" section (per-command column lists) duplicates material that belongs in references/schema.md, keeping some reference content inline. | 4 / 5 |
Total | 17 / 20 Passed |