Copilot instructions and what each surface reads

This page is about the instruction files of GitHub Copilot, the coding assistant. Microsoft 365 Copilot is a different product, and nothing here applies to it.

GitHub Copilot’s instructions file is .github/copilot-instructions.md, a Markdown file of rules for one repository. Copilot adds it to your requests without being asked. Nearly every Copilot surface reads it: Chat in each IDE and on GitHub.com, the Copilot CLI, the cloud agent and code review. Rules that matter only for some files go in .github/instructions, in files that name the files they cover.

Copilot often changes how it reads these files. Code review on GitHub changed in both June and July 2026, according to GitHub’s changelog. Everything below was checked against GitHub’s and Microsoft’s documentation on 12 October 2026.

Which Copilot surfaces read which file

A surface is one place you use Copilot. It might be Chat in an IDE, the Copilot CLI in a terminal or code review on a pull request. The cloud agent is a surface too. It works on a task by itself and opens a pull request. GitHub’s Support for different types of custom instructions (2026) sets out what each one reads:

GitHub’s pages disagree about Chat in JetBrains IDEs and Xcode. The support table lists path-specific files for both. Adding repository custom instructions for GitHub Copilot in your IDE (2026) says each supports “a single .github/copilot-instructions.md custom instructions file”. Until the two agree, don’t count on .github/instructions reaching Chat there.

Your own personal instructions, and any your organisation sets on GitHub.com, sit beside the repository’s. Adding repository custom instructions for GitHub Copilot (2026) says Copilot gets every set that applies. Personal instructions take priority, then the repository’s and then the organisation’s.

How to add a Copilot instructions file to a repository

1. Create .github/copilot-instructions.md at the root of the repository, making the .github folder first if there isn’t one.
2. Write the rules in Markdown. GitHub’s docs say whitespace between instructions is ignored, so lay the file out for people to read.
3. Commit and push it. Your IDE uses the file as soon as you save it, but the cloud agent and code review on GitHub read the pushed copy.
4. Check that Copilot found it. In VS Code, Visual Studio, JetBrains IDEs and Xcode, the file appears in the References list under a Chat answer. In the Copilot CLI, /instructions lists the files it found for the session.

The Copilot CLI picks up a change only in a new or resumed session, according to Adding custom instructions for GitHub Copilot CLI (2026). Code review uses the file because of a repository setting, Use custom instructions when reviewing pull requests, under Settings, Copilot and Code review. It’s on by default.

Copilot instructions best practices

“Instructions are automatically added to requests that you submit to Copilot,” says GitHub’s page on repository instructions. So every line in the file goes with every request on the surfaces that read it. Keep it to rules that apply to every task, and move the rest to files that load only when they’re needed. AI3 Working Context argues for keeping that always-sent text short.

GitHub’s code review tutorial (2026) is written for code review, but its advice suits the file wherever it’s read:

• Give each topic its own heading, and write the rules as bullet points.
• Write short, direct instructions rather than long paragraphs, with examples of right and wrong code.
• Start with 10 to 20 specific instructions, try them on real pull requests and add more as you learn what works.
• Leave out vague requests such as “Be more accurate”. The tutorial says they add noise.
• Copy a standard into the file rather than linking to it. Code review doesn’t follow external links.
• Don’t let two rules contradict each other, in this file or in any other file Copilot reads.

GitHub’s tutorial also sets a ceiling on length: “Limit any single instruction file to a maximum of about 1,000 lines. Beyond this, the quality of responses may deteriorate.”

Copilot instructions examples

Prickles builds a rule pack for Copilot from its canon, the single text every Prickles pack is generated from. In release 3.0.0, the pack’s .github/copilot-instructions.md holds every tenet’s rule under nine pillar headings, in 82 lines and about 11 KB. Each heading names the file that holds the rest of that pillar and says when to read it. Here’s one pillar’s section:

## Style (S2–S5). Before you write or change source code, read `.github/instructions/prickles-style.instructions.md`.

