Content
71%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 information-dense, highly actionable CLI reference with strong pre-write validation semantics and real feedback loops for batch and destructive operations. The weaknesses are structural: two links target a `patterns/workflow-actions.md` file absent from the bundle, and long policy sections are inlined in SKILL.md instead of being split into clearly signaled one-level-deep references.
Suggestions
Resolve the broken navigation: either add patterns/workflow-actions.md to the bundle (including the quota-holds section anchor) or move the quota-hold and multi-step workflow details into an existing file under references/ and update both links.
Move the Shared label maintenance and Issue Creation Routing policy prose into a reference file (e.g., references/label-policy.md), keeping a two- to three-line summary with a clearly signaled link in SKILL.md.
Restructure the `issues complete` bullet (Option Behavior section) into a short numbered sequence with its validation checkpoints (parse Done-when checklist, refuse on open boxes, tick with evidence, set state) instead of one run-on paragraph.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious operational rules (refusal lines, format-rename semantics, guard behavior) and contains no padding or explanations of concepts Claude already knows, matching "efficient; minor instances that could be trimmed." It misses anchor 5 because a few passages repeat `issues --help` pointers and several run-on sentences (e.g., the `issues complete` bullet) pack many rules together and could be tightened. | 4 / 5 |
Actionability | Concrete, executable commands are present (e.g., `linear.sh issues list --project "Phase 2" --state "Todo,In Progress" --max`, `linear.sh attachments fetch [URL] --output tmp/[FILENAME]`) along with exact flags, env vars, stderr refusal lines, and per-command `--help` routes. It stops short of anchor 5 because the most common write operations (create, update, complete) never get an example invocation — the reader must consult `--help` to construct them. | 4 / 5 |
Workflow Clarity | Multi-step processes carry explicit validation: the label workflow ("Fetch current labels, compute the final set, validate it against `labels list --max --format=safe`"), "Run `auth-check --strict` before the first mutation", bulk-refusals listed before writes with `partial: true` exit-nonzero semantics, and `issues bulk-get` named as the post-mutation verification path. The destructive/batch cap at 3 does not apply since validation is present throughout; it misses 5 because sections like Issue Creation Routing and the `issues complete` bullet state rules as dense prose rather than a sequenced procedure with checkpoints. | 4 / 5 |
Progressive Disclosure | The two bundle references are real and clearly signaled ([authentication](references/authentication.md), [request journal](references/request-journal.md)), but the body links `patterns/workflow-actions.md` twice (including the "Quota Holds" section anchor) and no `patterns/` directory exists in the bundle — a broken navigation path. Additionally, substantial inline rule/policy content (Shared label maintenance, Issue Creation Routing, Option Behavior minutiae) reads as material that belongs in reference files, matching anchor 3 ("content that should be separate is inline") rather than anchor 4's "most content is appropriately placed." | 3 / 5 |
Total | 15 / 20 Passed |