【30分で理解する】GitHub CopilotのAgent Skills

はじめに

GitHub Copilotを使っていて、こんなことを思ったことはないでしょうか。

「毎回同じこと説明するの、だるいな」
「テストの書き方、プロジェクトごとに違うんだけど、覚えてくれないかな」
「このリポジトリ特有のルール、何回言えばわかるんだ」

わかります。自分もそうでした。

Copilotは確かに賢いんですが、あくまで「汎用的に賢い」んですよね。自分たちのプロジェクトの事情なんて知らないし、毎回ゼロからやり直しになる。カスタムインストラクション（copilot-instructions.md）を書いてみても、全部のタスクに毎回読み込まれるので、情報量が増えると逆にノイズになってしまう。

そこで登場したのが Agent Skills です。

この記事では、Agent Skillsの基本的な考え方から、実際にスキルを作って動かすところまでを一通り解説します。前提知識はVS CodeでGitHub Copilotを使ったことがある程度で大丈夫です。

この記事の対象読者

• GitHub Copilotを普段使っているけど、Agent Skillsはまだ触っていない人
• copilot-instructions.md は書いたことがあるけど、もう少し踏み込んだカスタマイズがしたい人
• Agent Skillsって聞いたことはあるけど、結局何なのかよくわからない人

Agent Skillsってなに？

ひとことで言うと、「Copilotに特定のタスクの"やり方"を教えるための仕組み」 です。

もう少しかみ砕くと、こういうイメージです。

普通のCopilot → 「何でもそこそこできる新人エンジニア」
Agent Skillsを入れたCopilot → 「プロジェクトの手順書を読み込んだ、即戦力のエンジニア」

技術的には、SKILL.mdというMarkdownファイルと、必要に応じてスクリプトやリソースをフォルダにまとめたものです。Copilotがタスクの内容を見て「あ、このスキル使えそうだな」と判断したら、自動的にそのSKILL.mdを読み込んで、書かれた手順に従って動いてくれます。

Custom Instructionsとの違い

ここ、最初に混乱しやすいポイントなので整理しておきます。

Custom Instructions（copilot-instructions.md）

• 毎回のチャットで常にシステムプロンプトに読み込まれる
• 「このリポジトリではTypeScriptを使う」「変数名はキャメルケース」みたいな、常に適用したいルールを書く場所
• 情報量が増えるとコンテキストを圧迫する

Agent Skills

• 必要なときだけ動的に読み込まれる（Progressive Disclosure）
• 「テストを書くときはこの手順で」「デプロイはこのフローで」みたいな、特定タスクに特化した手順書
• スクリプトやテンプレートも一緒に持てる

イメージとしては、Custom Instructionsが「社員証の裏に書いてある会社の行動指針」だとしたら、Agent Skillsは「特定の業務のマニュアル本」みたいな感じです。全部のマニュアルを常にポケットに入れておくのは無理だけど、必要なときに棚から取り出して読めばいい。Agent Skillsはそれを自動でやってくれる、という話です。

Agent Skillsが動く仕組み

内部的にどう動いているか、ざっくり知っておくと理解が深まります。

1. 起動時：メタデータだけ読み込む

Copilotが起動すると、リポジトリ内のスキルフォルダを探して、各スキルのnameとdescriptionだけをシステムプロンプトに載せます。この時点ではSKILL.mdの本文はまだ読み込みません。メタデータだけなので、1スキルあたり50〜100トークン程度で済みます。

2. ユーザーがタスクを依頼する

「テスト書いて」「デプロイ手順を教えて」みたいなプロンプトを投げると、Copilotは手元にあるスキルのdescriptionを見て「このスキルが関係しそうだ」と判断します。

3. 関連するスキルのSKILL.mdを全文読み込む

ここではじめて、SKILL.mdの本文がコンテキストに展開されます。スクリプトの参照やテンプレートの使用指示なども、この段階でCopilotに渡ります。

