Where does copilot-instructions.md go?
Inside the .github directory at the repository root, as .github/copilot-instructions.md. Path-specific files go in .github/instructions and end in .instructions.md.
GitHub Copilot reads repository-wide instructions from .github/copilot-instructions.md and path-specific ones from .github/instructions. Which other files it reads depends on where you use Copilot.
.github/copilot-instructions.md is GitHub Copilot's repository-wide instructions file. It is plain Markdown that Copilot adds to requests made in the context of the repository. It is the one instructions file that every Copilot surface with custom instruction support reads.
Last verified 2026-11-13 against the vendor documentation. GitHub's support matrix differs by surface:
| Surface | copilot-instructions.md | .instructions.md | AGENTS.md / CLAUDE.md / GEMINI.md |
|---|---|---|---|
| Copilot Chat on GitHub.com | Yes | No | No |
| Cloud agent (GitHub.com) | Yes | Yes | Yes, all three |
| Code review (GitHub.com) | Yes | Yes | Yes, plus REVIEW.md |
| VS Code chat | Yes | Yes | AGENTS.md only |
| Visual Studio chat | Yes | Yes | No |
| JetBrains chat | Yes | Yes | No |
| Copilot CLI | Yes | Yes | Yes, all three |
Because several chat surfaces read only copilot-instructions.md, a file that merely says "see AGENTS.md" leaves them with nothing useful. Keep the essentials inline. The full cross-tool view is on the compatibility page.
The pattern 2prompt generates: a pointer to AGENTS.md for surfaces that read it, plus the essentials inline for those that do not.
# Copilot instructions
Project: shop-api. Order and checkout API for the storefront.
The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.
## Stack
- Language: TypeScript
- Framework: Fastify
- Database: PostgreSQL
- Tests: Vitest
- Package manager: pnpm
## Commands
- Install dependencies: `pnpm install`
- Run locally: `pnpm dev`
- Run all tests: `pnpm test`
- Lint: `pnpm lint`
- Type-check: `pnpm tsc --noEmit`
## Working rules
- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
Files named NAME.instructions.md under .github/instructions/ apply only to matching paths, declared with an applyTo glob in frontmatter:
---
applyTo: "src/db/**/*.ts"
---
- Use parameterized queries only.
- Every new migration needs a matching rollback.We did not find a hard character limit in GitHub's documentation on the verification date, so check GitHub's docs for current guidance. Practically, the file is added to many requests, so keep it to a screen or two: the stack, the commands, and the handful of rules that prevent the most common bad suggestions.
Because this file reaches every Copilot surface, it should hold the rules whose absence causes the most rework: the package manager, the commands that prove a change works, and the handful of constraints a reviewer would reject a pull request for. It is a poor place for long explanations of architecture or history.
A short file that is always right beats a long one that is half stale.
One practical test: open the file and ask whether a new contributor would learn something concrete from every line. If a line would only make sense to someone who already knows the project, move it to AGENTS.md or delete it.
Generate a matched pair with the generator, check an existing file with the linter, convert one with the copilot-instructions.md to AGENTS.md converter, or read AGENTS.md vs copilot-instructions.md.
Inside the .github directory at the repository root, as .github/copilot-instructions.md. Path-specific files go in .github/instructions and end in .instructions.md.
In some places. The cloud agent, code review and the Copilot CLI read AGENTS.md, CLAUDE.md and GEMINI.md, and VS Code chat reads AGENTS.md. Copilot Chat on GitHub.com, Visual Studio and JetBrains chat do not, according to the GitHub support matrix.
applyTo is the frontmatter field in a path-specific .instructions.md file. It holds a glob such as src/db/**/*.ts, and the instructions apply only when Copilot works on files that match it.
No. Several Copilot chat surfaces read only copilot-instructions.md, so a pointer alone leaves them without instructions. Keep the stack, commands and key rules inline and point to AGENTS.md for the rest.