Does GitHub Copilot Read AGENTS.md? How Instructions Files Work

Yes, GitHub Copilot reads AGENTS.md, but not everywhere. Copilot cloud agent, wherever you start it, and the Copilot CLI read AGENTS.md (and also CLAUDE.md or GEMINI.md). Copilot code review on GitHub.com reads AGENTS.md only, and GitHub lists the same for Copilot Chat in VS Code, though VS Code’s Local agent can also read CLAUDE.md when a setting is on. Copilot Chat on GitHub.com and in Visual Studio, JetBrains IDEs, Eclipse and Xcode do not read it at all; they use .github/copilot-instructions.md. If you want one set of rules to reach every surface, you need both files.

The three kinds of repository instructions

GitHub’s guide to adding repository custom instructions↗ (opens in a new tab) describes three kinds of file you can commit:

• Repository-wide instructions: .github/copilot-instructions.md, applied to every request made in the context of the repository.
• Path-specific instructions: one or more NAME.instructions.md files in or below .github/instructions/, applied when Copilot works on files that match a pattern. Where both apply, Copilot gets both.
• Agent instructions: one or more AGENTS.md files anywhere in the repository, or a single CLAUDE.md or GEMINI.md at the root. These are for agents, as the name says.

There are also personal instructions, kept in your own settings or, for the CLI, under ~/.copilot/, and organisation instructions set by an organisation owner. Those are not in the repository, so they do not travel with the code.

Which Copilot surface reads which file

GitHub keeps a support table for custom instructions↗ (opens in a new tab) by surface. As it stands today:

• Copilot cloud agent (started from GitHub.com, VS Code, JetBrains, Eclipse or Xcode): repository-wide, path-specific and agent instructions, meaning AGENTS.md, CLAUDE.md or GEMINI.md. On GitHub.com, organisation instructions too.
• Copilot CLI: repository-wide, path-specific, agent instructions (all three names) and personal instructions.
• Copilot code review on GitHub.com: repository-wide, path-specific, AGENTS.md only, and organisation instructions.
• Copilot Chat in VS Code: repository-wide, path-specific and AGENTS.md. GitHub’s table stops there, but VS Code’s own documentation adds CLAUDE.md for the Local agent when chat.useClaudeMdFile is on (see below).
• Copilot Chat on GitHub.com: repository-wide, personal and organisation instructions. No path-specific files, no AGENTS.md.
• Copilot Chat in Visual Studio and Xcode: repository-wide and path-specific. JetBrains adds personal instructions. Eclipse: repository-wide only.
• Code review in VS Code and Visual Studio: repository-wide only. In Eclipse, code review does not support custom instructions yet.

Two things follow. .github/copilot-instructions.md is the only file every chat surface reads, so it is the safe place for rules that must always hold. And AGENTS.md is the file that reaches the agents, which is where rules about how to carry out a task matter most. This table changes as GitHub adds support, so check the reference page before relying on a gap.

How Copilot picks an AGENTS.md

• You can have several AGENTS.md files at different depths. When Copilot is working, the nearest one in the directory tree takes precedence, so apps/web/AGENTS.md beats the root file for work inside apps/web.
• For the cloud agent, CLAUDE.md and GEMINI.md are read as a single file at the repository root only. The GitHub Copilot CLI looks further: GitHub’s page on custom instructions for the CLI↗ (opens in a new tab) says it finds them at the root, in the current working directory and in the folders in between, and also reads .claude/CLAUDE.md.
• In VS Code, chat now runs through an agent harness (Local, Copilot, Claude or Codex, or a Cloud target), and which instruction files load depends on the harness you pick; the chat.* instruction settings apply to the Local agent. There, an AGENTS.md outside the workspace root is not used unless you turn it on. VS Code’s custom instructions page↗ (opens in a new tab) lists chat.useAgentsMdFile for the root file, chat.useNestedAgentsMdFiles for nested ones, which it marks as experimental, and chat.useClaudeMdFile for CLAUDE.md.
• AGENTS.md is not a Copilot format. It is a plain Markdown convention described at agents.md↗ (opens in a new tab) and read by several coding agents, which is why one file can serve Copilot, Cursor and Codex in the same repository.

