はじめに Cedar ポリシーの基本 アクション名のフォーマット パターン1: IAM 認証（SigV4）での検証 構成 検証1: すべてのアクションを許可するポリシー 検証2: 特定のアクションだけ許可するポリシー 検証3: OAuth クレームによる条件付きポリシー IAM 認証パターンのまとめ 追記: GA 後の再検証で発生した問題 パターン2: OAuth 認証（Cognito）での検証 構成 ゲートウェイのサービスロールにポリシーエンジン関連の権限が必要 検証4: client_id による条件付きポリシー 正しい client_id での検証（許可） 間違った client_id …

ども！最近 Gist の出番が増えた龍ちゃんです。スニペットの保存はもちろん、プロジェクト横断で使い回すプロンプトテンプレートとか、ちょっとした設定ファイルとか。操作が面倒で使ってなかったんですけど、チャットで完結するようにしたら話が変わりました。 .claude/skills/gh-gist/SKILL.md という Markdown ファイル1枚で、Gist の検索・取得・保存・更新がチャットの一言で動きます。この記事ではスキルの使い方と、CRUD をスキル化するときのトークン効率・安全設計の考え方を解説します。 GitHub Gist の課題 — 検索性と保存コスト Gist 自体は優秀な仕組みなんですよね。URL 一つでコードを共有できて、バージョン管理もついてくる。複数ファイルをまとめられるし、secret / public の切り替えもできます。「ちょっとしたコードの保存と共有」にちょうどいい粒度で設計されています。 でも実態、使いこなせてなくないですか？ 僕の場合がまさにそうでした。問題は2つあります。 検索性が弱い。 Gist が増えてくると、Web UI では目視スクロールで探すことになります。「あのスニペットどこだっけ」が頻発して、見つからないとそのまま諦めてしまう。 保存のハードルが高い。 ブラウザで gist.github.com を開いて、ファイル名を入力して、コードを貼り付けて、description を書いて、public か secret を選んで、Create ボタンを押す。コードを書いてる最中にこの手順をやる気にはなれないんですよね。 結果どうなるかというと、「保存するほどでもないか」→ 使わなくなる → 存在を忘れる。もったいない。 操作コストが下がれば話は変わる 「Gist に保存して」「Python のスニペット取ってきて」で済むなら話は別です。VS Code のチャットで完結するなら、コーディングの流れも切れません。 スニペットの保存・取得だけじゃなくて、操作コストが下がると 使い方の発想自体が変わる んですよね。たとえばプロジェクト横断で使い回すファイル（人格設定、プロンプトテンプレートなど）を Gist で一元管理して、必要なプロジェクトにスキルで引っ張ってくるとか。1ファイル完結 × 複数プロジェクトで共有 × バージョン管理つき、という Gist の粒度にぴったりハマります。「Gist ＝ ちょっとしたコード置き場」から「プロジェクト横断のファイル管理」へ。 これを Claude Code の Skills （SKILL.md）と GitHub CLI（ gh コマンド） で作りました。この記事ではスキルの使い方と作り方を解説します。SKILL.md の全文は付録に載せているので、すぐ試したい人はそちらもどうぞ。 なぜ gh CLI + スキルを選んだか Gist をエディタ内で操作する方法は他にもあります。 GitHub の Web UI は Gist の作成・閲覧・編集が一通りできますが、前述のとおり検索性が弱い。何よりコードを書いてる最中にブラウザに切り替えると作業の流れが切れます。 GitHub MCP Server には Gist 関連のツールがありません（2026年2月時点）。仮に対応していたとしても、MCP はツールの戻り値が大きくなりがちでトークン消費が膨らみやすいのはわりとあるあるな話です。 その上で gh CLI + SKILL.md を選んだのは、Gist の操作に合っていたからです。 gh CLI が Gist のサブコマンドを持っている。 gh gist list / view / create / edit / delete で CRUD 全部できます。 --filter や --raw --filename で出力を絞れるので、トークン効率のルールを設計しやすい 認証が gh auth で済む。 devcontainer の postCreateCommand に入れておけば環境構築時に自動で認証できる SKILL.md 一枚で完結する。 .claude/skills/gh-gist/SKILL.md に Markdown で手順を書くだけで動きます。 Skills は description だけが常時コンテキストに入り、本文は呼び出し時のみロードされるので、普段の会話を圧迫しません 選択肢が複数ある中で gh CLI を選んだのは優劣の話ではなく、自分の環境と用途に合っていたからです。 gh CLI × Claude Code で Gist を操作する（デモ） ここからは実際のデモです。検証用に Gist を事前に作成して、Claude Code のチャットで操作しました。前提として、 gh CLI がインストール済みで認証が完了している必要があります。 認証方法について : とりあえず試すなら gh auth login でブラウザ認証するのが一番手軽です。ただし OAuth はスコープが広くなりがちなので、運用するなら PAT（Personal Access Token）で最小限のスコープに絞るのがおすすめです。Classic PAT なら gist スコープだけで Gist の全操作が動きます。 # PAT を使った認証 echo "<your-pat>" | gh auth login --with-token SKILL.md は5モード対応（一覧 / 取得 / 保存 / 更新 / データ管理）ですが、よく使う3モードをデモで見ていきます。 取得 —「Python のスニペット取ってきて」 「Gist から Python のスニペット取ってきて」と打つと、スキルが以下のステップを自動で実行します。 Step 1: キーワードで Gist を検索 gh gist list --filter "Python" e7236579... Python useful snippets (updated) 2 files secret 2026-02-26T14:20:47Z Step 2: ファイル一覧を確認 gh gist view e72365796014c25d70629f6d8cfe01bc --files snippets.py todo.md Step 3: 目的のファイルを取得 gh gist view e72365796014c25d70629f6d8cfe01bc --raw --filename snippets.py """Python useful snippets - よく使うコードスニペット集""" # --- flatten nested list --- def flatten(nested: list) -> list: ... 「Python のスニペット」という曖昧な指示から、3ステップで目的のファイルに辿り着いています。 --filter で絞り → --files でファイル一覧 → --filename で中身取得。この 段階的な絞り込み がトークン効率のルールと連動していて、各ステップで情報量を削っています。このあたりの工夫は SKILL.md の解説セクションで詳しく説明します。 保存 —「このコードを Gist に保存して」 コードを渡して「Gist に保存して、description は Verification test で」と打ちます。 Step 1: 一時ファイルに書き出し ユーザーが指定したコードを application/tools/tmp/hello.py に書き出します。 gh gist create はファイルパスを引数に取るので、一時ファイル経由で作成する形です。 Step 2: Gist を作成 gh gist create application/tools/tmp/hello.py -d "Verification test" https://gist.github.com/user/xxxx デフォルトは secret で作成されます。public にしたい場合は「public で」と明示する必要があり、SKILL.md にそのルールを書いてあります。書き込み操作をスキル化するときに入れておきたい安全策の一つです。 更新 —「さっきの Gist にファイル追加して」 「さっき保存した Gist に README.md を追加して」と打つと、スキルが直前の会話のコンテキストから Gist ID を拾い、 gh gist edit でファイルを追加します。 ファイル追加 gh gist edit <gist-id> --add application/tools/tmp/README.md description 変更 gh gist edit <gist-id> --desc "Verification test (updated)" gh gist edit はデフォルトだとエディタが開いて対話的な編集になります。Claude Code から使うにはオプション引数で非対話的に更新する必要があって、このあたりも SKILL.md に手順を書いてあります。 SKILL.md の設計 — トークン効率と安全策 ここからは「どうやって作ったか」の話です。スキルの実体は .claude/skills/gh-gist/SKILL.md という Markdown ファイル1枚（全文は付録参照）。中身をパートごとに見ていきます。 メタデータ（ --- で囲まれたヘッダー部分） --- name: gh-gist description: | This skill should be used when the user asks to "Gist一覧", "Gistに保存して", "Gistから取ってきて", "Gistを更新して", "コードをGistに", "Gist確認して", "/gh-gist", or needs to manage GitHub Gists via gh CLI. allowed-tools: Bash, Read --- description にスキルの起動条件を書いておくと、Claude がユーザーの発言を見て自動的にスキルを呼び出します。「Gist に保存して」のような日本語のトリガーも列挙できます。 allowed-tools: Bash, Read で、このスキルが使えるツールを制限しています。 Skills は description だけが常時コンテキストに入っていて、本文はスキルが呼び出されたときにだけロードされるので、普段の会話には影響しません。 モード判定 | モード | トリガー例 | 主なコマンド | |--------|-----------|-------------| | 一覧 | 「Gist一覧」 | `gh gist list` | | 取得 | 「Gistから取ってきて」 | `gh gist view --raw --filename` | | 保存 | 「Gistに保存して」 | `gh gist create` | | 更新 | 「Gistを更新して」 | `gh gist edit` | | データ管理 | 「Gistのデータ更新して」 | `gh gist view` + jq + `gh gist edit` | ユーザーの一言からどのモードを実行するかを、このテーブルで Claude に判断させています。 CI 編 が読み取り中心の4モードだったのに対して、Gist 編は CRUD 操作を含む5モード構成です。 トークン効率のルール ここが SKILL.md で一番重要なパートです。 CI 編 では --log に --job 必須・ watch 禁止というルールでしたが、Gist 編ではサブコマンドが違う分、ルールの中身も変わります。ただし 「必要な情報だけに絞り込む」 という設計思想は共通です。 **必ず守ること:** - `gh gist list --include-content` は使用禁止（全 Gist の中身を取得してトークンを大量消費する） - `gh gist view` で複数ファイル Gist を扱う場合は必ず `--filename` で絞る - `gh gist view --files` でファイル一覧を先に確認してから `--raw --filename` で中身取得 --include-content を禁止しているのは、 gh gist list に付けると全 Gist の中身まで取得してしまうからです。 --filter だけで description とファイル名は検索できるので、中身を全部取る必要はありません。 --filename を必須にしているのは、複数ファイルの Gist で --filename なしだと全ファイルが連結出力されるからです。検証では2ファイルの Gist で --filename ありだと6行、なしだと37行の出力差がありました。ファイル数が多い Gist だとこの差はさらに開きます。 デモで見た「 --filter → --files → --raw --filename 」という段階的な絞り込みも、このルールに基づいています。最初から全部取るのではなく、ステップを分けて必要な情報だけに辿り着く設計です。 --raw の落とし穴 検証で見つけた話なんですが、 gh gist view <id> --raw を --filename なしで実行すると、description が出力の先頭行に入ります。 $ gh gist view e72365796014c25d70629f6d8cfe01bc --raw Python useful snippets ← description が1行目に出る """Python useful snippets - よく使うコードスニペット集""" ... ターミナルで見る分には気にならないんですけど、 > file.json でリダイレクトすると JSON の先頭に description が混入してパースが壊れます。後述するデータ管理モードで JSON を取得→更新するフローがあるので、SKILL.md に 「 --raw は必ず --filename と併用する」 というルールを明記して、Claude が --filename なしで実行するのを防いでいます。 書き込み操作の安全策 CI 編 のスキルは読み取り専用でしたが、Gist 編は CRUD 全操作を含むので、安全策の設計が必要になります。 secret デフォルト : --public はユーザーが「public で」と明示した場合のみ使う。意図せず公開されるのを防ぐ 削除前確認 : gh gist delete はユーザーに確認を取ってから実行する --yes フラグ : 非インタラクティブ環境（Claude Code）では削除時に --yes が必須。検証中に --yes なしで実行してエラーになって気づいた 一時ファイル経由 : 保存・更新は application/tools/tmp/ に一時ファイルを書き出してからコマンドに渡す 読み取り専用のスキルにはない設計ですが、CRUD をスキル化するなら、こういう安全策のセットはテンプレートとして使い回せると思います。 データ管理モード SKILL.md には5つ目のモードとして「データ管理」を入れています。description に [data] プレフィックスを付けてデータ用 Gist を識別する規約で、JSON の取得 → jq で変換 → Gist に反映、というフローを定義しています。Gist を簡易 DB 的に使う発想ですね。実用レベルかはまだ試行中ですが、仕組みとしては動きます。興味がある人は付録の SKILL.md 全文を参照してください。 改善の余地 gh CLI には gh gist clone でローカルに落として編集→ push するフローや、 gh gist rename でのファイル名変更もあります。SKILL.md にはまだ組み込んでいませんが、使いながら必要になったら足していく予定です。 まとめ ざっくり振り返ると、Before / After はこうなりました。 Before : Gist は便利な仕組みだけど、操作コストが高くて使いこなせていなかった。保存するにもブラウザ、探すにもブラウザ。結局「保存するほどでもないか」で使わなくなる。 After : 「Gist に保存して」「スニペット取ってきて」とチャットで打つだけ。VS Code から離れない。操作コストが下がると、Gist を「使おう」と思えるようになる。 これを実現しているのは .claude/skills/gh-gist/SKILL.md という Markdown ファイル1枚です。特別なインフラもサーバーも不要で、プロジェクトにファイルを1つ追加するだけで動きます。 トークン効率のルール（ --include-content 禁止、 --filename 必須、段階的絞り込み）は gh CLI スキル共通のパターンとして使えます。書き込み操作の安全策（secret デフォルト、削除前確認、 --yes ）は CRUD をスキル化するときの設計テンプレートになると思います。 ほなまた〜 シリーズ記事 記事 内容 概要編 — ブラウザなし GitHub 操作を実現する 問題提起と解決策の全体像 CI 編 — GitHub Actions 失敗ログをチャットで即解決 失敗ログの取得から原因分析まで この記事（Gist 編） Gist の検索・保存・更新 付録 SKILL.md 全文 .claude/skills/gh-gist/SKILL.md の内容です。 --- name: gh-gist description: | This skill should be used when the user asks to "Gist一覧", "Gistに保存して", "Gistから取ってきて", "Gistを更新して", "コードをGistに", "Gist確認して", "/gh-gist", or needs to manage GitHub Gists via gh CLI. allowed-tools: Bash, Read --- # GitHub Gist Management gh CLI を使って GitHub Gist の管理（一覧・取得・保存・更新・データ管理）を行います。 ## Mode Selection ユーザーの指示から以下の5モードを自動判定して実行する。 | モード | トリガー例 | 主なコマンド | |--------|-----------|-------------| | 一覧 | 「Gist一覧」「Gist確認して」 | `gh gist list` | | 取得 | 「Gistから取ってきて」「Gistの中身見せて」 | `gh gist view --raw --filename` | | 保存 | 「Gistに保存して」「コードをGistに」 | `gh gist create` | | 更新 | 「Gistを更新して」「Gistに追加して」 | `gh gist edit` | | データ管理 | 「Gistのデータ更新して」「Gistの設定を変更」 | `gh gist view --raw` + jq + `gh gist edit` | ## Token Efficiency Rules **必ず守ること:** - `gh gist list --include-content` は使用禁止（全 Gist の中身を取得してトークンを大量消費する） - `gh gist view --raw` を `--filename` なしで使うと description が先頭行に混入する。特にリダイレクトで JSON/YAML を取得する場合は **必ず `--filename` を指定する**（パースが壊れる） - `gh gist view` で複数ファイル Gist を扱う場合は必ず `--filename` で絞る（全ファイル連結出力になる） - `gh gist view --files` でファイル一覧を先に確認してから `--raw --filename` で中身を取得する - 新規作成時はデフォルト secret（`--public` はユーザーの明示的指示がある場合のみ） - データ管理モードでは `application/tools/tmp/` に一時ファイルを書き出して `gh gist edit` で反映 --- ## Mode 1: 一覧 自分の Gist 一覧を表示する。 ### Step 1: Gist 一覧の取得 ```bash # 最新10件 gh gist list --limit 10 # フィルタ付き（description / ファイル名で検索） gh gist list --filter "keyword" # public のみ / secret のみ gh gist list --public gh gist list --secret ``` ### Step 2: 結果を報告テンプレートで表示 ## Mode 2: 取得 特定の Gist からファイル内容を取得する。 ### Step 1: 対象 Gist の特定 ユーザーが Gist ID / URL を指定していない場合は一覧から検索する。 ```bash # キーワードで検索 gh gist list --filter "keyword" ``` ### Step 2: ファイル一覧の確認 ```bash # Gist 内のファイル名を確認 gh gist view <gist-id> --files ``` ### Step 3: ファイル内容の取得 ```bash # 特定ファイルの内容を raw で取得 gh gist view <gist-id> --raw --filename <filename> ``` **重要:** 複数ファイル Gist では必ず `--filename` を指定する。省略すると全ファイルが出力されトークンを大量消費する。 ## Mode 3: 保存 新しい Gist を作成する。 ### Step 1: ファイルの準備 ユーザーが指定したコードやテキストを `application/tools/tmp/` に一時ファイルとして書き出す。 ### Step 2: Gist の作成 ```bash # 単一ファイル（secret、デフォルト） gh gist create application/tools/tmp/<filename> -d "description" # 複数ファイル gh gist create application/tools/tmp/file1 application/tools/tmp/file2 -d "description" # public（ユーザーが明示的に指示した場合のみ） gh gist create application/tools/tmp/<filename> -d "description" --public # stdin から作成 echo "content" | gh gist create -f <filename> -d "description" ``` **重要:** デフォルトは secret。`--public` はユーザーが「public で」「公開で」と明示した場合のみ使用する。 ### Step 3: 結果を報告テンプレートで表示 ## Mode 4: 更新 既存の Gist を更新する。 ### Step 1: 対象 Gist の特定 ユーザーが Gist ID / URL を指定していない場合は一覧から検索する。 ```bash gh gist list --filter "keyword" ``` ### Step 2: 現在の内容を確認 ```bash gh gist view <gist-id> --files gh gist view <gist-id> --raw --filename <filename> ``` ### Step 3: 更新の実行 ```bash # ファイル内容の上書き（一時ファイル経由） gh gist edit <gist-id> --filename <target> application/tools/tmp/<local-file> # ファイルの追加 gh gist edit <gist-id> --add application/tools/tmp/<new-file> # description の変更 gh gist edit <gist-id> --desc "new description" # ファイルの削除（ユーザーの明示的指示がある場合のみ） gh gist edit <gist-id> --remove <filename> ``` ### Step 4: 結果を報告テンプレートで表示 ## Mode 5: データ管理 JSON / YAML などの構造化データを Gist に保存し、DB 的に管理する。 ### データ用 Gist の識別 description に `[data]` プレフィックスを付けてデータ用 Gist を識別する。 ```bash # データ用 Gist の検索 gh gist list --filter "\\[data\\]" ``` ### データの取得と更新 ```bash # 1. 現在のデータを取得 gh gist view <gist-id> --raw --filename <filename> > application/tools/tmp/<filename> # 2. jq で変換（JSON の場合） jq '.key = "new_value"' application/tools/tmp/<filename> > application/tools/tmp/<filename>.updated # 3. Gist に反映 gh gist edit <gist-id> --filename <filename> application/tools/tmp/<filename>.updated ``` ### データ用 Gist の新規作成 ```bash # JSON データ gh gist create application/tools/tmp/data.json -d "[data] project-config" # YAML データ gh gist create application/tools/tmp/data.yaml -d "[data] settings" ``` **削除操作:** ユーザーの明示的指示がある場合のみ実行。必ず確認を取る。 ```bash # 削除（非インタラクティブ環境では --yes が必須） gh gist delete <gist-id> --yes ``` ## Report Templates 以下のテンプレートを使って結果を報告する。 ### 一覧 ``` ## Gist 一覧 | # | Description | Files | Visibility | Updated | |---|-------------|-------|------------|---------| | 1 | <description> | <file-count> | <public/secret> | <date> | ``` ### 取得結果 ``` ## Gist 内容 **Gist:** <description> **ID:** <gist-id> **File:** <filename> <ファイル内容をコードブロックで表示> ``` ### 保存完了 ``` ## Gist 作成完了 **URL:** <gist-url> **Description:** <description> **Visibility:** <public/secret> **Files:** <file-list> ``` ### データ管理 ``` ## データ更新完了 **Gist:** <description> **File:** <filename> **変更内容:** <変更のサマリ> ``` ## Important Notes - **gh CLI 未認証の場合**: `gh auth status` で認証状態を確認し、未認証ならユーザーに通知 - **`--include-content` は絶対に使わない**: トークン効率のため。`--filter` だけで description とファイル名は検索可能 - **secret がデフォルト**: ユーザーが明示的に public を指定しない限り secret で作成する - **削除操作は慎重に**: `gh gist delete` はユーザーの明示的な指示 + 確認の上でのみ実行。非インタラクティブ環境では `--yes` フラグが必須 - **一時ファイルの場所**: 必ず `application/tools/tmp/` を使用する（`/tmp/` は使わない） ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post gh CLI × Claude Code で Gist 操作をチャット1行で完結させる first appeared on SIOS Tech Lab .

