AGENTS.MD VS COPILOT

GitHub Copilot reads copilot-instructions.md everywhere it supports instructions, but reads AGENTS.md only in some places. So Copilot users need both files, with AGENTS.md as the source and a short copilot-instructions.md.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

Which Copilot Surfaces Read Which File?

Last verified 2026-11-13 against the vendor documentation. From GitHub's custom instructions support matrix:

Copilot surfacecopilot-instructions.mdAGENTS.md
Chat on GitHub.comYesNo
Cloud agentYesYes
Code review on GitHub.comYesYes
VS Code chatYesYes
Visual Studio chatYesNo
JetBrains chatYesNo
Copilot CLIYesYes

So copilot-instructions.md is the only file every surface sees, and AGENTS.md is the only file other agents see.

What Is the Difference in Format?

  • Both are plain Markdown with no required structure.
  • copilot-instructions.md lives in .github/; AGENTS.md lives at the root and can be nested.
  • Copilot adds path-specific .github/instructions/*.instructions.md files with an applyTo glob; AGENTS.md scopes by directory instead.
  • Only AGENTS.md is read by Codex, Cursor, Windsurf, Zed, Cline and Jules.

When Do You Need Only One?

If nobody uses anything but Copilot, copilot-instructions.md alone covers every surface. If nobody uses Copilot, AGENTS.md alone covers the rest. Most teams mix tools, though, and then a pointer-only Copilot file fails: Copilot Chat on GitHub.com cannot follow it to AGENTS.md.

How Do You Keep Both Without Duplication?

Accept a small, deliberate overlap. The Copilot file repeats only the essentials: the stack, the commands and the working rules. Everything else lives in AGENTS.md. This is what the 2prompt generator writes:

# Copilot instructions

Project: shop-api. Order and checkout API for the storefront.

The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.

## Stack

- Language: TypeScript
- Framework: Fastify
- Database: PostgreSQL
- Tests: Vitest
- Package manager: pnpm

## Commands

- Install dependencies: `pnpm install`
- Run locally: `pnpm dev`
- Run all tests: `pnpm test`
- Lint: `pnpm lint`
- Type-check: `pnpm tsc --noEmit`

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.

How Do You Migrate an Existing copilot-instructions.md?

  1. Paste it into the copilot-instructions.md to AGENTS.md converter.
  2. Review the AGENTS.md it produces and add missing commands.
  3. Replace the Copilot file with the short essentials version the converter also produces.
  4. Move folder-specific rules into .github/instructions files or nested AGENTS.md files.
  5. Lint AGENTS.md with the linter.

Who Should Own the Two Files?

Instruction files are configuration, and configuration without an owner decays. Give both files the same owner as the build and CI configuration, because they describe the same things: how to install, build and test the project, and what a change must satisfy before it merges.

  • Add both paths to CODEOWNERS if your repository uses it.
  • Change the files in the same pull request as the build or tooling change that makes them stale.
  • Mention instruction updates in the pull request description so reviewers look at them.
  • Run the linter in review when either file changes.

Teams that skip this step usually find the Copilot file months out of date, because nobody using another agent ever reads it. Keeping the Copilot file short makes the job small enough to actually happen.

When the build changes, the order of updates matters. Change AGENTS.md first, because it is the source, then copy the affected essentials into the Copilot file in the same commit. Reviewers then see both edits together, and a missing update in either file is easy to catch. A simple checklist item in the pull request template, asking whether the agent instruction files need an update, is often enough to keep both files honest over time.

What Are the Common Mistakes?

  • A Copilot file that only says "see AGENTS.md".
  • Two full copies that disagree after a few months.
  • Putting copilot-instructions.md at the repository root instead of in .github/.

Formats in detail: copilot-instructions.md and AGENTS.md.

Frequently Asked Questions

Does GitHub Copilot support AGENTS.md?

Partly. The Copilot cloud agent, code review, the Copilot CLI and VS Code chat read AGENTS.md. Copilot Chat on GitHub.com, Visual Studio and JetBrains chat do not, so keep a copilot-instructions.md too.

Which file wins if they disagree?

Do not rely on an order. Say in copilot-instructions.md that AGENTS.md wins on conflict, keep the overlap small, and change both files in the same pull request.

Can copilot-instructions.md import AGENTS.md?

We did not find an import syntax for copilot-instructions.md in GitHub documentation, so treat it as a standalone file. That is why the essentials are repeated inline.

Where do folder-specific Copilot rules go?

In .github/instructions as NAME.instructions.md files with an applyTo glob in frontmatter. Copilot Chat on GitHub.com does not read these, so keep must-follow rules in the main file.

Was this helpful?