How to Settle Which Copilot Instructions File Gets Read on Each Surface (2026 Guide)

GitHub publishes the list in full, introducing it as "The following list shows the complete order of precedence, with instructions higher in this list taking precedence over those lower in the list." The entries, in that order, are: personal instructions; then repository custom instructions, which are themselves ordered as "Path-specific instructions in any applicable .github/instructions/**/*.instructions.md file", then "Repository-wide instructions in the .github/copilot-instructions.md file", then "Agent instructions (for example, in an AGENTS.md file)"; and finally organization custom instructions.

Three things in that list surprise people.

Personal beats everything. Most instruction systems in software put the organisation at the top and the individual at the bottom. Copilot does the reverse, and it is deliberate: an organisation instruction to always answer in one language is a default, not a mandate, and an individual can override it. GitHub is explicit that organisation instructions "are used for all members of the organization, irrespective of whether they receive their Copilot subscription from that organization" — they apply broadly, and they still sit last.

Agent files sit below the repository files. AGENTS.md, CLAUDE.md and GEMINI.md are listed beneath both .github/instructions/**/*.instructions.md and .github/copilot-instructions.md. Teams that migrated to a vendor-neutral agent file and left the older repository file in place have, without meaning to, demoted the newer file. The migration direction itself is a real exercise with its own trade-offs, which we worked through in moving a CLAUDE.md into AGENTS.md and, for this specific destination, moving a CLAUDE.md into Copilot.

Nothing is discarded. This is the sentence that changes how you should read the whole list: "However, all sets of relevant instructions are provided to Copilot." Precedence here is not a filter that drops the losers. Every applicable set is handed to the model, and the order describes which one wins where they conflict. So a contradictory rule you forgot to delete is still in the prompt, still consuming attention, still occasionally winning on a phrasing you did not anticipate. GitHub's advice follows directly: "Whenever possible, try to avoid providing conflicting sets of instructions."

Underneath all of that sits the coverage question. Of agent instructions, GitHub writes that they are "similar to repository-wide custom instructions, but are currently not supported by all Copilot features," and that they "are specified in files called AGENTS.md, CLAUDE.md, or GEMINI.md." For organisation instructions, the support note is narrower still: "Organization custom instructions are currently only supported for Copilot Chat on GitHub.com, Copilot code review on GitHub.com and Copilot cloud agent on GitHub.com."

Read those two notes together and the practical shape emerges. Which file governs a response depends on which Copilot surface you are in, and the same repository can behave differently in the editor, in chat on GitHub.com, and in a pull request review — with no message anywhere saying which rules were loaded. That is the general failure mode we described in why agents quietly skip your instruction files.

Adding the rule again, one level up. The instinct when a rule is ignored is to escalate it: if the repository file is not working, put it in the organisation settings. Given the published order, that moves the rule down the precedence list, not up. If a personal instruction is contradicting it, escalating makes the contradiction worse.

Consolidating everything into one file. Reasonable, and it does remove conflicts. It also throws away the one thing path-scoped instructions do well: .github/instructions/**/*.instructions.md applies where it matches, which is how you keep front-end conventions out of a back-end answer. Collapsing everything into a single repository-wide file makes every rule global.

Deleting the old file without checking which surface reads which. Safe only if you know the answer. Because agent instructions are documented as not supported by every Copilot feature, removing .github/copilot-instructions.md in favour of AGENTS.md can leave some surfaces with nothing at all — and it will not announce that.

Testing in the wrong place. People verify a repository instruction in the editor and conclude it works everywhere, or test in chat on GitHub.com and conclude the reverse. Given the per-surface support notes, one test proves one surface.

Assuming a pull request reads the merged state. It does not. GitHub is specific: "When reviewing a pull request, Copilot reads repository custom instructions, agent instructions, and agent skills from the head branch (the branch with your changes), not the base branch." The upside is stated in the same note — "so you can test changes to them in the same pull request" — and the downside is the mirror image: a branch that has drifted from main reviews itself against its own older rules.

Treating instruction files as a memory layer. They are configuration that is re-read, not a record that accumulates. Setting up the persistent side is a separate exercise, covered in setting up Copilot memory in VS Code.

The goal is not to pick the one true file. It is to be able to answer, in five seconds, which file governs a given response.

Step 1: Write down the order, then check which files you actually have

Start by listing what exists in the repository: a path-scoped instructions directory, a repository-wide file, an agent file, or some combination. Then put your personal instructions next to them, because in the published order they outrank all three.

