Adding repository custom instructions for GitHub Copilot

Create repository custom instructions files that give Copilot additional context on how to understand your project and how to build, test and validate its changes.

Tool navigation

In this article

This version of this article is for using repository custom instructions on the GitHub website. Click the tabs above for information on using custom instructions in other environments.

Introduction

Repository custom instructions let you provide Copilot with repository-specific guidance and preferences. For more information, see About customizing GitHub Copilot responses.

Prerequisites for repository custom instructions

  • You must have a custom instructions file (see the instructions below).

This version of this article is for using repository custom instructions and prompt files in VS Code. Click the tabs above for instructions on using custom instructions in other environments.

Introduction

Repository custom instructions let you provide Copilot with repository-specific guidance and preferences. For more information, see About customizing GitHub Copilot responses.

Prerequisites for repository custom instructions

  • You must have a custom instructions file (see the instructions below).

This version of this article is for using repository custom instructions and prompt files in Visual Studio. Click the tabs above for instructions on using custom instructions in other environments.

Introduction

Repository custom instructions let you provide Copilot with repository-specific guidance and preferences. For more information, see About customizing GitHub Copilot responses.

Prerequisites for repository custom instructions

  • You must have a custom instructions file (see the instructions below).

This version of this article is for using repository custom instructions in JetBrains IDEs. Click the tabs above for instructions on using custom instructions in other environments.

Introduction

Repository custom instructions let you provide Copilot with repository-specific guidance and preferences. For more information, see About customizing GitHub Copilot responses.

Prerequisites for repository custom instructions

  • You must have a custom instructions file (see the instructions below).

This version of this article is for using repository custom instructions in Xcode. Click the tabs above for instructions on using custom instructions in other environments.

Introduction

Repository custom instructions let you provide Copilot with repository-specific guidance and preferences. For more information, see About customizing GitHub Copilot responses.

Prerequisites for repository custom instructions

  • You must have a custom instructions file (see the instructions below).

This version of this article is for using repository custom instructions with the GitHub Copilot CLI. Click the tabs above for instructions on using custom instructions in other environments.

Prerequisites for repository custom instructions

  • You must have a custom instructions file (see the instructions below).

Note

This feature is currently in public preview and is subject to change.

This version of this article is for using repository custom instructions in Eclipse. Click the tabs above for instructions on using custom instructions in other environments.

Introduction

Repository custom instructions let you provide Copilot with repository-specific guidance and preferences. For more information, see About customizing GitHub Copilot responses.

Prerequisites for repository custom instructions

  • You must have a custom instructions file (see the instructions below).
  • The latest version of the Copilot extension must be installed in your JetBrains IDE.
  • The latest version of the Copilot extension must be installed in Xcode.
  • The latest version of the Copilot extension must be installed in Eclipse.

Creating custom instructions

JetBrains IDEs support a single .github/copilot-instructions.md custom instructions file stored in the repository, and a locally stored global-copilot-instructions.md file.

You can create the .github/copilot-instructions.md file in your repository using the Copilot settings page, or you can create the file manually.

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.

Using the settings page

  1. In your JetBrains IDE, click the File menu (Windows), or the name of the application in the menu bar (macOS), then click Settings.
  2. Under Tools, click GitHub Copilot, then click Customizations.
  3. Under "Copilot Instructions", click Workspace or Global to choose whether the custom instructions apply to the current workspace or all workspaces.

Manually creating a workspace custom instructions file

  1. In the root of your repository, create a file named .github/copilot-instructions.md.

    Create the .github directory if it does not already exist.

  2. Add natural language instructions to the file, in Markdown format.

Once saved, these instructions will apply to the current workspace in JetBrains IDEs that you open with Copilot enabled.

Manually creating a global custom instructions file

