You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/copilot/how-tos/copilot-cli/cli-best-practices.md
+3-11Lines changed: 3 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,21 +27,13 @@ This article provides tips for getting the most out of {% data variables.copilot
27
27
28
28
### Use custom instructions files
29
29
30
-
{% data variables.copilot.copilot_cli_short %} automatically reads instructions from multiple locations, allowing you to define organization-wide standards and repository-specific conventions.
30
+
{% data variables.copilot.copilot_cli_short %} automatically combines applicable user-level, repository, and path-specific instructions. Use repository instructions for project conventions and user-level instructions for preferences that should apply across projects.
|`{% data variables.product.prodname_copilot_short %}.md`, `GEMINI.md`, `CODEX.md`| Repository |
32
+
For the complete list of supported locations and details about discovery, file references, and how multiple instruction files interact, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions).
41
33
42
34
#### Best practice
43
35
44
-
Repository instructions **always take precedence** over global instructions. Use this to enforce team conventions. For example, this is a simple `.github/copilot-instructions.md` file.
36
+
Avoid conflicting instructions. For example, this is a simple `.github/copilot-instructions.md` file.
Copy file name to clipboardExpand all lines: content/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions.md
+23-30Lines changed: 23 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,43 +19,30 @@ docsTeamMetrics:
19
19
20
20
## Types of custom instructions
21
21
22
-
{% data variables.copilot.copilot_cli %} supports the following types of custom instructions.
22
+
{% data variables.copilot.copilot_cli %} supports instructions from the following locations.
23
23
24
-
### Repository-wide custom instructions
24
+
Unless noted in the table below, {% data variables.copilot.copilot_cli_short %} 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.
25
25
26
-
These apply to all requests made in the context of a repository.
26
+
| Location | Scope and behavior |
27
+
| --- | --- |
28
+
|`$HOME/.copilot/copilot-instructions.md`| User-level instructions that apply across repositories. |
|`.github/copilot-instructions.md`| Repository-wide instructions, discovered in the standard locations. |
31
+
|`.github/instructions/**/*.instructions.md`| Modular repository instructions, discovered in the standard locations but not intermediate directories. |
32
+
|`AGENTS.md`| Agent instructions, discovered in the standard locations. For more information, see the [agentsmd/agents.md repository](https://github.com/agentsmd/agents.md). |
33
+
|`CLAUDE.md`| Agent instructions, discovered in the standard locations. {% data variables.copilot.copilot_cli_short %} also uses `.claude/CLAUDE.md`. |
34
+
|`GEMINI.md`| Agent instructions, discovered in the standard locations. |
35
+
| Directories listed in `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`| Additional `AGENTS.md` and `*.instructions.md` files. Separate multiple directories with commas. |
27
36
28
-
These are specified in a `copilot-instructions.md` file in the `.github` directory at the root of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions).
37
+
If you set the `COPILOT_HOME` environment variable, {% data variables.copilot.copilot_cli_short %} uses that directory instead of `$HOME/.copilot` for both user-level instruction locations.
29
38
30
-
### Path-specific custom instructions
39
+
Use the `/instructions` command to view the instruction files discovered for the current session and enable or disable individual files.
31
40
32
-
These apply to requests made in the context of files that match a specified path.
41
+
## How multiple instruction files interact
33
42
34
-
These are specified in one or more `NAME.instructions.md`files within or below the `.github/instructions` directory at the root of the repository, or within or below a `.github/instructions` directory in the current working directory. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions).
43
+
When multiple applicable user-level and repository instruction files exist, {% data variables.copilot.copilot_cli_short %} 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.
35
44
36
-
If the path you specify in these instructions matches a file that {% data variables.product.prodname_copilot_short %} 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 {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic.
37
-
38
-
### Agent instructions
39
-
40
-
These are used by various AI agents.
41
-
42
-
You can create one or more `AGENTS.md` files. These can be located in the repository's root directory, in the current working directory, or in any of the directories specified by a comma-separated list of paths in the `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` environment variable.
43
-
44
-
Instructions in the `AGENTS.md` file in the root directory, if found, are treated as primary instructions. If an `AGENTS.md` file and a `.github/copilot-instructions.md` file are both found at the root of the repository, the instructions in both files are used.
45
-
46
-
Instructions found in other `AGENTS.md` files are treated as additional instructions. Any primary instructions that are found are likely to have more effect on {% data variables.product.prodname_copilot_short %}'s responses than additional instructions.
47
-
48
-
For more information, see the [agentsmd/agents.md repository](https://github.com/agentsmd/agents.md).
49
-
50
-
Alternatively, you can use `CLAUDE.md` and `GEMINI.md` files. These must be located at the root of the repository.
51
-
52
-
### Local instructions
53
-
54
-
These apply within a specific local environment.
55
-
56
-
You can specify instructions within your own home directory, by creating a file at `$HOME/.copilot/copilot-instructions.md`.
57
-
58
-
You can also set the `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` environment variable to a comma-separated list of directories. {% data variables.copilot.copilot_cli_short %} will look for an `AGENTS.md` file, and any `.github/instructions/**/*.instructions.md` files, in each of these directories.
45
+
Path-specific instructions are included only when their `applyTo` value matches a file that {% data variables.copilot.copilot_cli_short %} is working with. An instruction file that you disable using `/instructions` is not included.
59
46
60
47
## Creating repository-wide custom instructions
61
48
@@ -69,6 +56,12 @@ You can also set the `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` environment variable to
69
56
70
57
For help on writing effective custom instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization#writing-effective-custom-instructions).
71
58
59
+
### Referencing other files
60
+
61
+
In `.github/copilot-instructions.md`, `AGENTS.md`, or `CLAUDE.md`, use `@` followed by a relative path to include another file. {% data variables.copilot.copilot_cli_short %} reads the referenced file immediately and supports references within referenced files.
62
+
63
+
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.
64
+
72
65
## Creating path-specific custom instructions
73
66
74
67
{% data reusables.copilot.custom-instructions-path %}
Copy file name to clipboardExpand all lines: content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,11 @@ You can allow or deny permissions for tools either when you start the CLI or dur
24
24
25
25
## Persisted permissions
26
26
27
-
If you answer "yes, always" or otherwise choose the option to allow similar requests for the current location, the approval is saved to `permissions-config.json` in your configuration directory (by default, `~/.copilot/permissions-config.json`).
27
+
Some prompt options save your consent so you aren't asked again. Where your approval is stored depends on what you approved.
28
+
29
+
When you approve a tool for the current location, the approval is saved to `permissions-config.json` in your configuration directory. By default, this file is `~/.copilot/permissions-config.json`. For example, you might choose "don't ask again in this repo" (or "in this directory") for a shell command, file write, MCP tool, or memory update. The approval is scoped to the current location: either the Git repository root, or the working directory if you aren't in a repository. Any directories you grant access to are saved to the same file.
30
+
31
+
URL approvals work differently. When you approve a URL permanently, its domain is added to the `allowedUrls` list in your `settings.json`. By default, this file is `~/.copilot/settings.json`. This approval applies across all your sessions, rather than being tied to a single location.
28
32
29
33
Command-line options such as `--allow-tool` and `--deny-tool` apply only to the current session and aren't written to `permissions-config.json`. Deny rules still take precedence over saved approvals.
The CLI uses only the first applicable configuration directory in this order. It doesn't also load `permissions-config.json` from the lower-priority locations.
143
+
142
144
The `--config-dir` option is a legacy option. Prefer `COPILOT_HOME` when you need to change the configuration directory.
143
145
144
146
On Windows, the default file is typically:
@@ -206,16 +208,14 @@ For MCP approvals, `serverName` must match the configured MCP server name exactl
206
208
207
209
#### Shell command matching
208
210
209
-
`commandIdentifiers`match the command identifiers extracted from a shell request. Matching is exact except for the `:*`suffix.
211
+
`permissions-config.json` doesn't support regular expressions or general glob patterns. String values are matched literally, except that a trailing `:*` in a shell `commandIdentifiers`value matches the text before `:*`, either by itself or followed by a space and more text. A plain `*` has no special meaning, so `git*`doesn't match `git status`.
The `:*` suffix isn't a general glob pattern. It matches the exact stem, or the stem followed by a space and more text.
218
-
219
219
#### Directory matching
220
220
221
221
`allowed_directories` entries allow {% data variables.copilot.copilot_cli_short %} to access paths inside those directories without a separate path prompt. They don't approve the tool operation itself. For example, editing a file in an allowed directory can still require a `write` approval.
0 commit comments