What Are GitHub Copilot Custom Instructions?

What Are GitHub Copilot Custom Instructions?

Custom instructions are the standing context you give GitHub Copilot once so you stop repeating it in every chat. Your stack, your conventions, the things your team always does differently.

They are mostly plain Markdown files committed to your repository, which makes them reviewable and version-controlled like anything else.

The part worth getting right is not how to write one. It is knowing which file gets read where, because the answer is not the same on every surface and GitHub is careful about what it will and will not promise.

What Is the Short Answer?

Put repository-wide instructions in a file called .github/copilot-instructions.md. Create the .github directory if it does not exist yet.

For rules that should only apply to some files, add one or more files ending in .instructions.md inside .github/instructions/, each with an applyTo glob.

Your personal preferences are a setting rather than a file, configured from Copilot Chat on GitHub and applying only there.

Changes take effect when you save the file. There is no build step and nothing to publish.

Writing standing instructions for how your content should be produced? Get a free SEO audit and start from what your site actually needs.

Which Kinds of Instruction File Does GitHub Support?

There are four, and they do different jobs rather than being alternatives to one another.

Repository-wide instructions

One file, .github/copilot-instructions.md, applying to everything in the repository. This is the one most teams want and the one supported in the most places.

Keep it short. GitHub's guidance is that these are sent along with every chat message, so length has a running cost rather than a one-off one.

Path-specific instructions

These live in .github/instructions/ and the filename must end in .instructions.md. Subdirectories inside that folder are allowed.

Each file carries YAML frontmatter with a required applyTo key holding a glob. That glob is what scopes the file to part of your repository.

When a path-specific file and the repository-wide file both apply to what you are doing, GitHub's documentation says instructions from both are used. They combine rather than compete.

Agent instruction files

Copilot also reads AGENTS.md, the cross-tool convention. GitHub says a repository may hold one or more of these, anywhere in the tree.

Where several exist, the nearest AGENTS.md in the directory tree takes precedence. That is the only nearest-wins rule GitHub publishes anywhere in this system.

As an alternative, Copilot will read a single CLAUDE.md or GEMINI.md file stored in the root of the repository. Note the asymmetry: one file, root only, where AGENTS.md can be many and anywhere.

GitHub adds a caveat on all of these, saying agent instruction files are currently not supported by all Copilot features.

Personal and organization instructions

Personal instructions are set through the UI, not committed anywhere, and GitHub states they are only supported for Copilot Chat on GitHub. Copilot CLI handles personal instructions through local files instead.

Organization instructions are also a UI setting, available to organization owners on a Copilot Business or Copilot Enterprise plan.

The important limit on organization instructions is where they run. GitHub documents them as supported for sessions running on the GitHub website and for Copilot code review, and not supported in local client sessions.

How Do You Add Repository Instructions, Step by Step?

1. Create the file. Add .github/copilot-instructions.md at the root of your repository, creating the .github directory first if needed.
2. Write in plain Markdown. No frontmatter is required for this file. Natural-language statements of your conventions are what it is for.
3. Keep each instruction self-contained. GitHub's advice is to keep them short and broadly applicable, because they ride along with every message.
4. Commit and push it. It is an ordinary file in your repository, so it goes through whatever review process your other files do.
5. Add path-specific files if you need them. Create .github/instructions/backend.instructions.md or similar, with frontmatter at the top:

---
applyTo: "app/models/**/*.rb"
---

1. Use a comma-separated list for several patterns. GitHub's own example covers two extensions at once:

---
applyTo: "**/*.ts,**/*.tsx"
---

1. Confirm it was actually used. In Copilot Chat, expand the References list at the top of a response and look for .github/copilot-instructions.md. You can click through to open it.
2. Check the code review toggle if that is your use case. In the repository, go to Settings, then under "Code, planning, and automation" choose Copilot, then Code review.

What Does applyTo Actually Match?

The applyTo value takes a single string, and the glob behaviour is worth reading carefully because one asterisk and two mean genuinely different things.

A single * matches files in the current directory only. Two, written as ** or **/*, match all files in all directories.

So src/*.py matches only direct children of src, while src/**/*.py matches Python files at any depth beneath it.

