GitHub Actions失敗ログ、まだ手動で読む？Copilot Agent Skills で CI デバッグを自動化する実装ガイド

GitHub Actions の失敗ログ、まだ手動で読んでいませんか？

ども！龍ちゃんです。

CI が落ちたときの対応、毎回こうなっていませんか？

1. GitHub Actions の UI を開く
2. 失敗した Run を探す
3. 失敗したジョブを開く
4. ログをスクロールしてエラー行を目視で探す
5. エラーメッセージをコピーしてググる

地味に面倒なんですよね、これ。特にジョブが複数あるワークフローだと、どのジョブのどのステップで落ちたのかを探すだけで時間を食う。

これ、Agent Skills に任せたら1行で終わります。

本記事では、gh CLI を使った CI ログ自動分析スキルを GitHub Copilot の Agent Skills として実装する手順を解説します。Claude Code で同じスキルを作った「gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決」の Copilot 移植版です。

190行あった Claude Code 版の SKILL.md を、Copilot の 500 トークン制限に合わせて 58 行に圧縮する設計がメインの話題になります。

対象読者

• Agent Skills で実用的なスキルを作りたい人
• Claude Code のスキルを Copilot に移植したい人
• CI/CD のデバッグを自動化したい人

Agent Skills の基本（ディレクトリ構造、SKILL.md の書き方）は「【2026年版】Agent Skills 入門」を参照してください。

GitHub Actions の失敗を Agent Skills で自動分析する

作り方の前に、まず完成形を見てください。こういうやりとりになります。

龍ちゃん

CI失敗してるから原因を調べて

GitHub Copilot

失敗した Run を特定します。
→ gh run list –status failure –limit 5
→ gh run view 22573804432 –json jobs
→ gh run view 22573804432 –log –job 65388009712

## Failure Analysis
Root Cause: integration test が HTTP 503 で失敗
Suggested Fix: サービスのヘルスチェックをテスト前に実行

1行のプロンプトで、失敗 Run の特定からログ取得、原因分析まで全自動。この動きを実現するスキルの作り方を、このあと順を追って解説します。

前提条件

• VS Code + GitHub Copilot（Agent Mode が使える状態）
• gh CLI がインストール・認証済み（gh auth status で確認）
• .github/skills/gh-workflow/ にスキルが配置済み（本記事で作ります）

テスト用の失敗ワークフロー（demo-failure.yml）

検証用に、意図的に失敗するワークフローを用意しました。

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..."

Setup → Test → Deploy の3ジョブ構成で、Test ジョブの integration tests が 503 エラーで exit 1 します。CI/CD でよくあるパターンを再現しています。

手動実行して失敗させておきます。

gh workflow run "Demo - Failure Workflow"
# 30秒ほど待ってから確認
gh run list --workflow "demo-failure.yml" --limit 1

デモ 1：gh run list でクイックステータス確認

VS Code の Agent Mode で「CI確認して」と入力します。

スキルが発火すると、Copilot は SKILL.md の Mode 1（クイックステータス）に従い、gh run list で最新の実行状況を一覧取得します。

実行されたコマンド：

git branch --show-current
gh run list --branch main --limit 10 --json databaseId,status,conclusion,name,headBranch,event,createdAt,displayTitle

出力（Copilot のレポート）：

「最新の CI が失敗しています」と報告したうえで、「失敗ログを分析しますか？」と次のアクションを提案してくれます。ブランチ取得から一覧表示まで自動で、自分が打つのはプロンプト1行だけです。

デモ 2：gh run view –log で失敗ログを自動分析

ここがメインのデモです。「3/2に失敗したものを取得してほしい」と入力すると、スキルの Mode 4（ログ分析）が起動します。

Copilot は SKILL.md に書かれた Progressive Filtering（段階的絞り込み）の手順に従って、4ステップで自動分析します。

Step 1: 失敗 Run の特定

gh run view 22573804432 --json jobs,status,conclusion,createdAt,updatedAt,headBranch,event,workflowName

