Custom instructions for GitHub Copilot in VS Code

You can enhance Copilot's chat responses by providing it with contextual details about your team's workflow, tools, or project specifics. Instead of manually including this context in every chat query, you can create a custom instructions file that automatically incorporates this information with every chat request.

Copilot applies these instructions to chat prompts in the Chat view, Quick Chat, or Inline Chat. These instructions are not displayed in the chat, but are passed to Copilot by VS Code.

You can specify custom instructions for specific purposes:

Code-generation instructions - provide context specific for generating code. For example, you can specify that private variables should always be prefixed with an underscore, or that singletons should be implemented a certain way. You can specify code-generation instructions in settings, or in a Markdown file in your workspace.
Test-generation instructions - provide context specific for generating tests. For example, you can specify that all generated tests should use a specific testing framework. You can specify test-generation instructions in settings, or in a Markdown file in your workspace.
Code review instructions - provide context specific for reviewing the current editor selection. For example, you can specify that the reviewer should look for a specific type of error in the code. You can specify review-selection instructions in settings, or in a Markdown file in your workspace.
Commit message generation instructions - provide context specific for generating commit messages. You can specify commit-message-generation instructions in settings, or in a Markdown file in your workspace.
Pull request title and description generation instructions - provide context specific for generating pull request titles and descriptions. You can specify pull request title and description generation instructions in settings, or in a Markdown file in your workspace.

Custom instructions consist of natural language instructions and should be short, self-contained statements that add context or relevant information to supplement chat questions.

Define code-generation custom instructions

Copilot can help you generate code, for example as part of a refactoring, generating unit tests, or implementing a feature. You might have specific libraries you want to use in your project, or a particular coding style you want to follow for the code that Copilot generates.

Note

Copilot does not apply code-generation instructions for code completions.

Use settings

You can configure custom code-generation instructions by using the github.copilot.chat.codeGeneration.instructions setting. You can define custom instructions at the User or Workspace level, and you can also specify language-specific instructions. Get more information about language-specific settings.

The following code snippet shows how to define a set of instructions in the settings.json file. To define instruction directly in settings, configure the text property. To reference an external file, configure the file property.

  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Always add a comment: 'Generated by Copilot'."
    },
    {
      "text": "In TypeScript always use underscore for private field names."
    },
    {
      "file": "code-style.md" // import instructions from file `code-style.md`
    }
  ],

An example of the contents of the code-style.md file:

Always use React functional components.

Always add comments.

Use a `.github/copilot-instructions.md` file

You can also store custom instructions in your workspace or repository in a .github/copilot-instructions.md file and have VS Code automatically pick up this file.

If you define custom instructions in both the .github/copilot-instructions.md file and in settings, Copilot tries to combine instructions from both sources.

Note

GitHub Copilot in Visual Studio also detects the .github/copilot-instructions.md file. If you have a workspace that you use in both VS Code and Visual Studio, you can use the same file to define custom instructions for both editors.

Set the github.copilot.chat.codeGeneration.useInstructionFiles setting to true to instruct Copilot in VS Code to use the custom instructions file.
Create a .github/copilot-instructions.md file at the root of your workspace. If needed, create a .github directory first.

Tip
In the Explorer view in VS Code, you can create the folder and directly in one operation by typing the full path as the file name.
Add natural language instructions to the file. You can use the Markdown format.

Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.

Define test-generation custom instructions

You can use Copilot to generate tests for your code, for example by using the @workspace /tests prompt in the Chat view. You can define custom instructions to help Copilot generate tests that are specific to your project and development workflow.

To configure custom test-generation instructions, use the github.copilot.chat.testGeneration.instructions setting. You can define custom instructions at the User or Workspace level.

  "github.copilot.chat.testGeneration.instructions": [
    {
      "text": "Always use vitest for testing React components."
    },
    {
      "text": "Use Jest for testing JavaScript code."
    },
    {
      "file": "code-style.md" // import instructions from file `code-style.md`
    }
  ],

An example of the contents of the code-style.md file:

Always add code comments.

Always use React functional components.

Define code review custom instructions

You can use Copilot to review a selection of code in the editor. You can define custom instructions to help Copilot take into account specific code review criteria that are relevant to your project and development workflow.

To configure custom code review instructions, use the github.copilot.chat.reviewSelection.instructions setting. You can define custom instructions at the User or Workspace level.

Define commit message generation custom instructions

In the Source Control view, you can use Copilot to generate a commit message for the pending code changes. You can define custom instructions to help Copilot generate a commit message that takes into account specific formatting and structure that are specific to your project and development workflow.

To configure custom commit message generation instructions, use the github.copilot.chat.commitMessageGeneration.instructions setting. You can define custom instructions at the User or Workspace level.

Define pull request title and description generation custom instructions

