GitHub Copilot Agent Instructions vs AGENTS.md Compared

AGENTS.md is read by 25+ coding tools, yet GitHub.com Copilot Chat reads only the repository-wide .github/copilot-instructions.md file—not AGENTS.md or path-specific instruction globs, according to a Copilot support analysis. That contradiction is the whole comparison: GitHub supports AGENTS.md, but not uniformly across GitHub.

For engineering teams, the practical answer is rarely “pick one.” Use AGENTS.md as the shared engineering baseline, then maintain a deliberately small Copilot-specific layer for GitHub surfaces that need guaranteed repository-wide coverage.

Which tools should you compare for repository instructions?

GitHub Copilot agent instructions, AGENTS.md, and tool-specific files serve different jobs. The comparison below focuses on the toolchains most likely to touch the same repository: Copilot, Claude Code, Cursor, and Codex.

Tool	Pricing	Instruction behavior	Best fit
GitHub Copilot	Business at $19/user/month and Enterprise at $39/user/month	Repository-wide instructions are the only custom-instruction mechanism supported on every Copilot surface; AGENTS.md works in the CLI and cloud agent but not GitHub.com Chat	A GitHub-centered team that needs consistent rules across editors, CLI, review, and the web
Claude Code	Team at $25 per standard seat per month	Reads AGENTS.md when no CLAUDE.md exists at or above the working directory	Mixed toolchains needing a shared baseline plus Claude-specific overrides
Cursor	Teams at $40 per standard seat	Reads AGENTS.md as part of the 25+ tool open-format ecosystem	Teams that want one repository policy across several editors and agents
Codex	—	Reads AGENTS.md as part of the 25+ tool open-format ecosystem	OpenAI-centered workflows that still share the repository with other agents

This is not an instruction-quality ranking. Copilot’s repository-wide file wins on surface coverage; AGENTS.md wins on portability. A team using every tool needs both properties, which means it needs an explicit ownership model.

The most important distinction is where you expect the rules to be read. If GitHub.com Chat is part of the workflow, assume AGENTS.md is absent there. If the requirement is one policy across Copilot, Codex, Cursor, Gemini CLI, and other tools, assume Copilot’s private file is only an adapter.

How should AGENTS.md and Copilot instructions be layered?

AGENTS.md should be the canonical cross-tool baseline, while Copilot’s repository-wide file should carry only the rules needed where AGENTS.md isn’t available. That division preserves portability without pretending GitHub has uniform file semantics.

The precedence data makes the asymmetry explicit. AGENTS.md sits at rank 2c, the lowest repository tier, beneath .github/instructions/*.instructions.md at 2a and .github/copilot-instructions.md at 2b. Copilot also reads the repository-wide file in its CLI, so the problem isn’t that Copilot rejects AGENTS.md everywhere.

Location still matters for AGENTS.md. The format can live anywhere in the repository tree, with the nearest file taking precedence. That makes a short root file plus narrow directory files a sensible structure. A root policy can describe universal engineering constraints, while a package-specific file covers local commands, tests, or architectural boundaries.

Precedence also doesn’t mean “replace everything below.” GitHub supplies all relevant personal, repository, and organization instruction sets simultaneously, with personal instructions ranked above repository instructions and repository instructions above organization instructions. In other words, a developer’s preference can enter the same context window as a company policy without automatically erasing it.

None of these files should be described as a hard control boundary. Copilot’s custom instructions are guidance rather than enforcement: models generally follow them, but can misread or lose them. CI checks, permission boundaries, and code-owner rules still need to enforce anything that must never be skipped.

Where does GitHub.com Copilot Chat create the biggest gap?

GitHub.com Copilot Chat creates the largest gap because it follows a narrower loading path than many developers expect. It reads .github/copilot-instructions.md, but not path-specific *.instructions.md globs or AGENTS.md. A polished directory rule can therefore work perfectly in an IDE and disappear entirely in web chat.

The repository-wide file itself is straightforward: GitHub Copilot adds it to every request made in that repository. Harbor’s guidance is to keep it under two pages and avoid making it task-specific. Treat it as a compact list of mistakes a new engineer would otherwise repeat, not as an onboarding manual or a copy of the project wiki.

Path-specific files have a different operating model. They live in .github/instructions/, end in .instructions.md, and begin with frontmatter containing an applyTo glob. When Copilot works on a matching file, the path-specific instructions are combined with the repository-wide file. That’s useful in IDE, CLI, agent, and review contexts, but it doesn’t solve the GitHub.com Chat gap.

A practical example makes the ownership obvious. A repository-wide instruction such as “never rewrite a merged database migration; add a new one” belongs in .github/copilot-instructions.md because it applies across the project and may be requested through web chat. A rule governing retry handling only for src/payments/**/*.ts belongs in a path-specific file. Architecture documentation belongs in ordinary docs, linked rather than pasted into every agent prompt.

