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