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.

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

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.

Settings

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