github-cli-ops

github-cli-ops

概要

このスキルを使うと、エージェントはあらゆるGitHub 操作をCLI 優先で実行できます。gh が対応するすべての操作には gh CLI を使用します。これは、シークレットを暗号化し、出力を整形する使いやすい方法です。gh コマンドが存在しない場合に限り gh api（REST）にフォールバックし、GraphQL のみで対応できる一部の機能には gh api graphql を使います。認証は呼び出しごとに行われます。呼び出し元から注入されたトークンを使って、各呼び出しの前に GH_TOKEN="$<token var>" を付けるため、グローバル設定が変更されることはありません。gh はベース URL、ページネーション、出力をすでに管理しているため、エージェントが HTTP 処理を再実装する必要はありません。REST の残りのエンドポイントについては、エージェントが同梱の OpenAPI 仕様で エンドポイントインデックスと $ref リゾルバーを使ってエンドポイントを検索し、gh api の呼び出しを組み立てます。

有効化するタイミング

• ✅ ファーストクラスのコマンドがある GitHub 操作を実行する場合 — issue、プルリクエスト、リポジトリ、リリース、ラベル、gist、Actions の実行／ワークフロー、Projects、シークレットなど（gh <command>）。
• ✅ ファーストクラスのコマンドが存在しないREST 操作の場合 — gh api <endpoint> で実行します。
• ✅ GraphQL のみで対応できる操作（例：Discussions）が必要な場合 — gh api graphql を使います。
• ✅ github.com に対してプログラムで書き込みを行う必要がある場合。

次の場合は有効化しないでください：

• ローカルでの対話的な gh 操作の場合 — gh auth …、gh browse、gh repo clone、gh pr checkout、gh config、gh alias、gh extension、gh completion。これらはローカルでの利便機能であり、API 操作ではありません。gh／git を直接使用してください。
• 主な対象がGitHub Enterprise Server の場合（このスキルの v1 は github.com を対象としています。Enterprise のホストは注入された host と GH_HOST／GH_ENTERPRISE_TOKEN を介してルーティングされますが、ここではテストされていません）。
• 認証情報の設定のみが必要な場合 — 認証情報は呼び出し元から提供されます。このスキルは認証情報をプロビジョニングしたり解決したりしません（このスキルが利用する契約については references/auth.md を参照してください）。

ワークフロー

ステップ 1 — 注入された認証情報を受け取る

呼び出し元はすでにアカウントを特定し、この操作に必要な情報を注入しています。自分でレコードを探さず、それを使用してください。コンテキストから次の情報を受け取ります。

• host（およびアカウントが利用する権限）— ファイルから読み取るのではなく、コンテキスト値として渡されます。
• 順序付きの読み込みルールで指定されたトークン。コンテキストには変数名が含まれています。その名前は、プロジェクトレベルの .env ファイルが存在し、そのファイルで変数が定義されていればその値、それ以外の場合はその名前の環境変数として解決します。プロジェクトの .env が最初に参照されます（これにより、プロジェクトの .env がグローバルな環境変数を上書きします）。トークンの値はコンテキストの説明文には含まれません。含まれるのは変数名のみです（以下の例では $<token_env>）。トークンを読み取るのは gh サブプロセスだけです。プロジェクトルートはコンテキストから提供されるため、.env を探すためのスコープ解決やディレクトリ走査は行わないでください。また、対象はプロジェクトの .env であり、.envrc ではありません。

実際の操作を行う前に、次のコマンドでトークンが機能することを確認してください：GH_TOKEN="$<token_env>" gh api user --jq .login。アカウントを選択するために gh auth switch／gh auth login は使用しないでください。これらは gh のグローバルなアクティブアカウント（ユーザーの複数のシェルで共有されます）を変更します。認証は GH_TOKEN を使って呼び出しごとに行います。契約全体と環境変数のブリッジについては references/auth.md を参照してください。

ステップ 2 — CLI と API のどちらを使うか決める

assets/cli-index.md（コマンドごとに 1 行）を調べ、操作に一致する gh コマンドを探してください。判断ルール： gh コマンドがある場合は常にそれを優先します。gh api は対応していない操作に限り使用し、GraphQL のみで対応できる操作には gh api graphql を使います。注意：コマンドが存在しない領域もあります（teams、checks、packages、code-scanning／-security、dependabot、git データ、reactions、apps、migrations など）。そうした領域では一覧を調べず、直接 gh api を使用してください（対象一覧は references/gh-api.md にあります）。

ステップ 3a — CLI パス（推奨）

gh <cmd> --help からコマンドの正確なフラグを読み取ります（インストール済みの gh に対応した最新情報です）。呼び出しごとのトークンを使って実行します。

GH_TOKEN="$<token_env>" gh issue create --repo OWNER/REPO --title "…" --body "…"
GH_TOKEN="$<token_env>" gh repo view OWNER/REPO --json name,visibility,defaultBranchRef --jq '.defaultBranchRef.name'
GH_TOKEN="$<token_env>" gh secret set MYSECRET --repo OWNER/REPO --body "$VALUE"   # gh encrypts client-side

