GitHub Copilot Custom Instructions Explained

“Custom instructions” is not one feature. It is five mechanisms with different scopes, different file locations, and — this is the part that catches people — different support across the nine places you can use Copilot.

The single most common claim in third-party writing about this is that custom instructions work everywhere. That is wrong in both directions: some mechanisms are much narrower than assumed, and AGENTS.md is broader.

The five mechanisms

Personal instructions describe how you want Copilot to respond, across every repository. Configured in GitHub settings, and for the CLI in ~/.copilot/copilot-instructions.md.

Repository-wide instructions live at .github/copilot-instructions.md and describe the project. Broadest support of anything here.

Path-specific instructions live at .github/instructions/**/*.instructions.md and apply to files matching a glob declared in frontmatter.

Agent instructions are AGENTS.md — plus CLAUDE.md and GEMINI.md — and can sit anywhere in the tree, with the nearest file to the work taking precedence.

Organization instructions are configured in organization settings and apply across repositories.

Who supports what

This matrix is the reason this lesson exists. It was verified against GitHub’s own support reference on 2026-08-24.

Read down the columns rather than across the rows, because the surprises here are per-surface rather than per-mechanism:

VS Code chat does not support personal instructions. Repository, path-specific and AGENTS.md all work; your personal preferences do not follow you there.

Eclipse chat supports repository-wide instructions and nothing else. Eclipse code review supports none.

Visual Studio chat has no AGENTS.md support, unlike every other IDE listed.

The CLI supports the most of any single surface: repository, path-specific, AGENTS.md and personal instructions all reach it.

Code review varies by where it runs — repository-wide only in VS Code and Visual Studio, more on GitHub.com and JetBrains, nothing in Eclipse. This one catches teams out, because review is where they most want their standards applied and it is the surface with the least consistent support.

Why the variation exists

The support gaps are not arbitrary, and understanding the pattern makes them easier to remember than the table.

Repository-wide instructions are the oldest and simplest mechanism: one file, one known location, no frontmatter to parse and no glob matching. Every client can implement that cheaply, which is why every client has.

Path-specific instructions require glob evaluation against the file being worked on, which means the client must know which file that is. Surfaces without a strong notion of “the current file” have less reason to implement it.

AGENTS.md is a cross-vendor convention rather than a GitHub-specific one, which is why it appears in the agentic surfaces — the CLI, the cloud agent, the IDE agents — and not in every chat implementation.

Personal instructions require the client to fetch per-user configuration, which is a different integration from reading a file in the repository.

None of this is a promise about the future. Support has been expanding, and a gap today may close. It is a reason to check rather than to assume in either direction.

Scope, and choosing between them

The mechanisms differ by who and what they apply to.

Two decisions follow from this.

Is this about you or about the project? A preference for terse explanations is personal. A requirement to run the formatter is the project’s. Putting a personal preference in a repository file imposes it on colleagues who did not agree to it, and they will discover it as unexplained behaviour rather than as a decision anyone made.

Does it apply everywhere in the repository, or only to part of it? Test conventions and application conventions frequently contradict each other — mocking is fine in one and a smell in the other. That is what path-specific files are for.

Path-specific instructions

Frontmatter declares the glob:

---
applyTo: "tests/**/*.py"
---

# Test conventions

- Use pytest, not unittest.
- Cover the failure case, not only the success case.
- No network access. No writes outside tmp_path.
- Tests must be deterministic: no wall-clock time, no unseeded randomness.

Multiple patterns go in one quoted string, comma-separated:

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

An optional excludeAgent keyword excludes a file from code-review or cloud-agent — useful when a rule is about how to write code rather than how to review it.

AGENTS.md and monorepos

AGENTS.md differs in one important way: it can live anywhere, and the nearest file to the work wins.

The root file carries what is true everywhere — layout, commit convention, review process. Each package carries its own language, test runner and constraints.