To apply the same instructions across all workspaces in JetBrains IDEs, you can create a global custom instructions file on your local machine.

  1. Open your file explorer or terminal.

  2. Navigate to the appropriate location for your operating system:

    • macOS: /Users/YOUR-USERNAME/.config/github-copilot/intellij/
    • Windows: C:\Users\YOUR-USERNAME\AppData\Local\github-copilot\intellij\

  3. Create a file named global-copilot-instructions.md in that directory.

  4. Add your custom instructions in natural language, using Markdown format.

Once saved, these instructions will apply globally across all workspaces in JetBrains IDEs that you open with Copilot enabled.

Xcode supports a single .github/copilot-instructions.md custom instructions file stored in the repository.

You can create a custom instructions file in your repository via the Copilot settings page.

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.

  1. Open the GitHub Copilot for Xcode application.
  2. At the top of the application window, under Settings, click Advanced.
  3. To the right of "Custom Instructions", click Current Workspace or Global to choose whether the custom instructions apply to the current workspace or all workspaces.

Eclipse supports two types of repository custom instructions: workspace and project custom instructions.

To create a workspace custom instructions file, you can use the Copilot settings page. To create a project custom instructions file, you can create the file manually in the project directory.

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.

Creating a workspace custom instructions file

  1. To open the Copilot Chat panel, click the Copilot icon () in the status bar at the bottom of Eclipse.
  2. From the menu, select "Edit preferences".
  3. In the left pane, expand GitHub Copilot and click Custom Instructions.
  4. Select Enable workspace instructions.
  5. In the "Workspace" section, under "Set custom instructions to guide Copilot's code suggestions in this workspace", add natural language instructions to the file, in Markdown format.

Creating a project custom instructions file

  1. In the root of your project directory, create a file named .github/copilot-instructions.md.
  2. Add your custom instructions in natural language, using Markdown format.

Once saved, these instructions will apply to the current project in Eclipse that you open with Copilot enabled.

GitHub Copilot supports three types of repository custom instructions.

  • Repository-wide custom instructions, which apply to all requests made in the context of a repository.

    These are specified in a copilot-instructions.md file in the .github directory of the repository. See Creating repository-wide custom instructions.

  • Path-specific custom instructions, which apply to requests made in the context of files that match a specified path.

    These are specified in one or more NAME.instructions.md files within the .github/instructions directory in the repository. See Creating path-specific custom instructions.

    If the path you specify matches a file that Copilot is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as Copilot's choice between conflicting instructions is non-deterministic.

  • Agent instructions are used by AI agents.

    You can create one or more AGENTS.md files, stored anywhere within the repository. When Copilot is working, the nearest AGENTS.md file in the directory tree will take precedence. For more information, see the openai/agents.md repository.

    Alternatively, you can use a single CLAUDE.md or GEMINI.md file stored in the root of the repository.

Creating repository-wide custom instructions

  1. In the root of your repository, create a file named .github/copilot-instructions.md.

    Create the .github directory if it does not already exist.

  2. Add natural language instructions to the file, in 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.

Creating path-specific custom instructions

  1. Create the .github/instructions directory if it does not already exist.

  2. Create one or more NAME.instructions.md files, where NAME indicates the purpose of the instructions. The file name must end with .instructions.md.

  3. At the start of the file, create a frontmatter block containing the applyTo keyword. Use glob syntax to specify what files or directories the instructions apply to.

    For example:

    ---
applyTo: "app/models/**/*.rb"
---

    You can specify multiple patterns by separating them with commas. For example, to apply the instructions to all TypeScript files in the repository, you could use the following frontmatter block:

    ---
applyTo: "**/*.ts,**/*.tsx"
---

    Glob examples:

    • * - will all match all files in the current directory.
    • ** or **/* - will all match all files in all directories.
    • *.py - will match all .py files in the current directory.
    • **/*.py - will recursively match all .py files in all directories.
    • src/*.py - will match all .py files in the src directory. For example, src/foo.py and src/bar.py but not src/foo/bar.py.
    • src/**/*.py - will recursively match all .py files in the src directory. For example, src/foo.py, src/foo/bar.py, and src/foo/bar/baz.py.
    • **/subdir/**/*.py - will recursively match all .py files in any subdir directory at any depth. For example, subdir/foo.py, subdir/nested/bar.py, parent/subdir/baz.py, and deep/parent/subdir/nested/qux.py, but not foo.py at a path that does not contain a subdir directory.

  4. Optionally, to prevent the file from being used by either Copilot coding agent or Copilot code review, add the excludeAgent keyword to the frontmatter block. Use either "code-review" or "coding-agent".

    For example, the following file will only be read by Copilot coding agent.

    ---
