Blog
Published: September 23, 2026
.github/copilot-instructions.md is the repository-wide instruction file GitHub Copilot adds to every request in that repo. Keep it under two pages and not task specific. Put rules for one part of the codebase in .github/instructions/*.instructions.md with an applyTo glob. Copilot's agents also read AGENTS.md.
Every fact below was checked against GitHub's custom instructions docs and its support matrix on 2026-09-23. Which Copilot surface reads which file differs more than most guides admit, so the matrix is the part worth bookmarking.
What are the types of Copilot custom instructions? #
| Type | File | Applies to |
|---|---|---|
| Repository-wide | .github/copilot-instructions.md |
Every request in the repository |
| Path-specific | .github/instructions/NAME.instructions.md |
Files matching its applyTo glob, on top of the repository-wide file |
| Agent instructions | AGENTS.md ,CLAUDE.md orGEMINI.md , anywhere in the repo |
Copilot agents. The nearest file in the directory tree takes precedence |
| Personal | Your GitHub settings | You, on the surfaces that support it |
| Organization | Org settings | Everyone in the org, on the surfaces that support it |
When more than one applies, GitHub sends all of them. Where they conflict, personal instructions win, then repository, then organization.
How do you write copilot-instructions.md? #
GitHub's guidance is that the repository-wide file should be no longer than two pages and should not be task specific. Treat it as the short list of things a new engineer would get wrong in their first week, not as the onboarding doc.
TypeScript, Node 22, Postgres through Prisma. Tests: npm test.
- Webhook handlers must be idempotent. Key on the provider's event id.
- Retries go through src/lib/retry.ts. Five attempts, then dead-letter.
Why: docs/decisions/0012-webhook-retries.md
- Never edit a migration that has been merged. Write a new one.
The same rules of thumb apply as for any instruction file. Write down what the model cannot infer from the code, give the reason next to the rule, and point at files instead of pasting them. The research on whether these files help at all is summarised in is AGENTS.md useful.
How do path-specific .instructions.md files work? #
A path-specific file lives in .github/instructions/, ends in .instructions.md, and opens with frontmatter naming the paths it covers:
---
applyTo: "src/payments/**/*.ts"
---
Use the shared backoff in src/lib/retry.ts. Do not add a retry loop.
An optional excludeAgent key keeps a file away from either code review or the cloud agent. When Copilot works on a matching file, the path-specific instructions are combined with the repository-wide ones. This is the cheapest way to keep a rule about payments out of a request about CSS.
Which Copilot features read which instruction files? #
Not every surface reads every file. From GitHub's support matrix, for the surfaces most teams use:
| Surface | copilot-instructions.md | .instructions.md | AGENTS.md / CLAUDE.md |
|---|---|---|---|
| GitHub.com chat | Yes | No | No |
| Cloud agent (GitHub.com) | Yes | Yes | Yes |
| Code review (GitHub.com) | Yes | Yes | AGENTS.md only |
| VS Code chat | Yes | Yes | AGENTS.md only |
| VS Code code review | Yes | No | No |
| JetBrains chat | Yes | Yes | No |
| Visual Studio chat | Yes | Yes | No |
| Copilot CLI | Yes | Yes | Yes |
The practical reading: copilot-instructions.md is the only file every surface reads. A rule that lives only in AGENTS.md reaches the cloud agent, the CLI and VS Code chat, and misses GitHub.com chat and JetBrains chat.
AGENTS.md vs copilot-instructions.md: which should you use? #
If everyone uses Copilot, copilot-instructions.md reaches the most surfaces. If the team is mixed, and most are, the rules end up needing to be in both: AGENTS.md for Codex, Cursor and Claude Code, and copilot-instructions.md for the Copilot surfaces that do not read AGENTS.md. The usual answer is to keep one canonical file and make the other a short pointer to it, then check that the pointer is actually followed on each surface. The tool-by-tool view is in AGENTS.md vs CLAUDE.md: which tools read which.
How do you know Copilot used your instructions? #
In Copilot Chat, expand the References list at the top of a response. If .github/copilot-instructions.md is listed, the file was sent with that request. That tells you the file was included. It does not tell you which line of it shaped the answer, and on a two-page file that is the question that matters when you are deciding what to cut.
What is Copilot Memory, and does it replace instructions? #
Copilot Memory is in public preview. It stores repository-level facts with citations to the code that supports them, checks those citations against the current branch before using a fact, and deletes facts that go unused for 28 days. The cloud agent, code review and the CLI use it. Repository owners can review and delete what it stored.
It does not replace instructions, and it is not built to. It learns from the code and from work in that one repository. The decision your team made in a Slack thread last month, which is in no code yet, is not something it can learn. How it compares with Claude Code, Codex and Cursor is in Claude Code memory vs Codex, Cursor and Copilot.
Where Harbor fits #
An instruction file is a copy of decisions made somewhere else: a pull request review, a thread in #eng-payments, a design doc. Somebody has to notice, write it down, and write it down again for each tool's file. Harbor reads those places, a person approves what becomes a fact (or a policy you set approves the routine ones), and every agent is served only the facts that apply to its task.
Copilot's agent mode in VS Code can add a remote MCP server, and Harbor is one: any client that speaks MCP can search your team's approved facts at https://mcp.gethrbr.com/mcp. That is a pull-only connection. harbor init installs the fuller setup, with facts served at session start and write-back through review, for Claude Code, Codex and Cursor, not for Copilot. Answers cite the facts they used as [#1], and Harbor counts, per fact, served against cited. A cite is evidence, not proof, and that count is the one the References list cannot give you. See served vs cited.
Questions #
Where does copilot-instructions.md go?
In the .github folder at the root of the repository: .github/copilot-instructions.md. Copilot adds it to every request made in the context of that repository.
How long should copilot-instructions.md be?
GitHub says repository-wide instructions should be no longer than two pages and should not be task specific. Move rules for one area of the code into path-specific .instructions.md files.
Does GitHub Copilot read AGENTS.md?
Partly. The Copilot cloud agent and Copilot CLI read AGENTS.md, CLAUDE.md and GEMINI.md, and VS Code chat and GitHub.com code review read AGENTS.md. GitHub.com chat and JetBrains chat do not.
What is the difference between copilot-instructions.md and .instructions.md files?
copilot-instructions.md applies to every request in the repository. A .instructions.md file in .github/instructions/ applies only to files matching its applyTo glob, and is combined with the repository-wide file.
How do I check that Copilot used my instructions?
In Copilot Chat, expand the References list at the top of a response. If .github/copilot-instructions.md is listed, the file was sent with that request.