gh-aw-adoption

GitHub Agentic Workflows 導入スキル

目的

次の手順を通じて、あらゆるリポジトリへの GitHub Agentic Workflows（gh-aw）の導入を案内します。

1. 既存のワークフローと自動化の機会を調査する
2. リポジトリのニーズに基づいて、作成するワークフローの優先順位を決める
3. 本番環境に対応できるエージェント型ワークフローを並行して作成する
4. CI の問題、マージの競合、統合の問題を解決する
5. ワークフローがコンパイルされ、ベストプラクティスに従っていることを検証する

このスキルでは、gh-aw の導入プロセス全体を調整し、ゼロの状態から本番環境に対応できるエージェント型自動化を実現します。

このスキルを使用するタイミング

次のような場合に、このスキルを有効にしてください。

• エージェント型ワークフローのないリポジトリに gh-aw を導入する
• gh-aw リポジトリで利用できる gh-aw ワークフローのパターンを学ぶ
• 複数のエージェント型ワークフローを効率よく作成する
• リポジトリの反復的なタスク（Issue のトリアージ、PR のラベル付け、セキュリティスキャンなど）を自動化する
• 既存のエージェント型ワークフローをデバッグまたはアップグレードする
• ワークフローの失敗をトラブルシューティングする（MCP サーバーのエラー、権限の問題、CI の失敗）

クイックスタート

基本的な使い方：

Adopt GitHub Agentic Workflows in this repository

具体的な目標を指定する場合：

Adopt gh-aw to automate:
- Issue triage and labeling
- PR review reminders
- Security scanning
- Deployment automation

調査のみの場合：

Investigate what agentic workflows the gh-aw team uses

トラブルシューティング：

My workflow is failing with "MCP server(s) failed to launch: docker-mcp"

Help me fix the "lockdown mode without custom token" error

仕組み

フェーズ 1：調査（15～20 分）

目標：どのようなエージェント型ワークフローが存在するか、リポジトリにどのような不足があるかを把握します。

手順：

1. gh-aw リポジトリに問い合わせる：gh api を使って、github/gh-aw 内のすべてのワークフローを一覧表示します
2. ワークフローを分析する：さまざまなワークフローファイルを 5～10 個読み、パターンを把握します
3. ワークフローを分類する：目的（セキュリティ、メンテナンス、自動化など）ごとにグループ化します
4. 不足を特定する：リポジトリの現在の自動化と比較します
5. 優先順位リストを作成する：影響と実現可能性に基づいてワークフローを順位付けします

成果物：次の内容を含む Markdown レポート：

• 利用可能なすべてのワークフローパターンの一覧
• リポジトリのギャップ分析
• 優先順位を付けた実装計画（推奨ワークフロー 15～20 個）

フェーズ 2：ワークフローの並行作成（30～45 分）

目標：本番環境に対応できる複数のエージェント型ワークフローを同時に作成します。

アーキテクチャ：

• ワークフローごとに個別のエージェントスレッドを起動する
• 各エージェントが独立してワークフローを作成する
• 中央コーディネーターが進捗を追跡し、競合に対処する
• すべてのワークフローをフィーチャーブランチで作成する

ワークフロー作成プロセス（ワークフローごと）：

1. gh-aw リポジトリから参照ワークフローを読み込む
2. リポジトリの状況と要件に合わせて調整する
3. .github/workflows/[name].md にワークフローファイルを作成する
4. 包括的なエラー耐性を追加する（API の失敗、レート制限、ネットワークの問題）
5. safe-outputs、権限、ツールを適切に設定する
6. フィーチャーブランチを作成してコミットする
7. コーディネーターに完了を報告する

並行実行の例：

Agent 1 → issue-classifier.md
Agent 2 → pr-labeler.md
Agent 3 → security-scanner.md
Agent 4 → stale-pr-manager.md
Agent 5 → weekly-summary.md
... (up to N agents in parallel)

フェーズ 3：CI 診断と統合（15～30 分）

目標：すべてのワークフローがコンパイルされ、CI チェックに合格することを確認します。

よくある問題と解決方法：

問題：ワークフローのコンパイルに失敗する

