Content
67%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 dense, highly actionable command reference with strong validation checkpoints and a sound overview-to-help/reference split, weakened mainly by two long, tangled prose sections that duplicate the --help contracts they cite and could be trimmed or moved to reference files.
Suggestions
Move the PR Merge Outcomes and Review reply check contract prose into reference files (e.g. references/merge-outcomes.md) or shrink them to exit-code/routing summaries, keeping the full contract in pr-merge --help as the body already advertises.
Add a copy-paste example for the VAR_SIGN multi-line GraphQL query with -F variables, and a worked pr-merge --check / queue-wait sequence covering the common merge case.
Break the merge-route paragraph into a short ordered list or decision table so the exit-75 → arm → queue-wait → re-check sequence is scannable instead of prose.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The command table is extremely lean with no general-knowledge padding, but the ~450-word PR Merge Outcomes and Review reply check prose paragraphs restate contract detail that each section itself defers to "Full contract: pr-merge --help" / "check-review-replies --help", so the body "could be tightened" — anchor 3. Not 4 because the tightening opportunity is substantial, not minor; not 2 because nothing explains concepts Claude already knows and there is no padded filler. | 3 / 5 |
Actionability | Concrete script paths, per-command flags, exit codes (0/75/1), and copy-paste snippets ("github.sh pr-threads 42", "env -u GH_TOKEN -u GITHUB_TOKEN gh pr list") cover most cases — anchor 4. Not 5 because a few guidance points stay abstract, e.g. "VAR_SIGN: use a multi-line GraphQL query with -F variables" gives no example query, and there is no worked pr-merge invocation. | 4 / 5 |
Workflow Clarity | Multi-step flows carry explicit validation checkpoints: pr-merge --check readiness JSON, the repeat-until-merge-clears loop in "PR blocked with no visible conversations", exit-code routing (exit 75 → arm one exact head → queue-wait), and the "Never gate termination on gh pr view --json mergeable" guard with the state-reading alternative. Not 5 because the merge-route workflow, while fully specified, is a tangled prose paragraph rather than a clearly ordered sequence, making the steps harder to extract than anchor 5's "clear sequence". | 4 / 5 |
Progressive Disclosure | Structure matches the bundle: an overview command table, detail deferred to per-command --help files (scripts/commands/ holds one script per table row), and one real, clearly-signaled reference (references/automatic-review.md, linked as markdown). Anchor 4 ("Good structure; most content is appropriately placed; references mostly clear"). Not 5 because the dense PR Merge Outcomes / reply-check contract prose is inlined in SKILL.md where the skill's own pattern would put it in a reference file or --help. | 4 / 5 |
Total | 15 / 20 Passed |