VS Codeのprompt fileをskillへ移行する方法｜公式Migrate Promptsの使い方

VS Codeで作成した既存のprompt fileを、Copilot CLIやagent host上のハーネスでも再利用したいものの、「.prompt.mdをSKILL.mdへ書き換えればよいのか」「どの設定を有効にすべきか」と迷う人も多いでしょう。

結論として、既存prompt fileからskillへの移行には、VS CodeのAI Customizations overviewに追加された「Migrate Prompts」アクションを使用します。単に拡張子やYAMLフロントマターを手作業で変更するのではなく、VS Codeが用意したmigration actionから変換するのが、公式リリースノートで示された移行経路です。 (Visual Studio Code)

この機能は、2026年7月に公開されたVS Code 1.127～1.131の更新内容として紹介され、詳細にはVS Code 1.129で実験的機能として追加されました。利用時には設定の有効化とagent host上のハーネス選択が必要です。 (code.visualstudio.com)

VS Codeの既存prompt fileをagent skillへ変換する方法

移行前に確認する条件

「Migrate Prompts」が常に表示されるわけではありません。次の条件を確認してから作業します。

確認項目	必要な状態
VS Codeのバージョン	1.129以降
移行機能	chat.customizations.promptMigration.enabledが有効
エージェント	agent host上で動作するハーネスを選択
prompt file	移行可能な*.prompt.mdが存在する
ワークスペース側の保存場所	通常は.github/prompts/
バックアップ	Gitへのコミット、またはファイルのコピーを作成

VS Code 1.129のリリースノートでは、移行機能を有効にし、agent host上のハーネスを選択した状態で、移行可能なprompt fileがある場合に「Migrate Prompts」が表示されると説明されています。 (code.visualstudio.com)

特に重要なのがバックアップです。VS Code公式リポジトリの1.129向けテスト計画では、移行完了後に元のprompt fileが削除される動作が確認項目に含まれています。ワークスペース内のファイルは事前にGitへコミットし、ユーザープロファイル側のprompt fileは別途コピーしておくと安全です。 (GitHub)

VS Codeを1.129以降へ更新する

VS Codeのメニューから更新を確認し、1.129以降へアップデートします。

VS Code 1.127や1.128では、2026年7月の更新シリーズには含まれていても、prompt fileのmigration actionはまだリリースノートに登場していません。具体的な「Migrate prompt files to skills」は、2026年7月15日公開のVS Code 1.129で追加されています。 (Visual Studio Code)

migration actionを有効にする

VS Codeの設定画面で、次の設定を検索して有効にします。

{
  "chat.customizations.promptMigration.enabled": true
}

agent host自体をまだ利用していない環境では、次の設定も確認します。

{
  "chat.agentHost.enabled": true,
  "chat.customizations.promptMigration.enabled": true
}

組織管理されたVS Codeでは、これらの設定が管理者ポリシーによって固定されている場合があります。設定を変更できない場合は、個人側で回避しようとせず、GitHub CopilotまたはVS Codeの管理者に確認してください。 (code.visualstudio.com)

agent host上のハーネスを選択する

チャットまたはAgents windowで、agent host上で動作するハーネスを選択します。

VS Code 1.129のテスト計画では、Copilotのagent-host harnessを有効にした状態でAI Customizationsを開く手順が使われています。ローカル側のハーネスを選択したままだと、移行対象が存在していても「Migrate Prompts」が表示されない可能性があります。 (GitHub)

AI Customizations overviewを開く

AI Customizations overviewは、次のいずれかの方法で開けます。

1. コマンドパレットを開く
2. Chat: Open Customizationsを実行する
3. またはChat view上部の歯車アイコンからカスタマイズ画面を開く

WindowsとLinuxではCtrl+Shift+P、macOSではShift+Command+Pからコマンドパレットを開けます。Agent Customizations editorでは、prompt files、skills、custom agents、instructionsなどを一元管理できます。 (Visual Studio Code)

「Migrate Prompts」を開く

条件を満たしている場合、AI Customizations overviewに「Migrate Prompts」の項目または移行カードが表示されます。

移行画面では、prompt fileが次のように整理されます。

• WorkspaceとUserのグループ別表示
• ファイル単位の選択
• グループ単位での一括選択
• ファイル名の検索
• 移行対象数の確認
• prompt fileの内容確認

すべてを一度に変換する必要はありません。まず代表的なprompt fileを1つだけ選択し、変換結果と実行結果を確認してから残りを移行する方法が安全です。移行画面のグループ表示や選択機能は、VS Code公式のテスト計画でも確認されています。 (GitHub)

選択したprompt fileをskillへ移行する

対象を選択して移行ボタンを押すと、確認ダイアログが表示されます。内容を確認して実行してください。

公式テスト計画では、移行後に次の処理が行われます。

1. 選択したprompt fileをskillへ変換
2. 元のprompt fileを削除
3. AI CustomizationsのSkillsセクションへ移動
4. 新しく作成されたskillを選択状態で表示

元ファイルが削除されるため、移行ボタンを押す前に、Gitの作業ツリーがクリーンであることを確認しておくと差分を追いやすくなります。 (GitHub)

