Copilot instructions: setup and what 90 top repos write

Updated October 15, 2026 · 9 min read

Copilot instructions are markdown files that GitHub Copilot adds to your requests so you do not repeat project rules in every prompt. Put repository-wide rules in .github/copilot-instructions.md, rules for certain files in .github/instructions/NAME.instructions.md with an applyTo glob, and rules every agent should read in AGENTS.md. Personal and organization instructions sit in GitHub settings. We read the files in 90 of the most-starred GitHub repositories: 14 just point to another file, and the 85 that hold text have a median of 64 lines.

The GitHub and VS Code facts below come from their documentation, read on 15 October 2026.

What kinds of Copilot instructions are there?

With AGENTS.md, the nearest file in the directory tree takes precedence when Copilot is working. Organization instructions apply to every member of the organization, whether or not their Copilot seat comes from it, and only an organization owner can set them.

Which Copilot features read which file?

Support differs by feature and editor. From GitHub’s support reference:

In VS Code, custom instructions do not apply to the inline suggestions you get as you type.

On GitHub.com, path-specific instructions reach only the cloud agent and code review. Code review reads instructions from the head branch of the pull request, so you can test a change to them in the same pull request before you merge it.

How do I write a copilot-instructions.md file?

1. Create .github/copilot-instructions.md at the root of the repository (make the .github folder if there is none).
2. Write the instructions in markdown. Whitespace between instructions is ignored.
3. Commit and push it. Copilot uses it from then on.

GitHub’s advice is short, self-contained statements that apply to most requests, because the file is sent with every chat message. Its suggested contents are a project overview, coding standards and conventions, and the tools, libraries and versions in use. It warns that instructions to consult external resources, answer in a set style or always give a certain level of detail may cause problems in a large, diverse repository.

A minimal file in that shape:

# Project overview
An invoicing API in TypeScript on Node.js 22, with Postgres through Prisma.

## Build and test
- Install with `pnpm install`; run `pnpm test` before you finish a change
- Run `pnpm lint --fix` on files you touch

## Conventions
- HTTP handlers live in `src/routes`, database access in `src/repositories`
- Return errors as `{ code, message }`; never throw raw strings from a handler
- Do not add a dependency without saying why in the pull request

You can also ask the Copilot cloud agent to write one. GitHub publishes the prompt to paste at github.com/copilot/agents; it asks for build, test and lint steps validated by running them, and limits the result to two pages. The first time the cloud agent opens a pull request in a repository, it leaves a comment with a link that does the same.

To check the file was used, expand the references at the top of a Copilot Chat response and look for .github/copilot-instructions.md.

How do path-specific .instructions.md files work?

Each file is named NAME.instructions.md and sits in .github/instructions/ or a subfolder of it. Frontmatter at the top says which files it covers:

---
applyTo: "**/*.ts,**/*.tsx"
---

- Use Vitest; one behavior per `it` block
- Import types with `import type`

When a path matches and a repository-wide file exists, Copilot uses both. On GitHub.com, excludeAgent: "code-review" or excludeAgent: "cloud-agent" keeps a file away from one of the two. VS Code adds two optional fields: name for display and description, which lets the agent load a file on demand when the task matches. A file with neither applyTo nor description is attached by hand in VS Code.

Which Copilot instructions win when they conflict?

GitHub’s order, highest first:

1. Personal instructions
2. Path-specific instructions in .github/instructions/
3. Repository-wide .github/copilot-instructions.md
4. Agent instructions such as AGENTS.md
5. Organization instructions

All of the sets that apply are still sent to Copilot. VS Code’s docs go further and say not to depend on any order, because discovery and merging differ by harness: fix contradictions in the files themselves.

What do real copilot-instructions.md files contain?

We used the same 1,000 most-starred active GitHub repositories as our CLAUDE.md examples study: public repositories with more than 1,000 stars, not archived, pushed since 1 July 2026, listed on 1 October 2026. On 12 October, 91 had .github/copilot-instructions.md and 24 had a .github/instructions/ folder. On 15 October we fetched each file from the default branch; 90 were still there.

Rows after the median count the 85 text files and leave the symlinks out. A script did the counting, with command and “do not” patterns like those in the CLAUDE.md study, so the figures are approximate.

The files run shorter than CLAUDE.md files. In our CLAUDE.md study, files that hold their own instructions had a median of 118 lines; the 76 Copilot files that hold their own have a median of 76.5.

Many projects use the file as an adapter. Five of the nine short notes send Copilot to AGENTS.md, and the others name CLAUDE.md, a Claude skill file or a project agent guide. The five symlinks are named after AGENTS.md or a similar agent file.