• 解決方法：gh aw compile を実行し、YAML の構文エラーを修正します
• よくあるエラー：必須フィールドの欠落、無効なツール名、権限の問題

問題：マージの競合

• 解決方法：フィーチャーブランチを最新の main/integration にリベースします
• 方針：integration をフィーチャーブランチに順番にマージします

問題：CI/CodeQL の失敗

• 解決方法：マージ前に外部チェックが合格していることを確認します
• gh pr checks を使ってステータスを監視します

問題：Safe-output の検証エラー

• 解決方法：Safe-output の種類ごとに適切な上限を設定します
• 参照先：Safe-output の構文について gh-aw のドキュメントを確認します

フェーズ 4：検証とデプロイ（10～15 分）

目標：ワークフローが本番環境で使用できる状態であることを確認し、main にマージします。

検証チェックリスト：

• すべてのワークフローが .lock.yml ファイルにコンパイルされる
• YAML 構文エラーがない
• 権限が最小権限の原則に従っている
• 適切な上限を設定して safe-outputs を構成している
• ネットワークファイアウォールルールを指定している
• エラー耐性のパターンを実装している
• workflow_dispatch イベントでワークフローをテストしている
• ドキュメントに目的と使用方法を記載している

デプロイ戦略：

1. まず機能ブランチを統合ブランチにマージします（存在する場合）
2. 統合ブランチで CI チェックを実行します
3. すべてのチェックに合格したら、統合ブランチを main にマージします
4. 最初のワークフロー実行を監視し、実行時エラーがないか確認します

ナビゲーションガイド

関連ファイルを読むタイミング

reference.md — 次の情報が必要な場合に読みます：

• gh-aw CLI コマンドの完全なリファレンス
• ワークフローのスキーマと構成オプションの詳細
• セキュリティのベストプラクティスとサンドボックスの詳細
• MCP サーバーの統合パターン
• Repo-memory の構成と使用方法

examples.md — 次の情報が必要な場合に読みます：

• 実際の導入セッションに基づくワークフロー作成例
• 特定のワークフロータイプに関する手順ごとの実装ガイド
• よくあるエラーのトラブルシューティングと解決策
• エージェントを並列にオーケストレーションするパターン
• CI/CD の統合例

patterns.md — 次の情報が必要な場合に読みます：

• 本番ワークフローのアーキテクチャパターン
• エラー耐性の戦略（再試行、フォールバック、サーキットブレーカー）
• safe-output の構成に関するベストプラクティス
• セキュリティ強化の手法
• パフォーマンス最適化のヒント

主な概念

GitHub Agentic Workflows（gh-aw）

概要：YAML フロントマター付きの Markdown ファイルを使用して、自然言語で AI を活用したワークフローを作成できる GitHub 用 CLI 拡張機能です。

主な機能：

• Markdown でワークフローを記述し、GitHub Actions YAML にコンパイル
• AI エンジン：Copilot、Claude、Codex、またはカスタムエンジン
• 追加のツールを利用するための MCP サーバー統合
• GitHub API と構造化されたやり取りを行うための Safe-outputs
• bash と edit ツールを既定で有効にしたサンドボックス実行
• エージェントの状態を永続化する Repo-memory

ワークフローの構造

---
on: [trigger events]
permissions: [required permissions]
engine: copilot | claude-code | claude-sonnet-4-5 | codex
tools: [tool configuration]
safe-outputs: [GitHub API output limits]
network: [firewall configuration]
---

# Workflow Name

[Natural language prompt for AI agent]

重要な構成要素

権限：常に最小権限を使用します

permissions:
  contents: read
  issues: write
  pull-requests: write

Safe-outputs：GitHub API の変更を制限します

safe-outputs:
  add-comment:
    max: 5
    expiration: 1d
  close-issue:
    max: 3

ネットワーク：明示的なファイアウォールルールを設定します

network:
  firewall: true
  allowed:
    - defaults
    - github

エラー耐性のパターン

必ず実装してください：

• API レート制限への対応（指数バックオフ）
• ネットワーク障害時の再試行（遅延を挟んで 3 回試行）
• 部分的な失敗からの復旧（エラーが発生しても処理を続行）
• 包括的な監査証跡（すべてのアクションを Repo-memory に記録）
• Safe-output の上限を考慮した対応（重要なアクションを優先）