migration actionで変換される内容

VS Code公式リポジトリのテスト計画では、prompt fileから作成されるskillについて、次の変換内容が示されています。

prompt file側	skill側
name	skillのnameとして引き継ぐ
nameがない場合	prompt file名を使用
description	descriptionとして引き継ぐ
argument-hint	argument-hintとして引き継ぐ
Markdown本文	SKILL.mdの本文として引き継ぐ
手動呼び出し	disable-model-invocation: trueを設定
元の*.prompt.md	移行完了後に削除

変換後のSKILL.mdは、概念的には次のような構成になります。

---
name: api-security-review
description: REST APIのセキュリティレビューを実行する
argument-hint: "[レビュー対象のパス]"
disable-model-invocation: true
---

対象となるREST APIを確認し、認証、認可、入力検証、
レート制限、ログ記録の観点から問題点を整理してください。

disable-model-invocation: trueが追加されることで、移行直後のskillはAIによって自動選択されず、従来のprompt fileと同じようにスラッシュコマンドから手動実行する形になります。これはprompt fileの呼び出し方を維持するための重要な変換です。 (GitHub)

prompt fileとagent skillの違い

prompt fileとskillは、どちらも繰り返し使う指示を保存できます。しかし、ファイル形式と想定される利用範囲が異なります。

比較項目	prompt file	agent skill
基本構成	1つの*.prompt.md	フォルダーとSKILL.md
主な用途	手動実行する再利用可能なプロンプト	再利用可能な能力や作業手順
呼び出し	主にスラッシュコマンド	スラッシュコマンドまたは自動選択
追加ファイル	外部ファイルをリンク可能	スクリプト、例、テンプレートなどを同梱可能
利用範囲	VS Codeのprompt file対応環境	VS Code、Copilot CLI、Copilot cloud agentなど
読み込み	ユーザーが明示的に実行	関連するタスクで段階的に読み込み可能
標準	VS Codeのカスタマイズ形式	複数エージェントで利用できるオープン標準

prompt fileは、チャットで手動実行する独立したMarkdownファイルです。一方、skillはSKILL.mdを中心とするフォルダーであり、手順だけでなくスクリプトやテンプレート、実行例などもまとめられます。 (Visual Studio Code)

プロジェクト用skillは.github/skills/、.claude/skills/、.agents/skills/などに保存できます。ユーザー用skillには~/.copilot/skills/、~/.claude/skills/、~/.agents/skills/などの対応場所があります。実際の移行先は、変換後にVS Codeが開くSKILL.mdのパスで確認してください。 (Visual Studio Code)

手作業で形式変換しないほうがよい理由

.prompt.mdの内容をコピーし、.github/skills/にSKILL.mdを作ること自体は可能です。しかし、それだけでは正式なmigration actionと同じ結果になるとは限りません。

prompt fileとskillではフロントマターが異なる

prompt fileでは、次のような項目を指定できます。

agent:
model:
tools:
name:
description:
argument-hint:

一方、skillでは次のような項目が定義されています。

name:
description:
argument-hint:
user-invocable:
disable-model-invocation:
context:

両者の項目は一致していません。特にprompt fileでagent、model、toolsを指定している場合、単純なコピーでは同じ実行条件を再現できない可能性があります。公式の移行テスト計画で明示されている引き継ぎ対象は、name、description、argument-hint、本文です。そのため、agent、model、toolsを利用しているprompt fileは、移行後に動作を個別確認する必要があります。 (Visual Studio Code)

手動変換では自動実行の挙動が変わる可能性がある

skillでは、disable-model-invocationを省略すると、スラッシュコマンドとして実行できるだけでなく、タスク内容に応じてAIが自動的に読み込む対象になります。

prompt fileは原則として手動実行するため、手作業でskillを作ってこの設定を入れ忘れると、意図していない会話でもskillが選択される可能性があります。公式のmigration actionではdisable-model-invocation: trueを追加し、手動呼び出しの動作を維持します。 (Visual Studio Code)

skill名には厳しい制約がある

skillのnameには、次の制約があります。

• 小文字の英字、数字、ハイフンのみ使用可能
• 親フォルダー名と一致させる
• 最大64文字
• スラッシュ、コロン、ピリオドなどは使用不可

無効な名前はskillが読み込まれない原因になります。公式ドキュメントでは、名前が不正な場合にskillが通知なしで読み込まれなくなる可能性も示されています。移行後は、生成されたフォルダー名とnameが一致していることを確認してください。 (Visual Studio Code)

移行後に確認すべきポイント

相対リンクの参照先を確認する

prompt fileでは、Markdownリンクの相対パスがprompt fileの保存場所を基準に解決されます。skillでも相対リンクを利用できますが、基準となる場所はskillのディレクトリです。 (Visual Studio Code)

たとえば、移行前が次の場所だったとします。

.github/prompts/review.prompt.md

移行後は、次のような階層になる可能性があります。

.github/skills/review/SKILL.md

ファイルの階層が変わるため、本文に次のような相対リンクがある場合は注意が必要です。

