Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？原因と解決策

Claude CodeのSkillsがCopilotで発火しない・読み込まれない原因はdescriptionの書き方。単一行で書かないとCopilotが読み込めない問題と、3つの解決策を検証データ付きで解説。

【2026年3月追記】description の複数行記法に関する重要な修正

本記事は2026年2月の公開時、description: | による複数行記法を推奨していましたが、その後の検証で GitHub Copilot では複数行記法が正しく読み込まれない ことが判明しました。本記事は検証結果を反映してリライトしています。

修正前: description: | + 複数行で詳しく書くことを推奨
修正後: 単一行で書くことを推奨（description: | は使わない）

既に複数行記法で実装している方は、1行にまとめるだけで解決します。

Claude CodeのスキルをCopilotに移植したら動かない？

ども！龍ちゃんです。

Claude Code で作ったスキルを GitHub Copilot に移植したことがある人、こんな経験ありませんか？

「同じ SKILL.md 形式なのに、Copilot だとスキルがまったく発火しない…」

自分もまさにこれでした。「網羅5種ブログ」と「Claude Code→GitHub Copilot移行」で紹介した Agent Skills を実際に移植したら、Claude Code では動いていたスキルが Copilot では全然反応しない。description を充実させても、トークン数を削っても、何をやっても安定しない。

結局 Instructions ルーティングという力技で動かしていたんですが、後日の追加検証でもっとシンプルな原因が見つかりました。description の書き方が Copilot のパーサーに合っていなかった。それだけだったんです。

本記事では、この問題の正体と3つの解決策を検証データ付きで解説します。Claude Code ユーザーならスラッシュコマンドで呼び出せば使用感はそのままなので、自動発火にこだわらない人は移植チェックリストだけ見ればOKです。

検証環境

• 初回検証日: 2026年2月2日
• 追加検証日: 2026年3月3日（description 複数行問題の検証）
• 環境: VS Code 1.108以降 + GitHub Copilot
• 参考: VS Code Docs – Agent Skills

前提：Agent Skills の基本

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

本記事では「発火しない」問題と解決策に特化します。

発火しない原因：description が正しく読み込まれていない

結論から言います。description の書き方が間違っていたから、Copilot がスキルを認識できなかった。これが本質です。

当初は「Claude Code と GitHub Copilot で発火メカニズムが根本的に異なる」と推測していましたが、追加検証でもっとシンプルな原因が判明しました。

Copilot のスキル発火の仕組み：Progressive Disclosure

GitHub Copilot も Claude Code も、Agent Skills には「Progressive Disclosure（段階的開示）」という設計思想を採用しています。

具体的には、Copilot は以下の2段階でスキルを扱います。

Phase 1：メタデータの把握（常時）

Copilot は全スキルの name と description を軽量なメタデータとしてシステムプロンプトに保持しています。内部的にはこんな感じで渡されています。

<skill>
  <name>gh-workflow</name>
  <description>GitHub Actionsのワークフロー状態確認と...</description>
  <file>.github/skills/gh-workflow/SKILL.md</file>
</skill>

Phase 2：本文の読み込み（発火時のみ）

ユーザーの発話と description がマッチしたスキルだけ、SKILL.md の本文がコンテキストに読み込まれます。

つまり、Phase 1 の description がスカスカだと、Phase 2 に進めない。発火しない原因はここにあります。

検証で判明した致命的な問題：description: | が壊れる

ここからが今回の追加検証で判明した重要な発見です。

GitHub Copilot 経由の Claude に「自分に渡されているスキル情報を見せて」と聞いてみました。すると衝撃の結果が。

description: | で複数行記法を使うと、Copilot は | だけを description として認識する。

これはつまり、Phase 1 の時点でモデルには | という1文字しか渡されていないということ。「ブログをスクレイピングして」と言っても、| との類似度は 0。そりゃ発火しないわけです。

Claude Code ではこの問題は起きません。 Claude Code の YAML パーサーは | 記法を正しく処理できるので、複数行で書いても description が完全に読み込まれます。つまり、Claude Code だけを使っているなら description: | で何の問題もないんです。

さらに言うと、GitHub Copilot でもスラッシュコマンド（/skill-name）での明示的な呼び出しは問題なく動きます。description のマッチングは「自然言語での自動発火」にだけ影響するので、スラッシュコマンドで呼び出す分には description が壊れていても SKILL.md の本文が直接読み込まれます。

Claude Code ユーザーにとっては、普段から /blog-scraper のようにスラッシュコマンドでスキルを呼び出す習慣があると思います。この使い方なら GitHub Copilot でも使用感はほぼ変わりません。自動発火にこだわらなければ、description の書き方を気にせず移植できます。

ただし、自動発火（「ブログを取得して」のような自然言語で勝手にスキルが選ばれる）を活用したい場合は、description を単一行で正しく書く必要があります。

この問題、自分だけじゃなかった

