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?
| Copilot surface | copilot-instructions.md | Path-specific .instructions.md | AGENTS.md, CLAUDE.md, GEMINI.md |
|---|---|---|---|
| Cloud agent (any IDE or github.com) | Yes | Yes | Yes |
| Code review on github.com | Yes | Yes | Yes, plus REVIEW.md |
| Copilot CLI | Yes | Yes | Yes |
| Chat on github.com | Yes | — | — |
| VS Code Chat | Yes | Yes | AGENTS.md only |
| VS Code code review | Yes | — | — |
| Visual Studio Chat | Yes | Yes | — |
| JetBrains Chat | Yes | Yes | — |
| Xcode Chat and code review | Yes | Yes | — |
| Eclipse Chat | Yes | — | — |
— 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/pathreferences work in copilot-instructions.md, AGENTS.md and CLAUDE.md, not in GEMINI.md or.instructions.mdfiles. - 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.useAgentsMdFileon; nested files also needchat.useNestedAgentsMdFiles, experimental and off by default.chat.useClaudeMdFileadds CLAUDE.md,.claude/CLAUDE.md,~/.claude/CLAUDE.mdand 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?
| File | Where | Notes |
|---|---|---|
| Prompt files | .github/prompts/*.prompt.md | Reusable 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.md | Both 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?
- 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. - Check the path and name:
.github/copilot-instructions.mdat the repo root, and path files ending in.instructions.mdunder.github/instructions/. - Check the surface reads that file (table above). A path file or AGENTS.md does nothing in Chat on github.com.
- Check the
applyToglob matches the file being edited:src/*.pymissessrc/api/app.py. - In VS Code's Local harness, turn on
chat.useAgentsMdFileif your rules live in AGENTS.md. - Code review reads instructions from the pull request's head branch, so a change counts only once it's on that branch.
- 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.useClaudeMdFileon. 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