This solves a genuine problem. A monorepo with a Go service, a TypeScript frontend and a Python pipeline cannot describe its conventions in one file without most of the content being irrelevant to any given task.

CLAUDE.md and GEMINI.md at the repository root are also recognised — a compatibility affordance so a repository already configured for another agent is not starting from nothing.

Precedence

GitHub documents the ordering as personal first, then repository, then organization — with all relevant sets provided to Copilot rather than one overriding another.

That last clause explains a class of confusing behaviour. If a personal instruction and a repository instruction disagree, the model is not applying a rule to pick a winner. It receives both and reconciles them, and the resolution may not be the one you expect.

What belongs in instructions

The test is durability. Instructions describe conventions that hold across many tasks; they are not a place for today’s work.

Good:

Use pytest for tests.
Do not add dependencies without explaining why.
Run Ruff before considering Python changes complete.
Business logic belongs in src/services/, not in HTTP handlers.

Bad:

Fix issue #247 today.
Focus on the login bug this sprint.

The second set will still be there in six months, quietly instructing an agent about a sprint that ended. Task-shaped content belongs in a prompt, or — if you repeat it often enough to be annoyed by retyping it — in a prompt file.

Rules the model can act on

The difference between an instruction that changes behaviour and one that does not is usually whether it names something concrete.

Rules that name a command, a path, or a defined action when blocked work. Rules that name a quality — “write maintainable code”, “follow best practices” — do not, because there is no observation the model can make to tell whether it complied.

The test: could you check compliance by looking at the output? If not, neither can the model.

Writing instructions that survive

Instruction files fail in two directions, and both are common enough to be worth naming.

Too long. A file with forty rules does not get forty rules followed. It competes with itself, and it competes with the code the model needs to read — instructions occupy the same finite context window as everything else. The rules most likely to be lost under context pressure are the specific ones near the bottom, which are usually the ones you added because something went wrong.

Too vague. A file full of aspirations reads well to a human and gives a model nothing to act on. “Write clean, maintainable code” is not a rule; it is a sentiment.

The shape that works is short and concrete:

# Project conventions

## Environment
- Python 3.12, virtual environment at `.venv`.
- Invoke tools as `.venv/bin/python -m <tool>`, never bare.

## Before completing a task
- Run `.venv/bin/python -m pytest -q` and report the actual output.
- Run `.venv/bin/python -m ruff check .` and fix what it reports.

## Constraints
- Do not modify tests to make them pass. Fix the cause, or stop and explain.
- Do not add dependencies. If one seems necessary, explain why and wait.
- Business logic belongs in `src/services/`, not in HTTP handlers.

Eight rules. Every one checkable, and every one something you would otherwise be typing into a prompt.

How long is too long

There is no published limit, and the useful heuristic is behavioural rather than numeric: if the model reliably follows the rules at the top of your file and drifts on the ones at the bottom, the file is too long.

In practice most teams land somewhere between eight and twenty rules for a repository file, with anything longer either splitting into path-specific files or being a sign that documentation is being pasted where a link belongs.

If you genuinely have a hundred pages of standards, the instruction file should contain the dozen rules that matter most and a pointer to the rest. A model given a link cannot follow it; a model given a hundred pages follows none of them particularly well.

Keeping them true

Instruction files rot in a specific way: the project changes and the file does not, so it now confidently describes something that used to be true. That is worse than having no file.

Three habits keep them current.

Update instructions in the same pull request as the change. Migrating from pip to uv means the instruction file changes in that pull request, not later. Treated as follow-up work, it does not happen.

Read them when onboarding someone. If a rule needs explaining to a new colleague, it needs rewriting for the model too — the ambiguity is in the text.

Notice when you correct the model. A correction you type twice is either a missing instruction or a broken one, and that signal arrives naturally in the course of work.

Instructions are not enforcement

An instruction saying “never commit secrets” makes that behaviour less likely. It does not make it impossible, and treating it as a control is a mistake teams make regularly.