[レビュー基準](../docs/review-guideline.md)

公式のテスト計画では本文の引き継ぎが確認されていますが、すべての相対リンクを新しい位置に合わせて書き換えることまでは明記されていません。移行後にリンクを開き、目的のファイルを参照できるか確認してください。 (GitHub)

スラッシュコマンドとして実行する

チャット入力欄で/を入力し、移行したskillが表示されるか確認します。

次に、従来と同じ引数を付けて実行します。

/api-security-review src/api

skillはprompt fileと同様にスラッシュコマンドとして表示できます。移行によってdisable-model-invocation: trueが設定されていれば、AIによる自動読み込みは無効になり、明示的に選択したときだけ実行されます。 (Visual Studio Code)

入力変数やツール参照を確認する

prompt file内で次のような構文を使用していた場合は、実際に値を渡して確認します。

${input:targetPath}
${selection}
#tool:browser

prompt fileの公式ドキュメントでは、入力変数、選択範囲、ツール参照などが利用できます。ただし、skillへの移行後もすべての実行条件が完全に同一になるとは限りません。特にツールやモデルをprompt fileのフロントマターで固定していた場合は、期待するツールが利用できているかを確認してください。 (Visual Studio Code)

Gitの差分を確認する

ワークスペース側のprompt fileを移行した場合は、次の差分を確認します。

git status
git diff

確認するポイントは次のとおりです。

• 元の*.prompt.mdだけが削除されているか
• 新しいskillディレクトリが追加されているか
• SKILL.mdの本文が欠けていないか
• nameとディレクトリ名が一致しているか
• disable-model-invocation: trueが設定されているか
• 相対リンクが正しいか
• 秘密情報や個人用パスが追加されていないか

問題があれば、移行結果をコミットする前に修正します。元に戻したい場合は、Gitからprompt fileを復元して原因を確認できます。

「Migrate Prompts」が表示されない場合の確認方法

原因	確認・対処方法
VS Codeが古い	1.129以降へ更新する
migration actionが無効	chat.customizations.promptMigration.enabledを有効にする
agent hostが無効	chat.agentHost.enabledを確認する
ローカル側のハーネスを選択している	agent host上のハーネスへ切り替える
prompt fileが存在しない	.github/prompts/*.prompt.mdなどを確認する
ユーザー用ファイルだけ存在する	AI CustomizationsでUserグループを確認する
組織設定で無効化されている	CopilotまたはVS Codeの管理者へ確認する
リポジトリの一部だけを開いている	親リポジトリからのcustomization検出を確認する

モノレポでサブディレクトリだけをワークスペースとして開いている場合、リポジトリルートの.github/prompts/が検出されないことがあります。その場合は、次の設定を検討します。

{
  "chat.useCustomizationsInParentRepositories": true
}

この設定を有効にすると、VS Codeは親リポジトリにあるprompt filesやskillsなどのカスタマイズを検出できます。ただし、親リポジトリが信頼済みであることなど、適用条件があります。 (Visual Studio Code)

prompt fileは廃止されるのか

今回の更新は、prompt fileの即時廃止を告知するものではありません。

VS Codeの現行ドキュメントでは、prompt fileの作成方法や実行方法が引き続き説明されており、チャットのスラッシュコマンド一覧にはprompt filesとskillsの両方が表示されます。したがって、少なくとも今回の公式情報からは、prompt fileが直ちに利用できなくなるとは読み取れません。 (Visual Studio Code)

一方、VS Code 1.129のリリースノートでは、prompt filesはLocal agent harnessで利用され、ほかのハーネスではskillsによってスラッシュコマンドを表現すると説明されています。複数のハーネス、Copilot CLI、cloud agentなどで同じカスタマイズを再利用したい場合は、skillへの移行が推奨されます。 (Visual Studio Code)

実務では、すべてを一括変換するよりも、次の順序で進めると安全です。

1. Gitでprompt filesをバックアップする
2. 利用頻度の高い1ファイルを移行する
3. スラッシュコマンド、引数、リンク、ツールを確認する
4. チームメンバーの環境でもテストする
5. 問題がなければ残りを段階的に移行する
6. 移行結果をGitへコミットする

VS Codeのprompt file移行は公式アクションから実行する

VS Codeの既存prompt fileを再利用可能なskillへ移行するときは、AI Customizations overviewの「Migrate Prompts」を使用します。

重要なポイントは次のとおりです。

• migration actionはVS Code 1.129で実験的機能として追加された
• chat.customizations.promptMigration.enabledを有効にする
• agent host上のハーネスを選択する
• WorkspaceとUserのprompt filesを選択して移行できる
• 移行後は元のprompt fileが削除されるため、事前バックアップが必要
• disable-model-invocation: trueによって手動呼び出しが維持される
• agent、model、tools、相対リンクは移行後に個別確認する
• 単なるファイル名変更や手作業のコピーを正式な移行手順と考えない

まずVS Codeを1.129以降へ更新し、代表的なprompt fileを1つだけmigration actionで変換してください。生成されたSKILL.mdと実行結果を確認してから、残りのファイルを段階的に移行するのが確実です。