4. 手順に従って実行する

あとはCopilotがSKILL.mdに書かれた手順通りに作業を進めてくれます。

この「必要なときだけ読み込む」仕組みが、Agent Skillsの最大の特徴です。公式ドキュメントでは「Progressive Disclosure（段階的開示）」と呼ばれています。コンテキストウィンドウは有限なので、使わない情報で埋め尽くすのはもったいない。そこを最適化してくれるわけです。

前提条件

Agent Skillsを使うには、以下が必要です。

• GitHub Copilotの有料プラン（Pro / Pro+ / Business / Enterprise）
• VS Code（安定版でもOK。以前はInsidersのみでしたが、現在は安定版でもサポートされています）
• VS Codeの設定で chat.useAgentSkills を true にしておくこと

settings.jsonに追加する設定はこれだけです。

{
  "chat.useAgentSkills": true
}

スキルの作り方：実践編

ここからは実際に手を動かしていきます。

ディレクトリ構成

スキルの配置場所は2種類あります。

# プロジェクトスキル（リポジトリ固有）
.github/skills/<スキル名>/SKILL.md

# パーソナルスキル（PC全体で共有）
~/.copilot/skills/<スキル名>/SKILL.md

プロジェクトスキルはリポジトリにコミットして、チーム全員で共有できます。パーソナルスキルは自分のマシンのホームディレクトリに置くので、どのリポジトリでも使えます。

まずはプロジェクトスキルから試してみましょう。

最小構成のスキルを作る

一番シンプルなスキルを作ってみます。やることは2つだけ。ディレクトリを作って、SKILL.mdを書く。

mkdir -p .github/skills/hello-skill

.github/skills/hello-skill/SKILL.md を作成します。

---
name: hello-skill
description: あいさつスキルのテスト。「こんにちは」「挨拶して」と言われたときに使う。
---

# あいさつスキル

ユーザーに挨拶を求められたら、以下のルールに従ってください。

1. 必ず「やあ！」で始める
2. 今日の日付を含める
3. 何か一つ、豆知識を添える

これだけです。VS Codeを再読み込み（またはCopilot Chatを開き直し）して、チャットで「こんにちは」と打ってみてください。Copilotがこのスキルを読み込んで、指示通りに応答してくれるはずです。

SKILL.mdの構造

SKILL.mdはYAMLフロントマターとMarkdown本文で構成されます。

---
name: スキル名（必須。小文字、ハイフン区切り）
description: |
  スキルの説明（必須）。
  いつ使うべきかを具体的に書く。
  ここがCopilotの判断材料になるので、手を抜かないこと。
license: MIT（任意）
---

# スキル本文

ここにCopilotへの具体的な指示を書く。

ポイント：descriptionの書き方が超重要

descriptionはCopilotが「このスキルを読み込むかどうか」を判断する唯一の材料です。ここが曖昧だと、使ってほしいときに使ってくれなかったり、関係ないときに読み込まれたりします。

悪い例：

description: テスト関連のスキル

良い例：

description: |
  ユニットテストの作成・修正を行うスキル。
  「テスト書いて」「テスト追加」「カバレッジ上げて」
  のようなリクエストで発火する。

「どんな言葉でユーザーが依頼してきたときに使うか」まで書いておくと、発火精度がぐっと上がります。

もう少し実践的なスキル

実際の開発で役立つスキルの例を見てみましょう。ユニットテスト作成スキルです。

ディレクトリ構成：

.github/skills/unit-testing/
├── SKILL.md
└── templates/
    └── test-template.ts

.github/skills/unit-testing/SKILL.md：

---
name: unit-testing
description: |
  ユニットテストを作成・修正するスキル。
  「テスト書いて」「テスト追加して」「カバレッジ上げて」
  「〇〇のテストが落ちてる」などで使用する。
---

# ユニットテスト作成ガイド

## テストファイルの配置

