What are Copilot instructions?
Copilot instructions are Markdown files in a repository that GitHub Copilot adds to every request it handles there. The repository-wide file is .github/copilot-instructions.md; path-specific files end in .instructions.md and carry an applyTo glob. Copilot Chat, the cloud agent and code review all read them, and a reply lists the file among its references.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
Create .github/copilot-instructions.md and write it in Markdown: what the project is, how to build and test it, the conventions. It is live once saved.
For rules that only fit some files, add NAME.instructions.md under .github/instructions with applyTo front matter, for example applyTo: "**/*.ts,**/*.tsx".
When you ask Copilot something in that repository, it adds the repository-wide file plus any path-specific file whose glob matches the file it is working on.
Personal instructions outrank repository instructions, which outrank organization instructions, but every relevant set is sent. Avoiding conflicts is your job.
To see what was used, expand the references at the top of a response. The instructions file is listed there and opens when you click it.
Source: GitHub Docs: Adding repository custom instructions for GitHub Copilot
Copilot instructions versus AGENTS.md
GitHub documents three file types under the same heading. The repository-wide file, .github/copilot-instructions.md, is Copilot's own format and applies to the whole repository. Path-specific files, .github/instructions/NAME.instructions.md, carry an applyTo glob and load when Copilot works on a matching file. AGENTS.md is the cross-agent format: you can have several in one repository, and the nearest one up the directory tree takes precedence. A single CLAUDE.md or GEMINI.md in the root is accepted as an alternative.
Pick by audience. If Codex, Cursor or Claude Code also work in the repository, put the shared facts in AGENTS.md and keep copilot-instructions.md for things only Copilot needs, such as how it should behave in code review. Whitespace between instructions is ignored, so lay the file out for people, not for the parser.
Example: a path-specific file for database models
---
applyTo: "app/models/**/*.rb"
excludeAgent: "code-review"
---
Every model needs a matching factory in spec/factories.
Run bin/rails db:migrate:status before changing a migration.
Because of applyTo, this loads only when Copilot is editing a model file. excludeAgent keeps it out of code review; leave it off and both the cloud agent and code review use the file. Several patterns go in one comma-separated string, such as "**/*.ts,**/*.tsx".
Where the files live and who reads them
Everything lives in the repository and ships with it. On GitHub.com, path-specific files are currently used by the cloud agent and code review; Copilot Chat on the site uses the repository-wide file, and attaching the repository to a chat starts a conversation under its instructions. In VS Code, the editor also searches .github/instructions recursively, reads a personal always-on file at ~/.copilot/copilot-instructions.md, and attaches an .instructions.md file whenever its applyTo pattern matches a file the agent creates or modifies. A file with neither description nor applyTo has to be attached by hand.
Three layers can apply at once: personal, repository and organization instructions. Priority runs in that order, but all three are sent, so a contradiction between them is not resolved for you. For pull request reviews, Copilot reads the head branch. Custom instructions for code review can be turned off in the repository's settings on GitHub.com.
Common mistakes
- Writing task instructions. GitHub's own prompt for generating the file says it must not be task specific and should fit in two pages. Describe the project; don't script a single job.
- Repeating the linter. Rules a formatter already enforces waste the budget. Spend it on non-obvious things: build commands with tool versions, known workarounds, CI checks.
- Assuming it was used. Open the references list on the reply. If the file isn't there, it wasn't loaded.
- Expecting it in inline completions. Instructions shape chat and agents, not the ghost text as you type.
FAQ
- Does Copilot read AGENTS.md as well as copilot-instructions.md?
- Yes. You can keep one or more AGENTS.md files anywhere in the repository and the nearest one in the directory tree takes precedence; a single CLAUDE.md or GEMINI.md in the root works too. When a path-specific file matches and a repository-wide file exists, Copilot uses both.
- Why are my Copilot instructions not applied in VS Code?
- VS Code's local harness only discovers .github/copilot-instructions.md when the setting github.copilot.chat.codeGeneration.useInstructionFiles is on. Expand References on the reply to see what loaded. Instructions never affect inline suggestions while you type, only chat.
- Which branch does Copilot code review take its instructions from?
- The head branch of the pull request, not the base branch. A pull request that edits the instructions file is reviewed under the new rules, so review that change like any other.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.