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.

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:

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