Which AGENTS.md does GitHub Copilot use in a monorepo with one per service folder, and do all Copilot surfaces read them?
answer
- distance in the directory tree
- root CLAUDE.md or GEMINI.md alternative
- not every surface supports agent files
- an editor setting off by default
- opened subfolder misses the root
basics
~20 sGitHub's docs say the nearest AGENTS.md in the directory tree takes precedence while Copilot works. Support varies: the cloud agent and Copilot CLI read agent files, VS Code reads subfolder files only with chat.useNestedAgentsMdFiles, and Copilot Chat on GitHub.com reads none.
solid answer
~40 sCopilot treats `AGENTS.md` as **agent instructions**: you may place one or more anywhere in the repository, and the nearest one in the directory tree takes precedence; alternatively a single root `CLAUDE.md` or `GEMINI.md` serves the same role. Surfaces differ. The cloud agent reads `AGENTS.md`, `CLAUDE.md` and `GEMINI.md`; Copilot CLI discovers them in the repository root, the working directory, the folders between, and folders on the path of a file it works on. In VS Code's Local agent the root file is on by default (`chat.useAgentsMdFile`), but subfolder files need `chat.useNestedAgentsMdFiles`, which defaults to `false`. Copilot Chat on GitHub.com does not read agent instructions at all.
go deeper
Recall that Copilot reads AGENTS.md files as agent instructions, that the nearest one takes precedence, and that a root CLAUDE.md or GEMINI.md is an accepted alternative.
Explain which surfaces read agent files, that Chat on GitHub.com does not, and the VS Code settings chat.useAgentsMdFile and chat.useNestedAgentsMdFiles with their defaults.
Show you diagnose a service's ignored rules by surface and setting, including subfolder workspaces and parent discovery, and keep root and service files from contradicting each other.
Decide how a monorepo splits shared and service-specific guidance across agent files and applyTo-scoped files so every Copilot surface the teams use gets the right rules.
## The rule GitHub documents Copilot recognises three kinds of repository instructions: repository-wide (`.github/copilot-instructions.md`), path-specific (`.github/instructions/**/*.instructions.md`) and **agent instructions**. For the last kind, GitHub's documentation says you can create one or more `AGENTS.md` files stored anywhere in the repository, and that **when Copilot is working, the nearest `AGENTS.md` in the directory tree takes precedence**. As an alternative to `AGENTS.md`, Copilot accepts a single `CLAUDE.md` or `GEMINI.md` stored at the repository root. For a monorepo this means a service folder such as `services/billing/AGENTS.md` can carry billing-specific conventions, and an agent editing billing code should favour it over the root file. That promise holds only on surfaces that read nested agent files, and the documentation describes agent instructions as **not supported by all Copilot features**. ## Which surface reads which agent file | Surface | Agent instructions read | |---|---| | Copilot cloud agent | `AGENTS.md`, `CLAUDE.md` or `GEMINI.md` | | Copilot code review on GitHub.com | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `REVIEW.md`; its page describes `AGENTS.md` at the root | | Copilot Chat on GitHub.com | None | | Copilot Chat and agent in VS Code | `AGENTS.md` at the workspace root by default; nested files only when enabled | | Copilot CLI | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` in its standard locations | ## VS Code's switches VS Code's Local agent controls agent files with settings: - `chat.useAgentsMdFile` (default `true`) enables `AGENTS.md` as context. - `chat.useNestedAgentsMdFiles` (default `false`) enables `AGENTS.md` files in subfolders. When on, VS Code lists the nested files with their folder locations so the agent can load the relevant ones for the task. GitHub's IDE page puts it the same way: support for `AGENTS.md` outside the workspace root is turned off by default. - `chat.useClaudeMdFile` (default `true`) enables `CLAUDE.md` files as always-on instructions. - `chat.useCustomizationsInParentRepositories` (default `false`) matters when you open a **subfolder** of the monorepo rather than its root: by default VS Code discovers customizations only inside the open workspace folder, so the root `AGENTS.md` and `.github` files are missed. With the setting on, VS Code walks up to the folder containing `.git` and collects customizations from every folder in between. ## Copilot CLI's discovery Copilot CLI looks for `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` in its standard locations: the repository root, the current working directory, the directories between them, and directories on the path of a file it is working on. It combines applicable files, removes identical duplicates and defines **no** general precedence between them, so conflicting service files are a problem to fix at the source. The `/instructions` command shows which files a session discovered and lets you disable individual ones. ## Designing for a monorepo 1. Put rules true for every service in the root `AGENTS.md` or in `.github/copilot-instructions.md`. 2. Put service-specific rules in that service's `AGENTS.md`, and keep them consistent with the root file rather than contradicting it. 3. If editor users must get service rules without changing settings, mirror them in `.github/instructions/billing.instructions.md` with `applyTo: "services/billing/**"`, which VS Code attaches automatically when the agent edits matching files. 4. Tell VS Code users who open a single service folder about `chat.useCustomizationsInParentRepositories`. How `AGENTS.md` behaves as a convention shared with other tools is a separate subject; what matters here is how each Copilot surface discovers it. ## A worked scenario A repository has a root `AGENTS.md` saying "use the shared logger" and `services/billing/AGENTS.md` saying "amounts are integers in minor units; never use floating point". Then: - The **cloud agent**, assigned an issue that touches billing code, works under GitHub's nearest-file rule, so the billing file should take precedence for that work. - **Copilot CLI** started in `services/billing` finds both files, because the root, the working directory and the folders between are standard locations, and combines them. - A developer in **VS Code** with default settings gets only the root file; the billing rule is invisible until `chat.useNestedAgentsMdFiles` is turned on or the rule is mirrored in an `applyTo`-scoped instructions file. - **Copilot Chat on GitHub.com** sees neither file; of the repository's files, only `.github/copilot-instructions.md` reaches it. The same repository can therefore produce four different behaviours from one set of files, which is why "the agent ignored our AGENTS.md" is first a question about which surface was used.
- A developer opens only services/billing in VS Code and Copilot ignores the repository's root .github/copilot-instructions.md. Why, and what fixes it?By default VS Code discovers customizations only inside the open workspace folder, so files at the repository root are outside it. Enabling chat.useCustomizationsInParentRepositories makes VS Code walk up to the folder that contains .git and collect instructions, AGENTS.md and other customizations from every folder in between.
- Your repository has no AGENTS.md but does have a root CLAUDE.md. Does Copilot cloud agent use it?Yes. GitHub's documentation allows a single CLAUDE.md or GEMINI.md at the repository root as an alternative to AGENTS.md, and the support table lists all three as agent instructions for the cloud agent. Copilot Chat on GitHub.com still ignores it, because Chat there reads no agent instructions.
- Copilot only ever reads an AGENTS.md at the repository root.
- Every Copilot surface, including Chat on GitHub.com, reads AGENTS.md.
- VS Code reads nested AGENTS.md files out of the box.
- On GitHub.com, the root AGENTS.md always outranks a service folder's AGENTS.md.
- Copilot ignores CLAUDE.md because that file belongs to another tool.