機械可読な出力には --json <fields> [--jq <expr>] を使います。references/cli-reference.md を参照してください。

ステップ 3b — API によるフォールバック

コマンドが存在しない場合：assets/endpoint-index.md で操作を探し、python3 scripts/endpoint.py <operationId> を使ってスキーマを解決します（$ref 解決済みのパラメーター／本文／レスポンスとスケルトン）。次に、以下を構築します。

GH_TOKEN="$<token_env>" gh api repos/{owner}/{repo}/traffic/views --jq '.count'
GH_TOKEN="$<token_env>" gh api -X PATCH repos/{owner}/{repo} -f description='…'
GH_TOKEN="$<token_env>" gh api graphql -f query='{ viewer { login } }'

{owner}／{repo}／{branch} のプレースホルダーには、現在のリポジトリまたは GH_REPO の値が入ります。フラグ、ページネーション、GraphQL の詳細については、references/gh-api.md を参照してください。

ステップ 4 — レスポンスを処理する

• 出力： --jq／--json（CLI）または --jq／--template（gh api）。
• ページネーション（gh api）： --paginate は Link ヘッダーを自動的にたどります。--slurp はすべてのページを 1 つの配列にまとめます。GraphQL のページネーションには、クエリ内の $endCursor と pageInfo{hasNextPage,endCursor} が必要です。
• エラー： 終了コードがゼロ以外の場合／HTTP 4xx は API の回答です。多くの場合、トークンスコープの問題です。必要なスコープを持つトークンを発行してください（references/auth.md を参照）。これはスキルの不具合ではありません。

ルール

必須ルール（決して違反しないこと）：

• 呼び出しごとに GH_TOKEN のみを使います。 すべての呼び出しを GH_TOKEN="$<token_env>" gh … で認証してください。gh auth switch／gh auth login は決して使わないでください（グローバル状態が変更されます）。デフォルト以外のホストには GH_HOST／GH_ENTERPRISE_TOKEN を使います。
• トークンの値を読み取ったり、表示したりしないでください。 $<token_env> としてのみ参照してください。gh サブプロセスは環境からトークンを読み取ります。トークンは .env（gitignore 対象）にのみ保存されます。
• CLI を優先します。 コマンドが存在する場合は gh コマンドを優先してください。gh api は不足分を補うために使い、GraphQL 専用の場合は gh api graphql を使います。gh が標準で実行できる処理に対して、gh api の呼び出しを手動で組み立てないでください。
• gh api の呼び出しを構築する前にスキーマを解決します。 推測または記憶に頼ったフィールドセットではなく、$ref 解決済みのスキーマ（ステップ 3b）からパラメーター／本文を組み立ててください。
• シークレットには gh secret set を使います。 クライアント側で暗号化されます。libsodium を独自に扱ったり、生のシークレット値を自分で PUT したりしないでください。
• このスキルは認証情報を書き込みません。 認証情報は呼び出し元から提供されます。このスキルが認証情報を発行したり解決したりすることはありません。

推奨事項（変更可能）：

• 出力を小さく保つため、必要なフィールドだけを要求します（コマンドでは --json <fields>、絞り込みには --jq／-q）。
• 人間向けテキストを解析するより、ファーストクラスコマンドの構造化出力（--json）を優先します。
• 大規模な gh api コレクションでは --paginate を使います（単一の統合配列が必要な場合は --slurp も使います）。

注意事項

• gh auth switch はグローバルに作用します。 この呼び出しだけでなく、すべてのシェルでアクティブなアカウントを変更します。これは、このスキルが回避するまさにその失敗です。代わりに、常に呼び出しごとに GH_TOKEN を渡してください。
• gh api の -f と -F の違い。 -f／--raw-field は文字列を送信します。-F／--field は型を自動判定します（true／false／null／整数は JSON の型になり、@file はファイルを読み込み、{owner} プレースホルダーには値が入ります）。ブール値や整数に -f を使うと、リテラル文字列が送信され、API に拒否されます。
• フィールドを追加するとメソッドが POST に切り替わります。 -f／-F を使うと、gh api は自動的に GET から POST に切り替わります。クエリパラメーターを指定して GET するには -X GET を使います（指定しない場合、パラメーターはクエリ文字列に入ります）。
• 不具合ではなく、トークンスコープの問題です。 有効な呼び出しで 4xx が返る場合、通常はトークンスコープ（例：repo、delete_repo、read:org）が不足しています。原因を示して適切なスコープを持つトークンを発行し、むやみに再試行しないでください。
• プレースホルダーにはリポジトリコンテキストが必要です。 {owner}／{repo} は、現在の git リポジトリまたは GH_REPO の値からのみ埋められます。リポジトリ外では、完全なパス（repos/OWNER/REPO/…）を渡してください。
• GH_TOKEN 設定時の gh auth status は環境変数のトークンを報告し、login／switch を無効にします。これは想定どおりであり、呼び出しごとの認証が有効であることを意味します。

アンチパターン