A pattern like **/subdir/**/*.py matches inside any directory named subdir, at any depth. And applyTo: "**" means every file in every directory, which is how you write a repository-wide rule in a path-specific file.

There is a second optional key, excludeAgent, which accepts "code-review" or "cloud-agent". GitHub's example combines the two:

---
applyTo: "**"
excludeAgent: "code-review"
---

That file is read by the cloud agent only. Without excludeAgent, both code review and the cloud agent use the file.

GitHub does not publish a formal glob grammar beyond these examples, and every example uses double quotes rather than single.

Want standing rules for your own content that are based on real search data? Request a free audit.

Which File Wins When Two of Them Disagree?

This is the question every guide answers confidently, and it is the one GitHub answers for exactly one surface.

For Copilot Chat on GitHub.com, the order is published: personal instructions, then repository instructions, then organization instructions, and GitHub states that personal instructions take the highest priority.

Everywhere else, GitHub declines to give one. The documentation says most surfaces and clients, including Copilot CLI, Visual Studio Code and Visual Studio, combine applicable instruction files without defining a general precedence order.

That is a deliberate non-answer rather than an omission, and it is the most useful sentence on the page. If you are in your editor, there is no documented tie-breaker to design around.

What GitHub says instead is that all sets of relevant instructions are provided to Copilot, and advises you to avoid writing conflicting sets in the first place.

So the practical rule is not "learn the precedence". It is "do not create the conflict", because nothing is published that would resolve it for you.

What Are the Limitations Worth Knowing?

The first is stated by GitHub and is easy to skip past: Copilot may not always follow your custom instructions in exactly the same way every time they are used.

That is non-determinism acknowledged by the vendor. Instructions shape behaviour, they do not configure it.

The second is scope on GitHub.com. Path-specific instructions are supported there only for the cloud agent and code review, not for Chat, so the file you just wrote may not apply where you first test it.

On github.com/copilot specifically, a conversation uses repository instructions only if you add the repository as an attachment. Nothing happens automatically.

The third is a category of instruction that GitHub says may cause problems, especially in large or diverse repositories.

Three kinds are named: asking Copilot to refer to external resources when answering, instructions dictating a particular answer style, and requests to always answer with a fixed level of detail.

GitHub's own examples of instructions that may not have the intended results include pointing at a styleguide, referencing @terminal, setting a tone, and imposing a character limit on responses.

There is also a compliance disclaimer worth quoting as written: custom instructions do not guarantee that generated content will comply with a policy.

One operational detail for code review: it reads repository instructions, agent instructions and agent skills from the pull request head branch, not the base branch.

And GitHub does not publish a verification method for path-specific files, personal instructions or organization instructions comparable to the References list that confirms the repository-wide one.

Treating your site the way you treat your repo? Get a free SEO audit and see what the standing rules should be.

How Do Instructions Compare to the Alternatives?

Against prompt files, the difference is who chooses. Prompt files live in .github/prompts as .prompt.md files and are picked deliberately per conversation. Instructions apply without being asked for.

Against custom agents, which live in .github/agents, instructions are not a definition of a persona or a toolset. They are context layered onto whatever you are already doing.

Against skills, the distinction is loading. Instructions are always sent; skills are fetched when Copilot judges them relevant. Our guide to GitHub Copilot skills covers that side in detail.

The practical split follows from that. Standing rules that apply everywhere go in instructions. Long procedures that apply occasionally go in skills, so you are not paying for them on every message.

Against simply typing context into chat, instructions win on anything you would otherwise type twice. For a genuine one-off, the prompt is still the right place.

Final Thoughts

Custom instructions are one of the cheapest improvements available in Copilot, and most of the work is deciding what belongs in them rather than where the file goes.

Start with .github/copilot-instructions.md and keep it short. Add path-specific files only when a rule genuinely does not apply repository-wide.

Then verify it once through the References list in Chat, because a file in the right place that is never read looks exactly like a file that is working.

And resist the temptation to build a layered hierarchy that depends on precedence. GitHub publishes an order for one surface and explicitly declines to for the rest, which is as clear a signal as you will get that the hierarchy is not the feature.

Ready to put the same discipline into your content as into your tooling? Start with a free SEO audit.