---
title: "GitHub Copilot custom instructions: paths and format · DotsAgent"
description: "Where .github/copilot-instructions.md lives, its format and frontmatter, how global and nested copies merge, and which tools read it. Checked 2026-10-01."
url: https://dotsagent.io/instructions/files/github-copilot-instructions
---

.github/copilot-instructions.md

# 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: `applyTo``excludeAgent`

`.github/copilot-instructions.md`

```
# 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.

Generate an AGENTS.md and matching rule files for five tools from one form. [Open the AGENTS.md generator →](https://dotsagent.io/instructions)

## Other instruction files

[AGENTS.md](https://dotsagent.io/instructions/files/agents-md)

[CLAUDE.md](https://dotsagent.io/instructions/files/claude-md)

[GEMINI.md](https://dotsagent.io/instructions/files/gemini-md)

[.cursor/rules/*.mdc](https://dotsagent.io/instructions/files/cursor-rules)

[.devin/rules/*.md](https://dotsagent.io/instructions/files/windsurf-rules)

[.clinerules/](https://dotsagent.io/instructions/files/cline-rules)

[~/.openclaw/workspace/AGENTS.md](https://dotsagent.io/instructions/files/openclaw-workspace)

## Sources

1. [docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)/en/copilot/how-tos/configure-custom-instructions/add-repository-instr
2. [docs.github.com](https://docs.github.com/en/copilot/reference/custom-instructions-support)/en/copilot/reference/custom-instructions-support
3. [docs.github.com](https://docs.github.com/en/copilot/tutorials/customize-code-review)/en/copilot/tutorials/customize-code-review
4. [github.blog](https://github.blog/changelog/2026-06-12-copilot-code-review-new-configurations-and-controls/)/changelog/2026-06-12-copilot-code-review-new-configurations-and-contr

Independent reference for people who build AI agents. Not affiliated with any vendor named here.

© 2026 DotsAgent · Facts checked October 1, 2026