better-github-skill

better-github-skill

コマンドが分かっている場合は、まず生の gh を使ってください。スクリプトは、エージェントが繰り返し間違えるフローだけを置き換えます。スクリプトは TS を直接実行し（node ≥ 23.6）、依存関係はありません。

スクリプト

スクリプト	用途
scripts/pr-snapshot.ts [pr] [-R o/r]	1 回の呼び出しで PR の全状態を取得します。メタ情報、マージ可能性、チェック、ファイル、レビュー、コメント、スレッド数が含まれます。pr view --json のフィールドを手作業で組み立てたり、view／checks／comments の呼び出しを連結したりする代わりに使ってください。
scripts/pr-threads.ts [pr] [-R o/r] [--all] [--author X] [--since ISO]	レビューの会話全体を取得します。レビュー本文、Issue コメント、未解決のインラインスレッド（gh では取得できない解決状態）を含みます。解決済み／古いスレッドはデフォルトで非表示になり、ヘッダーに件数が表示されます。--all を指定すると、それらも含まれます。読み取り専用です。明示的な指示がない限り、スレッドへの返信や解決はしないでください。
scripts/ci-failures.ts [run-id] [--pr N] [--list] [-R o/r]	失敗したチェック → 失敗したジョブ／ステップ → 各ログの抜粋を表示します。完全なログはファイルに保存され（パスが表示されます）、再取得する代わりに rg で検索できます。--list [--workflow W] [-L n] は結論付きの最近の実行を表示します。gh run list --json のフィールドを組み立てる代わりに、これを使って失敗した実行 ID を見つけてください。

経験則：pr-snapshot は「この PR の状態はどうなっているか」に答え、pr-threads は「レビュー担当者は何を書いたか」に答えます。どちらも、もう一方の代わりにはなりません。

すべてのスクリプトで、構造化出力には --json、使い方（--json の形式を含む）の確認には --help を指定します。PR 番号を省略すると、現在のブランチの PR が使われます。デフォルトの出力はコンテキストに合わせたサイズです。必要な情報が切り詰め表示（[…+N chars]）で隠れている場合にのみ、--full を指定してください。CI が赤、またはスレッドが未解決でも、レポートの取得に成功すれば終了コードは 0 です。

注意点（いずれも、実際のセッションで何度も問題になりました）

• gh を head にパイプしないでください。SIGPIPE によって書き込み途中で gh が終了する（誤った非ゼロ終了、シェルに依存）場合や、大きな出力が黙って切り詰められる場合があります。 ファイルにリダイレクトして読み取るか、--jq '.[0:20]' で絞り込んでください。
• gh pr diff に --stat や正のパス指定はありません（--name-only と -e/--exclude の glob は gh ≥ 2.95 で利用できます）。ファイルごとの統計： gh api 'repos/{owner}/{repo}/pulls/N/files' --jq '.[]|[.filename,.additions,.deletions]|@tsv' 差分全体：gh pr diff N > "$TMPDIR/pr.diff" を一度実行し、その後はファイルを rg／sed で検索してください。
• gh pr checks は、失敗時は 1、保留中は仕様上 8 で終了します。|| true を付けて、表を確認してください。
• 任意の ref にあるファイルを取得する際、base64 の処理は不要です： gh api 'repos/{owner}/{repo}/contents/PATH?ref=SHA' -H 'Accept: application/vnd.github.raw'
• gh api は cwd のリポジトリから {owner}/{repo} を補います（GH_REPO=o/r で上書きできます）。? を含む api パスは引用符で囲んでください（zsh では glob として扱われます）。または -X GET -F per_page=100 を使ってください（-X GET がないと、-f／-F はリクエストを黙って POST に切り替えます）。
• リストのエンドポイント（/comments、/files、/reviews）では --paginate を指定してください。--jq はページごとに実行されるため、--slurp は追加しないでください。
• PR／コメントの本文には、--body-file file.md または引用符で囲んだヒアドキュメントを使ってください。バッククォートを含む --body "..." をインラインで指定しないでください。
• フィールドの早見表：PR の CI ステータス = statusCheckRollup（pr view）；ステップは gh run view N --json jobs 配下にあります；gh search prs のフィールドは gh pr view のフィールドとは異なります。
• gh に -C はありません。すべてのコマンドに -R owner/repo を渡すか、先に cd してください。
• 最近のリポジトリでは、ブランチルールは gh api 'repos/{owner}/{repo}/rulesets' にあります。/branches/main/protection は、従来の保護が有効で、かつ管理者権限がある場合を除き 404 になります（"Branch not protected" と単なる "Not Found" のどちらも、パスのエラーではなく rulesets を確認する必要があることを意味します）。
• ブランチの差分： gh api 'repos/{owner}/{repo}/compare/BASE...HEAD' --jq '{ahead_by,behind_by}'
• 1 行を超える jq の処理では、プログラムをファイルに書き込み、jq -f prog.jq を使ってください。zsh ではインラインの引用符処理が壊れます。
• 実行やチェックを sleep でポーリングしないでください。gh run watch ID と gh pr checks N --watch --fail-fast が使えます。ハーネスにバックグラウンドで実行させてください。