• アカウント選択に gh auth switch を使うこと。 絶対に使わないでください。グローバル状態が変更されます。ここでアカウントを選択する唯一の方法は、呼び出しごとに GH_TOKEN を指定することです。
• トークンを表示すること。 echo $TOKEN は絶対に実行せず、表示されるコマンドにトークンを貼り付けず、その値をファイルに書き込まないでください。環境変数のみを参照してください。
• gh がネイティブに実行できる操作に gh api を使うこと。 gh issue create があるのに、gh api repos/{owner}/{repo}/issues -f title=… を手作業で組み立てないでください。利便性と検証機能が失われます。
• シークレットの暗号化を独自に実装すること。 公開鍵を取得して libsodium で自分で暗号化しないでください。gh secret set が処理します。
• gh api の本文を推測すること。 スキーマを確認してください（ステップ 3b）。フィールドの要件はエンドポイントによって異なります。
• 仕様全体を読み込むこと。 数 MB の OpenAPI JSON を cat でコンテキストに読み込まないでください。インデックスを検索し、対象のオペレーションを 1 つ解決してください。

出力

このスキルは GitHub に副作用（リクエストされた操作）を発生させ、解析した結果を呼び出し元のエージェントに返します。独自のファイルは書き込みません（呼び出し元から注入された認証情報を 使用するだけ です）。書き込み操作では作成・更新されたリソース（番号、URL、ID）を報告し、読み取り操作では必要に応じてページネーションしながら結果セットを返します。抽象的な利用者は、操作の実行を必要とする呼び出し元のエージェント（またはサブエージェント）です。トークンが出力に含まれることはありません。

関連項目

• references/auth.md — このスキルが使用する認証情報の契約（呼び出し元から注入されるホストと、順序付きトークン読み込みルール）、呼び出しごとの GH_TOKEN、検証プローブ、シークレットの適切な取り扱いについて説明します。
• CLI を優先し、次に gh api にフォールバックするパターン（同梱の OpenAPI 仕様を使用）は、専用 CLI を提供する他のプロバイダーにも応用できます。

段階的な情報開示

詳細な内容はサブフォルダーにあり、必要な場合にのみ読み込みます。

• references/auth.md — このスキルが使用する認証情報の契約について説明します。呼び出し元から注入されるホスト、順序付きトークン読み込みルール、呼び出しごとの GH_TOKEN、検証プローブ、サンプルスクリプト向け環境変数ブリッジが含まれます。ステップ 1 で読み込みます。
• references/cli-reference.md — CLI を優先する際の詳細です。判断ルール、--json／--jq の出力、gh secret set（クライアント側の暗号化）、cli-index.md と実際の gh --help の使用方法が含まれます。ステップ 2～3a で読み込みます。
• references/gh-api.md — フォールバックについて説明します。gh api のフラグ（-X、-f／-F、-H、--paginate、--slurp、--jq、--input、--hostname）、インデックスとリゾルバーのワークフロー、GraphQL、エラーとスコープが含まれます。ステップ 3b で読み込みます。
• references/sources.md — 出典（gh のマニュアルと同梱されている仕様のバージョン）について説明します。

拡張（フェーズ 2.C）で追加し、上記で参照しているもの：

• assets/cli-index.md — 検索用に、各 gh コマンドを 1 行で記載します（ステップ 2）。
• assets/github-openapi.json — 同梱の GitHub REST OpenAPI 仕様です（信頼できる情報源です。照会しますが、全体を読み込むことはありません）。
• assets/endpoint-index.md — 検索用に、各 REST オペレーションを 1 行で記載します（ステップ 3b）。
• scripts/endpoint.py + scripts/endpoint.py.validation.md — $ref を解決する python3 スクリプトです（ステップ 3b）。
• scripts/<example>.sh + .validation.md — 検証済みの gh／gh api 呼び出し例です。

単独での使用（任意、必須ではありません）

これは、エージェントフローの外部で 人間がスキルを手動実行する場合 の利便性を目的としたものです。スキルの依存関係ではありません。 スキルの正式な契約は呼び出し元からの注入（ステップ 1）です。この付録は手動で操作する人向けの橋渡しにすぎません。

手動で実行するには、.service-accounts.yaml のレコードとその .env トークンを使って、GH_TOKEN（必要に応じて GH_HOST／GH_REPO も）を自分で設定し、その後スクリプトを実行してください。レコードの例：

accounts:
  - name: github-personal
    provider: github
    host: github.com
    token_env: GH_PERSONAL_TOKEN     # the var holding the token value; value lives in .env (gitignored)

set -a; source .env; set +a                 # loads $GH_PERSONAL_TOKEN, never prints it
export GH_TOKEN="$GH_PERSONAL_TOKEN"
export GH_REPO="OWNER/REPO"                  # optional: fills {owner}/{repo}
bash scripts/create-issue.sh "My title" "My body"

値は名前でのみ参照し、表示することはありません。呼び出しごとの GH_TOKEN も引き続き適用されます（gh auth switch は使用しません）。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン以下にします（毎ターン、コンテキストに保持されるためです）。詳細は references/ に記載します。
• assets/github-openapi.json はサイズが大きいため、ディスク上で照会し、コンテキストには読み込みません。