What should each file own in a multi-tool repository?

AGENTS.md should own shared engineering rules, while each proprietary layer should own compatibility and tool-specific behavior. The goal is a small policy core with thin adapters, not two complete manuals.

Start with AGENTS.md for facts an agent cannot reliably infer from the code:

• The package manager and standard validation commands.
• Architectural boundaries that aren’t enforced by types.
• Rules for migrations, generated files, or sensitive paths.
• Documentation that must accompany a change.
• Clear conditions under which the agent should stop and ask.

Keep the file concise enough to read in one sitting. Our guide to writing an AGENTS.md file for Cursor, Copilot, and Codex covers the formatting and progressive-disclosure details. The core principle is simple: write down consequential context, then point to the source instead of copying it wholesale.

Claude Code’s September 18, 2026 release makes this baseline more useful. Version 2.1.277 added native AGENTS.md fallback support, reading the file whenever no CLAUDE.md exists at or above the working directory. That reduces the need for a shim, though a repository with both formats needs to state which rules are intentionally different.

For Copilot, maintain .github/copilot-instructions.md as an adapter containing only:

1. Universal guardrails that web chat must receive.
2. Copilot-specific workflow instructions.
3. References to the canonical AGENTS.md, without duplicating the whole document.
4. The smallest set of critical rules that must be physically mirrored.

The comparison in AGENTS.md vs Cursor rules goes deeper into this layered pattern. The key maintenance control is a pull-request check that flags substantive differences between the shared baseline and any mirrored Copilot rules. Duplication is acceptable only when the compatibility requirement is explicit.

Should Copilot Memory be treated as configuration?

No. Copilot Memory should be audited like generated state, not authored like a policy file. It is non-deterministic: Copilot writes it for itself, and its presence doesn’t prove that a team-approved rule was applied.

When repository-wide instructions, path-specific files, AGENTS.md, and Memory are all enabled, four systems compete to influence the same model. Memory is the odd one out because it isn’t part of GitHub’s documented precedence list, is read by only three Copilot surfaces, and expires after 28 days of disuse.

The source describes it as a non-deterministic cache that GitHub’s model writes for itself. Teams that edit it directly are fighting the system: they can create guidance that disappears, isn’t versioned with the repository, and doesn’t travel with the codebase.

Your review process should distinguish three states:

• Committed files: Team-authored, reviewable, portable, and versioned.
• Generated Memory: Copilot-authored, surface-dependent, and disposable.
• Actual output: Evidence of whether the agent followed policy during a specific task.

That separation is especially important when diagnosing silent failures. Our explanation of why AI coding agents ignore repository instructions covers the mechanical causes: discovery paths, precedence, and content quality. Memory makes the diagnosis harder because it can create the appearance of context without providing a reproducible policy source.

How do you choose without creating a governance mess?

Choose based on the Copilot surfaces your team actually uses, then add portability only where another tool requires it. Don’t begin by copying one file everywhere and hoping the semantics converge.

Use this sequence:

1. List the surfaces. Include GitHub.com Chat, IDE chat, CLI, cloud agent, and code review only if they are part of normal work.
2. Map file coverage. Mark which surface reads AGENTS.md, the repository-wide Copilot file, and path-specific files.
3. Classify each rule. Put universal engineering policy in AGENTS.md; put Copilot surface requirements in its native file.
4. Test the critical path. Ask a harmless repository question on each surface and verify whether the expected rule appears.
5. Automate drift checks. Flag major differences between AGENTS.md and manually mirrored Copilot rules.

A Copilot-only team can start with .github/copilot-instructions.md, especially when web chat is central. A multi-tool team should use AGENTS.md as the baseline and maintain a small Copilot adapter. A monorepo also needs narrow path-specific files, but only for rules that materially change behavior in those directories; otherwise the context cost outweighs the benefit.

My default recommendation is two committed files: a concise AGENTS.md and a concise .github/copilot-instructions.md that covers GitHub’s web-chat gap without becoming a second manual. Then ask one question in every interface your developers use: “Which committed file is governing this answer?” If no one can answer confidently, your instruction architecture is already too ambiguous.