Copilotのプロンプトファイルをスキルに移そう：変換機能の使い方と書き直しのコツ

Posted at 2026-11-11

VS CodeのCopilotで、.github/prompts/ に置いたプロンプトファイルを / で呼び出して使っていないでしょうか。便利な機能ですが、VS Codeの公式ドキュメントでは、プロンプトファイルからエージェントスキル（Agent Skills）への移行がすすめられています。

この記事では、プロンプトファイルとスキルの違い、VS Codeに用意されている変換機能の使い方、そして変換したあとに見直したいところを紹介します。例として、私が公開している doc-to-markdown のプロンプトファイルを使います。

VS Codeとエージェント周りの機能は、更新がとても速い分野です。この記事は2026年10月時点の公式ドキュメントをもとに書いています。画面の項目名などは変わることがあるので、実際に作業するときは公式ドキュメントも確認してください。

何が起きているのか

VS Codeの公式ドキュメントには、プロンプトファイルについてこう書かれています。

Prompt files are deprecated for Agent Host sessions and aren't loaded by Agent Host. They continue to work with the Local agent for now, but the Local agent will be removed in a future release.

まとめると、次のとおりです。

Agent Host のセッションでは、プロンプトファイルは非推奨で、読み込まれない
今は Local agent では動くが、Local agent は将来のリリースで削除される予定
移行先は、エージェントスキル

つまり、今すぐ動かなくなるわけではありません。ただ、これから新しく作るならスキルで作り、今あるものも計画的に移していくのが安全です。

プロンプトファイルとスキルの違い

	プロンプトファイル	スキル
置き場所（ワークスペース）	`.github/prompts/〇〇.prompt.md`	`.github/skills/〇〇/SKILL.md`
呼び出し方	`/` + 名前	`/` + 名前（人が呼ぶ）、または関係する依頼のときにAIが自動で読み込む
形	1ファイル	フォルダ（テンプレートやスクリプトを一緒に置ける）
必須の項目	なし	`name` と `description`
使えるところ	主にVS Code	VS Code、GitHub Copilot CLI、Copilot coding agent など

一番大きな違いは、AIが自分で読み込めることです。プロンプトファイルは、人が / で呼ばない限り使われません。スキルは、description を見て「この依頼に関係がある」とAIが判断すれば、自動で中身を読み込みます。

もう一つは、フォルダごと持てることです。手順書と一緒に、テンプレートや補助スクリプトを同じフォルダに置けます。

ハーネスの記事で、Skillsを「棚に並んだ業務マニュアル」にたとえました。プロンプトファイルが「人が毎回手渡す指示書」だとすると、スキルは「AIが必要なときに自分で棚から取るマニュアル」です。

スキルは段階的に読み込まれる

スキルは、たくさん用意してもAIの負担になりにくい作りになっています。読み込みは3段階です。

見つける：まず name と description だけを読み、関係がありそうか判断する
手順を読む：関係があれば、SKILL.md の本文を読み込む
追加のファイルを読む：本文から参照されているファイルだけを、必要になったときに読む

最初に読むのは名前と説明だけなので、スキルが増えても、毎回の会話が重くなりにくいのです。

変換機能で移す

VS Codeには、プロンプトファイルをスキルに変換する機能があります。公式ドキュメントの手順は次のとおりです。

チャットビューで、スキルを使う Agent Host を選ぶ
歯車のアイコン（Configure Chat）から、Agent Customizations のエディタを開く
Overview タブの「Migrate Prompt Files」で、「Convert to Skills...」を選ぶ
変換するプロンプトファイルを選ぶ
「Convert to Skills」を押す
確認のダイアログで、元のプロンプトファイルを消すかどうかを選ぶ

最初は、元のプロンプトファイルを消さずに変換するのがおすすめです。変換結果を見比べて、問題がなければ消しましょう。Gitで管理していれば、消しても戻せます。

変換したあとに見直したい4つのこと

変換機能でファイルの形はそろいます。ただ、プロンプトファイルとスキルでは書き方の前提が違うので、中身は見直しておきましょう。ここでは、doc-to-markdown のプロンプトファイル /doc2md-investigate-loss（変換で内容が欠けたときに原因を調べる）を例にします。元のファイルはこうです（抜粋）。

---
description: 変換ロス（loss.* の警告）や「内容が足りない」原因を調べ、対処法を提案する
agent: agent
argument-hint: 対象ファイルのパス
---

次の文書の変換で欠けている内容がないか調べてください。

対象: ${input:path:対象ファイルのパス}

## 手順

1. 通常の変換: `doc2md "<対象>" -d out/normal -f json`
2. レイアウト優先の変換（Office 文書のみ。LibreOffice が必要）: `doc2md "<対象>" -d out/via-pdf --via-pdf -f json`
...

1. descriptionに「いつ使うか」を書く

スキルの description は、AIが「このスキルを使うべきか」を判断する材料です。公式ドキュメントでも「what the skill does and when to use it（何をするか、いつ使うか）」を書くよう説明されています。

プロンプトファイルの description は、人がメニューで見るための短い説明でした。スキルでは、AIが判断できるように、使う場面まで書きます。

description: >-
  doc2md で Office / PDF を Markdown に変換したときに、内容が欠けていないかを調べる。
  変換レポートに loss.* の警告が出たとき、または「変換結果に内容が足りない」と言われたときに使う。

「loss.* の警告が出たとき」のように、AIが気づけるきっかけを書いておくのがコツです。