When you have the GitHub Pull Requests extension installed, you can use Copilot to generate a title and description for a pull request. You can define custom instructions to help Copilot generate a title and description that take into account specific formatting and structure that are specific to your project and development workflow.

To configure custom pull request title and description generation instructions, use the github.copilot.chat.pullRequestDescriptionGeneration.instructions setting. You can define custom instructions at the User or Workspace level.

Tips for defining custom instructions

Keep your instructions short and self-contained. Each instruction should be a single, simple statement. If you need to provide multiple pieces of information, use multiple instructions.
Don't refer to external resources in the instructions, such as specific coding standards.
Make it easy to share custom instructions with your team or across projects by storing your instructions in an external file. You can also version control the file to track changes over time.

Reusable prompt files (experimental)

Prompt files (prompts) let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file that mimics the existing format of writing prompts in Copilot Chat (for example, Rewrite #file:x.ts). This allows blending natural language instructions, additional context, and even linking to other prompt files as dependencies.

While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction.

Common use cases include:

Code generation: create reusable prompts for components, tests, or migrations (for example, React forms, or API mocks).
Domain expertise: share specialized knowledge through prompts, such as security practices, or compliance checks.
Team collaboration: document patterns and guidelines with references to specs and documentation.
Onboarding: create step-by-step guides for complex processes or project-specific patterns.

Prompt file examples

react-form.prompt.md - documents a reusable task for generating a form:

Your goal is to generate a new React form component.

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

security-api.prompt.md - documents reusable security practices for REST APIs, which can be used to do security reviews of REST APIs:

Secure REST API review:
* 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
…

Usage

To enable prompt files, configure the chat.promptFiles VS Code setting. By default, prompt files are located in the .github/prompts directory of your workspace. You can also specify additional folders where prompt files are located.

Create a prompt file

Set the chat.promptFiles setting to true for the .github/prompts directory.
Create a .prompt.md file in the .github/prompts directory of your workspace.

Alternatively, use the Create Prompt command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
Write prompt instructions by using Markdown formatting.

Within a prompt file, reference additional workspace files as Markdown links ([index](../index.ts)), or as #file:../index.ts references within the prompt file.

You can also reference other .prompt.md files to create a hierarchy of prompts, with reusable prompts that can be shared across multiple prompt files.

Create a user prompt file

User prompt files are stored in your user profile. With user prompt files, you can share reusable prompts across multiple workspaces.

You can add a user prompt file to a chat prompt in the same way as a workspace prompt file.

To create a user prompt file:

Select the Create User Prompt command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
Enter a name for your prompt file.
Write prompt instructions by using Markdown formatting.

User prompt files can now be synced across multiple devices with Settings Sync. Make sure to enable support for prompt files in your Settings Sync configuration. Select Settings Sync: Configure from the Command Palette, and make sure Prompts is selected.

Attach a prompt file to a chat request

Select the Attach Context icon (⌘/ (Windows, Linux Ctrl+/)), and then select Prompt....

Alternatively, use the Chat: Use Prompt command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
Choose a prompt file from the Quick Pick to attach it to your chat request.

You can use prompt files in both Copilot Chat and Copilot Edits.
Optionally, attach additional context files required for the task.

For reusable tasks, send the prompt without any additional instructions.

To further refine a reusable prompt, include additional instructions to provide more context for the task at hand.

Tip

Reference additional context files like API specs or documentation by using Markdown links to provide Copilot with more complete information.

Settings

Custom instructions settings

github.copilot.chat.codeGeneration.useInstructionFiles: controls whether code instructions from .github/copilot-instructions.md are added to Copilot requests.
github.copilot.chat.codeGeneration.instructions (Experimental): set of instructions that will be added to Copilot requests that generate code.
github.copilot.chat.testGeneration.instructions (Experimental): set of instructions that will be added to Copilot requests that generate tests.
github.copilot.chat.reviewSelection.instructions (Preview): set of instructions that will be added to Copilot requests for reviewing the current editor selection.
github.copilot.chat.commitMessageGeneration.instructions (Experimental): set of instructions that will be added to Copilot requests that generate commit messages.
github.copilot.chat.pullRequestDescriptionGeneration.instructions (Experimental): set of instructions that will be added to Copilot requests that generate pull request titles and descriptions.

Prompt files (experimental) settings

chat.promptFiles (Experimental): enable reusable prompt files.

chat.promptFilesLocations (Experimental): a list of folders where prompt files are located. You can specify one or more folders where prompt files are located. Relative paths are resolved from the root folder(s) of your workspace. Supports glob patterns for file paths.

Setting value	Description
`["/path/to/folder"]`	Enable prompt files for a specific path. Specify one or more folders where prompt files are located. Relative paths are resolved from the root folder(s) of your workspace. By default, `.github/prompts` is added but disabled.