The common discovery at this point is a file nobody remembers adding. Because all applicable sets are provided to Copilot rather than filtered, an abandoned file is not inert — it is still in the prompt. Delete what you are not maintaining, before tuning what you are.

Step 2: Decide scope per rule, not per file

GitHub's own guidance is about scope: custom instructions "are most effective when they are short, self-contained statements," and you should "Consider the scope over which you want the instruction to apply when choosing whether to add an instruction on the personal, repository, or organization level."

That is the right decision axis. A language preference is personal. A framework convention is repository-wide. A rule that only applies to one directory belongs in a path-scoped file, which is the one capability you give up by consolidating. A policy every member should get by default, and may override, is organisational — and worth writing knowing it sits last and is supported on three GitHub.com surfaces.

Step 3: Verify per surface, and verify on the branch you are reviewing

Run the same prompt in each surface your team actually uses, and note where the rule holds. It is a ten-minute exercise that replaces a recurring argument.

For pull requests, remember the head-branch rule. If you change an instruction file and want the review to reflect it, change it in the branch under review. If a long-running branch is producing reviews that ignore a rule everyone agreed to last month, check whether that rule reached the branch. Conflicting layers across a repository are their own maintenance problem, which we took up in reconciling contradictory instruction layers.

Instruction files answer "how should you behave." They are a poor home for "what did we decide and why," which is the thing people keep trying to store in them. MemoryLake is a store you write those decisions into on purpose, kept apart from any one tool's configuration and readable from every assistant you connect. You write the entries yourself, in your own words. Nothing is read out of, written to, or deleted from GitHub's systems or any other vendor's store — your repository files and Copilot settings stay entirely under their own controls.

Step 1: Create an API key

Generate a key from the dashboard. It is what lets Copilot, a terminal agent, and a chat assistant reach the same set of facts without each of them needing its own file.

Step 2: Upload your first memories

Start with the decisions behind the rules: why the convention exists, what it replaced, which approach was ruled out and on what grounds. Instruction files carry the rule; they rarely carry the reason, which is what stops the rule being reversed by the next person.

Step 3: Connect your AI & agents

Point your tools at the layer so those facts load at the start of a session rather than being inferred from a rules file. Then test it the only way that proves anything: ask a different assistant for one of the decisions back. If it answers, your reasoning stopped being tied to one vendor's file format.

The first change is that the precedence argument ends. The order is published, personal outranks organisation, and all sets are provided regardless. Once a team has read the list together, most of the debate turns into a short cleanup.

The second is that coverage becomes the question people actually ask. "Which file wins" matters much less than "which file is even read here," and the per-surface support notes are where the surprises live.

The third is that abandoned files stop being harmless. Because every applicable set reaches the model, an old file is an active participant. Treating deletion as maintenance rather than housekeeping changes behaviour immediately.

The fourth is that pull request reviews become predictable. Reading instructions from the head branch is a sensible design — it lets you test rule changes in the same pull request — and it is only a trap while it is unknown.

Keep one file per scope, and delete the rest. Path-scoped for directory rules, repository-wide for project rules, agent file where your other tools need it, personal for you.

Write short, self-contained statements. GitHub's own guidance, and it matters more when several sets are combined.

Expect personal instructions to win. If a team rule keeps losing, check whether someone's personal settings contradict it before rewriting the repository file.

Verify each surface separately. Agent instructions are documented as not supported by all Copilot features, and organisation instructions as supported on three GitHub.com surfaces.

Change instruction files on the branch under review. Pull request reviews read them from the head branch, not the base branch.

Keep the reasoning somewhere else. A rules file that also carries its own history stops being short, and short is what makes it work.

GitHub publishes the complete precedence order for Copilot instructions, and the shape of it is worth knowing: personal instructions first, then path-scoped repository instructions, then the repository-wide file, then agent files such as AGENTS.md, with organisation instructions last. Every applicable set is still provided to Copilot, so precedence decides conflicts rather than removing losers.

The part that causes more lost afternoons is coverage rather than order. Agent instructions "are currently not supported by all Copilot features," organisation instructions are documented for three GitHub.com surfaces, and pull request reviews read these files from the head branch. A rule can be perfectly written, correctly placed, and simply not loaded where you tested it.

None of this is a flaw, and GitHub documents all of it in the open. The practical move is to hold fewer files, decide each rule's scope deliberately, verify on each surface your team uses, and keep the reasoning behind the rules somewhere a configuration file was never meant to hold.