For anything that must not happen, the mechanism is a permission or a scanner, not a sentence. Cluster 5’s custom agents lesson draws that line precisely: prose describes intent, capability decides what is possible.

Instructions among the other mechanisms

Instructions are one of several customization surfaces, and reaching for the wrong one produces something awkward. The distinction is when it applies and whether the model can decline.

Instructions are always-on prose. They apply automatically within their scope, cost context on every request, and are advisory.

Prompt files at .github/prompts/*.prompt.md are invoked deliberately. Same kind of content, different trigger — and a much narrower support matrix, covered in the prompt files lesson.

Agent skills are folders of instructions and resources loaded when relevant to a task, discovered from .github/skills/, .claude/skills/, .agents/skills/ and their personal equivalents. A skill is a packaged procedure rather than a standing rule.

Custom agents at .github/agents/ package a role with a restricted tool list. Where an instruction says “do not modify files”, an agent whose tools omit edit cannot — which is the difference between guidance and capability.

Hooks at .github/hooks/*.json run shell commands at defined points. They execute rather than advise, which makes them the enforcement mechanism of the set and the one to review most carefully in someone else’s repository.

The rule of thumb: instructions for “usually do it this way”, prompt files for “here is a task I repeat”, skills for “here is how to do this particular thing”, agents for “this role has these capabilities”, hooks for “this must happen every time”.

Organization instructions and governance

Organization-level instructions apply across repositories and are configured in settings rather than committed to a repo. They reach GitHub.com chat, the cloud agent and code review.

Two things are worth being careful about.

Do not assume they override repository instructions. GitHub documents the precedence order and documents that all relevant sets are provided. Nothing in that says an organization rule wins a contradiction, and writing organization rules that contradict repository rules produces behaviour nobody can predict.

They are invisible to the developer. Someone debugging why Copilot behaves oddly in their repository cannot see an organization instruction from inside their editor. If your organization sets them, tell people they exist and what they say.

Seeing what is actually in force

In the CLI, /instructions lists the files loaded and lets you toggle them, and /env shows the complete picture including agents, hooks and MCP servers. --no-custom-instructions disables loading entirely, which is the fastest way to test whether an instruction file is the cause of a problem.

Asking the model to restate the rules is a genuinely useful check. If it cannot summarise them, they are not loaded, too long, or ambiguous — and all three are worth knowing before you rely on them. Run it once after writing a file and once again a few months later, when you have forgotten what is in it.

Common mistakes

Assuming universal support. The matrix above exists because this is the default assumption and it is wrong. Check before relying on a mechanism.

Personal preferences in repository files. Your taste in explanation length is not a project convention, and committing it imposes it on everyone.

Duplicating what the model already knows. It knows PEP 8. It does not know that your team rejected a linting rule for a specific reason — write the second, not the first.

Duplicating what a linter enforces. If a rule is checked automatically, the check is more reliable than the instruction and the instruction is now maintenance. Write instructions for things tools cannot check.

Contradicting yourself across scopes. A repository file and a path-specific file that disagree produce unpredictable behaviour, because both are supplied.

Forgetting the file exists. Six months on, instructions describe a framework you migrated away from — and the model follows them confidently.

Treating instructions as a security control. They are guidance. Secret scanning, branch protection and tool permissions are controls.

A useful framing

Instructions are the answer to: what would I tell a competent new colleague on their first day that they could not work out by reading the code?

That excludes language basics, which they know. It excludes anything obvious from the repository, which they will read. What remains is the history, the constraints, and the commands — which is exactly the right content, and it is usually shorter than people expect.

Next

Building a copilot-instructions.md file is the hands-on version of this lesson. Prompt files covers the invoked counterpart to always-on instructions, and team coding standards is how several of these mechanisms combine into something a team owns.

For the CLI’s implementation specifically, Cluster 5 covers custom instructions in that context.