Run 全体の情報を取得。3ジョブの中から Test ジョブが failure であることを特定。

Step 2: 失敗ジョブの絞り込み

JSON レスポンスから失敗ジョブの ID（65388009712）を抽出。Step 4 の「Run integration tests」が failure であることを確認。

Step 3: ログ取得

gh run view 22573804432 --log --job 65388009712

--log は必ず --job と併用します。これは SKILL.md の Token Efficiency Rules で定義したルールです。--job なしだと全ジョブのログが出力されてトークンを大量消費するので、失敗ジョブに絞って取得します。

Step 4: エラー分析とレポート出力

## Failure Analysis

**Run:** #22573804432 - Demo - Failure Workflow
**Branch:** main

| Job | Error Summary |
|-----|--------------|
| Test | AssertionError: Expected status code 200, got 503 |

**Root Cause:**
Integration test `test_pipeline.py::test_full_pipeline` が失敗。
外部サービスへの接続で HTTP 503 (Service Unavailable) を受信。

**Suggested Fix:**
1. サービスのヘルスチェックをテスト前に実行
2. テストエンドポイントへのネットワーク接続を確認
3. テストデータ・環境設定を見直し

Run 全体 → 失敗ジョブ → 失敗ステップ → エラー行と、段階的に絞り込んで 503 エラーを特定し、原因と修正方針をレポートにまとめてくれました。これが Progressive Filtering の実際の動きです。

デモ 3：英語プロンプトでの発火確認

description に英語キーワードも埋め込んであるので、英語でも発火します。

「Analyze the GitHub Actions error logs」と入力すると、同じく Progressive Filtering が走り、英語で Failure Analysis Report が出力されました。日本語チームと英語チームが混在する環境でも使えます。

Copilot 用 SKILL.md の作り方：190行→58行に圧縮する設計

やっと本題です。ここが一番悩んだところで、Claude Code 版の SKILL.md（190行）を Copilot の制約に合わせて58行に圧縮する設計を解説します。

ディレクトリ構成と配置ルール

.github/
├── copilot-instructions.md     ← ルーティング追記
├── skills/
│   └── gh-workflow/
│       ├── SKILL.md            ← 本体（58行・219語）
│       └── references/
│           └── commands.md     ← 詳細情報（79行・266語）
└── workflows/
    ├── demo-failure.yml        ← テスト用（意図的に失敗）
    └── demo-success.yml

ポイント：

• ファイル名は SKILL.md（大文字必須）
• ディレクトリ名は kebab-case で name フィールドと一致させる
• Claude Code 版（.claude/skills/gh-workflow/）とは別ディレクトリなので、両方共存できる

SKILL.md と references/ の分離基準

GitHub Copilot には SKILL.md に対する 500 トークン制限（約60行・300語以内）があります。Claude Code にはこの制限がないので、190行の SKILL.md がそのまま動いていましたが、Copilot ではそうはいきません。

圧縮の方針は「SKILL.md はルーター、詳細は references/ に分離」です。

残す基準: Copilot がスキルを実行するときに「最初に読む必要がある情報」だけ残す。モード判定（何をすべきか）とトークン効率ルール（やってはいけないこと）。この2つがないと、Copilot は最初の一歩を踏み出せません。

分離する基準: 必要になったタイミングで参照すればいい情報。JSON の出力パターンやレポートテンプレートは、実行が進んだ段階で references/ から読み込めば十分です。「あとで見ればいいもの」は全部 references/ に押し出す。割り切りが大事でした。

Copilot の Progressive Disclosure（関連度に基づいて必要なファイルだけ読み込む仕組み）がこの分離設計と噛み合います。SKILL.md を読んでモードを判定し、実行に必要な詳細情報を references/ から追加で読む、という流れになるわけです。

圧縮結果：

行数の合計はあまり変わりませんが、SKILL.md 単体が 500 トークン予算の 73% に収まっているのがポイントです。

description の書き方：単一行で書く鉄則

description は Copilot がスキルを選ぶかどうかを判定する最重要フィールドです。ここの設計が発火率を左右します。

