Skip to main content

KTDEVX

VS CodeでAgent Skillsを作成して使う方法

/ja/blog/agent-skills-in-vs-code/ map[email:ktdevx@gmail.com name:Kaito Takemura]
Table of Contents

Agent Skillsは、GitHub CopilotなどのAIエージェントに、特定の作業を進める手順や判断基準を追加する仕組みです。単なる質問への回答ではなく、調査、編集、テストなどのまとまった作業方法を再利用できるようにします。

この記事では、VS Codeでプロジェクト用のAgent Skillを作成し、実際のチャットで呼び出すまでをハンズオン形式で説明します。作成するスキルは、リリースノートの下書きを作るためのrelease-notesです。

# 前提条件

次のものを準備します。

  • GitHub CopilotのChatやAgent機能を利用できるVS Code
  • GitHub Copilotを利用できるGitHubアカウント
  • スキルを追加できるGitリポジトリ

画面の項目名や利用できるモデルは、バージョンや契約によって異なる場合があります。

# Agent Skillsとは

Agent Skillsは、複数のAIエージェントで利用できるオープン標準です。Agent SkillはAIエージェントが必要なときに読み込む専門的な作業手順で、この記事ではGitHub CopilotのVS Code拡張機能から利用します。プロジェクトに保存する場合、代表的な配置は次のとおりです。

.github/skills/<skill-name>/SKILL.md

SKILL.mdのYAML front matterには、少なくとも次の2項目を記述します。

  • name: スキルの識別名。小文字、数字、ハイフンだけを使い、親ディレクトリ名と一致させる
  • description: 何ができ、どのような依頼で使うかを説明する文章

本文には、スキルを使うときの手順、守る条件、確認方法などを書きます。必要であれば、同じディレクトリにスクリプト、サンプル、参考資料を追加できます。

カスタム指示との違いは、主に使われる範囲です。カスタム指示はプロジェクトのコーディング規約などを継続的に伝えるのに向いています。一方、Agent Skillsはテスト、デバッグ、デプロイなど特定の作業で必要な手順を必要なときに読み込ませるのに向いています。

# ハンズオンの準備

練習用のGitリポジトリをVS Codeで開きます。既存のリポジトリを使う場合は、変更前の状態をコミットしておくと、生成された変更を確認しやすくなります。

プロジェクトのルートで、次のディレクトリを作成します。

.github/
└── skills/
    └── release-notes/
        └── SKILL.md

VS Codeのエクスプローラーで作成しても、ターミナルで次のコマンドを実行しても構いません。

New-Item -ItemType Directory -Force .github\skills\release-notes
New-Item -ItemType File -Force .github\skills\release-notes\SKILL.md

# スキルを書く

SKILL.mdを開き、次の内容を貼り付けます。

---
name: release-notes
description: 現在のGitリポジトリの変更からリリースノートの下書きを作成します。リリース概要、変更履歴、プルリクエスト用のリリースノートを作成するときに使用します。
---

# リリースノート

現在のリポジトリの変更から、簡潔なリリースノートの下書きを作成します。

## 手順

1. 現在のブランチと、デフォルトブランチとの差分を確認します。
2. 関連するコミットメッセージと変更ファイルを確認します。下書きに秘密情報や機密情報の完全な値を含めないでください。
3. 変更を追加、変更、修正、削除に分類します。該当しない分類は省略します。
4. 変更による影響を理解する必要があるユーザー向けに、各項目を記述します。
5. 比較対象のブランチやリリースの範囲が不明確な場合は、確認の質問をします。
6. ユーザーからファイル変更を明示的に依頼されない限り、プロジェクトのファイルを編集しません。

## 出力形式

次のセクションを出力します。

- 1文の概要
- Markdown形式のリリースノートの下書き
- 確認したファイルまたはコミットの簡単な一覧
- 未解決の質問と確認事項

下書きは事実に基づく内容にします。 issue番号、性能測定結果、互換性に関する主張、破壊的変更を推測で追加しないでください。

descriptionには機能だけでなく、どのような依頼で使うかも書くことが重要です。説明が曖昧だと、関連する依頼で自動的に選ばれにくくなります。本文には、作業の順序と出力形式を記述します。