- テスト対象のファイルと同じディレクトリに配置する
- ファイル名は `<対象ファイル名>.test.ts` とする

## テストの書き方

1. [テンプレート](./templates/test-template.ts) を基本構造として使う
2. テストケース名は日本語で書く（例：「正常系：ユーザーが作成される」）
3. AAA パターン（Arrange / Act / Assert）を守る
4. モックは必要最小限にする

## 使用ライブラリ

- テストランナー：Vitest
- DOMテスト：@testing-library/react
- APIモック：MSW

## カバレッジの目安

- 新規コード：80%以上
- バグ修正時：該当箇所のテストを必ず追加

templates/test-template.ts：

import { describe, it, expect, beforeEach } from 'vitest';

describe('【テスト対象】', () => {
  beforeEach(() => {
    // セットアップ
  });

  describe('正常系', () => {
    it('【テストケース名】', () => {
      // Arrange
      // Act
      // Assert
      expect(true).toBe(true);
    });
  });

  describe('異常系', () => {
    it('【テストケース名】', () => {
      // Arrange
      // Act & Assert
      expect(() => {}).toThrow();
    });
  });
});

こうしておくと、「このファイルのテスト書いて」と頼むだけで、プロジェクトの規約に沿ったテストを生成してくれます。テンプレートも自動で参照してくれるので、毎回「AAAパターンで書いて」「Vitestで書いて」と言う必要がなくなります。

スクリプト付きのスキル

Agent Skillsのすごいところは、Markdownの指示だけじゃなくて、スクリプトも一緒に持てることです。

たとえば、画像変換スキル：

.github/skills/image-converter/
├── SKILL.md
└── scripts/
    └── convert.sh

SKILL.md内で「画像を変換するときは scripts/convert.sh を使え」と書いておけば、Copilotがターミナルツールを使ってスクリプトを実行してくれます。定型的な作業をスキルに閉じ込めておけるのは、地味にめちゃくちゃ便利です。

複数スキルの管理

スキルが増えてきたときの全体像はこんな感じになります。

.github/
├── skills/
│   ├── unit-testing/
│   │   ├── SKILL.md
│   │   └── templates/
│   │       └── test-template.ts
│   ├── code-review/
│   │   └── SKILL.md
│   ├── deploy-procedure/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── deploy-check.sh
│   └── architecture/
│       ├── SKILL.md
│       └── references/
│           └── directory-structure.md
└── copilot-instructions.md

copilot-instructions.mdとAgent Skillsの使い分けは、先ほど書いた通りです。

• 常に適用したいルール → copilot-instructions.md
• 特定のタスクの手順 → Agent Skills

両方使うのが一番効果的です。

VS Code上でスキルを確認する

スキルが正しく認識されているか確認する方法がいくつかあります。

• チャットで /skills と入力すると、スキルの一覧が表示される
• チャットで「今どのスキルが読み込まれていますか？」と聞く
• VS Code 1.108以降であれば、Chat Customizations エディタからも確認可能（コマンドパレットで Chat: Open Chat Customizations を実行）

また、VS Codeの chat.agentSkillsLocations 設定を使えば、.github/skills 以外のディレクトリにスキルを置くことも可能です。

{
  "chat.agentSkillsLocations": [
    ".github/skills",
    "./my-custom-skills"
  ]
}

コミュニティのスキルを使う

自分でゼロから書かなくても、すでに公開されているスキルを使うこともできます。

• github/awesome-copilot ── GitHubが運営するコミュニティリポジトリ。スキル、カスタムエージェント、インストラクションなどが集まっている
• anthropics/skills ── Anthropic公式のリファレンススキル集。PDF操作、フロントエンド設計、ドキュメント生成などの実用的なスキルが揃っている

使い方は簡単で、スキルフォルダをダウンロードして .github/skills/ に配置するだけです。ただし、他人が作ったスキルは中身を必ず確認してから使いましょう。スクリプトが含まれている場合は特に注意が必要です。