鉄則：description は単一行で書く。description: | の複数行記法は使わない。

# NG: 複数行記法 → Copilot が "|" だけ読み込んでしまう
description: |
  GitHub Actions の Workflow 状態確認とログ分析を行うスキル。
  Use when: CIが失敗した原因を調べたい。

# OK: 単一行 → Copilot が全文を正しく読み込む
description: GitHub Actionsのワークフロー状態確認と失敗ログ分析を行うスキル。gh CLIでCI/CDのログ取得から原因分析まで実行する。Use when: CIが失敗した原因を調べたい、ワークフローの状態を確認したい、PRのチェック結果を見たい。Triggers on: CI確認, Workflow確認, CI失敗, ログ分析, GitHub Actions debug,CI status check, workflow failure, PRチェック, エラーログ, pipeline debug.

GitHub Copilot のスキルローダーは YAML の複数行記法（description: |）を正しくパースできません。| という文字列だけが description として読み込まれ、発火判定に使われる情報がほぼゼロになります。Claude Code ではこの問題は起きないので、移植時に見落としがちな落とし穴です。

description に含める3要素：

1. 機能説明 — 何をするスキルか
2. Use when — どういう場面で使うか（ユーザーの意図）
3. Triggers on — 発火キーワード（日本語 + 英語）

Copilot は description の文字列とユーザーの発話の類似度でスキルを選ぶので、「ユーザーが実際に言いそうな言葉」を入れておくのがコツです。

description の設計思想や、なぜ発火しないのかの原因分析は「Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？原因と解決策」で詳しく解説しています。本記事では実装だけ押さえて先に進みます。

copilot-instructions.md でスキル発火を安定させる

description だけでは発火が不安定な場合の補強策として、copilot-instructions.md にルーティングテーブルを追加します。copilot-instructions.md は Agent Mode で常に読み込まれるファイルなので、ここにスキルへの道しるべを書いておくと発火が安定します。

## Agent Skills Routing

| キーワード | スキル | パス |
|-----------|--------|------|
| CI確認, Workflow, GitHub Actions, ログ分析, CI失敗, pipeline debug | gh-workflow | `.github/skills/gh-workflow/SKILL.md` |

既存の copilot-instructions.md の末尾に追記するだけです。中身は触らない。

注意点として、ルーティングに登録するスキルは 重要なもの3〜5個に絞る べきです。copilot-instructions.md に書いた内容は毎回のコンテキストに含まれるので、スキル全部を登録するとトークンを無駄遣いします。

この手法の効果と限界は「Agent Skillsが動かない？」の「解決策③：Instructions ルーティング」セクションで検証データ付きで解説しています。

allowed-tools の検証：agentskills.io 仕様と実装のギャップ

SKILL.md のフロントマターには allowed-tools というフィールドがあります。スキルが使ってよいツールを制限する仕組みです。今回のスキルでは以下のように書きました。

allowed-tools: Bash(gh:*) Bash(git:*) Bash(jq:*) Read

「gh CLI と git と jq のコマンド実行、それとファイル読み取りだけ許可する」という意味です。

agentskills.io Specification での定義

agentskills.io の仕様では、allowed-tools は正式なオプションフィールドとして定義されています。ただし Experimental（実験的） ステータスで、”Support for this field may vary between agent implementations” と注記されています。

記法は2パターンあります：

# パターン記法（コマンドプレフィックス指定）
allowed-tools: Bash(gh:*) Bash(git:*) Read

# ツール名列挙（MCP ツール等）
allowed-tools: list_workflow_runs summarize_job_log_failures get_job_logs

GitHub Copilot での動作検証結果

結論から言うと、現時点では allowed-tools の enforcement（強制）は実装されていません。

今回の検証では、allowed-tools を書いた状態でスキルは正常に発火し、gh CLI のコマンドも問題なく実行されました。一方で、allowed-tools に列挙していないツールの使用を制限する動作は確認できませんでした。