また、スキルには「しないこと」も書けます。例では、ユーザーの明示的な依頼なしにファイルを編集しないよう指定しています。AIエージェントにコマンド実行や編集を任せるスキルでは、対象範囲、確認手順、秘密情報の扱いも具体的に書きます。

# スキルを認識させる

SKILL.mdを保存したら、Chatビューを開きます。入力欄で/を入力すると、利用できるスキルの一覧にrelease-notesが表示されるはずです。

表示されない場合は、次を確認します。

  1. VS Codeでリポジトリのルートフォルダーを開いているか確認する。
  2. ファイル名が正確にSKILL.mdになっているか確認する。
  3. name: release-notesとディレクトリ名release-notesが一致しているか確認する。
  4. nameに大文字、スラッシュ、コロン、ドットなどを使っていないか確認する。
  5. front matterの開始と終了に---があるか確認する。
  6. Chatビューを一度閉じて開き直し、スキル一覧を更新する。

Agent Skillsは、依頼との関連性に応じて自動的に読み込まれることがあります。確実に使いたい場合は、チャットで/release-notesを選択して明示的に呼び出します。

# スキルを実行する

変更のあるリポジトリで、Chatに次のように入力します。

/release-notes 現在のブランチの変更から、次回リリース用の下書きを作成してください。

回答では、変更されたファイルやコミットを調べたうえで、指定した形式の下書きが返されます。内容を確認するときは、次の点を見ます。

  • 実際の差分に存在しない機能が追加されていないか
  • Added、Changed、Fixed、Removedの分類が適切か
  • 破壊的変更や互換性について根拠のない記述がないか
  • 秘密情報や個人情報が出力に含まれていないか
  • 確認が必要な項目が明示されているか

/release-notesを使わず、次のような依頼だけを送って自動選択されるか試すこともできます。

次回リリースの変更点を、ユーザー向けのリリースノートにまとめてください。

自動選択されなかった場合は、descriptionをより具体的に書き直すか、スラッシュコマンドで明示的に呼び出します。スキルの本文を更新したときは、チャットを新しく開始して再度確認します。

# 追加ファイルを使う

作業手順が長くなる場合は、SKILL.mdにすべてを書き込まず、スキルのディレクトリに資料を分けます。

.github/skills/release-notes/
├── SKILL.md
├── examples/
│   └── release-notes.md
└── templates/
    └── changelog.md

追加ファイルは、SKILL.mdから相対リンクで参照します。

テンプレートは[CHANGELOGの例](./templates/changelog.md)を参照してください。

参照先を本文に書いておくと、エージェントが必要になったときに資料を読み込めます。スクリプトを含める場合は、内容をレビューし、入力値の検証、ネットワーク通信、ファイル削除などの動作を確認してから使ってください。

# Agent Skillsを設計するときの注意点

## 目的を一つに絞る

一つのスキルに、テスト、デプロイ、リリースノート作成をすべて詰め込むと、適用条件と手順が曖昧になります。作業の目的が異なる場合は、スキルを分けて必要なものだけを組み合わせます。

## 手順と完了条件を書く

「適切に確認する」のような表現だけでは判断できません。実行するコマンド、見るべきファイル、出力の形式、失敗時の対応を具体的に記述します。

## 権限を広げすぎない

Agent Skillsは手順を伝える仕組みですが、エージェントがコマンドを実行したり、ファイルを変更したりする場合があります。削除、外部サービスへの送信、デプロイなどを含む場合は、対象と確認ポイントを明記し、実行前に差分やコマンドを確認します。

## 秘密情報を含めない

APIキー、パスワード、アクセストークン、顧客情報をSKILL.mdやサンプルに書かないでください。リポジトリにコミットするファイルなので、公開範囲とアクセス権も確認します。

# まとめ

Agent Skillsを使うと、特定の作業に必要な手順、判断基準、出力形式をプロジェクトに保存し、必要なときにGitHub Copilotへ読み込ませられます。

基本の作成手順は、.github/skills/<skill-name>/SKILL.mdを作り、nameとdescriptionを設定し、本文に具体的な手順を書くことです。まずは今回のrelease-notesのように、目的と完了条件が明確な小さなスキルから始め、実際の依頼で結果を確認しながら改善してください。

詳しい仕様は、VS CodeのAgent SkillsとAgent Skills仕様を参照してください。

Read next