- **S2 Cyclomatic Caps.** Cap cyclomatic complexity per function. The number is editorial. Pick one and put it in the linter.
- **S3 Parameter Object.** Cap function parameters at three. The fourth parameter is the missing struct.
- **S4 Guard Clauses.** When a function's preconditions are nested as conditionals, lift each one to a guarded early return at the top of the function.
- **S5 Inline-First.** Inline first. Extract when a name is needed. A binding justifies itself when its name carries information the expression does not.

Each heading names its pillar’s file as a plain path, never as an @ import. The CLI docs say the Copilot CLI reads a file named with @ “immediately”. An import would load every pillar in full at the start of each CLI session.

That file is the same for all five languages the packs cover. Only the path-specific files differ, in their applyTo globs, which say which files each one covers. Foundations, Architecture, Style and Patterns cover code files. Types & Schema adds schema files such as **/*.sql, and Testing covers test files:

Every language’s test globs also take **/*.feature, for Gherkin scenarios. Here’s the top of the TypeScript pack’s Testing file, .github/instructions/prickles-testing.instructions.md:

---
applyTo: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,**/__tests__/**,**/*.feature"
description: "Use before writing, changing or reviewing any test in this repository: unit tests, end-to-end tests and Gherkin scenarios. Holds the rest of the Prickles Testing tenets, TS1 Living Documentation, TS2 Specification by Example, TS3 Parameterised Scenarios, TS4 Real-Dependency E2E, TS5 Structural Assertions, TS6 Behaviour Testing, TS7 Test Isolation, TS8 One Concept Per Test, which bind you exactly as the always-loaded Prickles entry does."
---

Process, AI Collaboration and Tooling aren’t tied to a kind of file, so they’re skills in .github/skills. Copilot reads a skill when a task needs it. The pack’s Strict layout puts the whole canon in one copilot-instructions.md of 543 lines instead.

For other people’s files, GitHub’s Awesome GitHub Copilot repository collects instruction files from the community. Its README says they come from third-party developers and asks you to inspect them before you install one.

Instructions for some files only

