Adding repository custom instructions

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.

In this article

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.

Creating custom instructions

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

Did you successfully add a custom instructions file to your repository?

Yes No

Repository custom instructions in use

The instructions in the file(s) are available for use by Copilot as soon as you save the file(s). The complete set of instructions will be automatically added to requests that you submit to Copilot in the context of that repository. For example, they are added to the prompt you submit to Copilot Chat.

Further reading