GitHub Copilot custom instructions: where it lives and how tools read it

GitHub Copilot reads one repository-wide file, .github/copilot-instructions.md, plus path-specific .instructions.md files. It also honours AGENTS.md, or a single root CLAUDE.md or GEMINI.md.

Where it lives

• .github/copilot-instructions.md, applied to the whole repository.
• .github/instructions/**/NAME.instructions.md, applied to the files matched by applyTo.
• AGENTS.md anywhere in the repository; the nearest one wins.
• A single root CLAUDE.md or GEMINI.md, as an alternative.

Format

Markdown; whitespace between instructions is ignored. Only .instructions.md files take frontmatter: applyTo holds comma-separated globs and excludeAgent takes "code-review" or "cloud-agent". Code review dropped its 4,000-character limit on 2026-06-12, and GitHub recommends at most about 1,000 lines per file.

Frontmatter keys: applyToexcludeAgent

# Copilot instructions

This is a Rails app with a React front end in app/javascript/.

## Build and test

- Install: `bundle install && yarn install`
- Test: `bin/rails test`
- Lint: `bin/rubocop`

## Conventions

- Put business logic in app/services/, not in controllers.
- Every migration must be reversible.
- Never commit credentials or edit config/master.key.

Precedence and merging

Personal instructions come first, then repository, then organisation, and all relevant sets are still sent. When a path-specific file and the repository-wide file both match, Copilot uses both. Code review reads instructions from the pull request's head branch.

Tips

• On github.com, path-specific .instructions.md files work only for Copilot cloud agent and Copilot code review.
• Add excludeAgent: "code-review" to keep a file out of reviews while the cloud agent still uses it.
• Copilot cloud agent can draft copilot-instructions.md for you; keep it to about two pages and not tied to one task.

Other instruction files