Agent Skillsは汎用ツール

一つ知っておいてほしいのが、Agent Skillsは特定のツールに閉じた仕様ではないということです。

もともとAnthropicがClaude Code向けに開発した仕組みですが、2025年12月にオープンスタンダードとして公開されました。仕様は agentskills.io で誰でも読めます。

現在、GitHub Copilot以外にも、Claude Code、OpenAI Codex、Cursor、Gemini CLIなど、多くのAIツールがこの仕様をサポートしています。つまり、一度作ったスキルは他のAIツールでもそのまま使い回せるということです。

MCP（Model Context Protocol）がAIの「ツール接続」を標準化したのに対して、Agent Skillsは「知識・手順の共有」を標準化した、という関係性です。

よくあるつまづきポイント

自分が実際に試してみて引っかかったポイントを共有します。

スキルが読み込まれない

descriptionが曖昧だと、Copilotが「このスキルは関係ない」と判断してスルーすることがあります。descriptionに「どんな言葉で依頼されたら使うか」を明示的に書くと改善することが多いです。あとは、VS Codeの再読み込みを忘れていたというパターンも。

Agent Modeで使う必要がある

Agent Skillsが動作するのはAgent Mode（エージェントモード）のときだけです。通常のAskモードやEditモードでは動きません。チャットパネルの上部でモードが「Agent」になっているか確認してください。

スキルが多すぎてメタデータだけでコンテキストを食う

スキルを何十個も作ると、起動時のメタデータ読み込みだけでそこそこのトークンを消費します。不要なスキルは消すか、パーソナルスキルとプロジェクトスキルを整理して、本当に必要なものだけ残すようにしましょう。

SKILL.mdが長すぎる

公式の推奨は本文5000トークン以内、500行以内です。それを超える場合は、詳細な情報をreferences/ディレクトリに分離して、SKILL.mdからはリンクで参照する形にしましょう。

/create-skill で楽にスキルを作る

実は、スキルを手書きしなくても、Copilot Chatで /create-skill と入力して、自然言語で説明するだけでスキルを自動生成してもらう方法もあります。

/create-skill Playwrightを使ったE2Eテストの作成を支援するスキル

こうすると、CopilotがSKILL.mdのひな形を生成してくれます。ゼロから書くのが面倒なときはこれで下書きを作って、あとから手直しするのがおすすめです。

また、チャットの中で複雑な問題を解決した後に「今の手順をスキルにして」と頼むと、その会話の内容をベースにスキルを作ってくれたりもします。

まとめ

Agent Skillsの要点を整理します。

• Agent Skillsは、Copilotに「特定タスクの手順書」を渡す仕組み
• SKILL.md + スクリプト + リソースをフォルダにまとめて .github/skills/ に配置する
• 必要なときだけ動的に読み込まれるので、コンテキストを無駄遣いしない
• Custom Instructionsが「常時適用のルール」なら、Agent Skillsは「タスク別のマニュアル」
• オープンスタンダードなので、GitHub Copilot以外のAIツールでもそのまま使える
• /create-skill で自動生成もできる

正直なところ、Agent Skills自体はそこまで複雑な仕組みではないです。SKILL.mdを書いて、所定の場所に置くだけ。でも、プロジェクトの知識やチームのノウハウをスキルとして整理しておくことで、Copilotの出力品質は目に見えて変わります。

まずはシンプルなスキルをひとつ作って、動かしてみてください。「あ、ちゃんと手順通りにやってくれるじゃん」という体験が得られるはずです。そこからプロジェクト固有の手順をスキル化していけば、Copilotが本当の意味で「チームの一員」になってくれると思います。

参考リンク

• GitHub公式ドキュメント - About agent skills
• VS Code公式ドキュメント - Agent Skills
• Agent Skills仕様 - agentskills.io
• github/awesome-copilot - コミュニティ製スキル集
• anthropics/skills - Anthropic公式スキル集