ども！最近 GitHub Actions の Workflow を新規で書くことが増えている龍ちゃんです。Bicep のデプロイパイプラインとか、ブログのビルドチェックとか、地味に CI 周りをいじる機会が多いんですよね。 GitHub Actions のログ確認で作業が途切れる問題 CI をいじってると避けられないのが「CI が落ちたときの確認作業」。 VS Code の GitHub Actions 拡張機能 を入れてれば、どのステップが落ちたかはサイドバーのツリーで確認できます。ただ、拡張機能が教えてくれるのは 「どこが落ちたか」 まで。 「なぜ落ちたのか」をテキストレベルで確認する手段 が足りないんですよね。エラーログの中身を確認しようとすると、ブラウザで GitHub Actions の Run ページを開いて、ジョブを展開して、ログをコピーして…というエディタとブラウザの反復横跳びが発生します。コードの修正を Claude Code と進めてる最中だったら、作業の流れもそこで切れてしまう。 僕がほしかったのは、 「なぜ落ちたか」のログを VS Code 内でテキストとして取得できる仕組み でした。テキストさえ手に入れば、「どう直すか」は Claude Code が分析してくれます（人間もやるよ…）。そこで、 Claude Code の Skills （SKILL.md）と GitHub CLI（ gh コマンド） を組み合わせて、CI のログ取得から分析までを VS Code 内で完結させるスキルを作りました。この記事ではスキルの使い方と作り方を解説します。SKILL.md やデモ用 Workflow の全文は付録に載せているので、すぐ試したい人はそちらもどうぞ。 gh-workflow スキルで何が変わるか /gh-workflow スキルを入れると、Claude Code のチャットで「CI 失敗してるから見て」と打つだけで、失敗した Run の特定 → ログの取得 → 原因分析 → 修正方針の提示まで一気に進みます。SKILL.md に gh CLI の手順を書いておくだけで、Claude がログ取得から分析まで全部やってくれる仕組みです。 なお、 GitHub Actions 拡張機能 は「どこが落ちたか」のツリー確認や YAML 編集支援が得意で、このスキルは「なぜ落ちたか」のログ取得と分析が得意です。置き換えではなく補完関係なので、両方入れておくのがおすすめです。 なぜ gh CLI + スキルを選んだか CI のログを VS Code 内で取得する方法は他にもあります。 GitHub MCP Server の Actions toolset を使えば、 list_workflow_runs や get_job_logs といったツールで同等のことが実現できます。機能的には十分ですが、MCP はツールの戻り値が大きくなりがちで、トークン消費が膨らみやすいというのはわりとあるあるな話です。また、Claude Code の組み込みツール（WebSearch / WebFetch）で GitHub の情報を取りにいくという手もなくはありません。 その上で gh CLI + SKILL.md を選んだのは、僕の環境に合っていたからです。 CLI があるなら CLI で叩きたい。 これは完全に好みの話ですが、サービスが公式 CLI を出しているなら、僕は CLI を選びがちです。MCP だとツールの戻り値をスキル側でコントロールしにくいけど、CLI なら --json や --jq で出力形式を自在に絞れる。SKILL.md に書く手順も Bash コマンドそのままなので、トークン効率のルールをスキル側で設計しやすいのが大きいです プロジェクトで利用実績があった。 Bicep との統合でシークレット登録に gh CLI を使っていたので、認証周りは設定済みだった 認証が gh auth で済む。 devcontainer の postCreateCommand に入れておけば、環境構築時に自動で認証できる SKILL.md 一枚で完結する。 Markdown ファイルを .claude/skills/gh-workflow/SKILL.md に置くだけで動く。Skills は description だけが常時コンテキストに入り、本文は呼び出し時のみロードされるので、普段の会話を圧迫しない 選択肢が複数ある中で gh CLI を選んだのは優劣の話ではなく、自分の環境と好みに合っていたからです。 gh CLI × Claude Code で CI ログを確認する（デモ） ここからは実際のデモです。前提として、 gh CLI がインストール済みで認証が完了している必要があります。 認証方法について : とりあえず試すなら gh auth login でブラウザ認証するのが一番手軽です。ただし OAuth はスコープが広くなりがちなので、運用するなら PAT（Personal Access Token）で最小限のスコープに絞るのがおすすめです。Fine-grained PAT なら対象リポジトリと Actions の読み取り権限だけに制限できます。 # PAT を使った認証 echo "<your-pat>" | gh auth login --with-token このリポジトリにデモ用の Workflow を2つ用意しました。 demo-success.yml : ファイル構造のチェックと YAML バリデーションを行う2ジョブ構成の CI パイプライン demo-failure.yml : 3ジョブ構成で、Test ジョブが意図的に失敗する Workflow（テスト失敗のログを再現） SKILL.md は4モード対応（クイックステータス / Run 詳細 / PR チェック / ログ分析）ですが、今回はデモ用 PR がないので3モードで見ていきます。 クイックステータス — 「CI 確認して」 一番シンプルなモードです。「CI 確認して」と打つと、スキルが gh run list を実行して直近の Workflow 実行状況を取得します。 completed failure Demo - Failure Workflow main workflow_dispatch 22430458939 22s 2026-02-26T06:20:53Z completed success Demo - CI Pipeline main workflow_dispatch 22430440934 21s 2026-02-26T06:20:13Z completed success Demo - CI Pipeline main workflow_dispatch 22430416062 46s 2026-02-26T06:19:12Z completed failure Demo - CI Pipeline main workflow_dispatch 22430368912 48s 2026-02-26T06:17:20Z この生データを、スキルのレポートテンプレートに従って整形します。 ## Workflow Status | # | Workflow | Branch | Status | Conclusion | Triggered | |---|---------|--------|--------|------------|-----------| | 1 | Demo - Failure Workflow | main | completed | failure | workflow_dispatch | | 2 | Demo - CI Pipeline | main | completed | success | workflow_dispatch | | 3 | Demo - CI Pipeline | main | completed | success | workflow_dispatch | | 4 | Demo - CI Pipeline | main | completed | failure | workflow_dispatch | ブラウザを開かなくても、今の CI の状況がチャット上で確認できます。 Run 詳細 — 「この Run の詳細を見て」 成功した Run の中身を確認したいこともあります。「この Run、ジョブの実行時間どのくらいだった？」みたいなとき、Run ID を指定すると gh run view <run-id> で詳細を取得します。 ✓ main Demo - CI Pipeline · 22430440934 Triggered via workflow_dispatch about 4 minutes ago JOBS ✓ Code Check in 6s (ID 64947983939) ✓ Config Validate in 7s (ID 64947996283) ジョブごとの実行時間とステータスが見えるので、Workflow の構成を変えた後に「ちゃんと速くなったか」を確認するのに使ったりします。 ログ分析 — 「CI 失敗してるから見て」 ここがメインの見せ場です。「CI 失敗してるから見て」と打つと、スキルが以下のステップを自動で実行します。 Step 1: 失敗した Run を特定する gh run list --branch main --status failure --limit 5 completed failure Demo - Failure Workflow main workflow_dispatch 22430458939 Step 2: 失敗したジョブを特定する gh run view 22430458939 --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name}' {"id": 64948053027, "name": "Test"} --json と jq を使って、失敗したジョブだけを抽出しています。全ジョブの情報を取得する必要はなく、失敗したものだけに絞ることでトークンを節約しています。このあたりの工夫は SKILL.md の解説セクションで詳しく説明します。 Step 3: 失敗したジョブのログを取得する gh run view 22430458939 --log --job 64948053027 Test Run integration tests Running integration tests... Test Run integration tests Test Run integration tests FAILED: test_pipeline.py::test_full_pipeline Test Run integration tests AssertionError: Expected status code 200, got 503 Test Run integration tests File: tests/test_pipeline.py, line 42 Test Run integration tests assert response.status_code == 200 Test Run integration tests Test Run integration tests 1 passed, 1 failed in 3.42s Test Run integration tests ##[error]Process completed with exit code 1. --log には必ず --job を付けています。これがないと全ジョブのログが流れてきてトークンを大量に消費するので、失敗したジョブだけに絞るのが鉄則です。 Step 4: Claude が分析してレポートを出す ログを取得したら、Claude がエラー内容を読み取って原因分析と修正方針をまとめます。 ## Failure Analysis **Run:** #22430458939 - Demo - Failure Workflow **Branch:** main **Failed Jobs:** | Job | Error Summary | |-----|--------------| | Test | integration test で AssertionError（期待 200、実際 503） | **Root Cause:** test_pipeline.py の test_full_pipeline テストで、API レスポンスのステータスコードが 期待値 200 に対して 503 (Service Unavailable) を返している。 **Suggested Fix:** - テスト対象の API サーバーが起動しているか確認 - urllib3 のバージョン互換性を確認（requests 2.31.0 は urllib3<3 を要求） 「CI 失敗してるから見て」の一言で、ここまで出てきます。手作業だと Run を探して、ジョブを開いて、ログを読んで…とやっていた調査が全部自動で走り、Claude がそのまま分析に入ります。コードの修正をしていた会話の流れのまま「じゃあこう直しましょう」と続けられるのがポイントです。 このデモではテスト失敗を再現するために作った Workflow を使っています。 demo-failure.yml は echo で pytest 風のエラー出力を再現して exit 1 する構成で、実際のプロジェクトではここに本物のテスト結果が出ます。 SKILL.md の設計 — トークン効率とログ分析の工夫 ここからは「どうやって作ったか」の話です。スキルの実体は .claude/skills/gh-workflow/SKILL.md という Markdown ファイル1枚（全文は付録参照）。自分のプロジェクトでも同じような仕組みを作りたい人向けに、中身をパートごとに見ていきます。 メタデータ（ --- で囲まれたヘッダー部分） --- name: gh-workflow description: | This skill should be used when the user asks to "CI確認して", "Workflow確認", "CIの状態を見て", "ワークフローのログを見て", "CI失敗してるから直して", "PRのチェック状況は", "/gh-workflow", or needs to check GitHub Actions workflow status or analyze CI logs. allowed-tools: Bash, Read --- description にスキルの起動条件を書いておくと、Claude がユーザーの発言を見て自動的にこのスキルを呼び出します。「CI確認して」のような日本語のトリガーも列挙できます。 allowed-tools: Bash, Read で、このスキルが使えるツールを制限しています。 Skills は description だけが常時コンテキストに入っていて、本文はスキルが呼び出されたときにだけロードされるので、普段の会話には影響しません。 モード判定 | モード | トリガー例 | 主なコマンド | |--------|-----------|-------------| | クイックステータス | 「CI確認して」 | `gh run list` | | Run 詳細 | 「Run #123 を見て」 | `gh run view <run-id>` | | PR チェック | 「PR #42 のチェック状況」 | `gh pr checks <pr-number>` | | ログ分析 | 「CI失敗してるから見て」 | `gh run view --log --job` | ユーザーの一言からどのモードを実行するかを、このテーブルで Claude に判断させています。 トークン効率のルール ここが SKILL.md で一番重要なパートです。ただ手順を書くだけなら誰でもできますが、 トークンを無駄遣いしないルール を入れることでスキルの実用性が大きく変わります。 **必ず守ること:** - `--log` は必ず `--job <job-id>` と併用する（全ジョブログは膨大でトークンを大量消費する） - `gh run watch` は使用禁止（リアルタイム出力でトークンを大量消費する） - `gh pr checks --watch` は使用禁止（同上） - JSON 出力 + jq で必要なフィールドのみ取得する --log を --job なしで実行すると、全ジョブのログが一気に流れてきます。CI のログは長くなりがちなので、これをそのままコンテキストに入れるとトークンがあっという間になくなります。 --job で失敗したジョブだけに絞るのが鉄則です。 gh run watch を禁止しているのも同じ理由です。リアルタイム出力がずっと流れ続けるとトークンを食い尽くします。進行中の Run は「今の状態を確認する」だけにして、完了を待ちません。 JSON + jq のルールは、 gh run view --json jobs --jq '.jobs[] | select(.conclusion == "failure")' のように必要なフィールドだけ抽出するためのものです。構造化データで取れるものは構造化データで取ります。 ログ分析モードの設計意図 デモセクションで「何が起きるか」を見ましたが、ここでは「なぜこの設計にしたか」を補足します。SKILL.md に以下の手順を書いておくと、Claude はこの順番で gh CLI を実行します。 ### Step 1: 失敗した Run の特定 gh run list --branch $(git branch --show-current) --status failure --limit 5 ### Step 2: 失敗したジョブの特定 gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name}' ### Step 3: 失敗ジョブのログ取得 gh run view <run-id> --log --job <job-id> ### Step 4: エラー分析と報告 Run 全体 → 失敗ジョブ → 失敗ジョブのログ、と段階的に絞り込んでいく設計です。最初から全部のログを取るのではなく、必要なものだけに辿り着くようにステップを分けています。この段階的な絞り込みがトークン効率のルールと連動していて、各ステップで情報量を削ることで Claude に渡すデータを最小限にしています。 レポートテンプレート ## Failure Analysis **Run:** #<run-id> - <workflow-name> **Branch:** <branch> **Failed Jobs:** | Job | Error Summary | |-----|--------------| | <job-name> | <error-summary> | **Root Cause:** <分析結果> **Suggested Fix:** <修正方針> 出力フォーマットを統一しておくと、毎回同じ形式で結果が出るので読み方が一定になります。「Root Cause を見て、Suggested Fix を見る」というパターンに慣れれば、確認作業がさらに速くなります。 改善の余地 gh CLI には --log-failed という失敗ステップのみ取得するオプションもあります。SKILL.md にはまだ組み込んでいませんが、 --log --job と組み合わせればさらにログを絞り込めるので、今後の改善候補です。 もう一つ気になっているのが、ログが大量になるケースです。 --job で絞っても、ジョブ自体のログが長いとトークンを圧迫する可能性があります。たとえばログを取得してファイルに保存だけしておくとか、失敗したログをテキストファイルとして書き出す CLI ツールを作るとか、いろいろ模索できそうだなと思っています。まだやってないですけどね。 まとめ ざっくり振り返ると、Before / After はこうなりました。 Before : CI が落ちたら、ブラウザで Run を探して、ジョブを開いて、ログをコピーして、Claude に貼って、文脈を説明する。コードの修正中だったら作業の流れが切れる。 After : 「CI 失敗してるから見て」と打つ。スキルが gh CLI でログを集めて、Claude が分析して修正方針を出す。コードの修正中でも会話の流れはそのまま。 これを実現しているのは、 .claude/skills/gh-workflow/SKILL.md という Markdown ファイル1枚です。特別なインフラもサーバーも不要で、プロジェクトにファイルを1つ追加するだけで動きます。 GitHub Actions 拡張機能 とは補完関係で使うのがおすすめです。YAML の編集支援や「どこが落ちたか」の確認は拡張機能が得意で、「なぜ落ちたか」のログ取得と分析はスキル + Claude が得意です。 SKILL.md は他のプロジェクトでもそのまま使えます。 gh CLI のコマンドを自分のプロジェクトに合わせて書き換えるだけで、同じ仕組みが動きます。トークン効率のルール（ --log には --job 必須、 watch 禁止、JSON + jq で絞り込み）はどのプロジェクトでも共通なので、テンプレートとして参考にしてもらえると思います。 ほなまた〜 シリーズ記事 記事 内容 概要編 — ブラウザなし GitHub 操作を実現する 問題提起と解決策の全体像 この記事（CI 編） 失敗ログの取得から原因分析まで Gist 編 — Gist 操作をチャット1行で完結させる Gist の検索・保存・更新 付録 SKILL.md 全文 .claude/skills/gh-workflow/SKILL.md の内容です。 --- name: gh-workflow description: | This skill should be used when the user asks to "CI確認して", "Workflow確認", "CIの状態を見て", "ワークフローのログを見て", "CI失敗してるから直して", "PRのチェック状況は", "/gh-workflow", or needs to check GitHub Actions workflow status or analyze CI logs. allowed-tools: Bash, Read --- # GitHub Actions Workflow Status & Log Analysis gh CLI を使って GitHub Actions の Workflow ステータス確認・ログ分析を行います。 ## Mode Selection ユーザーの指示から以下の4モードを自動判定して実行する。 | モード | トリガー例 | 主なコマンド | |--------|-----------|-------------| | クイックステータス | 「CI確認して」「Workflowの状態を見て」 | `gh run list` | | Run 詳細 | 「Run #123 を見て」「この Run の詳細」 | `gh run view <run-id>` | | PR チェック | 「PR #42 のチェック状況」「PRのCI」 | `gh pr checks <pr-number>` | | ログ分析 | 「CI失敗してるから見て」「エラーログ確認」 | `gh run view --log --job` | ## Token Efficiency Rules **必ず守ること:** - `--log` は必ず `--job <job-id>` と併用する（全ジョブログは膨大でトークンを大量消費する） - `gh run watch` は使用禁止（リアルタイム出力でトークンを大量消費する） - `gh pr checks --watch` は使用禁止（同上） - JSON 出力 + jq で必要なフィールドのみ取得する --- ## Mode 1: クイックステータス 現在のブランチまたはリポジトリの Workflow 実行状況を一覧表示する。 ### Step 1: Run 一覧の取得 ```bash # 現在のブランチの最新10件 gh run list --branch $(git branch --show-current) --limit 10 # 全ブランチの最新10件（ブランチ指定なし） gh run list --limit 10 ``` ### Step 2: 結果を報告テンプレートで表示 ## Mode 2: Run 詳細 特定の Run ID の詳細情報を取得する。 ### Step 1: Run の詳細取得 ```bash # Run の詳細表示 gh run view <run-id> # JSON で構造化データを取得 gh run view <run-id> --json status,conclusion,jobs,createdAt,updatedAt,headBranch,event ``` ### Step 2: ジョブごとのステータスを整理して報告 ## Mode 3: PR チェック PR に紐づくチェック状況を確認する。 ### Step 1: PR チェックの取得 ```bash # PR のチェック状況 gh pr checks <pr-number> # 現在のブランチの PR チェック（PR 番号不明時） gh pr checks ``` ### Step 2: チェック結果を報告テンプレートで表示 ## Mode 4: ログ分析 失敗した Workflow のログを取得・分析する。 ### Step 1: 失敗した Run の特定 ```bash # 現在のブランチで失敗した Run を検索 gh run list --branch $(git branch --show-current) --status failure --limit 5 ``` ### Step 2: 失敗したジョブの特定 ```bash # Run 内のジョブ一覧を JSON で取得 gh run view <run-id> --json jobs --jq '.jobs[] | {name, status, conclusion}' ``` ### Step 3: 失敗ジョブのログ取得 ```bash # 特定ジョブのログのみ取得（必ず --job を指定） gh run view <run-id> --log --job <job-id> ``` **重要:** `--log` は必ず `--job <job-id>` と併用する。`--job` なしだと全ジョブのログが出力されトークンを大量消費する。 ### Step 4: エラー分析と報告 ログからエラー箇所を特定し、原因と修正方針を報告する。 ## Status / Conclusion Reference | 値 | 種類 | 意味 | |----|------|------| | `queued` | status | キュー待ち | | `in_progress` | status | 実行中 | | `completed` | status | 完了 | | `waiting` | status | 承認待ち | | `success` | conclusion | 成功 | | `failure` | conclusion | 失敗 | | `cancelled` | conclusion | キャンセル済み | | `skipped` | conclusion | スキップ | | `timed_out` | conclusion | タイムアウト | | `action_required` | conclusion | アクション要求 | | `neutral` | conclusion | 中立（情報のみ） | | `stale` | conclusion | 古い結果 | ## JSON Output Patterns よく使う構造化データ取得パターン: ```bash # Run 一覧を JSON で取得 gh run list --limit 10 --json databaseId,displayTitle,status,conclusion,headBranch,createdAt,event # Run 内のジョブ詳細 gh run view <run-id> --json jobs --jq '.jobs[] | {id: .databaseId, name, status, conclusion, startedAt, completedAt}' # 失敗ジョブのみ抽出 gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name}' # PR チェックの詳細（JSON） gh pr checks <pr-number> --json name,state,description,detailsUrl ``` ## Report Template 以下のテンプレートを使って結果を報告する。 ### ステータス一覧 ``` ## Workflow Status | # | Workflow | Branch | Status | Conclusion | Triggered | |---|---------|--------|--------|------------|-----------| | 1 | <name> | <branch> | <status> | <conclusion> | <event> | ``` ### 失敗分析 ``` ## Failure Analysis **Run:** #<run-id> - <workflow-name> **Branch:** <branch> **Failed Jobs:** | Job | Error Summary | |-----|--------------| | <job-name> | <error-summary> | **Root Cause:** <分析結果> **Suggested Fix:** <修正方針> ``` ## Important Notes - **gh CLI 未認証の場合**: `gh auth status` で認証状態を確認し、未認証ならユーザーに通知 - **リポジトリ外で実行した場合**: エラーをユーザーに通知 - **大量のログ出力**: 必ず `--job` で絞り込み、それでも長い場合は主要なエラー行のみ抽出 - **進行中の Run**: ステータスが `in_progress` の場合、完了を待たずに現在の状態を報告（`watch` は使わない） デモ用 Workflow demo-success.yml 2ジョブ構成の CI パイプライン。ファイル構造のチェックと YAML バリデーションを行います。 name: Demo - CI Pipeline on: workflow_dispatch: jobs: check: name: Code Check runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Check file structure run: | echo "Checking project files..." test -f pyproject.toml && echo "OK: pyproject.toml" test -f CLAUDE.md && echo "OK: CLAUDE.md" echo "All checks passed." validate: name: Config Validate runs-on: ubuntu-latest needs: check steps: - name: Checkout repository uses: actions/checkout@v4 - name: Validate YAML configs run: | echo "Validating workflow files..." ls .github/workflows/*.yml | wc -l | xargs -I{} echo "Found {} workflow files" echo "Validation complete." demo-failure.yml 3ジョブ構成で、Test ジョブが意図的に失敗する Workflow。echo で pytest 風のエラー出力を再現しています。 name: Demo - Failure Workflow on: workflow_dispatch: jobs: setup: name: Setup runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Verify environment run: | echo "Environment check..." echo "OS: $(uname -s)" echo "Setup completed." test: name: Test runs-on: ubuntu-latest needs: setup steps: - name: Checkout repository uses: actions/checkout@v4 - name: Run unit tests run: | echo "Running unit tests..." echo "test_fetch_article ... PASSED" echo "test_parse_html ... PASSED" echo "Unit tests passed." - name: Run integration tests run: | echo "Running integration tests..." echo "" echo "FAILED: test_pipeline.py::test_full_pipeline" echo " AssertionError: Expected status code 200, got 503" echo " File: tests/test_pipeline.py, line 42" echo " assert response.status_code == 200" echo "" echo "1 passed, 1 failed in 3.42s" exit 1 deploy: name: Deploy runs-on: ubuntu-latest needs: test steps: - name: Deploy application run: echo "Deploying..." ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決 first appeared on SIOS Tech Lab .