copilot-instructions.md as a Repo-Level Instruction Convention¶
.github/copilot-instructions.mdis GitHub Copilot's repository-level instruction file -- a single Markdown file that injects project context into every Copilot interaction without repeating it per prompt.
Also known as: Instruction File Convention, Project Instruction Files
Copilot-specific convention. See also Instruction File Ecosystem (tool-agnostic) and CLAUDE.md Convention.
What it does¶
Copilot reads .github/copilot-instructions.md on every chat request, agent mode session, coding agent task, and code review (docs, GitHub Blog). Copilot appends the contents to the system prompt automatically. You do not reference or import the file.
File location and format¶
Place the file at .github/copilot-instructions.md. Write standard Markdown. Keep it under two pages (GitHub Blog) -- files approaching 1,000 lines degrade code review consistency (GitHub Blog).
What to include¶
GitHub recommends five categories:
- Project overview: purpose, audience, key features.
- Tech stack: frameworks, ORMs, runtimes, test runners (the Example below shows a TypeScript/Node stack).
- Coding guidelines: naming, error handling, formatting.
- Project structure: folder layout and directory purposes.
- Available resources: scripts, automation, MCP servers.
For the coding agent, add exact build and test commands, environment setup, and CI requirements (docs).
What not to include¶
- Task-specific instructions: put these in the prompt or path-specific files (docs).
- Full documentation: link to it instead of embedding it. Exception: code review cannot follow links, so inline review-specific content (GitHub Blog).
- Vague directives: "be more accurate" wastes tokens, so use imperative rules.
- Narrative prose: lists and headings work more reliably than paragraphs (GitHub Blog).
- Tool-specific syntax: Copilot ignores Claude Code or Cursor directives, so keep the file Copilot-specific or tool-neutral.
Instruction hierarchy¶
Copilot combines instructions from three scopes; higher-priority scopes win on conflict (docs):
| Priority | Scope | Where configured |
|---|---|---|
| 1 (highest) | Personal | GitHub.com user settings |
| 2 | Repository | .github/copilot-instructions.md |
| 3 (lowest) | Organization | Organization-level Copilot settings |
Path-specific instructions¶
For file-specific rules, create *.instructions.md files in .github/instructions/ with an applyTo glob (docs):
---
applyTo: "**/*.py"
---
Use type hints on all function signatures. Prefer `pathlib` over `os.path`.
These files also support excludeAgent ("code-review" or "coding-agent") to skip a feature. Move language-specific rules here to keep the repo-wide file short.
Feature support matrix¶
Support varies by IDE (docs):
| Platform | Chat | Code Review | Coding Agent |
|---|---|---|---|
| VS Code | Repo + Path + Agent | Repo + Path | Repo + Path + Agent |
| JetBrains | Repo + Path + Agent | Repo + Path | Repo + Path + Agent |
| GitHub.com | Repo + Path + Personal | Repo + Path + Org | Repo + Path + Agent |
| Visual Studio | Repo only | Repo only | -- |
| Xcode | Repo + Path | Repo + Path | Repo + Path + Agent |
copilot-instructions.md compared with AGENTS.md¶
| Dimension | copilot-instructions.md | AGENTS.md |
|---|---|---|
| Standard | GitHub Copilot proprietary | Open standard |
| Read by | GitHub Copilot features | Any AGENTS.md-compatible tool |
| Location | .github/copilot-instructions.md |
AGENTS.md at repo root |
| Hierarchy | Flat + path-specific | Directory-level traversal |
| Portability | Copilot only | Cross-tool |
Multi-tool teams can maintain both or consolidate into AGENTS.md (losing path-specific applyTo globs). See Instruction File Ecosystem for convergence strategies.
When this backfires¶
- Over-stuffed files: implementation details, full documentation, or task-specific context bloat the system prompt and use token budget that would otherwise hold conversation or code context. Stick to project-wide rules (GitHub Blog).
- Personal settings override: personal-scope instructions silently override repository instructions on conflict, so teammates with conflicting personal Copilot settings see different behavior.
- IDE feature gaps: Visual Studio only reads the repo-wide file -- it does not support path-specific and organization scopes, so
applyToworkflows break silently there. - Instructions do not guarantee compliance: GitHub notes that "providing instructions doesn't guarantee perfect code" -- the same request can yield different results across sessions (GitHub Blog). Treat instructions as a probabilistic nudge, not a contract.
Example¶
A minimal copilot-instructions.md for a Node.js API project:
# Project Overview
REST API for order management. Node.js 20, Express, PostgreSQL, Prisma ORM.
# Tech Stack
- Runtime: Node.js 20 (ESM)
- Framework: Express 5
- Database: PostgreSQL 16 via Prisma
- Tests: Vitest + Supertest
- CI: GitHub Actions
# Coding Guidelines
- TypeScript strict mode. No `any`.
- Use `zod` for request validation.
- Prefer named exports.
- Error responses follow RFC 9457 (Problem Details).
# Build & Test
- `npm run build` — compile TypeScript
- `npm test` — run Vitest suite
- `npm run lint` — ESLint + Prettier check
# Project Structure
- `src/routes/` — Express route handlers
- `src/services/` — business logic
- `src/db/` — Prisma client and migrations
- `tests/` — integration and unit tests
FAQ¶
What should I keep out of the file?
Task-specific instructions belong in the prompt or in path-specific files, and full documentation should be linked rather than embedded -- with one exception, since code review cannot follow links, so inline anything review-specific. Also drop vague directives like "be more accurate", narrative prose in place of lists and headings, and Claude Code or Cursor syntax, which Copilot ignores.
Does an instruction file guarantee Copilot follows it?
No. GitHub notes that "providing instructions doesn't guarantee perfect code" -- the same request can yield different results across sessions (GitHub Blog). Treat the file as a probabilistic nudge, not a contract. Personal-scope instructions also silently override repository ones, so teammates with conflicting personal settings see different behavior from the same file.
What does the coding agent need that chat does not?
Exact build and test commands, environment setup, and CI requirements, added on top of the five recommended categories -- project overview, tech stack, coding guidelines, project structure, and available resources. Copilot reads the repository file on every coding agent task, so those commands reach the system prompt automatically instead of being restated in each task description.
Key Takeaways¶
.github/copilot-instructions.mdis appended to Copilot's system prompt on every chat, agent mode, coding agent, and code review interaction -- no import needed.- Keep it under two pages; cover project overview, tech stack, coding guidelines, structure, and available resources.
- Personal scope outranks repository scope, which outranks organization scope -- conflicting personal settings silently override team intent.
- Move language- or path-specific rules into
.github/instructions/*.instructions.mdwithapplyToglobs; Visual Studio ignores them. - Compared to
AGENTS.md: Copilot-proprietary, flat plus path-specific, single location -- not portable to other tools.