How to configure VSCode Copilot prompts

[doggie]

Notes

Not entirely clear about the difference between prompt.md and instructions.md:

• 如何配置vscode copilot默认使用中文

Main Content

The following Chinese text is machine-translated. See the original English at:

Use prompt files in VS Code

Using Prompt Files in VS Code

Prompt files are Markdown files that define reusable prompts for common development tasks such as generating code, performing code reviews, or scaffolding project components. These are standalone prompts that can be run directly in chat, enabling you to build libraries of standardized development workflows.

They may include guidelines for specific tasks or reference custom instructions to ensure consistent execution. Unlike custom instructions, which apply to all requests, prompt files are triggered on-demand for specific tasks.

VS Code supports two scopes for prompt files:

• Workspace prompt files: Available only within a workspace and stored in the .github/prompts folder of the workspace.
• User prompt files: Usable across multiple workspaces and stored in the current VS Code profile.

Prompt File Structure

Prompt files are Markdown files with the .prompt.md extension and follow this structure:

Header (Optional)

The header uses YAML frontmatter format and includes the following fields:

Expand table

Field	Description
description	A short description of the prompt.
name	The name of the prompt used when typing / in chat. If not specified, the filename is used.
argument-hint	Optional placeholder text shown in the chat input box to guide users on how to interact with the prompt.
agent	The agent used when running the prompt: ask, edit, agent, or a custom agent name. By default, the current agent is used. If tools are specified and the current agent is ask or edit, the default becomes agent.
model	The language model used when running the prompt. If not specified, the currently selected model in the model selector is used.
tools	A list of available tools or toolset names for this prompt. This can include built-in tools, toolsets, MCP tools, or tools contributed by extensions. To include all tools from an MCP server, use the format <server name>/*. Learn more about tools in chat.

Note
If a tool is unavailable when the prompt runs, it will be ignored.

Body

The body of the prompt file contains the actual prompt text sent to the LLM when executed in chat. Provide specific instructions, guidelines, or other relevant information for the AI to follow.

You can reference other workspace files using Markdown links. Use relative paths based on the location of the prompt file and ensure path correctness.

When referencing agent tools in the body, use the #tool:<tool-name> syntax. For example, to reference the githubRepo tool, use #tool:githubRepo.

In prompt files, you can use the ${variableName} syntax to reference variables. Supported variables include:

• Workspace variables — ${workspaceFolder}, ${workspaceFolderBasename}
• Selection variables — ${selection}, ${selectedText}
• File context variables — ${file}, ${fileBasename}, ${fileDirname}, ${fileBasenameNoExtension}
• Input variables — ${input:variableName}, ${input:variableName:placeholder} (pass values from the chat input box into the prompt)

Prompt File Examples

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

Example: Generate a React Form Component

Markdown

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

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

Example: Perform a Security Review of a REST API

Markdown

---
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.

Creating a Prompt File

When creating a prompt file, you can choose to store it in your workspace or user profile. Workspace prompt files are limited to that workspace, while user prompt files can be used across multiple workspaces.

To create a prompt file:

1. In the Chat view, select Configure Chat (gear icon) → Prompt Files, then select New Prompt File.
   
   
   
   Alternatively, use the Chat: New Prompt File or Chat: New Untitled Prompt File command from the Command Palette (⇧⌘P).
2. Choose where to create the prompt file:
   • Workspace: Creates the prompt file in the .github/prompts folder of your workspace, making it available only in that workspace. Add additional prompt folders via the chat.promptFilesLocations setting.
   • User Profile: Creates the prompt file in the current profile folder, making it available across all workspaces.
3. Enter a filename for the prompt file. This will be the default name shown when typing / in chat.
4. Write your chat prompt using Markdown formatting.
   • Fill in the YAML frontmatter at the top of the file to configure settings like description, agent, tools, etc.
   • Add your prompt instructions in the body of the file.

To modify an existing prompt file, go to Configure Chat → Prompt Files in the Chat view and select one from the list. Alternatively, use the Chat: Configure Prompt File command from the Command Palette (⇧⌘P), then select the prompt file in the quick picker.

Using a Prompt File in Chat

There are several ways to run a prompt file:

• In the Chat view, type /, then enter the prompt file name in the input box. You can add extra information after the name. For example: /create-react-form formName=MyForm or /create-api for listing customers.
• Run the Chat: Run Prompt command from the Command Palette (⇧⌘P) and select a prompt file from the quick picker.
• Open the prompt file in the editor and click the play button in the editor title bar. You can choose to run the prompt in the current chat session or open a new one. This option is useful for quickly testing and iterating on your prompt files.

Tip
Use the chat.promptFilesRecommendations setting to show prompts as recommended actions when starting a new chat session.

Tool List Priority

You can specify the list of tools available to a custom agent or prompt file using the tools metadata field. Prompt files can also reference a custom agent via the agent metadata field.

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

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

Sync User Prompt Files Across Devices

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

To sync your user prompt files, enable Settings Sync and configure it to sync prompts and instructions:

1. Make sure Settings Sync is enabled.
2. Run Settings Sync: Configure from the Command Palette (⇧⌘P).
3. Select Prompts and Instructions from the list of settings to sync.

Tips for Defining Prompt Files

• Clearly describe the task the prompt should perform and the expected output format.
• Provide examples of expected input and output to guide the AI’s response.
• Use Markdown links to reference custom instructions instead of repeating guidelines in every prompt.
• Leverage built-in variables like ${selection} and input variables to make prompts more flexible.
• Test your prompts using the editor’s play button and refine them based on results.

Related Resources

• Customizing AI Responses Overview
• Creating Custom Instructions
• Creating Custom Agents
• Getting Started with Chat in VS Code
• Configuring Tools in Chat
• Community-contributed Instructions, Prompts, and Custom Agents

Help and support