A path-specific file lives in or below .github/instructions, and its name ends in .instructions.md. Its frontmatter, the block of settings between --- lines at the top, holds applyTo. That’s a glob, a file pattern. **/*.ts, for example, matches every TypeScript file in every folder. Several globs go in one string, separated by commas.

GitHub’s repository instructions page says that when a path-specific file and the repository-wide file both apply, Copilot uses both:

When a path-specific file loads depends on the surface:

• Code review on GitHub.com, the cloud agent and the Copilot CLI use it when its applyTo matches a file they’re working on.
• VS Code attaches it when its applyTo matches a file the agent creates or changes. Microsoft’s Use custom instructions in VS Code (2026) adds that a clear description in the frontmatter helps. The agent uses it to decide whether to read the file for the task in hand.
• Chat on GitHub.com and in Eclipse doesn’t read it, and nor does code review in VS Code or Visual Studio.

excludeAgent: "code-review" or excludeAgent: "cloud-agent" in the frontmatter keeps a file away from one of those two. A file with applyTo: "**" matches every file, so it loads as often as the repository-wide file does.

Skills make a third kind of file. Each skill is a folder in .github/skills holding a SKILL.md file. GitHub’s About agent skills (2026) says Copilot loads one “when relevant”. That works on the cloud agent, code review, the Copilot CLI, the GitHub Copilot app and agent mode in VS Code and JetBrains IDEs.

Copilot code review and custom instructions

Code review on GitHub.com reads more files than any other surface. GitHub’s code review page (2026) lists them:

• .github/copilot-instructions.md, for review guidance across the whole repository
• AGENTS.md at the root, for context on how the project works
• path-specific files, for the files they match
• CLAUDE.md, GEMINI.md and REVIEW.md, if they exist
• skills in .github/skills

Before 12 June 2026, code review stopped reading copilot-instructions.md and *.instructions.md files once they reached 4,000 characters. “That limit has now been removed,” GitHub’s changelog said that day, so a guide that still gives the limit is out of date. GitHub’s 1,000-line advice above comes nearest to a limit now.

Some instructions don’t work in code review, however they’re written. GitHub’s tutorial lists changing the format of review comments, adding emoji, editing the pull request’s overview comment and blocking a merge until every comment is dealt with.

Since 17 July 2026, code review has read instructions, AGENTS.md and skills from the pull request’s head branch, according to GitHub’s changelog. The head branch holds the changes. They merge into the base branch. GitHub’s code review page gives the reason. You can test a change to the review instructions in the same pull request, without merging it first.

Reading from the head branch also lets a pull request change the instructions that review it. That’s a risk where Copilot’s approval counts. By default Copilot leaves a comment rather than an approval. Once approvals are switched on, though, Using GitHub Copilot code review (2026) says Copilot’s approval can satisfy a required-approval rule. The feature is in public preview and off by default.

GitHub’s code owners feature works from the other side. A CODEOWNERS file names who owns each path, and GitHub asks those people to review any pull request that changes it. A branch protection rule can also require their approval:

/.github/copilot-instructions.md @your-org/maintainers
/.github/instructions/ @your-org/maintainers
/.github/skills/ @your-org/maintainers
/AGENTS.md @your-org/maintainers
/CLAUDE.md @your-org/maintainers
/GEMINI.md @your-org/maintainers
/REVIEW.md @your-org/maintainers

P7 Short-Lived Branches with AI+Human Review keeps a person in the review beside the AI. A pull request that edits the review rules is one for that person to read closely. For what to ask any reviewer to check, see AI code review.

Copilot instructions in VS Code

VS Code can hand a chat session to more than one agent program, each sending your request to a model and running the agent’s tools. Besides its own Local agent, it offers programs for Copilot, Anthropic’s Claude and OpenAI’s Codex. Microsoft’s VS Code page, last updated on 7 October 2026, says sessions on those “use the discovery rules and file formats of the selected harness”.

The Local agent reads copilot-instructions.md, AGENTS.md and CLAUDE.md. Each has a setting:

• github.copilot.chat.codeGeneration.useInstructionFiles switches copilot-instructions.md on or off.
• chat.useAgentsMdFile and chat.useClaudeMdFile do the same for AGENTS.md and CLAUDE.md.
• chat.useNestedAgentsMdFiles reads AGENTS.md files in subfolders too. It’s off by default.

GitHub’s support table lists only AGENTS.md for Chat in VS Code, so reading CLAUDE.md goes beyond it. To see what a request used, expand References under the answer. Microsoft’s page adds that all the sources that apply are added together, and advises against relying on any order between files to settle a conflict.

Copilot instructions vs AGENTS.md

Most other coding agents read AGENTS.md, a plain Markdown instructions file. Copilot reads it on the cloud agent, the Copilot CLI, Chat in VS Code and code review on GitHub.com. Everywhere else in the table, only copilot-instructions.md reaches Copilot. A team with anyone using Copilot Chat on GitHub.com or in Visual Studio, JetBrains IDEs, Eclipse or Xcode needs that file even when AGENTS.md holds the rules.

Copilot uses every copy it finds. The CLI docs say it removes a duplicate only when the copies are identical. They add that it defines no general order of precedence between files. So rules kept in both files reach the model twice on the surfaces that read both. Once one copy is edited and the other isn’t, Copilot gets two versions of the same rule. In the CLI, an @AGENTS.md line in copilot-instructions.md pulls the file in a second way. The docs don’t say whether the duplicate check catches it.

F3 Don’t Repeat Yourself applies to instruction files as much as to code. Give each rule one home, and generate any copy from it. CLAUDE.md vs AGENTS.md compares the files each agent reads. It also shows how to generate .github/copilot-instructions.md from AGENTS.md and fail CI when the two differ.