applyTo: "**"
excludeAgent: "code-review"
---

    If the excludeAgent keyword is not included in the front matterblock, both Copilot code review and Copilot coding agent will use your instructions.

  5. Add your custom instructions in natural language, using 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.

VS Code supports three types of repository custom instructions. For details of which GitHub Copilot features support these types of instructions, see About customizing GitHub Copilot responses.

  • Repository-wide custom instructions, which apply to all requests made in the context of a repository.

    These are specified in a copilot-instructions.md file in the .github directory of the repository. See Creating repository-wide custom instructions.

  • Path-specific custom instructions, which apply to requests made in the context of files that match a specified path.

    These are specified in one or more NAME.instructions.md files within the .github/instructions directory in the repository. See Creating path-specific custom instructions.

    If the path you specify matches a file that Copilot is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used.

  • Agent instructions are used by AI agents.

    You can create one or more AGENTS.md files, stored anywhere within the repository. When Copilot is working, the nearest AGENTS.md file in the directory tree will take precedence. For more information, see the openai/agents.md repository.

    Note

    Support of AGENTS.md files outside of the workspace root is currently turned off by default. For details of how to enable this feature, see Use custom instructions in VS Code in the VS Code documentation.

Creating repository-wide custom instructions

  1. In the root of your repository, create a file named .github/copilot-instructions.md.

    Create the .github directory if it does not already exist.

  2. Add natural language instructions to the file, in 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.

Creating path-specific custom instructions

  1. Create the .github/instructions directory if it does not already exist.

  2. Create one or more NAME.instructions.md files, where NAME indicates the purpose of the instructions. The file name must end with .instructions.md.

  3. At the start of the file, create a frontmatter block containing the applyTo keyword. Use glob syntax to specify what files or directories the instructions apply to.

    For example:

    ---
applyTo: "app/models/**/*.rb"
---

    You can specify multiple patterns by separating them with commas. For example, to apply the instructions to all TypeScript files in the repository, you could use the following frontmatter block:

    ---
applyTo: "**/*.ts,**/*.tsx"
---

    Glob examples:

    • * - will all match all files in the current directory.
    • ** or **/* - will all match all files in all directories.
    • *.py - will match all .py files in the current directory.
    • **/*.py - will recursively match all .py files in all directories.
    • src/*.py - will match all .py files in the src directory. For example, src/foo.py and src/bar.py but not src/foo/bar.py.
    • src/**/*.py - will recursively match all .py files in the src directory. For example, src/foo.py, src/foo/bar.py, and src/foo/bar/baz.py.
    • **/subdir/**/*.py - will recursively match all .py files in any subdir directory at any depth. For example, subdir/foo.py, subdir/nested/bar.py, parent/subdir/baz.py, and deep/parent/subdir/nested/qux.py, but not foo.py at a path that does not contain a subdir directory.

  4. Optionally, to prevent the file from being used by either Copilot coding agent or Copilot code review, add the excludeAgent keyword to the frontmatter block. Use either "code-review" or "coding-agent".

    For example, the following file will only be read by Copilot coding agent.

    ---
applyTo: "**"
excludeAgent: "code-review"
---

    If the excludeAgent keyword is not included in the front matterblock, both Copilot code review and Copilot coding agent will use your instructions.

  5. Add your custom instructions in natural language, using 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.

Visual Studio supports two types of custom instructions. For details of which GitHub Copilot features support these types of instructions, see