Content
65%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 exceptionally actionable command reference with concrete flags, error-recovery loops, and output schemas — top marks on actionability. It loses points for token-inefficient filler code and triple-stated rules, an unverified destructive unstack workflow, and a monolithic single-file layout that inlines a full command reference instead of splitting it into bundle files.
Suggestions
Remove the placeholder heredoc Go source files from the workflows and consolidate the non-interactivity rules (currently stated in Agent rules, the 'Never do' list, and per-command sections) into one authoritative location to cut substantial tokens.
Add a verification checkpoint to the destructive 'unstack' restructure workflow — e.g., run 'gh stack view --json' to confirm PR merge state before tearing down the stack locally and on GitHub.
Move the detailed per-command reference and the --json output schema into a references/ file (e.g., COMMANDS.md), keeping the quick-reference table and workflows in SKILL.md with clearly signaled one-level-deep links.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk is dense, tool-specific reference that Claude could not know, but ~80 lines of filler heredoc Go source files in the workflows add nothing about gh-stack, and the non-interactivity rules are repeated three times (Agent rules, the 'Never do' list, and per-command notes). Mostly efficient with clearly trimmable sections — matches anchor 3 better than the noticeably-padded anchor 2. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready guidance throughout: exact commands with flags, a quick-reference table, the full --json output schema, jq parsing recipes, exit-code-to-agent-action mapping, and specific conflict-resolution steps. Covers the common cases comprehensively. | 5 / 5 |
Workflow Clarity | Sequencing is excellent and the rebase-conflict workflow has a full validate/fix/retry feedback loop with --continue/--abort, but the destructive 'unstack' restructure workflow (tears down the stack locally and on GitHub) includes no verification checkpoint such as confirming PR merge state via 'gh stack view --json' first. Per the rubric, a destructive workflow without validation caps workflow clarity at 3 — this takes precedence over the otherwise strong sequencing. | 3 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), so everything lives in a single ~780-line SKILL.md. Internal structure is good (headers, quick-reference table), but ~400 lines of full per-command reference plus the JSON schema are inlined content that would be better split into a referenced file. Some structure with content that should be separate inline — anchor 3; not 2 because navigation via the table and headers is genuinely easy. | 3 / 5 |
Total | 14 / 20 Passed |