2. `${input:...}` の変数を書き直す

プロンプトファイルでは、${input:path:対象ファイルのパス} のような変数で、呼び出すときに値を受け取れました。スキルの説明には、この変数の仕組みは出てきません。スキルを / で呼ぶときは、名前のあとに続けて書いた文章が、追加の指示として渡されます。

/doc2md-investigate-loss samples/expense-flow.pptx

そこで本文は、「呼び出したときに指定されたファイル」を前提にした書き方に直します。指定がなかったときにどうするかも書いておくと親切です。

対象のファイルは、呼び出したときに利用者が指定したパスです。
指定がなければ、どのファイルを調べるかを利用者に質問してください（推測で選ばない）。

AIが自動で読み込んだ場合は、会話の流れの中で対象のファイルが決まります。どちらの使われ方でも動くように書いておきましょう。

3. `agent` や `tools` の指定を確認する

プロンプトファイルでは、frontmatterの agent（ask / edit / agent など）や tools で、実行のしかたを指定できました。公式ドキュメントのスキルの項目一覧には、これらは出てきません。

コマンドの実行が必要な手順なら、エージェントとして動かすことが前提になります。変換後に、実際に / で呼び出して、コマンドを実行できるかを確かめましょう。

4. 呼び出し方を決める

スキルには、呼び出し方を決める2つの項目があります。

項目	意味	既定値
`user-invocable`	`/` のメニューに出すか	true（出す）
`disable-model-invocation`	AIが自動で読み込むのを止めるか	false（自動で読み込む）

使い分けの目安です。

調査や変換など、AIに自動で使ってほしいもの → 既定値のまま
ファイルの一括置換など、人が明示的に呼んだときだけ動かしたいもの → disable-model-invocation: true

取り返しのつかない操作をするスキルは、AIが勝手に読み込まないようにしておくと安心です。

書き直した例

4つを反映すると、こうなります（.github/skills/doc2md-investigate-loss/SKILL.md）。

---
name: doc2md-investigate-loss
description: >-
  doc2md で Office / PDF を Markdown に変換したときに、内容が欠けていないかを調べる。
  変換レポートに loss.* の警告が出たとき、または「変換結果に内容が足りない」と言われたときに使う。
argument-hint: 対象ファイルのパス
---

# 変換ロスの調査

対象のファイルは、呼び出したときに利用者が指定したパスです。
指定がなければ、どのファイルを調べるかを利用者に質問してください（推測で選ばない）。

## 手順

1. 通常の変換: `doc2md "<対象>" -d out/normal -f json`
2. レイアウト優先の変換（Office 文書のみ。LibreOffice が必要）: `doc2md "<対象>" -d out/via-pdf --via-pdf -f json`
   - LibreOffice が無いと言われたら手順 2 は飛ばし、`doc2md --check-env` の結果とインストール方法（無料）を伝える
3. 両方の JSON の `findings` と、`convert.ok` の `actual`（見出し・表・文字数の統計）を比べる
4. 2 つの Markdown を比べ、片方にしか無い段落・表・文字を具体的に挙げる（多くても 10 個まで）
5. 報告: 欠けている内容と原因の候補、どちらの変換結果を使うべきか、原本で目視確認すべき箇所

手順の本文は、元のプロンプトファイルとほぼ同じです。変わったのは、frontmatterと「対象をどう受け取るか」の部分だけです。

移す順番

プロンプトファイルがたくさんある場合は、次の順で移すと安全です。

一覧を作る。 リポジトリにあるプロンプトファイルを洗い出す
よく使うものを1つ選んで、変換機能で移す。 元のファイルは残しておく
見直す。 上の4つ（description、変数、agentとtools、呼び出し方）を確認する
試す。 / で呼び出して動くか、関係する依頼をしたときにAIが自動で読み込むかを確かめる
残りを移す。 1つ目で分かったコツを使って、残りも変換する
元のプロンプトファイルを消す。 READMEなどに / の使い方を書いていれば、そちらも直す

最後の手順は忘れがちです。READMEに「Copilot Chatで /〇〇 と入力」と書いている場合、スキルの名前と呼び出し方に合わせて更新しましょう。

よくある失敗

descriptionを短いままにする
プロンプトファイルの短い説明をそのまま使うと、AIがスキルを使う場面を判断できません。「何をするか」に加えて「いつ使うか」を書きましょう。

${input:...} が残ったままになる
変数がそのまま残ると、AIにはただの文字列として見えます。変換後に ${ で検索して、残っていないか確認しましょう。

危ない操作も自動で読み込まれる設定のままにする
ファイルを書き換えるスキルが、AIの判断で勝手に使われると困ります。人が呼んだときだけ動かしたいものは、disable-model-invocation: true にしておきます。

一度に全部を移して、どれが動かないか分からなくなる
まず1つ移して試し、コツをつかんでから残りに広げましょう。

まとめ

プロンプトファイルは、スキルへの移行がすすめられています。変換機能を使えば形はすぐにそろいますが、中身の見直しまでやって完成です。

descriptionに「いつ使うか」を書く
${input:...} を、指定された内容を受け取る書き方に直す
危ない操作は、人が呼んだときだけ動くようにする

スキルにしておけば、VS Code以外のエージェントでも使えるようになり、AIが必要なときに自分で読み込んでくれます。人が毎回渡していた指示書を、AIが自分で取り出せるマニュアルに変えていきましょう。

参考

この記事は Zenn にも投稿しています。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up