QAエンジニアの採用・選考　どう採るどう通る？連載の第4回です。 前回の記事 では、求職者の立場から職務経歴書や面接で「採用したい」と思わせるアピール方法について解説しました。第2回・第3回は求職者側の視点での話でしたが、今回からは募集側が意識すべき、QAエンジニアの採用を成功させるためのポイントをお伝えしていきます。 QAエンジニアの募集を出しているけれどなかなか応募が来ない 応募はあるけれど、求めている人材とマッチしない といった悩みを持つ企業やエンジニア採用担当の方のお話を伺うことがあります。 市場におけるQAエンジニアの母数は開発者等に比べて少ないですし、かつ 第1回 でも触れたように、ハイレベルな人材が求められがちなので、結果として採用に苦労している企業が多い状況です。 本記事では、そのような状況の中で求めるQAエンジニアを採用するために必要な「QAに対する理解」を中心に説明します。 記事一覧：QAエンジニアの採用・選考［どう採る　どう通る］ 【第1回】QAテストエンジニア採用における募集側・求職者側のニーズと課題 ［全文公開中］ 【第2回】求職者側の課題1：求められているQA像を把握する 【第3回】求職者側の課題2：適切なアピールで「欲しい」と思わせる 【第4回】募集側の課題1：QAエンジニアの業務や考え方を理解し、敬意を伝える よくある「もったいない」パターン 私は過去に事業会社でQAエンジニアの採用を担当し、書類選考や面接を行ってきました。また、個人活動としてQA採用に悩む企業の方から相談を受けることも多くあります。その中で、「この書き方ではなかなか応募が来なさそうだな・・・」と感じる、もったいない募集のパターンがいくつかありました。 たとえば以下のようなものです。 業務内容が「テスト業務をお任せします」だけで具体性がない 必須要件が「品質評価業務の経験＊年」などふわっとしている プロセス改善や品質向上への取り組みに言及がない 「単純作業」「コツコツ作業できる人向け」などの表現が使われている 開発との協調や上流工程への関与について触れられていない 給与が開発職に比べて極端に低く設定されている テスト、評価、検証などの用語が混在している 類似のものや相互に関連するものも含まれますが、これらに共通しているのは QA業務や品質への理解が浅い ということです。 理解が浅いままだと、QAエンジニアからは「この会社はQAのことをわかっていないな」や「リスペクトが無いな」などと判断されてしまいます。理解やリスペクトのない状況に敢えて飛び込んでいくエンジニアは、あまり多くはないでしょう。（飛び抜けて待遇が良い、などであれば別かもしれませんが・・・） QAについて理解すべきこと では、QAを理解するとは具体的にどういうことでしょうか。大まかに3つのポイントがあります。 QAエンジニアの業務の幅広さ まず押さえておきたいのは、QAエンジニアの業務はテスト実行だけではない、という点です。 テストを実行するのはもちろん、テスト設計や、組織・チームにおけるテストや品質保証の方針を策定することや、テスト・QAプロセス改善、テスト自動化の推進、開発者へのテスト技術の移転、不具合分析等を通じた品質の可視化や改善アクションなどなど、QAエンジニアが担う可能性のある業務は多岐にわたります。QAエンジニアはその中で得意領域を持って開発組織に貢献したり、できること・領域自体を広げるための努力をしたりしています。 QAエンジニアは「開発の後工程でテストをする人」ではありません。 第2回 で触れた”自走できる人”というキーワードも、こうした幅広い業務を自律的にこなせる人材を指しています。プロダクトのQA活動を一貫して担い、必要であれば仕事を自分で作っていく。そのような役割を期待している企業が多いですし、多くのやる気のあるQAエンジニアはそのような期待に応えようとしているはずです。 にもかかわらず「QAってテストする人でしょ？」という理解で募集をしてしまっていては、QAエンジニア側とのギャップが大きく、採用はうまく進まないと思います。 品質文化とQAの位置づけ 続いて理解しておきたいのは、品質文化とQAの位置づけです。 QAエンジニアが重視しているものの一つに、「品質は全員で作るもの」という考え方が組織に根付いているかどうかがあります。品質はQAエンジニアだけが考えるものではなく、開発チーム全体で作り込むものだという理解が前提にあるのです。 そのため、既にQAチームが存在する場合は開発とQAが対立していない環境、一緒に良いプロダクトを作る仲間として協働している環境を求めたいところです。いわゆる「上流から関われる」「開発チームとの距離が近いor開発チームの中で働いている」といった、開発プロセスに何か意見を反映できる、品質向上のための活動が尊重されるような環境かどうかを気にする人が多いでしょう。 1人目QAを募集する場合は既存のQAチームが無い状態なので、「品質文化がありますよ」「ウチは上流から関わっていますよ」といったアピールはできません。が、QAチームの体制が整った暁にはそういった協働状態を目指したいと思っているんだ、という一つの理想像として提示すると良いと思います。 QAにとってのスタンダードな考え方を理解する もう一つ理解しておきたいのは、QA業界におけるスタンダードな考え方です。 たとえばシフトレフトやシフトレフトテストという考え方があります。開発プロセスの早い段階から品質を考えたりテスト活動を行うというアプローチで、以前はちょっとした流行り、最近よく聞くようになった言葉、といった位置づけだったように思います。しかし、今ではスタンダードな考え方として浸透しているのではないでしょうか。スタンダードとして浸透している、ということはつまり QAエンジニアの多くはその考え方を知っている・聞いたことがある状態であり （個別の賛否はあるものの）概ね皆が賛同している、取り入れたほうがいいと思っている ということです。 テスト自動化などもそうですし、上で述べたような「QAエンジニアの業務・やれることは幅広い」や「品質はQAだけでなく皆で作るものである」なども、スタンダードな考え方と言っていいでしょう。 これらのスタンダードな考え方を知っておくことは、募集文面を書くうえでも重要です。私自身、QAの求人票を見たときに、「この会社はQA界隈の考え方などを理解しているかな」と無意識に見ています。募集側が求職者の職務経歴書を見たときに「github（正しい表記はGitHub）」のような細かいミスが多かったり、自社の事業について的はずれな理解をしていては「大丈夫か？」と思ってしまいますよね。求職者から募集側を見たときにも同じです。 逆に言えば、こうしたスタンダードな考え方が反映された募集文面は、それだけで「QAのことをわかっている会社だな」という印象を与えることができます。 理解を深めるための具体的アクション ここまで、QAについて何を理解すればいいのかを整理してきました。しかし「理解しましょう！」だけでは実際に何をすればいいのかわかりません。ここからは、理解を深めるための具体的なアクションについて説明します。これらのアクションは主に1人目のQAを採用する際の活動が中心ですが、もちろん2人目以降の組織拡大フェーズにおいても適用できる方法だと考えています。 他社求人を参考に、自社のニーズを言語化する まず取り組みやすいのが、他社の求人を参考にすることです。ビズリーチやFindyなどのメジャーな媒体でQAエンジニアの求人を検索すると、さまざまな企業の募集文面を確認できます。 ここで重要なのは、他社の求人を「真似る」のが目的ではないということです。他社の求人を見ることで、QAエンジニアに期待したいことや、開発プロセスをどうしていきたいのかを適切に言語化することが本来の目的です。他社の求人はそのための「ヒント」として活用するものだと考えてください。 具体的には、業務内容の書き方や使われている表現、必須要件と歓迎要件の内容とバランスなどを参考にしながら、「自社の場合はどうか？」と置き換えて考えましょう。もちろん、他社が必須や歓迎としている要素すべてが自社に必要とは限りません。プロダクトがtoBなのかtoCなのか、モバイルアプリなのか基幹システムなのか、などプロダクトやドメインの性質によって要件は変わってきます。 似た業種や規模の会社の求人を参考にし、不要な要素は除きつつ、「考えていなかったけど、確かにこういう要素もほしいな」などの気づきがあれば取り入れる。このプロセスを通じて、「QAに何を期待しているのか」「開発プロセスをどうしたいのか」が少しずつ言語化されていきます。 実際に私がお話した、QA採用に成功した企業の方も、まずは他社の求人を研究することから始めたとおっしゃっていました。そのプロセスを通じて自社のニーズが明確になり、それが募集文面に反映されたとのことです。 QAコミュニティに触れる JaSSTやQA系のミートアップイベントなど、QAエンジニアが集まるイベントやコミュニティに参加してみることもおすすめです。QAエンジニアが何を話しているか、どんなトピックに関心を持っているかを直接知ることができます。 ただし注意点として、採用目的を前面に出した参加は避けましょう。私がお話した、QA採用に取り組んでいる方の中にも、「宣伝目的でコミュニティに参加すると、かえってQAエンジニアの間で心象を悪くしてしまうのでは」と懸念されている方がいました。これは非常にまっとうな考え方だと思います。 コミュニティへの参加はあくまでも「QA界隈の文化や考え方を学びに行く」ことや「自分たちの開発や品質保証のプロセスをよくするヒントを得にいく」ことをメインとして、結果としてつながりができたら嬉しい、というスタンスを大切にしましょう。こうした姿勢で参加することで、QAエンジニアとの自然な交流が生まれ、場合によってはカジュアル面談などにつながることもあるかもしれません。 一般にカジュアル面談では、自社に興味を持ってくれているエンジニアに対して自社のビジネスや課題感、採用にあたって期待することなどを話すと思います。しかし、採用がなかなかうまくいっていない、どうやっていけばいいかわからない、という場合は 現役のQAという立場で募集内容に対するフィードバックをくれませんか？ と素直にお伝えして、そのような意図のカジュアル面談を申し込むのも一つの手です。 自社がリーチしたい層に響く内容になっているかどうか、応募したくなるかどうか、現役のQAエンジニアの生の声を聞くことが最も確実な確認方法だと考えています。 なお、最近は複数社が合同でミートアップ形式のイベントを開催するケースも増えています。こうした場を活用して認知を広げることも一つの手ですが、そちらについては次回詳しく触れます。 社内におけるQAへの理解と、QA側の思いとのギャップを埋める QAコミュニティに触れて学んだことと、社内での理解との間には、ギャップがある場合があります。たとえば、本記事中でも説明したような、QAは品質向上に関わる幅広い業務をスコープとして考えているけれども、開発者は「テストする人でしょ？」と思っている、などです。 このようなギャップを放置したまま採用を進めると、うまくいかないことが多いです。採用が難航するだけでなく、仮に採用できたとしても早期離職につながるリスクがあります。 そのため、採用活動と並行して社内における QAや品質に対する理解 を得ることも大切にしてください。開発チームリーダーやプロダクトマネージャー、CTO・VPoEなど、とくに組織の文化を醸成したり広く情報を発信できる立場にある方から、「QAエンジニアという存在に対するイメージ」や「QAエンジニアに期待すること」を広めていただくのが理想です。こうした土台が整っていると、入社したQAエンジニアが力を発揮しやすい環境が生まれます。 もちろん、開発者やマネージャーなど他のロールの方に「QAエンジニアと同等の知識を身に着けてから採用活動をしてください」ということではありません。（それが実現できるならば、QAエンジニアの必要性があまりなくなってしまいますね。） そうではなく、誤った理解を減らし、今後入社したQAエンジニアの話に耳を傾けられる姿勢を皆がもっている状態を目指しましょう、ということです。特別扱いは必要ありませんが、QAエンジニアを品質の専門家として尊重することが大切です。これが、本記事の冒頭でも用いた「リスペクト」にあたります。 副業QAに入ってもらう 最後は、現役のQAエンジニアに業務委託として入ってもらう、いわゆる「副業QA」の活用です。副業QAに文化づくりや募集文面づくりなど、採用の土台を整える活動を担ってもらうというもので、社内の品質に関する現状把握や開発プロセスの分析、募集文面の作成・レビュー、社内への品質文化の醸成、採用面接のサポートなどを依頼することが考えられます。 このアプローチが有効な理由はいくつかあります。まず、QAの専門家の視点が社内に入ることで、募集文面が「QAに刺さる」内容になります。面接での見極めもより適切になるでしょう。また、副業QAと一緒に仕事をする中で、社内のメンバーが「QAとは何か」を実際に体験できます。これが品質文化の醸成にもつながります。そして、いきなり正社員を採用するよりもリスクが低く、まず試してみることができるという点も魅力です。 とくに初めてQAエンジニアを採用しようとしている企業にとっては、こうした形でQAの専門家と関わりを持つことが、その後の正社員採用をスムーズにする近道になるのではないかと考えています。2人目以降の採用を行うにあたっても、もし既存のQAメンバーが若手中心であれば、ベテランの副業QAに入ってもらうことで刺激や学びになる部分もあります。QA採用のためには「いまいるメンバーの、同僚としての魅力」が求められる場合もあるため、その点の強化にもつながります。 副業可能なQAエンジニアとの接点としては、前述のカジュアル面談から副業の話に発展させるなどの方法があります。ほかにも、YOUTRUSTなどのサイトでは転職希望のほか副業希望の度合いもエンジニア側が設定できるので、副業を希望しているエンジニアを探すことも可能です。 まとめ 本記事では、QAエンジニアの募集でなかなか応募が来なかったり、求めている人材とマッチしなかったりする原因として、「QAへの理解不足」があることをお伝えしました。 募集文面の表現を工夫する前に、まずQAエンジニアの業務の幅広さ、品質文化とQAの位置づけ、QA業界のスタンダードな考え方を理解することが大切です。そのうえで、他社求人を参考にした自社ニーズの言語化、QAコミュニティへの参加、社内での対話、副業QAの活用といったアクションを通じて、理解を深めていきましょう。 学ぶプロセスは、単に募集文面をよくするためだけではありません。QAについて学び、社内で対話を重ねること自体が、組織の品質意識を高めることにつながります。QA採用の成功は、こうした地道な積み重ねから始まるのではないかと考えています。 次回は募集側の課題2として、QAエンジニアの中での認知を獲得するための手法についてご紹介します。 【連載】QAエンジニアの採用・選考［どう採る どう通る］ 【第1回】QAテストエンジニア採用における募集側・求職者側のニーズと課題 ［全文公開中］ 【第2回】求職者側の課題1：求められているQA像を把握する 【第3回】求職者側の課題2：適切なアピールで「欲しい」と思わせる 【第4回】募集側の課題1：QAエンジニアの業務や考え方を理解し、敬意を伝える The post 【第4回】募集側の課題1：QAエンジニアの業務や考え方を理解し、敬意を伝える first appeared on Sqripts .

