Content
63%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.
The body is an information-dense operator manual with unusually concrete failure semantics and validation rules, but it reads as a wall of run-on prose that concentrates journal internals, governance policy, and per-option behavior in the top-level file. The dangling references to missing `patterns/` and `README.md` files are the clearest structural defect.
Suggestions
Add the referenced files (patterns/workflow-actions.md, README.md) to the bundle or remove/redirect the links — three links in the body currently point at files that do not exist, including the Quota Holds section that error handling depends on.
Move the Request journal section and Shared label maintenance into a reference file (e.g., references/journal.md, references/label-governance.md) and keep a 3-5 line pointer in SKILL.md, cutting roughly a third of the body.
Break the multi-clause run-on sentences (Issue Creation Routing, the `issues complete` bullet) into short imperative bullets or a numbered sequence so each rule is individually scannable and citable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body wastes no tokens on concepts Claude already knows — it is packed with operational facts like "A quota refusal exits nonzero with JSON stderr `code:\"RATELIMITED\"`" — but at ~162 lines of dense run-on prose (the single-sentence Issue Creation Routing paragraph, the ~700-word `issues complete` bullet) much of it (journal internals, label governance, option minutiae) is overstuffed for a top-level SKILL.md and could be significantly tightened. Mostly earns its tokens but noticeably could be trimmed and split, matching anchor 3. | 3 / 5 |
Actionability | Concrete, executable commands appear throughout — `linear.sh issues list --project "Phase 2" --state "Todo,In Progress" --max`, `auth-check --strict`, `comments bulk-list <ID1> <ID2> --stdin` — with exact refusal-line formats and exit-code semantics. Minor gaps keep it from anchor 5: common flows like a fully-flagged `issues create` example are never shown, and some guidance defers to external surfaces ("`linear.sh <resource> --help`", the project-management skill, `lane-mail peer send`). | 4 / 5 |
Workflow Clarity | Multi-step flows carry real validation checkpoints: pre-write refusals ("Refused before any write" for option validation, cross-team guards, taxonomy checks), post-mutation verification ("`issues bulk-get` ... is also the post-mutation verification path"), label updates as fetch → compute → "validate it against `labels list --max --format=safe`" → pass the complete set, and error recovery for partial failures ("`partial: true` and exits non-zero"). It falls short of anchor 5 because sequences are dispersed through prose rather than presented as ordered workflows, and a few checkpoints are implicit (e.g., attachment fetch failure handling). | 4 / 5 |
Progressive Disclosure | Section headers (## Commands, ## Reads, ## Attachments, ## Team Target) give real structure and the bundle genuinely splits code across `scripts/commands/` and `scripts/lib/`, but the body links to `patterns/workflow-actions.md`, `patterns/workflow-actions.md#quota-holds`, and `README.md#setup` — none of which exist in this bundle — and large chunks that belong in reference files (the ~40-line Request journal section, Shared label maintenance, Option Behavior detail) are inlined. This matches anchor 3: some structure, references present but flawed, content that should be separate is inline. | 3 / 5 |
Total | 14 / 20 Passed |