How to Create and Use Reusable .prompt.md Files in VS Code

VS Code prompt files are reusable chat templates. Instead of typing the same instructions every time you scaffold a React component, review a pull request, or generate tests, you save the workflow as a .prompt.md file. Type / in chat, pick the prompt name, and the AI runs it.

Prompt files are different from /vscode/how-to-use-custom-instructions-in-vs-code-with-agents-md-and-instructions-md. Instructions apply automatically. Prompts you invoke on demand.

Prompt file locations

Workspace prompts are shared with your team through version control. User prompts are private and available across all your workspaces.

See the official VS Code prompt files guide for the current fields and commands.

Create a prompt file

Open the Prompts editor

In the Chat view, select the gear icon (Configure Chat) and go to the Prompts tab. Select New Prompt (Workspace) or New Prompt (User).

Name the file

Enter a file name. This becomes the name you type after / in chat. For a React form generator, name it create-react-form.prompt.md. The slash command becomes /create-react-form.

Fill in the frontmatter

The YAML header configures how the prompt runs. At minimum, add a description:

yaml

---
description: Generate a React form component with validation
---

Optional fields:

• agent: force the prompt to use a specific agent (ask, agent, plan, or a custom agent name)
• model: lock the prompt to a specific language model
• tools: restrict which tools are available when the prompt runs
• argument-hint: hint text shown in the chat input to guide users

Write the prompt body

Write clear instructions for the AI. Be specific about the expected output format and constraints.

Here is a complete example for a React form generator. The frontmatter goes first:

yaml

---
description: Generate a React form component with validation
argument-hint: form name and fields
---

The body follows the frontmatter. Describe what the AI should produce, which libraries to use, and the output format. Be specific about requirements and constraints. Here is the body:

markdown

Generate a React form component using react-hook-form and zod validation.
 
Requirements:
- Accept a schema defined with zod.
- Use shadcn/ui Form components.
- Include error messages for each field.
- Export the component as a named export.

You can also type /create-prompt in chat and describe the task. The AI generates the prompt file for you. Alternatively, after a successful multi-turn chat session, ask "turn this into a reusable prompt" and the AI captures the workflow.

Run a prompt file

Three ways to run a prompt:

When you invoke a prompt with /, you can pass additional information in the chat input. For example, /create-react-form name=SignupForm fields=email,password adds context on top of the prompt template.

Prompts can optionally appear as recommendations when you start a new chat session. Enable chat.promptFilesRecommendations to show suggested prompts in the Chat view.

Reference context dynamically

Prompt files can reference the current selection or ask for user input. These forms are supported:

text

${selection}
${input:variableName}
${input:variableName:placeholder}

For required questions, the prompt can instead direct the agent to use the vscode/askQuestions tool. Here is a selection-based prompt body:

markdown

Explain the following code in plain English. Focus on control flow
and data transformations.
 
${selection}

When the user selects code in the editor and runs /explain-code, the selection is inserted into the prompt.

Specify tools and agents

A prompt file can override the default tools. Use the tools field to restrict or expand what the AI can do:

yaml

---
description: Security review of selected code
tools: ['search/codebase', 'search/usages']
---

If you specify tools, the default agent switches from Ask to Agent mode so it can use them. To use a different agent, set the agent field:

yaml

---
description: Create a minimal plan
agent: plan
---

Prompt files can also reference a /vscode/how-to-create-custom-agents-in-vs-code-with-agent-md-files by name. The prompt inherits that agent's tools and instructions unless the prompt file overrides them.

Tool priority

When a prompt file specifies both a custom agent and a tools list, the prompt file's tools win. The full priority order is:

1. Tools from the prompt file
2. Tools from the referenced custom agent
3. Default tools for the selected agent

Sync prompts across devices

Enable Settings Sync and run Settings Sync: Configure from the Command Palette. Check the Prompts and Instructions option. Your user prompt files now sync across all your devices.