Skip to content
Agent Friendly Code

copilot-instructions.md: setup, examples, AGENTS.md

GitHub Copilot reads repository instructions from .github/copilot-instructions.md. Its cloud agent, code review, CLI and VS Code also read AGENTS.md, so keep shared rules there and use copilot-instructions.md for the essentials and Copilot-only notes.

Where does copilot-instructions.md go?

.github/copilot-instructions.md, at the repository root. Plain Markdown, no frontmatter, applied to every request in the repo. Path-specific files go beside it in .github/instructions/.

In our census of the 388 GitHub repos on the board on 2026-11-16, 45 (12%) have a .github/copilot-instructions.md, and 32 of those also have a root AGENTS.md. Census counts include empty files.

Which Copilot features read which instruction files?

Repository instruction files each GitHub Copilot surface supports, per GitHub's support matrix
Copilot surfacecopilot-instructions.mdPath-specific .instructions.mdAGENTS.md, CLAUDE.md, GEMINI.md
Cloud agent (any IDE or github.com)YesYesYes
Code review on github.comYesYesYes, plus REVIEW.md
Copilot CLIYesYesYes
Chat on github.comYes——
VS Code ChatYesYesAGENTS.md only
VS Code code reviewYes——
Visual Studio ChatYesYes—
JetBrains ChatYesYes—
Xcode Chat and code reviewYesYes—
Eclipse ChatYes——

— means the matrix doesn't list it for that surface. Eclipse code review supports no custom instructions. Personal instructions (~/.copilot/copilot-instructions.md for the CLI) and organization instructions sit on top of these.

How do applyTo and .instructions.md files work?

Put NAME.instructions.md files in or below .github/instructions/. The applyTo frontmatter takes comma-separated globs: **/*.py for every Python file, src/*.py for that folder only, src/**/*.py for it and its subfolders. A matching file's instructions are added to the repo-wide ones, not swapped in.

excludeAgent keeps a file from one agent: "code-review" or "cloud-agent" (older docs said coding-agent). Without it both use the file. In VS Code the frontmatter can also carry name and description.

.github/instructions/react.instructions.md

---
applyTo: "**/*.ts,**/*.tsx"
excludeAgent: "code-review"
---

- Components are function components with named exports.
- Co-locate tests as `*.test.tsx` next to the component.

Few repos use them: 122 path-specific files across 17 repos in our census, most in microsoft/vscode, dotnet/runtime, dotnet/maui and PowerShell/PowerShell.

Does GitHub Copilot read AGENTS.md?

Yes, on the cloud agent, code review, the CLI and VS Code. AGENTS.md files can sit anywhere in the repo; the nearest one in the directory tree takes precedence. Alternatively Copilot takes a single CLAUDE.md or GEMINI.md at the repo root. Code review also reads CLAUDE.md, GEMINI.md and REVIEW.md, from the pull request's head branch.

  • Copilot CLI reads instruction files at the repo root, the working directory, every directory between, and directories on the path of a file it works on; it also reads .claude/CLAUDE.md. @relative/path references work in copilot-instructions.md, AGENTS.md and CLAUDE.md, not in GEMINI.md or .instructions.md files.
  • VS Code's Copilot harness finds AGENTS.md at the repo root, the working directory, the directories between, and along the paths of files it works with, and combines them.
  • VS Code's Local harness reads the root AGENTS.md only with chat.useAgentsMdFile on; nested files also need chat.useNestedAgentsMdFiles, experimental and off by default. chat.useClaudeMdFile adds CLAUDE.md, .claude/CLAUDE.md, ~/.claude/CLAUDE.md and CLAUDE.local.md.

copilot-instructions.md vs AGENTS.md: which should you use?

Both, split by job. Codex, Cursor, Devin and most other agents read AGENTS.md too, so the project's rules belong there once. copilot-instructions.md is the only file every Copilot surface reads: Chat on github.com, Visual Studio, JetBrains, Xcode and Eclipse don't list AGENTS.md. Keep it short: the build and test commands and the few rules that matter most, repeated, plus anything only Copilot needs, such as what code review should flag.

