AGENTS.md vs copilot-instructions.md: which one Copilot reads
AGENTS.md vs .github/copilot-instructions.md: which GitHub Copilot features read each, path-specific instructions, and a setup that also works for Claude Code.
A team writes careful build and test instructions in AGENTS.md. Copilot's cloud agent follows them. Then someone asks Copilot Chat on GitHub.com how to run the tests, and it guesses. Copilot reads different files depending on which Copilot feature you're using.
This guide sorts out which file each part of Copilot reads, from GitHub's repository instructions docs and its support reference, checked on 16 November 2026.
The short answer
.github/copilot-instructions.md | AGENTS.md | |
|---|---|---|
| Whose format | GitHub Copilot's | Cross-tool, from the agents.md project |
| Location | .github/ only | Anywhere; nearest file wins |
| Read by Copilot | Chat, cloud agent, code review | Cloud agent, code review, VS Code chat |
| Read by others | No | Codex, Cursor, Antigravity, and more |
| Alternatives | Path-specific .instructions.md files | A single root CLAUDE.md or GEMINI.md |
Copilot's three kinds of repository instructions
GitHub's docs describe three:
- Repository-wide:
.github/copilot-instructions.md, applied to every Copilot request in the repository. - Path-specific:
NAME.instructions.mdfiles in or below.github/instructions/, each with anapplyToglob. When a file matches, these apply alongside the repository-wide file. - Agent instructions:
AGENTS.mdfiles anywhere in the repository, with the nearest one in the directory tree taking precedence. A singleCLAUDE.mdorGEMINI.mdin the root also works.
Which Copilot feature reads what
From GitHub's support reference:
| Copilot feature | copilot-instructions.md | Path-specific | AGENTS.md, CLAUDE.md, GEMINI.md |
|---|---|---|---|
| Chat on GitHub.com | Yes | No | No |
| Cloud agent on GitHub.com | Yes | Yes | Yes |
| Code review on GitHub.com | Yes | Yes | Yes, plus REVIEW.md |
| Chat in VS Code | Yes | Yes | AGENTS.md |
The gap that catches people: Chat on GitHub.com reads only the repository-wide file among these. Anything it must know has to be in copilot-instructions.md.
Path-specific instructions
---
applyTo: "**/*.ts,**/*.tsx"
excludeAgent: "code-review"
---
Use named exports. Validate API input with zod.
Save as .github/instructions/typescript.instructions.md. excludeAgent takes "code-review" or "cloud-agent" and keeps the file away from that feature; without it, both use the file. GitHub notes that on GitHub.com, path-specific instructions only work for the cloud agent and code review.
A setup that works across tools
Teams rarely use only Copilot. A layout that serves Copilot, Claude Code, Codex, and Cursor:
AGENTS.md # shared: build, test, conventions
CLAUDE.md # @AGENTS.md, plus Claude-specific notes
.github/
copilot-instructions.md # short: what Copilot Chat must know
instructions/
typescript.instructions.md # path-specific, Copilot only
- AGENTS.md is the source of truth for build commands, test commands, and conventions. Codex, Cursor, Antigravity, and Copilot's agents read it directly. See AGENTS.md examples.
- CLAUDE.md imports it with
@AGENTS.md, so Claude Code gets the same rules. Note that GitHub's agent features may also read CLAUDE.md, so keep the two consistent rather than contradictory. - copilot-instructions.md stays short: the few things Chat on GitHub.com needs, or a pointer such as "See AGENTS.md for build and test commands." Chat may not follow the pointer, so copy anything essential.
- Avoid duplicating long content. Two copies drift, and agents follow whichever they read.
Rules vs decisions
All these files hold stable instructions: how to build, which patterns to use. They're a poor fit for decisions that change and need an owner, such as "the v1 API stays frozen until March." Edited by whoever opens a pull request, a line like that has no approval, no expiry, and no record of who decided it. See why Claude Code ignores CLAUDE.md for what instruction files do and don't do well.
Where Lockstep fits
Lockstep keeps those changing decisions separate from instruction files. It captures them from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply. Session briefings work in Claude Code only; Copilot and other MCP clients can call Lockstep's tools directly.
See how it works.
Sources checked 16 November 2026
- https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
- https://docs.github.com/en/copilot/reference/custom-instructions-support
Related reading
For AGENTS.md in depth, see AGENTS.md. For Cursor's equivalents, see Cursor rules vs skills vs AGENTS.md vs CLAUDE.md. For Copilot against Cursor overall, see Cursor vs GitHub Copilot.
Frequently asked questions
- Does GitHub Copilot read AGENTS.md?
- Some of it does. GitHub's support table lists AGENTS.md for Copilot cloud agent and Copilot code review on GitHub.com, and for Copilot Chat in VS Code. Copilot Chat on GitHub.com uses repository-wide instructions from .github/copilot-instructions.md, not AGENTS.md.
- What is the difference between AGENTS.md and copilot-instructions.md?
- copilot-instructions.md is Copilot's own file, in .github/, applied to all Copilot requests in the repository. AGENTS.md is a cross-tool format for agent instructions that can sit anywhere in the repository, with the nearest one taking precedence. Codex, Cursor, and other agents read AGENTS.md too.
- Can Copilot use CLAUDE.md?
- Yes, for agent instructions. GitHub's docs say you can use a single CLAUDE.md or GEMINI.md in the repository root instead of AGENTS.md, and its support table lists them for the cloud agent and code review.
- What are path-specific Copilot instructions?
- Files named NAME.instructions.md in or below .github/instructions/, with an applyTo glob in frontmatter, such as applyTo: "**/*.ts". They apply when Copilot works on matching files, alongside the repository-wide file. An excludeAgent key can keep a file away from code review or the cloud agent.
- Should I use both files?
- Usually yes. Put rules every agent should follow in AGENTS.md, so Copilot's agents, Codex, Cursor, and Claude Code via an import all see them. Use copilot-instructions.md for anything Copilot Chat on GitHub.com must see, or that only applies to Copilot.
Keep reading