allowed-tools はスキル選択時には参照されず、スキル実行時に SKILL.md の本文を読んだ段階で「ガイドライン」として機能している可能性があります。強制力のあるサンドボックスではなく、エージェントへの「お願い」に近い位置づけです。

コミュニティの allowed-tools 実装例

参考までに、heilcheng/awesome-agent-skills の github-actions-failure-debugging スキルを見ると、allowed-tools はフロントマターに書かず、本文テキスト内で手順として使用ツールを記述しています。

To debug failing GitHub Actions workflows:

1. Use `list_workflow_runs` to look up recent workflow runs
2. Use `summarize_job_log_failures` to get an AI summary of failed jobs
3. Use `get_job_logs` for full detailed failure logs if needed

フロントマターの allowed-tools で制限するか、本文で手順として指示するか。enforcement が実装されていない現時点では、本文に書くほうが確実にエージェントに伝わります。

正直どちらにするか迷ったんですが、自分のスキルでは「両方書いておく」方針にしました。フロントマターは将来の enforcement が来たときの保険、本文は今のエージェントへの確実な指示。二重管理にはなりますが、壊れるリスクよりマシだと判断しています。

Claude Code 版 SKILL.md との違い（比較表）

同じ gh-workflow スキルの Claude Code 版と Copilot 版を比較します。

変わる点：description・トークン予算・ファイル構成

一番大きいのは「トークン予算」です。Claude Code は SKILL.md を丸ごと読み込めるので圧縮の必要がなく、190行でも問題ありません。Copilot は 500 トークン制限があるので、references/ への分離が必須になります。

変わらない点：gh CLI コマンド・Progressive Filtering

gh CLI のノウハウはそのまま使えます。変えるのはスキルの外側（配置・description・トークン予算）だけで、中身は同じものが動きます。

リポジトリ/
├── .claude/skills/gh-workflow/SKILL.md    ← Claude Code版（190行・1ファイル完結）
├── .github/skills/gh-workflow/            ← Copilot版（58行 + references/）
│   ├── SKILL.md
│   └── references/commands.md
└── （両方共存可能・互いに干渉しない）

ちなみに GitHub Copilot は .claude/skills/ 配下のファイルも読み込みます。つまり Claude Code 用に作ったスキルが Copilot 側でも認識される。ただし 190 行の SKILL.md だとトークン予算を超えるし、description: | の複数行記法は Copilot で壊れるので、そのまま期待どおりに動くかは別問題です。Claude Code ユーザーが Copilot でも使いたいなら、本記事のように .github/skills/ に圧縮版を別途置くのが確実です。

まとめ

CI が落ちたら「CI失敗してるから原因を調べて」。それだけで原因分析から修正方針までレポートが出てきます。

やることは .github/skills/gh-workflow/ に SKILL.md と references/commands.md を置くだけ。あとは copilot-instructions.md にルーティングを1行追記すれば完了です。

本記事のポイント：

• SKILL.md は 500 トークン以内に圧縮
  — 190行→58行。モード判定とトークン効率ルールだけ残し、詳細は references/ に分離
• description は単一行で書く
  — description: | の複数行記法は Copilot で読み込まれない。詳細は「Agent Skillsが動かない？」
• allowed-tools は Experimental
  — 仕様にはあるが enforcement 未実装。書いておいて損はないが、過信しない
• gh CLI のノウハウは共通
  — Claude Code と Copilot で変えるのは外側だけ

ではまた！

Claude Code で同じことをやるなら「gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決」を参照してください。

検証環境

• 検証日: 2026年3月2〜3日
• 環境: VS Code + GitHub Copilot（Agent Mode）
• モデル: claude-sonnet-4.5（Copilot 経由）
• 参考: VS Code Docs – Agent Skills, agentskills.io Specification

付録：SKILL.md / references/commands.md 全文コピー用

自分のリポジトリに導入するときは、以下のディレクトリ構成でファイルを配置してください。

