Copilot instructions: repository-wide and per-path files

· 2 min read

GitHub Copilot reads two kinds of instruction file from your repository. One applies to everything; the others apply only to the files they name. This guide shows what goes in each and how to keep them short.

The two files

File Applies to
.github/copilot-instructions.md Every Copilot request in the repository
.github/instructions/<name>.instructions.md Files matching its applyTo patterns

Copilot also reads AGENTS.md. If you already keep project instructions there, keep the repository-wide file short, or leave it out, so the two do not say different things. See AGENTS.md vs CLAUDE.md.

Repository-wide instructions

Write what Copilot needs on every task and can not see from one file:

  • What the project is, in two or three sentences.
  • How to build, test and lint it, as exact commands.
  • Coding guidelines that apply everywhere.
  • Where things live: the main folders and what each holds.

It is added to every request, so every line costs on every request. Keep it to what changes the result.

Path instructions

A path instruction file starts with frontmatter that says which files it is for:

---
applyTo: 'src/**/*.test.ts'
description: How tests are written.
---

- Use Vitest. Put each test next to the file it tests.
- Test behaviour through public functions, not private helpers.
  • applyTo: glob patterns, separated by commas. **/* matches every file. Without it, Copilot does not use the file.
  • excludeAgent: optional, code-review or coding-agent, to keep the file away from one Copilot feature.

One file per concern (tests, React components, database migrations) is easier to keep true than one long file.

In Skill Builder

Add them under GitHub Copilot in the Files panel. Each starts from a short template, and the checks warn when applyTo is missing or a file grows past 500 lines. Export Ready for your project with GitHub Copilot ticked to get them in .github/.

Check GitHub’s Copilot documentation for the current fields: they change as Copilot adds features.

Next: How to write an AGENTS.md.