実は GitHub の公式リポジトリにも同様の問題が報告されています。

• Issue #12971
  – Skill descriptions using YAML multi-line literal block syntax (|) are not parsed correctly（2025年12月報告）
• Issue #11322
  – Skill frontmatter parser fails on Prettier-formatted multi-line descriptions（2025年11月報告）

いずれも anthropics/claude-code リポジトリへの報告ですが、影響を受けるのは GitHub Copilot 側のスキルローダーです。YAML の仕様的には | は有効な記法ですが、Copilot のパーサーが対応できていないというのが現状です。

Claude Code と GitHub Copilot の違い

メカニズムの違い自体は存在します。ただし、当初思っていたほど大げさな違いではありませんでした。

核心の一文: 「メカニズムが根本的に違うから発火しない」のではなく、「description の書き方が Copilot のパーサーに合っていなかったから発火しない」。

【コラム】なぜ当初の検証では気づけなかったのか？

2月の初回検証では、description を | 記法で強化 → Instructions ルーティングを追加 → 発火した、という流れでした。

実は発火していたのは Instructions ルーティングのおかげであって、description の強化が効いていたわけではなかった可能性が高いです。Instructions は常にコンテキストに読み込まれるので、description が壊れていてもルーティングテーブルでバイパスできていたんですね。

もうひとつの落とし穴：.claude/skills/ も Copilot に読み込まれる

知っておくべきもうひとつの事実。Claude Code 用に作ったスキル（.claude/skills/ 配下）も、GitHub Copilot に自動で読み込まれます。

Copilot のスキルローダーが検出するディレクトリは以下の通りです。

Agent Skills がオープンスタンダードとして公開された際に、Claude Code ユーザーのスキルがそのまま使えるよう .claude/skills/ も検出対象に入りました。

これ自体は便利な仕様なんですが、問題は .claude/skills/ のスキルが description: | で書かれていると、Copilot 側では壊れた状態で認識される こと。意図せず | だけの description を持つスキルが大量に登録されてしまいます。

関連して、VS Code のバリデータが .claude/skills/ の SKILL.md にエラーを出す問題もあります。こちらは見た目だけの問題で動作には影響しませんが、気になる方は「VS Code で Claude Code の SKILL.md にエラーが出る原因と対処法」を参照してください。

解決策①：description を正しく書く

ここが最も重要な解決策です。やることはシンプル。

鉄則：description は単一行で書く

description: [機能の説明]. Use when: [いつ使うか]. Triggers on: [発火キーワード].

description: | は使わない。 これだけ。

なぜ単一行で書く必要があるのか？

GitHub Copilot のスキルローダーは、YAML の複数行記法（description: |）を正しく処理できません。

複数行記法の場合:

---
name: my-skill
description: |
  スキルの説明。
  Use when: 使うタイミング。
---

Copilot が読み込む内容: description: "|" （パイプ記号だけ）

単一行記法の場合:

---
name: my-skill
description: スキルの説明。Use when: 使うタイミング。
---

Copilot が読み込む内容: description: "スキルの説明。Use when: 使うタイミング。" （完全）

Claude Code では複数行記法も正しく動作しますが、GitHub Copilot との互換性を保つなら単一行に統一してください。

検証日: 2026年3月3日

description の内容：「ユーザーの発話」を埋め込む

書き方を単一行にしたら、次は内容です。

Copilot は description の内容とユーザーの発話を照らし合わせてスキルを選択します。つまり、ユーザーが実際に使う言葉を description に埋め込む必要があります。

Claude Code では「何をするか」だけ書けば十分ですが、GitHub Copilot では「何をするか + いつ使うか + 発火キーワード」の3点セットが必要です。

落とし穴：「英語で書くべき」Tips が逆効果になる場合

よく「システムプロンプトは英語で書くべき」というTipsがありますよね。GitHub Copilot Agent Skills では、これが逆効果になる可能性があります。

Copilot の発火判定はモデルが description の内容とユーザーの発話を照合して行います。日本語でプロンプトを書くユーザーには、日本語の発火キーワードがないとマッチしません。

結論: description には日本語・英語両方の発火キーワードを列挙しましょう。

Before / After

Before（発火しない）:

# NG: 内容が薄い
description: HTMLをPlaywrightでレンダリングしてPNG画像に変換

# NG: 複数行記法（| を使っている）
description: |
  HTMLファイルをPlaywrightでレンダリングしてPNG画像に変換するスキル。
  Use when: HTMLを画像化したい、スクリーンショットを撮りたい。
  Triggers on: HTMLをPNGに変換, HTML to PNG, 画像に変換.

After（発火する）:

# OK: 単一行 + Use when + Triggers on
description: HTMLファイルをPlaywrightでレンダリングしてPNG画像に変換するスキル。Use when: HTMLを画像化したい、スクリーンショットを撮りたい。Triggers on: HTMLをPNGに変換, HTML to PNG, 画像に変換, HTMLを画像に, screenshot HTML, HTMLをキャプチャ.