.github/
├── copilot-instructions.md          ← 末尾にルーティングを追記
├── skills/
│   └── gh-workflow/
│       ├── SKILL.md                 ← 下記「SKILL.md 全文」をコピー
│       └── references/
│           └── commands.md          ← 下記「commands.md 全文」をコピー
└── workflows/
    └── demo-failure.yml             ← テスト用（本記事「テスト用の失敗ワークフロー」参照）

.github/skills/gh-workflow/SKILL.md（58行・219語）

---
name: gh-workflow
description: GitHub Actionsのワークフロー状態確認と失敗ログ分析を行うスキル。gh CLIでCI/CDのログ取得から原因分析まで実行する。Use when: CIが失敗した原因を調べたい、ワークフローの状態を確認したい、PRのチェック結果を見たい。Triggers on: CI確認, Workflow確認, CI失敗, ログ分析, GitHub Actions debug,CI status check, workflow failure, PRチェック, エラーログ, pipeline debug.
allowed-tools: Bash(gh:*) Bash(git:*) Bash(jq:*) Read
---

# GitHub Actions Workflow Status & Log Analysis

gh CLI を使って GitHub Actions の Workflow ステータス確認・ログ分析を行います。

## Mode Selection

ユーザーの指示から以下の4モードを自動判定して実行する。

| モード | トリガー例 | 主なコマンド |
|--------|-----------|-------------|
| クイックステータス | 「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` |

## Token Efficiency Rules（必須）

- `--log` は必ず `--job <job-id>` と併用（全ジョブログは膨大）
- `gh run watch` / `gh pr checks --watch` は使用禁止（トークン大量消費）
- JSON 出力 + jq で必要なフィールドのみ取得する
- Progressive Filtering: 一覧→絞り込み→詳細の順に段階的に情報取得

## 各モードの実行概要

### Mode 1: クイックステータス

`gh run list --branch $(git branch --show-current) --limit 10` で一覧取得→テンプレート報告。

### Mode 2: Run 詳細

`gh run view <run-id> --json status,conclusion,jobs,createdAt,updatedAt,headBranch,event` で詳細取得。

### Mode 3: PR チェック

`gh pr checks <pr-number>` でチェック状況取得。PR番号不明時はブランチから自動検出。

### Mode 4: ログ分析（メイン）

1. `gh run list --status failure` で失敗 Run 特定
2. `gh run view <run-id> --json jobs` で失敗ジョブ特定
3. `gh run view <run-id> --log --job <job-id>` でログ取得（必ず --job 指定）
4. エラー箇所を分析し原因と修正方針を報告

## 詳細リファレンス

JSON 出力パターン、レポートテンプレート、ステータス一覧は `references/commands.md` を参照。

.github/skills/gh-workflow/references/commands.md（79行・266語）

# gh-workflow コマンドリファレンス

> SKILL.md から参照される詳細情報。Copilot が必要に応じて読み込む。

## 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:**
<修正方針>
```

## 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 | 古い結果 |

## Important Notes

- **gh CLI 未認証の場合**: `gh auth status` で認証状態を確認し、未認証ならユーザーに通知
- **リポジトリ外で実行した場合**: エラーをユーザーに通知
- **大量のログ出力**: 必ず `--job` で絞り込み、それでも長い場合は主要なエラー行のみ抽出
- **進行中の Run**: ステータスが `in_progress` の場合、完了を待たずに現在の状態を報告（`watch` は使わない）

copilot-instructions.md に追記するルーティング

## Agent Skills Routing

| キーワード | スキル | パス |
|-----------|--------|------|
| CI確認, Workflow, GitHub Actions, ログ分析, CI失敗, pipeline debug | gh-workflow | `.github/skills/gh-workflow/SKILL.md` |

参考リンク

公式ドキュメント

• VS Code Docs – Agent Skills
• agentskills.io Specification
• VS Code Docs – Copilot Customization

関連 Issue

• microsoft/vscode-copilot-release#14131 — VS Code バリデータが allowed-tools を未認識

関連記事

• 【2026年版】Agent Skills 入門：SKILL.md の基本から実践まで
• Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？原因と解決策
• gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決