GitHub Copilot .prompt.md の変数を活用する

GitHub Copilot のよく使う指示（「READMEを作成して」など）をプロンプトファイルに保存しておくと、簡単に再利用できて便利です。久しぶりに使おうとしたら警告が出ていて、2025年末のアップデートで仕様が変わったようでした。これを機に改めて調べ直したので、基本の使い方から実際に役立つポイントまでまとめておきたいと思います。

.prompt.md 基本の作り方

拡張子を .prompt.md にしてマークダウンファイルを作るだけです。ヘッダー部分は YAML のルール（frontmatter）がありますが、本文（body）に厳密なルールはありません。拡張子が正しく認識されていれば、エディタに実行ボタンが表示されて実行できます。

---
description: '選択ファイルの修正'
name: 'demo-copyedit-input'
argument-hint: '修正対象のファイルを指定してください。'
agent: 'agent'
---

## Role
日本語文章のプロの編集者として、下記タスクを実施してください。

## Task
- 対象のファイルを修正してください。
 - 対象が指定されていない場合は、ユーザーに編集対象のファイル名を尋ねてください。
- 対応する内容
 - 誤字脱字
 - 文法の誤り
 - 表記ゆれ
- 対応しない内容
  - トーン、スタイルの変更

## 対象のファイル
${input:filename:ファイルを指定してね}

エディタで開くと実行ボタンが表示され、クリックするとチャットに展開されます。

Running GitHub Copilot Prompts

frontmatter の書き方

frontmatter でよく使うフィールドは以下の通りです。

  • description: プロンプトの説明
  • name: 呼び出し時の識別名
  • argument-hint: 引数のヒント（ユーザーに説明を表示）
  • agent: エージェント処理を使う場合に指定
  • model: モデルを固定する場合（通常は未指定で OK）
  • tools: 使用するツール名（githubRepo, github など）

本文で使える変数一覧

本体のマークダウンには厳密なルールがありません。awesome-copilot の投稿や VS Code 開発者が使っている記述を見ると、Role と Task の記述は定番ですね。通常のプロンプトと同じ書き方です。

ドキュメントにはいくつかの変数の記載がありますが、VS Code のソースコードを見たところ、ドキュメント以外にもいくつか変数がありました。以下に整理します。

ワークスペース

  • ${workspaceFolder}: 現在のワークスペースフォルダーの絶対パス
  • ${workspaceFolderBasename}: フォルダー名のみ
  • ${workspaceFolderIndex}: マルチルート時の 1 始まりインデックス
  • ${workspaceFolder:<name>}: 名前でフォルダー指定

ファイル文脈（アクティブエディタ）

  • ${file}: アクティブファイルの絶対パス
  • ${fileBasename}: ファイル名（拡張子付き）
  • ${fileBasenameNoExtension}: ファイル名（拡張子なし）
  • ${fileExtname}: 拡張子（ドット込み）
  • ${fileDirname}: 親ディレクトリ
  • ${fileWorkspaceFolder}: そのファイルを含むワークスペースフォルダーのパス
  • ${fileWorkspaceFolderBasename}: そのフォルダー名
  • ${relativeFile}: ワークスペース基準の相対パス
  • ${relativeFileDirname}: 同上ディレクトリ部分

選択 & カーソル

  • ${selection}: 現在の選択範囲。未選択なら空（自動拡張なし）
  • ${selectedText}: ${selection} と同じソース。空白も含めてそのままほしい場合は ${selection} を推奨
  • ${lineNumber}: カーソル（選択開始位置）の 1 始まり行番号

入力 & ユーザー値

  • ${input:var}: 実行時に入力必須
  • ${input:var:placeholder}: プレースホルダー付き。空のままでも空文字として進行

環境 & 設定

  • ${env:NAME}: 環境変数 NAME
  • ${config:section.setting}: VS Code の設定値
  • ${command:commandId}: コマンド実行結果（文字列）
  • ${userHome}: ホームディレクトリ
  • ${cwd}: 変数解決時のカレントディレクトリ
  • ${pathSeparator}: POSIX は /、Windows は
  • ${execPath}: VS Code 実行ファイルのパス
  • ${defaultBuildTask}: デフォルトビルドタスク名（定義されている場合）

ツール/ファイルマーカー

  • #tool:<toolName>: 本文に書くと、そのツールを要求するマーカーになります。登録済みのチャットツールや MCP ツール名を指定
  • #file:<path>: ファイル/フォルダー添付を指定。パスはプロンプトファイルからの相対解決（絶対パスも可）

