better-github-skill: gh, optimized for coding agents

Built from an analysis of 1,843 gh calls across real agent sessions, better-github-skill reduces context window usage and returns agent-optimized output for the GitHub workflows agents run most:

• pr-snapshot returns a PR's full state in one call: metadata, mergeability, checks, files, reviews, and thread counts as a few dozen dense lines, replacing the 3-5 command loop and raw JSON dumps it takes to assemble the same picture.
• pr-threads returns the full review conversation in one call: review bodies, issue comments, and unresolved inline threads, using the resolution state porcelain gh can't surface. Resolved and outdated threads stay out of context by default (the header counts what --all would add), and bodies are truncated at the point of diminishing returns. Snapshot is the PR's state; threads is everything reviewers wrote.
• ci-failures returns the failing jobs, their failed steps, and an error-anchored ~45-line snippet per job; full logs are written to disk and referenced by path, so 10k lines of CI output never enter context. --list shows recent runs with conclusions, replacing the gh run list --json field-guessing that otherwise precedes every drilldown.

For everything the scripts don't cover, agents use raw gh directly, and SKILL.md hardens that too: 13 gotchas mined from the same sessions, each a real failure mode (SIGPIPE truncation, exit-code semantics, silent GET→POST flips) with the working alternative, so agents skip the retry loops instead of rediscovering them.

	raw gh loop	with the skill
tool calls per flow	3-5 + retries	1
context consumed	full logs, diffs, JSON dumps	bounded snippets, files on disk
false-error retries	SIGPIPE / exit-code noise	none; exit 0 when the report succeeds
latency	sequential multi-turn	parallel, single turn

Why these three (the data)

The mining covered ~7 months of Claude Code and Codex session transcripts. The scripts target the highest-frequency failure classes actually observed:

observed pattern	count	script
reviewThreads GraphQL hand-retyped from scratch (7 distinct failure modes)	62–78×	pr-threads.ts
improvised pr view --json field-set guessing (40+ distinct combos)	~430 lines	pr-snapshot.ts
multi-call composites stitched with echo separators	67 lines	pr-snapshot.ts
CI drilldown chains (run list → run view --json jobs → --log | grep, 3–5 passes per run)	46 chains	ci-failures.ts
gh pr diff --stat / pathspec (flags gh doesn't have)	34 failures	SKILL.md gotcha
gh | head SIGPIPE false failures	~37% of flagged gh errors	SKILL.md gotcha

An audit of the OpenAI Codex GitHub plugin over the same corpus shaped the philosophy. Its orienting SKILL.md was its most-used artifact; its bundled scripts had zero successful runs; its ~80 connector write-tools were never called once. The lesson: minimal prose, scripts easier than the raw alternative, read-only surface.

What using it gets you

• Fewer tool calls. PR orientation and CI drilldown were reliably 3-5 call guessing loops in the mined sessions; each script collapses the chain to one.
• Less context. Output is bounded by design: bodies truncated with markers, files capped, full CI logs parked on disk with paths printed. A raw log dump is often 10k+ lines; the snippet that enters context is ~45.
• Lower cost. Fewer calls and smaller outputs mean fewer tokens per GitHub task, and the most expensive failure mode is gone: scripts exit 0 when the report succeeds, so agents never burn a turn investigating a phantom SIGPIPE or exit-code error.
• Faster answers. API calls run concurrently (measured 1.5s vs 2.3s sequential), and killing the retry loops turns multi-turn flows into single turns.
• A failure class deleted, not documented. The most re-typed, most error-prone command in the corpus was a 15-line review-threads GraphQL query with 7 observed failure modes. It's now one short command.

Testing

Beyond live self-testing during development, the skill went through an adversarial three-agent verification pass:

• Edge-case tester: ~30 live commands against real PRs: merged, closed, zero-thread, 55-file, and nonexistent PRs; non-repo cwd; malformed args; --json validity piped through jq; green runs; workflow-level (startup) failures; exit-code contract on every path.
• Adversarial code reviewer: hunted shape assumptions vs real gh JSON, parseArgs strictness, pagination, error-path masking, Promise.all failure semantics, maxBuffer overflow, type-stripping compatibility.
• Docs verifier: executed every claim in SKILL.md against gh 2.95 and flagged anything wrong or version-dependent.

The pass surfaced 9 real issues, all fixed and regression-tested, including: -F coercing all-digit repo names (broke gabrielecirulli/2048), real gh errors masked as "no checks reported", a silent wrong-PR path when -R was combined with current-branch inference, one deleted run killing the whole report, and a SKILL.md tip that would 404 (-f/-F silently flips GET→POST).

Install

Requires gh (authenticated) and node ≥ 23.6 (scripts run TS directly).

Via the skills CLI (installs into whichever agents you use):

npx skills add AVGVSTVS96/better-github-skill

Or manually:

git clone https://github.com/AVGVSTVS96/better-github-skill ~/.agents/skills/better-github-skill
ln -s ../../.agents/skills/better-github-skill ~/.claude/skills/better-github-skill   # Claude Code

Scripts are plain executables; they work standalone without the skill harness:

~/.agents/skills/better-github-skill/scripts/pr-threads.ts 5017 -R owner/repo --unresolved
~/.agents/skills/better-github-skill/scripts/pr-snapshot.ts 5017 -R owner/repo
~/.agents/skills/better-github-skill/scripts/ci-failures.ts --pr 5017 -R owner/repo