GitHub Copilot prompt files: .prompt.md setup and variables

GitHub Copilot prompt files turn a repeated chat request into a versioned .prompt.md file that a developer can run on demand. Put a repository prompt in .github/prompts/, give it a focused job, and invoke it from Copilot Chat instead of rebuilding the same instructions every time.

Applies to: GitHub Copilot prompt files (public preview) in GitHub’s and Visual Studio Code’s documentation; the practical steps use VS Code’s Local harness. Last checked: October 25, 2026.

On this page

What a prompt file does

A prompt file is a reusable Markdown template for one interaction. GitHub’s prompt files overview says it can carry input variables and extra context, while VS Code’s prompt file guide lets it select an agent, a model and tools.

That makes a prompt file a good fit for work that has a stable procedure but changing inputs. VS Code’s own examples are scaffolding a new component, running and fixing tests and preparing a pull request. It is not a standing rule: unlike custom instructions, which GitHub says apply automatically within their scope, a prompt file is invoked for a specific interaction.

GitHub lists prompt-file support in Visual Studio Code, Visual Studio, JetBrains IDEs and Xcode, and points to its customization cheat sheet and feature matrix for version-specific availability. The metadata and run controls differ between editors, so this guide keeps the runnable steps to VS Code.

Put repository prompts in .github/prompts

VS Code’s prompt file locations table lists the workspace default as:

.github/prompts

Prompt files are Markdown files with the .prompt.md extension. GitHub’s first prompt file tutorial saves its example as explain-code.prompt.md in that folder.

Commit a workspace prompt when the task belongs to the repository and should travel with it. VS Code also supports user-level prompt files stored in your VS Code profile, which are available across workspaces; the VS Code guide creates them with the Agent Customizations editor or the Chat: New Prompt File command.

In a monorepo, VS Code says to enable chat.useCustomizationsInParentRepositories to discover prompt files from the parent repository root.

Start with GitHub’s example

This is the prompt file from GitHub’s Your first prompt file tutorial:

---
agent: 'agent'
description: 'Generate a clear code explanation with examples'
---

Explain the following code in a clear, beginner-friendly way:

Code to explain: ${input:code:Paste your code here}
Target audience: ${input:audience:Who is this explanation for? (e.g., beginners, intermediate developers, etc.)}

Please provide:

* A brief overview of what the code does
* A step-by-step breakdown of the main parts
* Explanation of any key concepts or terminology
* A simple example showing how it works
* Common use cases or when you might use this approach

Use clear, simple language and avoid unnecessary jargon.

The YAML block is optional; the Markdown body is the actual prompt. ${input:code:Paste your code here} is a named input with placeholder text. VS Code’s guide documents both ${input:variableName} and ${input:variableName:placeholder}.

Saved as explain-code.prompt.md in .github/prompts, the tutorial runs it by entering /explain-code in the Copilot Chat view. GitHub says Copilot then switches to agent mode if needed and asks for the code and the audience.

Run the prompt in VS Code

Select Local in the Chat view first. VS Code’s documentation says prompt files run only in Local harness sessions; for reusable workflows in other harnesses it recommends an agent skill instead.

Then run the file in one of three ways the same page lists:

1. Type / followed by the prompt name in the chat input, and add any extra information after it.
2. Run Chat: Run Prompt from the Command Palette and pick the file.
3. Open the .prompt.md file and press the play button in the editor title area, in the current chat or a new one.

The slash-command name comes from the name field; if name is absent, VS Code uses the file name. With Local selected, typing /prompts opens the Configure Prompt Files menu. VS Code suggests the play button for testing and iterating on a prompt, which is worth doing on a small, known file before the prompt becomes a team workflow.

Use frontmatter only when it controls something useful

VS Code documents six optional frontmatter fields in its prompt file format section:

Without model, VS Code uses the model currently selected in the picker. Without agent, it uses the current agent, or agent when tools are specified. If a listed tool is not available when the prompt runs, VS Code ignores it.

When a prompt file and its referenced custom agent both specify tools, VS Code’s tool list priority puts the prompt file’s tools first, then the custom agent’s, then the selected agent’s defaults. For a reusable role with its own tool policy, use a custom agent and keep the prompt focused on the task; see GitHub Copilot custom agents.

Reference context instead of pasting it

The prompt body can reference files with Markdown links or the #file: syntax. Workspace paths are relative to the prompt file, home-folder paths start with ~, and VS Code recommends Unix-style / separators so prompts stay portable. Its example:

Review [my personal instructions](~/copilot/instructions.md).
Use #file:~/templates/component.md as the component template.

To name an agent tool in the body, VS Code uses #tool: followed by the tool name, for example #tool:browser. When the prompt needs more information from the user, the same page points to the vscode/askQuestion tool or to ${input:...} variables. VS Code’s writing tips also suggest linking to custom instructions rather than duplicating guidelines in each prompt; the Copilot custom instructions guide covers those always-on files.

Prompt file, instructions or skill?

Use the smallest mechanism that matches the job:

• A prompt file is manual and task-specific: VS Code has you invoke it in chat.
• Custom instructions apply automatically within their scope and carry repository conventions across many requests.
• A custom agent defines a role and a reusable tool list that a prompt file can reference through agent.
• An agent skill is what VS Code recommends when the workflow must run outside the Local harness.

Keeping the layers separate makes it clearer which context Copilot used and where a future edit belongs.

Review and security boundaries

A prompt file guides Copilot; it does not replace review of the changes the agent makes. Treat linked files and input variables as part of the prompt’s effective context, and do not put secrets, production credentials or private customer data into a shared prompt.

For a prompt that can edit files or run commands, list only the tools the workflow needs in tools. If the task needs automatic enforcement before or after a tool call, a prompt is the wrong layer; Copilot hooks cover that control point.

GitHub’s tutorial marks prompt files as public preview and subject to change. Check the GitHub overview and your editor’s current documentation before standardizing a cross-editor workflow.