oubakiou gh-cli
GitHub CLI (gh) をエージェントが使うためのスキル。gh 2.90.0 系の help と
公式マニュアル を元にしている。
help 全文の複製はしない。個々のフラグの完全な一覧が必要なら
gh <command> <subcommand> --help を実行するのが常に最新で正確。
このスキルは「エージェントが踏みやすい罠」と「頻出レシピ」に絞る。
大原則
1. 対話プロンプトを発生させない
gh は引数が足りないと対話プロンプトや $EDITOR を開き、エージェントはそこでハングする。
- 必須情報（title / body / tag 等）は必ずフラグで渡す。
gh pr createを裸で実行しない -e/--editorフラグは使わない（エディタが開く）-w/--webフラグは使わない（ブラウザが開く）- 破壊的操作の確認プロンプトは
--yes等の明示フラグで抑止する - 保険として
GH_PROMPT_DISABLED=1を設定すると、対話プロンプトが必要な場面で ハングせずエラー終了になる
複数行の body はインライン文字列より --body-file が安全（クォート事故を防ぐ）:
gh pr create --title "feat: add X" --body-file - <<'EOF'
## Summary
...
EOF
2. 出力は --json + --jq で機械的に取る
人間向けのデフォルト出力（表形式・色付き）を文字列パースしない。
--json 対応コマンドでは必ず --json <fields> を使う。
- 利用可能なフィールド名は
--jsonを値なしで実行するとエラーメッセージに一覧が出る - 絞り込みは
--jqを併用（jq 本体のインストール不要で gh に内蔵）
gh pr list --json number,title,author --jq '.[] | "\(.number)\t\(.title)"'
3. リポジトリ指定
カレントディレクトリが対象リポジトリの checkout でない場合は
-R owner/repo フラグか環境変数 GH_REPO=owner/repo を指定する。
checkout 内なら省略してよい。
4. 認証と exit code
- 認証状態の確認:
gh auth status。CI 等ではGH_TOKEN環境変数が最優先で使われる - exit code:
0成功 /1失敗 /2キャンセル /4認証が必要 gh run watch --exit-statusやgh pr checksのように、対象の失敗を exit code に反映させるフラグを持つコマンドがある（各リファレンス参照）
タスク別リファレンス
該当する作業を始める前に対応するファイルを読むこと。
| やりたいこと | リファレンス |
|---|---|
| PR の作成・確認・レビュー・マージ・CI チェック | references/pr.md |
| issue の作成・検索・更新・ブランチ連携 | references/issue.md |
| リリースの作成・アセット管理・ダウンロード | references/release.md |
| GitHub Actions の実行確認・失敗調査・再実行・workflow 起動 | references/actions.md |
| REST/GraphQL API 呼び出し、--json/--jq/--template の詳細 | references/api-and-json.md |
| リポジトリの作成・clone・fork・設定変更 | references/repo.md |
| リポジトリ・issue・PR・コード・コミットの横断検索 | references/search.md |
| agent skill の検索・インストール・更新・公開 (gh skill) | references/skill-management.md |
頻出ワンライナー
# 現在のブランチの PR を確認
gh pr view --json number,title,state,url
# CI が全部通るまで待ち、失敗したら非ゼロで終了
gh pr checks --watch --fail-fast
# 直近の workflow run の失敗ログだけ見る
gh run list --limit 1 --json databaseId --jq '.[0].databaseId' | xargs -I{} gh run view {} --log-failed
# リリースを notes 自動生成で作成
gh release create v1.2.3 --generate-notes
# REST API を呼んで必要なフィールドだけ抽出
gh api repos/{owner}/{repo}/releases --jq '.[].tag_name'