COPILOT INSTRUCTIONS

GitHub Copilot reads repository-wide instructions from .github/copilot-instructions.md and path-specific ones from .github/instructions. Which other files it reads depends on where you use Copilot.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

What Is copilot-instructions.md?

.github/copilot-instructions.md is GitHub Copilot's repository-wide instructions file. It is plain Markdown that Copilot adds to requests made in the context of the repository. It is the one instructions file that every Copilot surface with custom instruction support reads.

Which Copilot Surfaces Read Which Files?

Last verified 2026-11-13 against the vendor documentation. GitHub's support matrix differs by surface:

Surfacecopilot-instructions.md.instructions.mdAGENTS.md / CLAUDE.md / GEMINI.md
Copilot Chat on GitHub.comYesNoNo
Cloud agent (GitHub.com)YesYesYes, all three
Code review (GitHub.com)YesYesYes, plus REVIEW.md
VS Code chatYesYesAGENTS.md only
Visual Studio chatYesYesNo
JetBrains chatYesYesNo
Copilot CLIYesYesYes, all three

Because several chat surfaces read only copilot-instructions.md, a file that merely says "see AGENTS.md" leaves them with nothing useful. Keep the essentials inline. The full cross-tool view is on the compatibility page.

What Should copilot-instructions.md Contain?

The pattern 2prompt generates: a pointer to AGENTS.md for surfaces that read it, plus the essentials inline for those that do not.

# Copilot instructions

Project: shop-api. Order and checkout API for the storefront.

The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.

## Stack

- Language: TypeScript
- Framework: Fastify
- Database: PostgreSQL
- Tests: Vitest
- Package manager: pnpm

## Commands

- Install dependencies: `pnpm install`
- Run locally: `pnpm dev`
- Run all tests: `pnpm test`
- Lint: `pnpm lint`
- Type-check: `pnpm tsc --noEmit`

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.

How Do Path-Specific Instructions Work?

Files named NAME.instructions.md under .github/instructions/ apply only to matching paths, declared with an applyTo glob in frontmatter:

---
applyTo: "src/db/**/*.ts"
---

- Use parameterized queries only.
- Every new migration needs a matching rollback.
  1. Keep repository-wide rules in copilot-instructions.md.
  2. Move rules that only matter for one folder into a path-specific file.
  3. Check the surface table: Copilot Chat on GitHub.com does not read path-specific files.

How Long Should copilot-instructions.md Be?

We did not find a hard character limit in GitHub's documentation on the verification date, so check GitHub's docs for current guidance. Practically, the file is added to many requests, so keep it to a screen or two: the stack, the commands, and the handful of rules that prevent the most common bad suggestions.

What Belongs in copilot-instructions.md and What Does Not?

Because this file reaches every Copilot surface, it should hold the rules whose absence causes the most rework: the package manager, the commands that prove a change works, and the handful of constraints a reviewer would reject a pull request for. It is a poor place for long explanations of architecture or history.

  • Keep: stack, commands, must-follow rules, a pointer to AGENTS.md.
  • Move to AGENTS.md: project layout, detailed style rules, phase and background.
  • Move to path-specific files: rules that only apply to one folder or file type.
  • Remove: persona text, motivational lines and anything an agent cannot check.

A short file that is always right beats a long one that is half stale.

One practical test: open the file and ask whether a new contributor would learn something concrete from every line. If a line would only make sense to someone who already knows the project, move it to AGENTS.md or delete it.

What Are the Common Mistakes?

  • Putting the file at the repository root instead of inside .github/.
  • A pointer-only file that tells chat surfaces to read AGENTS.md, which they cannot.
  • Copying all of AGENTS.md in, so two long files drift apart.
  • Expecting path-specific instructions to work in every surface.
  • Vague guidance like "write good code" instead of concrete rules.

Generate a matched pair with the generator, check an existing file with the linter, convert one with the copilot-instructions.md to AGENTS.md converter, or read AGENTS.md vs copilot-instructions.md.

Frequently Asked Questions

Where does copilot-instructions.md go?

Inside the .github directory at the repository root, as .github/copilot-instructions.md. Path-specific files go in .github/instructions and end in .instructions.md.

Does Copilot read AGENTS.md?

In some places. The cloud agent, code review and the Copilot CLI read AGENTS.md, CLAUDE.md and GEMINI.md, and VS Code chat reads AGENTS.md. Copilot Chat on GitHub.com, Visual Studio and JetBrains chat do not, according to the GitHub support matrix.

What is applyTo?

applyTo is the frontmatter field in a path-specific .instructions.md file. It holds a glob such as src/db/**/*.ts, and the instructions apply only when Copilot works on files that match it.

Should copilot-instructions.md just point to AGENTS.md?

No. Several Copilot chat surfaces read only copilot-instructions.md, so a pointer alone leaves them without instructions. Keep the stack, commands and key rules inline and point to AGENTS.md for the rest.

Was this helpful?