これらを組み合わせることで、かなり柔軟なプロンプトが作れます。

呼び出し方法と保存場所

プロンプトファイルの呼び出し方法は 4 つあります。

  1. エディタの実行ボタン。チャットへ展開されます
  2. チャットから #filename で呼び出す
  3. ワークスペースの .github/prompts/ 以下に置くとチャットで /[name] で呼び出せる（ファイル名ではなく frontmatter の name を指定）
  4. VS Code プロファイルフォルダへ入れる。3 と同じ。すべてのワークスペースで使える

ある程度形になれば 4 のプロファイルに入れるのがよいのですが、使っているうちにちょっとづつ手を加えたくなりますし、自分カスタムをチーム共有の場所に置くのはちょっと邪魔になりそうです。よほど全員で共通化するもの以外は、結構適当に置いています。正確にはコマンドが覚えきれないので、見えるところにあるのがいいです。.github/prompts/ だと深いので使いにくかったり、カテゴリ分けできません。好きな場所において呼び出したほうが楽な感じです。

下記のようにユーザーと対話式進められる様にプロンプトを含めれば雑なプロンプトでもサクッと使えます。

- 対象が指定されていない場合は、ユーザーに編集対象のファイル名を尋ねてください。

Running GitHub Copilot Prompts

Windows 11 プロファイルフォルダの保存先に注意

プロファイルの保存フォルダはドキュメントに誤りがあるのでご注意ください。すぐに気づくと思いますが念のため。

  • ドキュメント記載: %APPDATA%CodeUserprofiles
  • v1.107 での実際の保存先: %APPDATA%RoamingCodeUserprompts

参考になるプロンプト集

awesome-copilot では汎用的なプロンプトが多く公開されています。やや汎用的すぎるかもしれませんが、これらをもとにしてカスタムして活用するのがよさそうです。いくつも参考にさせていただきました。

https://github.com/github/awesome-copilot/blob/main/docs/README.prompts.md

より実践的なプロンプトは Microsoft VS Code リポジトリが参考になります。開発者のセットアップ、QA 自動テストなどが含まれていて、長文ですが AI に読んでもらって参考にしています。

https://github.com/microsoft/vscode https://github.com/microsoft/vscode/tree/main/.github/prompts

私が作成したサンプルプロンプト例もあります。変数や引数を全部試すというテストプロンプトも作成しています。また、公式ドキュメントには変数仕様がすべて掲載されていませんが、VS Code のソースコードから読み取れたものを書面化しました。

https://github.com/catnipglitch/ai-agents-cookbook/blob/main/prompts/README.md

https://github.com/catnipglitch/ai-agents-cookbook/blob/main/docs/vscode-copilot-prompt-file-variables_ja.md

プロンプトの作成は AI に任せるのが楽

変数とかいろいろ覚えることが多そうに見えますが、チャットボットや Spaces に任せれば変数なんかもいい感じに仕上げてくれます。

https://github.com/copilot/spaces/catnipglitch/2

Copilot Spaces の Instructions に以下のようなプロンプトを設定しておくと、プロンプトファイルの作成が楽になります。

# Role
あなたは GitHub Copilot のプロンプト設計スペシャリストです。ユーザーが Prompt files（`.prompt.md`）および Custom instructions を作成・改善できるように支援してください。

## 指示
- ユーザーの目的に合わせて、設定ファイルやプロンプトファイルの構成・記述内容を提案してください
- YAML frontmatter を出力する場合、サポートフィールドの順番は必ず固定してください。順番を崩すことは忌諱し、例外なく禁止します  
  `description` → `name` → `argument-hint` → `agent` → `model` → `tools`
- `model` はデフォルトで未指定にしてください（モデル選択はユーザーの model picker に依存します）  
  - 指示がない限り `model` は指定しない  
  - ただし存在が分かるように、`model` 行はコメントアウトで残してください（例: `# model: ''  # model picker に依存`）
- 仕様にないフィールドは追加しないでください
- 不明点がある場合は、仕様の範囲内で合理的に補完し、必要なら追加質問をしてください
- 出力は Markdown で整理し、必要な箇所のみ簡潔に説明してください

まとめ

プロンプトファイルを活用することで、git 操作や issue 操作も一貫してできます。特にバックグラウンドと組み合わせることで、いままでなんかスムーズに利用できなかった Copilot Chat がいきなり快適になりました。思いついたらすぐに作って試せるので、よく使う操作はどんどんテンプレート化していくのがおすすめです。