| name | gh-cli |
| license | MIT |
| description | GitHub CLI (gh) をエージェントが非対話で安全に使うための実践パターン集。 PR の作成・レビュー・マージ、issue 管理、リリース作成、GitHub Actions の実行確認・失敗調査、 gh api での REST/GraphQL 呼び出し、リポジトリ操作、GitHub 上の検索、agent skill の インストール・公開 (gh skill) を扱う。ユーザーが「PR を作って」「issue を立てて」 「リリースして」「CI の結果を見て」「GitHub で検索して」「スキルをインストールして」など GitHub 操作に言及したら、gh コマンドを組み立てる前にこのスキルを参照すること。 gh は対話プロンプトでハングしたり人間向け出力が不安定だったりするため、 単純そうな gh 操作でも発動する側に倒す。 |
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'
...
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 に反映させるフラグを持つコマンドがある（各リファレンス参照）
タスク別リファレンス
該当する作業を始める前に対応するファイルを読むこと。
頻出ワンライナー
gh pr view --json number,title,state,url
gh pr checks --watch --fail-fast
gh run list --limit 1 --json databaseId --jq '.[0].databaseId' | xargs -I{} gh run view {} --log-failed
gh release create v1.2.3 --generate-notes
gh api repos/{owner}/{repo}/releases --jq '.[].tag_name'
