Use prompt files in VS Code

Prompt files simplify prompting for common tasks by encoding them as standalone Markdown files that you invoke as slash commands in chat. Each prompt file includes task-specific context and guidelines about how the task should be performed.

Unlike custom instructions that are applied automatically, you invoke prompt files manually in chat. See the decision matrix to compare prompt files with custom agents, agent skills, and the other options.

Use prompt files to:

• Simplify prompting for common tasks, such as scaffolding a new component, running and fixing tests, or preparing a pull request
• Override default behavior of a custom agent, such as creating a minimal implementation plan or generating mockups for API calls

With Local selected, use the Agent Customizations editor (Preview) to discover, create, and manage prompt files. Run Chat: Open Customizations from the Command Palette.

Prompt file locations

You can define prompt files for a specific workspace or at the user level, where they are available across all your workspaces. The following table lists the default file locations that the Local harness uses for prompt files.

To create a user-level prompt file, use the Agent Customizations editor or the Chat: New Prompt File command.

Prompt file format

Prompt files are Markdown files with the .prompt.md extension. The optional YAML frontmatter header configures the prompt's behavior:

The body contains the prompt text in Markdown format. Provide specific instructions, guidelines, or any other relevant information that you want the AI to follow.

Reference files

You can reference files in the prompt body by using Markdown links or the #file: syntax.

• For files in your workspace, use paths relative to the prompt file. For example, [coding standards](../instructions/coding.instructions.md) references a file in a sibling instructions folder.
• For files in your environment user home folder, use ~ or start the path with ~/. A standalone ~ references the user home folder, and a path such as ~/prompts/style-guide.md resolves from that folder.

Use Unix-style / path separators to keep prompt files portable across operating systems.

The following example uses both reference formats to reference files in the user home folder:

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

To reference agent tools in the body text, use the #tool:<tool-name> syntax. For example, to reference the browser tool, use #tool:browser.

The following examples demonstrate how to use prompt files. For more community-contributed examples, see the Awesome Copilot repository.

---
agent: 'agent'
model: GPT-4o
tools: ['search/codebase', 'vscode/askQuestions']
description: 'Generate a new React form component'
---
Your goal is to generate a new React form component based on the templates in the Github repo contoso/react-templates.

Use the #tool:vscode/askQuestions to ask for the form name and fields if not provided.

Requirements for the form:
* Use form design system components: [design-system/Form.md](../docs/design-system/Form.md)
* Use `react-hook-form` for form state management:
* Always define TypeScript types for your form data
* Prefer *uncontrolled* components using register
* Use `defaultValues` to prevent unnecessary rerenders
* Use `yup` for validation:
* Create reusable validation schemas in separate files
* Use TypeScript types to ensure type safety
* Customize UX-friendly validation rules

---
agent: 'ask'
model: Claude Sonnet 4
description: 'Perform a REST API security review'
---
Perform a REST API security review and provide a TODO list of security issues to address.

* Ensure all endpoints are protected by authentication and authorization
* Validate all user inputs and sanitize data
* Implement rate limiting and throttling
* Implement logging and monitoring for security events

Return the TODO list in a Markdown format, grouped by priority and issue type.

Create a prompt file

Before creating a prompt file, select the Local harness in the Chat view. Choose whether to store the file in your workspace or user profile. Workspace prompt files are available to Local sessions in that workspace. User prompt files are available to Local sessions across workspaces in the same profile.

To create a prompt file:

1. In the Chat view, select Open Customizations in the title bar to open the Agent Customizations editor, and then select Prompts.

2. Select New Prompt (plus icon) next to the Workspace or User group, depending on where you want to store the prompt file.

   

   Alternatively, use the Chat: New Prompt File or Chat: New Untitled Prompt File command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

3. Select the location and enter a file name for your prompt file. This is the default name that appears when you type / in chat.

4. Author the chat prompt by using Markdown formatting.

   • Fill in the YAML frontmatter at the top of the file to configure the prompt's description, agent, tools, and other settings.
   • Add instructions for the prompt in the body of the file.

You can modify existing prompt files by opening them in the Agent Customizations editor.

Generate a prompt file with AI

An agent with file-editing tools can help author a prompt file, even if you use a different harness to write it. Tell the agent that the file will run in a Local session and describe the task, expected output, and storage location. Review the generated file before using it.

Authoring a .prompt.md file in a Copilot session doesn't make that file runnable by the Copilot harness. To reuse a workflow in that harness, create a skill or convert an existing prompt file.

With Local selected, you can also type /create-prompt in chat followed by the description. The agent asks clarifying questions, generates a .prompt.md file with appropriate frontmatter and instructions, and offers you a choice between workspace and user storage. The /create-prompt command isn't available for other harnesses.

You can also ask an agent to capture an ongoing conversation as a prompt file for Local sessions. Specify the target harness so that it doesn't create a customization in a format you can't use.

With Local selected in the Chat view, you can also generate a prompt file from the Agent Customizations editor by selecting Generate with AI next to the Workspace group in the Prompts section.

Use a prompt file in chat

Select Local in the Chat view before running the prompt. The following options run prompt files in Local sessions:

• In the Chat view, type / followed by the prompt name in the chat input field. Agent skills also appear as slash commands alongside prompt files.

  You can add extra information in the chat input field. For example, /create-react-form formName=MyForm or /create-api for listing customers.

• Run the Chat: Run Prompt command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) and select a prompt file from the Quick Pick.

• Open the prompt file in the editor, and press the play button in the editor title area. You can choose to run the prompt in the current chat session or open a new chat session.

  This option is useful for quickly testing and iterating on your prompt files.

Tool list priority

You can specify the list of available tools for both a custom agent and prompt file by using the tools metadata field. Prompt files can also reference a custom agent by using the agent metadata field.

The list of available tools in chat is determined by the following priority order:

1. Tools specified in the prompt file (if any)
2. Tools from the referenced custom agent in the prompt file (if any)
3. Default tools for the selected agent (if any)

Sync user prompt files across devices

VS Code can sync your user prompt files across multiple devices by using Settings Sync.

To sync your user prompt files, enable Settings Sync and run Settings Sync: Configure from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). Select Prompts and Instructions from the list of settings to sync.

Tips for writing effective prompts

• Clearly describe what the prompt should accomplish and what output format is expected.

• Provide examples of the expected input and output to guide the AI's responses.

• Use Markdown links to reference custom instructions rather than duplicating guidelines in each prompt.

• Take advantage of built-in variables like ${selection} and input variables to make prompts more flexible.

• Use the editor play button to test your prompts and refine them based on the results.

Frequently asked questions

How do I know where a prompt file comes from?

Prompt files can come from different sources: built-in, user-defined in your profile, workspace-defined prompts in your current workspace, or extension-contributed prompts.

To identify the source of a prompt file:

1. Select Chat: Configure Prompt Files from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
2. Hover over the prompt file in the list. The source location is displayed in a tooltip.

Related resources

• Create custom instructions
• Configure agent tools
• Community contributed instructions, prompts, and custom agents