.github/copilot-instructions.md (starter)

# Copilot instructions

Shared project rules live in AGENTS.md. This file repeats the essentials for
Copilot features that don't read AGENTS.md, plus Copilot-only notes.

- Build: `npm ci && npm run build`
- Test: `npm test`; run a single file with `npm test -- path/to/file`
- TypeScript strict mode; no `any` in new code.
- In code review, flag any SQL built by string concatenation.

GitHub advises short, self-contained statements. There's no documented length limit; GitHub's prompt for generating the file asks for at most two pages.

What about Copilot prompt files, custom agents and skills?

Other repository files GitHub Copilot reads
FileWhereNotes
Prompt files.github/prompts/*.prompt.mdReusable prompts. VS Code and Visual Studio; preview in JetBrains and Xcode; not on github.com, Eclipse or the CLI. In VS Code only the Local harness runs them; for the Copilot harness, write a skill.
Custom agents.github/agents/NAME.md or NAME.agent.mdBoth extensions work. Organization agents go in /agents/ of the org's .github or .github-private repo.
Skills.github/skills/, .claude/skills/ or .agents/skills/One folder per skill with a SKILL.md. Personal skills: ~/.copilot/skills or ~/.agents/skills. VS Code's Copilot harness lists only .github/skills/.

Why are my Copilot instructions not working?

  1. Check it loaded: in Chat, expand the references list at the top of a response and look for .github/copilot-instructions.md. In VS Code, References shows inclusion, not compliance; the Agent Debug Logs show more.
  2. Check the path and name: .github/copilot-instructions.md at the repo root, and path files ending in .instructions.md under .github/instructions/.
  3. Check the surface reads that file (table above). A path file or AGENTS.md does nothing in Chat on github.com.
  4. Check the applyTo glob matches the file being edited: src/*.py misses src/api/app.py.
  5. In VS Code's Local harness, turn on chat.useAgentsMdFile if your rules live in AGENTS.md.
  6. Code review reads instructions from the pull request's head branch, so a change counts only once it's on that branch.
  7. Look for conflicts. Personal instructions take priority over repository ones, and repository over organization, but Copilot gets all of them.

Questions people ask

copilot-instructions.md vs CLAUDE.md?
Copilot's cloud agent, code review and CLI read a root CLAUDE.md; Chat in the IDEs doesn't, except VS Code's Local harness with chat.useClaudeMdFile on. If your rules are in CLAUDE.md for Claude Code, point both files at an AGENTS.md or repeat the essentials in copilot-instructions.md.
Can applyTo take more than one pattern?
Yes, comma-separated in one string: applyTo: "**/*.ts,**/*.tsx".
Does Copilot code review use copilot-instructions.md?
Yes, on github.com and in every IDE except Eclipse. On github.com it also reads path-specific files, AGENTS.md, CLAUDE.md, GEMINI.md and REVIEW.md. Use excludeAgent: "code-review" to keep a path file out of reviews.
Is there a copilot-instructions.md length limit?
Not in GitHub's current docs. Keep to short, self-contained statements; long files cost context on every request.
Which wins when instructions conflict?
Personal, then repository, then organization. Copilot still gets every relevant set, so remove the conflict rather than rely on the order.
Can one repo serve Copilot and other agents from the same file?
For the cloud agent, code review, the CLI and VS Code, yes: AGENTS.md. Some repos go further: lit/lit symlinks both AGENTS.md and CLAUDE.md to .github/copilot-instructions.md. See the one-file guide.

From the docs: docs.github.com/add-repository-instructions (new tab) · docs.github.com/custom-instructions-support (new tab) · docs.github.com/add-custom-instructions (new tab) · docs.github.com/customization-cheat-sheet (new tab) · code.visualstudio.com/custom-instructions-reference (new tab)

Check your AGENTS.md · One file for every agent · CLAUDE.md guide · AGENTS.md vs skills · What each agent reads · All guides