1行が長くなりますが、問題ありません。description の上限は 1024文字 です。

ポイントは「技術的に何をするか」ではなく、「ユーザーがどう言うか」を想像して書くことです。

解決策②：トークン予算を守る

Copilot はトークン効率を重視する設計です。SKILL.md が長すぎると、そもそも読み込まれない可能性があります。

分割パターン

長くなりそうな場合は、詳細を references/ に分割しましょう。

.github/skills/my-skill/
├── SKILL.md              # 概要 + Quick Start（〜60行）
└── references/
    ├── commands.md       # コマンド詳細
    └── troubleshooting.md

SKILL.md は「ルーター役」に徹して、詳細は必要な時だけ読み込まれるようにします。

解決策③：Instructions ルーティング

description を正しく書いていれば、ほとんどのケースで発火するはずです。ただし、それでも不安定な場合の手段として、copilot-instructions.md に明示的なルーティングテーブルを追加する方法があります。

## Agent Skills Routing

| キーワード                             | スキル       | パス                                   |
|----------------------------------------|--------------|----------------------------------------|
| ブログスクレイピング, tech-lab.sios.jp | blog-scraper | `.github/skills/blog-scraper/SKILL.md` |
| フローチャート, 図                     | html-diagram | `.github/skills/html-diagram/SKILL.md` |

なぜ有効か

• Instructions は常にコンテキストに読み込まれる
• description のマッチングに依存しないので発火が安定する

デメリット（トレードオフ）

• 保守性の低下: スキルを追加・変更するたびにルーティングテーブルの更新が必要
• スケーラビリティ: スキル数が増えると Instructions ファイルが肥大化
• 本来の設計思想から外れる: Progressive Disclosure の恩恵を受けられない

結論: 確実に発火させたい重要なスキル（3〜5個程度）に限定して使うのがおすすめです。

当初の検証（2月）ではこの Instructions ルーティングが「力技」として最も頼れる手段でした。しかし、description を単一行で正しく書けば、多くのケースで Instructions ルーティングなしでも発火します。まずは解決策①を試して、それでも不安定な場合にこの方法を検討してください。

検証結果：4スキルで発火確認

実際に Claude Code から移植した4つのスキルで検証しました。

検証に使用したスキルの概要:

移植チェックリスト

Claude Code Skills → GitHub Copilot への移植手順をまとめました。

- [ ] `.claude/skills/` → `.github/skills/` にコピー
- [ ] description を単一行に変換（複数行記法 `|` は使わない）★重要
- [ ] description に `Use when` / `Triggers on` を追加
- [ ] ユーザー発話を日本語・英語で列挙
- [ ] `allowed-tools` を削除（Copilot では実験的機能）
- [ ] SKILL.md を 500トークン以下（約60行目安）に削減
- [ ] `copilot-instructions.md` にルーティングテーブル追加（重要スキルのみ）
- [ ] VS Code リロード後、5〜10分待機（Copilot のキャッシュ更新に時間がかかるため）
- [ ] 発火テスト

このチェックリストに従えば、Claude Code で作ったスキルを GitHub Copilot でも活用できます。

まとめ

Agent Skills が発火しない問題と解決策を整理しました。

自分が最初に詰まったのはまさにこの description の書き方でした。「メカニズムが違うから仕方ない」と思い込んで Instructions ルーティングで力技していたんですが、単一行に直したらあっさり動いた。原因がわかってしまえばシンプルなんですよね。

発火しない場合は、まず description が単一行で書かれているか を確認してください。これだけで解決するケースがほとんどです。

Claude Code ユーザーが GitHub Copilot に移行する場合、スラッシュコマンドでの呼び出しなら description の書き方に関係なく動作します。自動発火が必要ない場合は、そのまま移植するだけでOKです。自動発火も活用したい場合は、description を単一行で書いて、Use when / Triggers on を充実させてみてください。

参考リンク

公式ドキュメント

• VS Code Docs – Agent Skills
• GitHub Docs – About Agent Skills
• GitHub Changelog – Agent Skills リリース
• Agent Skills 仕様 – agentskills.io

公式リポジトリ・Issue

• github/awesome-copilot – ベストプラクティス
• Microsoft GitHub-Copilot-for-Azure – Agent Skills 実装例
• Issue #12971 – YAML | 記法の description が正しくパースされない問題
• Issue #11322 – Prettier フォーマットの複数行 description が失敗する問題

関連記事

• GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術
• Claude Code→GitHub Copilot移行で使える設定ファイル6つの対応表
• 【2026年版】Agent Skills 入門：SKILL.md の基本から実践まで
• VS Code で Claude Code の SKILL.md にエラーが出る原因と対処法

ここまで読んでいただき、ありがとうございました！

Agent Skills の発火で詰まっている方は、まず description を単一行にしてみてください。Claude Code から移行する方は移植チェックリストも活用してもらえれば。