前提条件

このスキルを使用する前に、次の条件を満たしていることを確認してください：

1. gh CLI がインストールされている：gh --version
2. gh-aw 拡張機能がインストールされている：gh extension install github/gh-aw
3. リポジトリにアクセスできる：ブランチと PR を作成する書き込み権限
4. 認証が設定されている：適切なスコープを持つ GitHub トークン
5. 任意：統合ブランチ：main にマージする前にワークフローの変更をステージングするためのブランチ

Repo Guardian：最初に導入するワークフロー

Repo Guardian は、どのリポジトリでも最初に導入することを推奨するワークフローです。このスキルのディレクトリには、そのままコピーして使用できるテンプレートが含まれています：

• repo-guardian.md — gh-aw のエージェント型ワークフロー（AI エージェント向けの自然言語プロンプト）
• repo-guardian-gate.yml — エージェントの検出結果をブロッキング CI チェックとして適用する標準の GitHub Actions ワークフロー

機能

すべての PR をレビューし、リポジトリに含めるべきでない一時的なコンテンツを検出します：

• 会議メモ、スプリントの振り返り、進捗報告
• 一時的なスクリプト（fix-thing.sh、one-off-migration.py）
• 時間の経過とともに古くなる一時点のドキュメント
• スナップショットを示唆する日付の接頭辞が付いたファイル

検出結果を PR コメントとして投稿します。コラボレーターは repo-guardian:override <reason> で上書きできます。

クイックセットアップ

# 1. Copy templates
mkdir -p .github/workflows
cp .claude/skills/gh-aw-adoption/repo-guardian.md .github/workflows/repo-guardian.md
cp .claude/skills/gh-aw-adoption/repo-guardian-gate.yml .github/workflows/repo-guardian-gate.yml

# 2. Compile the agentic workflow (pins the gh-aw version)
cd .github/workflows
gh aw compile repo-guardian

# 3. Add COPILOT_GITHUB_TOKEN secret (PAT with read:org + repo scopes)
# Repository Settings → Secrets and variables → Actions → New repository secret

# 4. Commit and push all three files
git add .github/workflows/repo-guardian.md \
        .github/workflows/repo-guardian.lock.yml \
        .github/workflows/repo-guardian-gate.yml
git commit -m "feat: Add Repo Guardian agentic workflow"
git push

---

導入を検討する一般的なワークフロー

gh-aw リポジトリ内の100以上のワークフローを分析した結果、検討する価値のある、影響の大きいワークフローは次のとおりです。

セキュリティとコンプライアンス（優先度：高）：

• repo-guardian.md - 一時的なコンテンツを含む PR をブロックします（テンプレートとして同梱されています。上記を参照）
• secret-validation.md - シークレットの有効期限切れと漏えいを監視します
• container-security-scanning.md - コンテナーイメージをスキャンして脆弱性を検出します
• license-compliance.md - 依存関係のライセンスを検証します
• sbom-generation.md - ソフトウェア部品表を生成します

開発の自動化（優先度：高）：

• pr-labeler.md - 内容に基づいて PR に自動でラベルを付けます
• issue-classifier.md - Issue をトリアージしてラベルを付けます
• stale-pr-manager.md - 猶予期間を設けて、古い PR をクローズします
• changelog-generator.md - コミットから変更履歴を自動生成します

品質保証（優先度：中）：

• test-coverage-enforcer.md - カバレッジがしきい値を下回る PR をブロックします
• mutation-testing.md - ミューテーションテストを実行し、残存した変異を報告します
• performance-testing.md - パフォーマンスの自動リグレッションテストを実行します

メンテナンスと運用（優先度：中）：

• agentics-maintenance.md - ワークフローの健全性を監視するハブです
• workflow-health-dashboard.md - 毎週のメトリクスとステータスレポートを提供します
• dependency-updates.md - 依存関係を更新する PR を自動作成します

チームコミュニケーション（優先度：低）：

