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.

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.

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.

1. Set the github.copilot.chat.codeGeneration.useInstructionFiles setting to true to instruct Copilot in VS Code to use the custom instructions file.

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

3. 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, and you can also specify language-specific instructions. Get more information about language-specific settings. For example, you might specify a different testing framework to use for each language.

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

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,

• Define language-specific instructions to get more accurate generated code for each language.

• 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 are added to Copilot requests that generate code.
• github.copilot.chat.codeGeneration.useInstructionFiles : Controls whether code instructions from .github/copilot-instructions.md are added to Copilot requests.
• github.copilot.chat.testGeneration.instructions : A set of instructions that are added to Copilot requests that generate tests.

Related content

• Learn how you can use AI chat conversations with Copilot Chat.