Path-specific instructions, with an example

A path-specific file starts with a frontmatter block. applyTo takes one or more glob patterns separated by commas. excludeAgent keeps the file away from either "code-review" or "cloud-agent"; without it, both use it. On GitHub.com, only the cloud agent and code review read path-specific files.

---
applyTo: "**/*.test.ts,**/*.spec.ts"
excludeAgent: "code-review"
---
- Use the helpers in tests/support; do not build fixtures inline.
- Every new test must fail before the fix and pass after it.
- Run pnpm test -- <file> for the file you changed, not the whole suite.

Path-specific files are the right home for rules that only make sense for some files: test conventions, migration rules, a component library’s patterns. They keep the repository-wide file short.

When instructions disagree

More than one set can apply to a request. GitHub gives personal instructions the highest priority, then repository instructions, then organisation instructions, but every relevant set is sent to Copilot. Conflicting lines therefore do not cancel out neatly; they leave the model to choose. Write each rule in one place.

One more detail for reviews: Copilot code review reads instructions from the pull request’s head branch, not the base branch. You can change an instructions file and see its effect on review in the same pull request.

What a good instructions file contains

GitHub’s own advice for copilot-instructions.md is practical rather than stylistic. The file should help an agent that has never seen the repository build, test and validate a change without searching for how. In practice that means:

• A few sentences on what the repository does, its languages, frameworks and runtimes.
• The exact commands to bootstrap, build, test, run and lint, in the order they must run, with anything that looks optional but is not.
• The layout: where the main projects, configuration and tests live, so the agent knows where to make a change.
• The checks a change must pass before it is merged, such as the workflows your continuous integration runs, so the agent can run them itself.
• Nothing task-specific. The file is read on every request; a note about this week’s bug belongs somewhere else.

GitHub suggests keeping it to about two pages. You do not have to start from a blank file: from the Agents tab you can ask the cloud agent to write one, and the first time it opens a pull request in a repository it leaves a comment offering to generate it. Treat the result as a draft. Run each command it lists before you trust it, and cut anything you would not say to a new colleague on their first day.

The same advice applies to AGENTS.md. The difference is audience, not content: agents read AGENTS.md, every chat surface reads copilot-instructions.md, and the layout below keeps the two from repeating each other.

A layout that covers every surface

AGENTS.md                              # how an agent works here: build, test, rules, the board
apps/web/AGENTS.md                     # overrides for work inside apps/web
.github/copilot-instructions.md        # the few rules every surface must see, written out
.github/instructions/
  tests.instructions.md                # applyTo: test files
  migrations.instructions.md           # applyTo: db/**

• Put the full agent guidance in AGENTS.md: commands, layout, what never to touch, how work is tracked.
• Keep .github/copilot-instructions.md short, and write the non-negotiable rules out in it rather than pointing at AGENTS.md, because some chat surfaces will never open that file.
• Move file-type rules into .instructions.md files so neither main file grows.
• If the repository also serves Claude Code, the CLAUDE.md side is covered in managing multiple projects with CLAUDE.md.

Instructions say how; a board says what

Instruction files describe how to work in a repository. They are the wrong place for what to work on next, what was decided last week, or what the agent found and did not fix. Those change daily and belong on a board. A line in AGENTS.md connects the two: “Before starting, call fenbs_get_context and fenbs_get_item for the task you were given; when you stop, comment on it with what changed.”

fenbs also keeps AI context on the board itself: short notes about how you work, read by any connected assistant through fenbs_get_context. Rules about the repository go in the repository; rules about the work, true whichever tool picks it up, can live with the board.