• weekly-issue-summary.md - 視覚化を含む、週次の Issue ダイジェストです
• team-status-reports.md - チームの毎日のステータス更新です
• pr-review-reminders.md - レビューが滞っているレビュアーにリマインドします

トラブルシューティング

問題：gh-aw 拡張機能が見つかりません

gh extension install github/gh-aw
gh aw --help

問題：コンパイルエラーが発生します

gh aw compile --validate
gh aw fix --write  # Auto-fix some issues

問題：ワークフローが実行されません

• ワークフローファイルが .github/workflows/ にあることを確認します
• ワークフローに有効なトリガー（on: フィールド）が設定されていることを確認します
• GitHub Actions のログで実行エラーを確認します
• 必要なシークレットが設定されていることを確認します

問題：safe-output の上限を超えています

• ワークフローの frontmatter にある safe-output の設定を確認します
• 適切であれば、上限を引き上げます
• 上限内に収めるため、優先順位付けロジックを追加します

問題：権限が拒否されるエラーが発生します

• ワークフローの frontmatter にある permissions: ブロックを確認します
• GitHub トークンに必要なスコープがあることを確認します
• ワークフローに必要なリポジトリ権限があることを確認します

避けるべきアンチパターン

❌ しないこと：すべてを実行するモノリシックなワークフローを作成する
✅ すること：単一の責務に集中したワークフローを作成する

❌ しないこと：エラー処理を省略し、API が常に成功すると想定する
✅ すること：再試行、フォールバック、包括的なエラーログを実装する

❌ しないこと：広範すぎる権限を使用する（あらゆる場所で contents: write を指定するなど）
✅ すること：各ワークフローに最小権限の原則を適用する

❌ しないこと：リポジトリ固有の値をワークフローにハードコードする
✅ すること：GitHub コンテキスト変数（${{ github.repository }}）を使用する

❌ しないこと：テストせずにワークフローを作成する
✅ すること：自動トリガーを有効にする前に workflow_dispatch でテストする

成功基準

次の条件を満たせば、gh-aw の導入は成功です。

1. ✅ リポジトリに本番環境用のエージェント型ワークフローが10～20個ある
2. ✅ すべてのワークフローがエラーなくコンパイルできる
3. ✅ CI/CD パイプラインにワークフローの検証が含まれている
4. ✅ ワークフローがセキュリティのベストプラクティスに従っている
5. ✅ チームがワークフローの作成方法と変更方法を理解している
6. ✅ ワークフローがエラーを適切に処理し、監査証跡を提供する
7. ✅ メンテナンスハブがワークフローの健全性を監視している
8. ✅ ドキュメントで各ワークフローの目的と使用方法が説明されている

導入後の次のステップ

1. ワークフローの健全性を監視する：workflow-health-dashboard.md を使用します
2. フィードバックに基づいて改善する：チームのニーズの変化に応じてワークフローを調整します
3. カスタムワークフローを作成する：学んだパターンを活用して、新しい自動化を構築します
4. 学びを共有する：成功したパターンを他のリポジトリ向けに文書化します
5. ワークフローをアップグレードする：gh-aw 拡張機能を最新の状態に保ち、マイグレーションを適用します

---

ドキュメント構成（Diátaxis フレームワーク）

このスキルは、相互に補完する4つのリソースで構成されたDiátaxisドキュメントフレームワークに従っています。

1. SKILL.md（チュートリアル／概要）：導入ガイド、クイックリファレンス、概要レベルの概念
2. examples.md（ハウツーガイド）：実践的な例とトラブルシューティングの解決策を、手順ごとに解説します
3. patterns.md（解説）：パターン、アンチパターン、ベストプラクティスについて理解します
4. reference.md（リファレンス）：技術仕様、詳細な設定、トラブルシューティングのリファレンス

トラブルシューティングの場合：

• エラーと根本原因を理解するために、まずreference.mdを確認します
• 手順ごとの修正方法については、examples.mdを確認します
• 今後のワークフローでアンチパターンを避けるために、patterns.mdを確認します

---

注：このスキルは、gh-awの導入プロセス全体を自動化します。手動で制御する場合や特定のフェーズのみを実行する場合は、明示的な指示を付けてスキルを呼び出してください（例：「gh-aw-adoption: investigation only」）。