Introduction Hey, I’m VuongVu, a backend eng ...

GitHub Actions の失敗ログ、まだ手動で読んでいませんか？ ども！龍ちゃんです。 CI が落ちたときの対応、毎回こうなっていませんか？ GitHub Actions の UI を開く 失敗した Run を探す 失敗したジョブを開く ログをスクロールしてエラー行を目視で探す エラーメッセージをコピーしてググる 地味に面倒なんですよね、これ。特にジョブが複数あるワークフローだと、どのジョブのどのステップで落ちたのかを探すだけで時間を食う。 これ、Agent Skills に任せたら1行で終わります。 Before After 操作 GitHub UI → ログ目視 → 手動分析 「CI失敗してるから原因を調べて」 所要時間 5〜10分 30秒 得られるもの エラー行のコピペ 原因分析 + 修正方針のレポート 本記事では、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 のレポート）： 日時 ワークフロー名 ステータス Run ID 3/2 11:23 Demo – Failure Workflow failure 22573804432 2/26 06:20 Demo – Failure Workflow failure 22430458939 2/26 06:20 Demo – CI Pipeline success 22430440934 2/26 06:19 Demo – CI Pipeline success 22430416062 「最新の 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/ に分離」です。 分類 SKILL.md に残す references/commands.md に分離 モード判定 4モードのテーブル（4行） – Token Efficiency Rules 必須ルール4項目 – 各モードの手順 概要（主なコマンド1行ずつ） JSON 出力パターン全文 レポートテンプレート – ステータス一覧 + 失敗分析テンプレート Status/Conclusion 一覧 – 12行の値テーブル Important Notes – 4項目の注意事項 残す基準 : Copilot がスキルを実行するときに「最初に読む必要がある情報」だけ残す。モード判定（何をすべきか）とトークン効率ルール（やってはいけないこと）。この2つがないと、Copilot は最初の一歩を踏み出せません。 分離する基準 : 必要になったタイミングで参照すればいい情報。JSON の出力パターンやレポートテンプレートは、実行が進んだ段階で references/ から読み込めば十分です。「あとで見ればいいもの」は全部 references/ に押し出す。割り切りが大事でした。 Copilot の Progressive Disclosure（関連度に基づいて必要なファイルだけ読み込む仕組み）がこの分離設計と噛み合います。SKILL.md を読んでモードを判定し、実行に必要な詳細情報を references/ から追加で読む、という流れになるわけです。 圧縮結果： Claude Code 版 Copilot 版 SKILL.md 190行 58行（219語） 参照ファイル なし（全部入り） references/commands.md（79行・266語） 合計 190行 137行（2ファイル） 行数の合計はあまり変わりませんが、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要素： 機能説明 — 何をするスキルか Use when — どういう場面で使うか（ユーザーの意図） 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 が発火を妨げない） allowed-tools 内のツール使用 問題なし allowed-tools 外のツール制限 未確認（制限が効いている証拠なし） VS Code バリデータの警告 Issue #14131 として報告済み（Open、対応予定なし） 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 版 Copilot 版 ファイルパス .claude/skills/gh-workflow/ .github/skills/gh-workflow/ SKILL.md 行数 190行（1ファイル完結） 58行 + references/commands.md description トリガー文字列列挙 単一行で Use when + Triggers on allowed-tools Bash, Read Bash(gh:*) Bash(git:*) Bash(jq:*) Read 参照ファイル分離 不要（全文コンテキストに読み込み） 必須（500トークン制限） copilot-instructions.md 不要 ルーティング追記推奨 一番大きいのは「トークン予算」です。Claude Code は SKILL.md を丸ごと読み込めるので圧縮の必要がなく、190行でも問題ありません。Copilot は 500 トークン制限があるので、references/ への分離が必須になります。 変わらない点：gh CLI コマンド・Progressive Filtering 比較項目 Claude Code / Copilot 共通 gh CLI コマンド 同一（ gh run list , gh run view --log --job 等） Progressive Filtering 同一（一覧→ジョブ特定→ログ取得→分析の4ステップ） Token Efficiency Rules 同一（ --log は --job と併用、 watch 禁止等） Report Template 同一（references/commands.md に移植済み） 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 失敗ログをチャットで即解決 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post GitHub Actions失敗ログ、まだ手動で読む？Copilot Agent Skills で CI デバッグを自動化する実装ガイド first appeared on SIOS Tech Lab .