Where does GitHub Copilot's repository-wide instructions file live, and how do you confirm Copilot actually used it?
answer
- a Markdown file in a dot-folder
- same name as the product
- added silently to every request
- check the response's References list
- ghost text ignores it
basics
~20 sCopilot reads repository-wide instructions from .github/copilot-instructions.md at the repository root and adds them to every request made in that repository. In VS Code or GitHub.com chat, the file appears in the response's References list when it was sent.
solid answer
~40 sThe file is `.github/copilot-instructions.md`, created at the repository root, written as natural-language Markdown. Copilot adds it automatically to every request made in the context of the repository: On GitHub.com and in VS Code, Copilot Chat, the cloud agent and Copilot code review read it, and so does Copilot CLI. The instructions are not shown in the chat, so you verify them by expanding **References** on a response and looking for `.github/copilot-instructions.md`. In VS Code the behaviour is on by default and controlled by **Code Generation: Use Instruction Files** (`github.copilot.chat.codeGeneration.useInstructionFiles`). Two limits are worth saying out loud: inline suggestions as you type do not use custom instructions, and the docs warn that Copilot may not follow them the same way every time.
code
markdown · 14 lines# Project instructions
This service is a REST API written in TypeScript on Node.js.
## Coding standards
- Use early returns instead of nested conditionals.
- Put HTTP handlers under `src/api/routes`.
- Keep database access in `src/repositories`.
## Validation
- Run `npm test` after changing application code.
- Add or update a test for every behaviour change.go deeper
Recall the exact path, .github/copilot-instructions.md at the repository root, and that you confirm it through the References list rather than expecting the text to appear in chat.
Explain which surfaces read the file, that it is added automatically to every repository request, that inline suggestions ignore it, and which switch disables it for chat versus code review.
Show you keep the file short and broadly applicable, because every request pays for it, and that you verify adoption from References and generated output rather than trusting the file's existence.
Frame the file as the team's cheapest shared guidance and weigh what belongs there against path-scoped files, organization instructions and real enforcement in CI, since instructions steer but never guarantee.
## What the file is GitHub Copilot supports several kinds of **repository custom instructions**. The broadest is the **repository-wide** file: `.github/copilot-instructions.md`, stored in the `.github` directory at the root of the repository (create the directory if it does not exist). It holds natural-language instructions in Markdown. Whitespace between instructions is ignored, so you can write one paragraph, one instruction per line, or blank-line-separated blocks. Copilot adds the file's contents automatically to requests made in the context of the repository. Nobody has to mention it, attach it or type a command: the instructions are available as soon as the file is saved. Because they travel with every request, the docs advise keeping them short, self-contained and broadly applicable, for example: - the project's purpose and its main libraries and frameworks; - coding standards such as naming or early returns; - how to build, test and validate a change; - architectural patterns to follow or avoid. ## Which Copilot surfaces read it The repository-wide file is the one type that almost every Copilot surface supports, which is why it is the first file a team writes. | Surface | Reads `.github/copilot-instructions.md`? | |---|---| | Copilot Chat on GitHub.com | Yes, when the repository is attached to the conversation | | Copilot Chat and the agent in VS Code | Yes, on by default | | Copilot cloud agent | Yes | | Copilot code review | Yes, unless the repository turns custom instructions off for reviews | | Copilot CLI | Yes | | Inline suggestions as you type | No | The last row trips people up. VS Code's documentation states plainly that custom instructions are **not** taken into account for inline suggestions, so a rule such as "never use the legacy HTTP client" can steer a chat answer and still be ignored by ghost text. ## How to confirm it was used The instructions are added to the prompt but **not displayed** in the Chat view or inline chat. To check them: 1. Ask a question in Copilot Chat in the repository. 2. Expand the **References** list at the top of the response. 3. Look for `.github/copilot-instructions.md`; selecting it opens the file. If the file is missing from References in VS Code, check that the setting **Code Generation: Use Instruction Files** (`github.copilot.chat.codeGeneration.useInstructionFiles`, default `true`) has not been cleared. That setting affects only your own Chat use. For Copilot code review the switch lives on GitHub.com instead: the repository setting **Use custom instructions when reviewing pull requests**, enabled by default. A file that appears in References is still guidance, not enforcement. The docs note that, because of the non-deterministic nature of AI, Copilot may not follow custom instructions in exactly the same way every time. ## Getting a first version written You do not have to start from a blank page: - From the agents tab on GitHub.com you can ask **Copilot cloud agent** to onboard the repository; it opens a draft pull request containing a generated `copilot-instructions.md` and adds you as a reviewer. - The first time the cloud agent opens a pull request in a repository, it leaves a comment with a link to generate the file. - In a VS Code Local session, typing `/init` in chat generates project-wide instructions. Review generated text before merging it: commands and paths in it may be wrong, and a wrong build command repeated on every request costs more than a missing one. ## Where it sits among the other files The repository-wide file is one of three repository types. **Path-specific** files (`.github/instructions/**/*.instructions.md` with an `applyTo` glob) add rules for matching files only, and **agent instructions** (`AGENTS.md`, or a single root `CLAUDE.md` or `GEMINI.md`) are read by agent-style surfaces. When a path-specific file matches the file Copilot is working on and the repository-wide file also exists, Copilot uses both. Personal and organization instructions can be layered on top. Reusable prompt files are a different feature: they run only when someone invokes them, whereas this file is always on. ## Common mistakes - **Wrong location**: a `copilot-instructions.md` at the repository root, outside `.github`, is not the repository-wide file. - **Task-specific content**: instructions such as "fix the login bug first" go stale; the file should hold standing rules, not a to-do list. - **Expecting enforcement**: a rule that must never be broken also needs a linter, a test or a required check, because the file only steers the model. - **Overloading it**: language- or folder-specific rules belong in path-specific files, so that they are not sent with requests about unrelated code.
- Why might a rule in copilot-instructions.md steer chat answers but not the ghost text you see while typing?VS Code's documentation says custom instructions are not taken into account for inline suggestions as you type. The file is added to chat and agent requests, so a convention written there shapes Chat view answers and agent edits, while ghost text is generated without it. If a completion keeps contradicting the file, the instruction file is not the lever for that surface.
- A teammate disabled custom instructions in their VS Code settings. Does that change what Copilot code review reads on your pull requests?No. The VS Code checkbox Code Generation: Use Instruction Files applies only to that person's own Copilot Chat use. Copilot code review on GitHub.com has its own repository setting, Use custom instructions when reviewing pull requests, which is enabled by default and applies to every review in the repository.
- You must mention or attach copilot-instructions.md in each chat prompt.
- The file goes in the repository root as copilot-instructions.md, outside .github.
- Instructions in the file also govern inline ghost-text suggestions.
- If the file is listed in References, Copilot is guaranteed to obey it.
- Copilot shows the instruction text at the top of every chat answer.