better-github-skill

---
name: better-github-skill
description: "GitHub work via gh CLI: PRs, review conversations, CI failures, repo state, rate limits. Use when inspecting a PR, reading a review (bodies, comments, inline threads), debugging CI (finding which run failed, why a check or Actions run is red, reading job logs), waiting on or babysitting a PR (CI, reviews, conflicts), or composing non-trivial gh commands. Scripts cover what raw gh can't do (thread resolution state) or reliably fumbles (PR snapshots, CI log drilldown); use raw gh directly for everything else."
---

# better-github-skill

Raw `gh` first when you know the command; the scripts replace only the flows
agents repeatedly get wrong. Scripts run TS directly (node ≥ 23.6), no deps.

## Scripts

| script | use for |
|---|---|
| `scripts/pr-snapshot.ts [pr] [-R o/r]` | full PR state in one call: meta, mergeability, checks, files, reviews, comments, thread counts. Use instead of hand-assembling `pr view --json` field sets or chaining view/checks/comments calls. |
| `scripts/pr-threads.ts [pr] [-R o/r] [--all] [--author X] [--since ISO]` | the full review conversation: review bodies, issue comments, and unresolved inline threads (resolution state porcelain gh cannot get). Resolved/outdated threads are hidden by default, counted in the header; `--all` includes them. Read-only: never reply to or resolve threads unless explicitly told to. |
| `scripts/pr-watch.ts [pr] [-R o/r] [--timeout 9m]` | wait on a PR: blocks until a check fails, the required or all checks pass, someone else comments or reviews, the branch conflicts, or the PR merges or closes; prints what happened. Rerun after acting; it never repeats news. Quiet PRs cost nothing (conditional requests). Run it in the background, or give the tool a timeout above `--timeout`. |
| `scripts/ci-failures.ts [run-id] [--pr N] [--list] [-R o/r]` | failing checks → failing jobs/steps → log snippet each; full logs saved to files (paths printed); rg those instead of re-fetching. `--list [--workflow W] [-L n]` shows recent runs with conclusions; use it to find the failing run id instead of `gh run list --json` field sets. |

Rule of thumb: pr-snapshot answers "what's the state of this PR", pr-threads
answers "what did reviewers write". Neither replaces the other.

All scripts: `--json` for structured output, `--help` for usage (includes the
`--json` shape). Omit the PR number to use the current branch's PR. Default
output is sized for context; pass `--full` only when a truncation marker
(`[…+N chars]`) hides something you need. They exit 0 when the report
succeeds even if CI is red or threads are unresolved.

## Gotchas (each one burned real sessions repeatedly)

- Never pipe gh into `head`: SIGPIPE can kill gh mid-write (spurious nonzero
  exit, shell-dependent) or silently truncate large output.
  Redirect to a file and read that, or trim with `--jq '.[0:20]'`.
- `gh pr diff` has no `--stat` and no positive pathspec (`--name-only` and
  `-e/--exclude` globs exist in gh ≥ 2.95). Per-file stats:
  `gh api 'repos/{owner}/{repo}/pulls/N/files' --jq '.[]|[.filename,.additions,.deletions]|@tsv'`
  Full diff: `gh pr diff N > "$TMPDIR/pr.diff"` once, then rg/sed the file.
- `gh pr checks` exits 1 = failing, 8 = pending by design; append `|| true`, read the table.
- File at any ref, no base64 dance:
  `gh api 'repos/{owner}/{repo}/contents/PATH?ref=SHA' -H 'Accept: application/vnd.github.raw'`
- `gh api` fills `{owner}/{repo}` from the cwd repo (`GH_REPO=o/r` overrides).
  Quote any api path containing `?` (zsh globs it), or use `-X GET -F per_page=100`
  (any `-f`/`-F` silently flips the request to POST without `-X GET`).
- `--paginate` on any list endpoint (`/comments`, `/files`, `/reviews`); `--jq`
  already runs per page; don't add `--slurp`.