Some files exist only for code review. Six of the short ones cover nothing but pull request reviews, and two of those tell Copilot not to review at all: Django’s answers every request for a review with a fixed sentence telling contributors to ask for one in their own fork.

Path-specific files are rarer. The 24 repositories with .github/instructions/ have a median of 2 instruction files at the top of the folder; microsoft/vscode has 26 there. In the 65 files we sampled (up to five per repository), 59 have an applyTo line and 3 use excludeAgent.

These are public projects with many outside contributors, who use many different tools. A company that has standardized on Copilot may write longer files; we did not measure that.

Copilot instructions examples

Fiber, a Go web framework, keeps its whole file, 14 lines, to the steps every change goes through (source):

When modifying code, always perform these steps:

1. **Ensure code quality**
   - `make format` to format the project.
   - `make lint` for static analysis.
   - `make test` to run the test suite.

Metasploit uses the file as a pointer and keeps the detail elsewhere (source):

Refer to [AGENTS.md](../AGENTS.md) in the repository root for all project conventions, coding standards, and AI agent guidelines.

Path-scoped instructions in `.github/instructions/` provide file-type-specific guidance for modules, library code, tests, and documentation.

Should a team use copilot-instructions.md or AGENTS.md?

If the team uses only Copilot, .github/copilot-instructions.md plus a few path-specific files is enough. If people also use Claude Code, Codex or Cursor, put the shared rules in AGENTS.md (the AGENTS.md guide lists which agents read it) and keep copilot-instructions.md for what only Copilot needs.

Before you shrink the Copilot file to a one-line pointer, check the support table above. Copilot Chat on GitHub.com, Visual Studio and code review in VS Code do not read AGENTS.md, so a pointer leaves them with one sentence. GitHub’s code review guide says review does not follow links to outside standards, and VS Code documents linked instruction files only for its own chat. For the other features it is not documented, and we have not tested it. Copying the rules every review must see into the Copilot file costs a few lines and avoids the question.

For rules that cross repositories, organization instructions are the Copilot route, on Business and Enterprise plans. GitHub lists Copilot Chat, code review and the cloud agent on GitHub.com as the features that read them; VS Code includes them when github.copilot.chat.organizationInstructions.enabled is on. Cursor has team rules for the same job on its Teams plan, covered in the Cursor rules guide, and Claude Code has managed settings, covered in Claude Code for teams.

What do Copilot instructions not cover?

Instruction files hold short rules that load into every request, and GitHub’s code review guide recommends keeping each under about 1,000 lines. Knowledge that is not an instruction, such as why the team chose a vendor, what an incident review found or how three services fit together, does not belong in them, and each tool reads its own files. Our context engineering guide covers what to load and when.

Dexio is a hosted wiki that AI agents read and write over MCP. Claude Code, Codex, Cursor and your other agents search, read, write and link markdown pages in one wiki, and people see what their agents know as a page graph. It is open source (AGPL-3.0), free for one person, and agents never count as paid members.

Dexio’s setup instructions cover clients they do not name: add a remote MCP server over Streamable HTTP at https://app.dexio.wiki/mcp with an Authorization header carrying the API key. We have not tested that in Copilot. If you connect it, lines like these in copilot-instructions.md say when to use the wiki:

## Team wiki
- Search the Dexio wiki with `search_pages` before you work on an unfamiliar area
- When you work out something the team will need again, update the page that
  exists or write a new one, and put "Copilot" in the `agent` field

FAQ

Where does copilot-instructions.md go?

In the .github folder at the root of the repository: .github/copilot-instructions.md.

Does Copilot read AGENTS.md?

Yes, in the cloud agent, code review on GitHub.com, Copilot Chat in VS Code and Copilot CLI. Copilot Chat on GitHub.com, Visual Studio and code review in VS Code do not, per GitHub’s support reference.

How long should Copilot instructions be?

GitHub’s code review guide says to keep any single file under about 1,000 lines, and its generation prompt caps a generated file at two pages. The median in our sample is 64 lines.

Do custom instructions affect code completions?

Not in VS Code: its docs say custom instructions are not used for inline suggestions as you type.

Sources

• https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions
• https://docs.github.com/en/copilot/concepts/prompting/response-customization
• https://docs.github.com/en/copilot/reference/custom-instructions-support
• https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-organization-instructions
• https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-personal-instructions
• https://docs.github.com/en/copilot/tutorials/customize-code-review
• https://code.visualstudio.com/docs/agent-customization/custom-instructions
• https://github.com/gofiber/fiber/blob/main/.github/copilot-instructions.md
• https://github.com/rapid7/metasploit-framework/blob/master/.github/copilot-instructions.md
• https://github.com/django/django/blob/main/.github/copilot-instructions.md
• https://dexio.wiki/agents.md
• https://dexio.wiki/pricing/