Content
88%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 agent-facing CLI contract: executable examples, deterministic ordering, explicit error-recovery loops, and validation gates on every batch operation. The weaknesses are mild — some off-topic human-TUI/forks material and a monolithic single-file layout where reference files would slim the always-loaded body.
Suggestions
Cut the forks/CSV-mode section and the two `spn forks` Quick Reference rows down to a single pointer line to the `using-spn-forks` skill — the skill itself says fork work is a different use case, yet it still details the 24-column CSV header here.
Drop the "TUI parity" and "Spoon flag parallel" sections (human-facing tooling, not agent guidance), and collapse the BulkSkip.Reason table or the prose bullets above it — they state the same two rules twice within ten lines.
Move the stable reference material (error envelope shapes, exit-code catalog, rate-limit details, per-verb flag surfaces) into a references/ file (e.g. references/output-contract.md) and keep SKILL.md to the core loop, policies, and common mistakes.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk is non-derivable tool contract (exit codes, error envelopes, partial-failure dedup, per-verb flag surfaces) that earns its tokens, but there is trimmable material: the off-topic CSV-mode/forks section, the TUI parity and "Spoon flag parallel" sections about a human-facing tool, and the BulkSkip.Reason table duplicating the bullets immediately above it. Fits anchor 4 ("efficient; minor instances of over-explanation") more than 3, since the padding is a small fraction of the document. | 4 / 5 |
Actionability | Every workflow ships copy-paste-ready bash: the core `spn threads next` loop with jq field extraction, the rate_limited retry, the partial-failure dedup retry, the dry-run gating pattern, and apply-suggestion/counter-proposal invocations. Fully executable and covering the common cases — matches the 5 anchor. | 5 / 5 |
Workflow Clarity | The core loop is an explicit terminated sequence, and risky batch operations get explicit validation checkpoints: preview-then-act (`--dry-run` two-step and gating pattern), check `comment_posted` before retry, check `dryRun` before believing `isResolved`, and the mergeability gate before declaring done. Feedback loops for error recovery are present throughout, matching the 5 anchor; the destructive/batch cap does not apply because resolve-all is explicitly gated by dry-run previews. | 5 / 5 |
Progressive Disclosure | Well-sectioned, one level deep, no nested references, with in-document pointers ("see Code context and verbose mode") and a clean hand-off to the separate `using-spn-forks` skill. However, at ~360 lines everything lives inline in SKILL.md — the error-contract detail, BulkSkip reference, and per-verb flag surface are reference-file candidates — which fits anchor 4 ("good structure; minor organization gaps") rather than 5 ("content appropriately split"). | 4 / 5 |
Total | 18 / 20 Passed |