Adding custom instructions for GitHub Copilot CLI

GitHub Copilot can provide responses that are tailored to your personal preferences, the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create custom instructions that automatically add this information for you. The additional information is not displayed, but is available to Copilot to allow it to generate higher quality responses.

Types of custom instructions

GitHub Copilot CLI supports instructions from the following locations.

Unless noted in the table below, Copilot CLI discovers repository and agent instruction files in the standard locations: the repository root, the current working directory, intermediate directories between them, and any directories nested in the path of a file it is working on. Modular instruction files (those matching *.instructions.md) are path-specific—a file with an applyTo value applies only to matching files.

Location	Scope and behavior
`$HOME/.copilot/copilot-instructions.md`	User-level instructions that apply across repositories.
`$HOME/.copilot/instructions/*/.instructions.md`	Modular user-level instructions.
`.github/copilot-instructions.md`	Repository-wide instructions, discovered in the standard locations.
`.github/instructions/*/.instructions.md`	Modular repository instructions, discovered in the standard locations but not intermediate directories.
`AGENTS.md`	Agent instructions, discovered in the standard locations. For more information, see the agentsmd/agents.md repository.
`CLAUDE.md`	Agent instructions, discovered in the standard locations. Copilot CLI also uses `.claude/CLAUDE.md`.
`GEMINI.md`	Agent instructions, discovered in the standard locations.
Directories listed in `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`	Additional `AGENTS.md` and `*.instructions.md` files. Separate multiple directories with commas.

If you set the COPILOT_HOME environment variable, Copilot CLI uses that directory instead of $HOME/.copilot for both user-level instruction locations.

Use the /instructions command to view the instruction files discovered for the current session and enable or disable individual files.

How multiple instruction files interact

When multiple applicable user-level and repository instruction files exist, Copilot CLI combines their instructions. It removes duplicate copies of identical user-level copilot-instructions.md, repository-wide, and agent instructions, but does not define a general precedence order between these files. Avoid conflicting instructions.

Path-specific instructions are included only when their applyTo value matches a file that Copilot CLI is working with. An instruction file that you disable using /instructions is not included.

Creating repository-wide custom instructions

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

Create the .github directory if it does not already exist.
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.

For help on writing effective custom instructions, see About customizing GitHub Copilot responses.

Referencing other files

In .github/copilot-instructions.md, AGENTS.md, or CLAUDE.md, use @ followed by a relative path to include another file. Copilot CLI reads the referenced file immediately and supports references within referenced files.

Referenced files must remain within the repository, or within the custom instructions directory for local instructions. Absolute paths and paths beginning with ~/ are not loaded. File references are not expanded in GEMINI.md or *.instructions.md files.

Creating path-specific custom instructions

Create the .github/instructions directory if it does not already exist.
Optionally, create subdirectories of .github/instructions to organize your instruction files.
Create one or more NAME.instructions.md files, where NAME indicates the purpose of the instructions. The file name must end with .instructions.md.
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.
Optionally, to prevent the file from being used by either Copilot cloud agent or Copilot code review, add the excludeAgent keyword to the frontmatter block. Use either "code-review" or "cloud-agent".

For example, the following file will only be read by Copilot cloud agent.
```
---
applyTo: "**"
excludeAgent: "code-review"
---
```
If the excludeAgent keyword is not included in the front matterblock, both Copilot code review and Copilot cloud agent will use your instructions.
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.

Custom instructions in use

Changes you make to custom instructions files are not immediately available for use in active CLI sessions. To apply your changes, exit the current session and then either resume it (for example, run copilot --continue), or start a new session (for example, use /new from within an interactive session).