What Is copilot-instructions.md?
copilot-instructions.md is a Markdown file that provides project-specific instructions to GitHub Copilot. Location: .github/copilot-instructions.md (inside the .github directory, which also contains workflows and issue templates). When a developer uses Copilot in a repository with this file: Copilot reads the instructions and applies them to all chat responses and influences inline code suggestions. The file: customizes Copilot's behavior for your specific project, similar to how CLAUDE.md customizes Claude Code and .cursorrules customizes Cursor.
How Copilot reads it: Copilot Chat (Ctrl+Shift+I or the chat panel): reads the file and follows the instructions for all responses. Copilot inline suggestions (Tab completion): influenced by the instructions, though the influence is less direct than with chat (inline suggestions are also heavily influenced by the surrounding code context). The instructions: most impactful for Copilot Chat interactions where the AI generates multi-line code, explanations, and refactoring suggestions.
The file: Markdown format. No special syntax. Write your conventions as clear statements. The same content: works in copilot-instructions.md, CLAUDE.md, and .cursorrules. The only difference: the file name and the location (.github/ directory for Copilot, project root for Claude Code and Cursor). AI rule: 'The .github/ directory: Copilot's designated location for project files. The instructions file: sits alongside your GitHub Actions workflows and issue templates.'
Copilot-Specific Considerations
Context limitations: Copilot's instruction context is more limited than Claude Code's CLAUDE.md. A 5,000-word CLAUDE.md: Claude Code processes effectively. The same 5,000 words in copilot-instructions.md: Copilot may not apply all rules consistently (the later rules receive less attention). Recommendation: keep copilot-instructions.md concise — 15-20 of the most important rules. Under 2,000 words. The most critical rules: first in the file. AI rule: 'Copilot: concise instructions (15-20 rules, under 2,000 words). Claude Code: can handle more (30-50 rules, up to 5,000 words). If using both: the Copilot file may be a subset of the Claude Code file.'
Inline vs chat behavior: Copilot inline suggestions (Tab completion) are primarily context-driven — they learn from the surrounding code more than from the instructions file. The instructions: most effective for Copilot Chat (where the AI generates larger code blocks with more opportunity to follow conventions). For inline suggestions: the existing code in the file provides the primary context. The instructions file: reinforces conventions but does not override strong contextual signals from surrounding code.
Enterprise features: Copilot Business and Enterprise plans provide additional customization. Organization-level instructions (applied to all repos in the org — separate from the per-repo file), content exclusions (files Copilot should not suggest from), and knowledge bases (Enterprise only — Copilot references your organization's internal documentation). These features: supplement the per-repo instructions file. AI rule: 'Per-repo copilot-instructions.md: available on all Copilot plans. Organization-level instructions and knowledge bases: Business/Enterprise only.'
A 5,000-word instruction file: Copilot reads it but may not apply rules near the end consistently (context window effects). A 1,500-word file with 15 focused rules: Copilot applies each rule more consistently. For Copilot: less is more. The 15 most important rules: applied to every interaction. The remaining 35 (from your full rule set): handled by Claude Code or Cursor. Copilot gets the essential subset. Other tools get the complete set.
What to Include in copilot-instructions.md
The concise format: because Copilot's context is more limited, prioritize the highest-impact rules. Recommended sections: project context (2-3 sentences — tech stack and architecture), top 5 coding conventions (the patterns that matter most — naming, error handling, the primary framework pattern), testing convention (1-2 rules — framework and naming), and security essentials (2-3 rules — validation, authentication, no secrets). Total: 12-15 rules. Under 2,000 words.
Imperative language: Copilot responds well to direct instructions. 'Use async/await' rather than 'We prefer async/await.' 'Always validate inputs with Zod' rather than 'Input validation should be done when appropriate.' The imperative: clear, unambiguous, and leaves no room for interpretation. Compare: 'Consider using TypeScript strict mode' (vague — the AI may or may not enable it) vs 'TypeScript: strict mode enabled. No any type.' (specific — the AI follows it).
Example copilot-instructions content: 'Project: Next.js 16 App Router, TypeScript, Drizzle ORM, Tailwind CSS.\n\nConventions:\n- Server Components by default. "use client" only when needed.\n- async/await for all async. No .then() chains.\n- Named exports only.\n- Result<T, E> for error handling in services.\n\nTesting: Vitest. describe/it naming. Co-located.\n\nSecurity: Zod validation on all inputs. Parameterized queries only.' Total: 10 rules, ~200 words. Copilot: applies consistently because the instructions are concise and clear.
Copilot Chat: 'Create a new API endpoint.' The AI reads the instructions file AND the chat context. The instructions: strongly influence the output. Copilot inline (Tab): the developer types 'const user = ' and Copilot suggests the rest. The suggestion: primarily based on the surrounding code context (what patterns exist in the current file). The instructions: a secondary influence. For inline: the best way to guide Copilot is to have well-patterned code in the file (the AI learns from context). For chat: the instructions file is the primary guide.
copilot-instructions.md Alongside CLAUDE.md and .cursorrules
Many teams use multiple AI tools: Copilot for inline suggestions, Claude Code for CLI operations, and Cursor for complex features. Each tool: reads its own rule file. The content: should be consistent across all three. The approach: maintain one canonical source file, then distribute to all three locations. The source: contains the full 30-50 rule set. The Copilot version: may be a condensed subset (the top 15-20 rules) if the full file is too long for Copilot's context.
File coexistence: all three files can exist in the same repository simultaneously. CLAUDE.md (project root), .cursorrules (project root), and .github/copilot-instructions.md (.github directory). Git: tracks all three. Developers: use whichever AI tool they prefer. Each tool: reads its own file and follows the conventions. The result: consistent AI output regardless of which tool the developer uses. AI rule: 'All three files in one repo: no conflict. Each tool reads only its own file. The content: consistent (or the Copilot file is a concise subset of the others).'
Sync script: 'cp RULES.md CLAUDE.md && cp RULES.md .cursorrules && head -n 50 RULES.md > .github/copilot-instructions.md'. The script: copies the full source to Claude Code and Cursor files, and copies the first 50 lines (the most important rules) to the Copilot file. Add to: a pre-commit hook or the CI pipeline. The sync: ensures all three files are updated whenever the source changes. AI rule: 'The sync script: 1 line. Run in pre-commit or CI. All three files: always in sync. Zero manual maintenance.'
copilot-instructions.md goes in: .github/copilot-instructions.md. If the .github/ directory does not exist (some projects do not have GitHub Actions or issue templates): create it. mkdir .github && touch .github/copilot-instructions.md. A common mistake: placing the file at the project root (copilot-instructions.md without the .github/ directory). Copilot: does not read it from the root. It must be in .github/. Verify: the file path is exactly .github/copilot-instructions.md.
copilot-instructions.md Quick Reference
Quick reference for copilot-instructions.md.
- What: GitHub Copilot's project-specific instruction file for conventions and patterns
- Where: .github/copilot-instructions.md (inside the .github directory)
- Format: Markdown. Imperative language. Direct instructions, not suggestions
- Size: concise — 15-20 rules, under 2,000 words. Most important rules first
- Inline vs chat: strongest influence on Copilot Chat. Inline suggestions also influenced but context-driven
- Enterprise: organization-level instructions, content exclusions, knowledge bases (Business/Enterprise)
- Multi-tool: coexists with CLAUDE.md and .cursorrules. Same content or concise subset for Copilot
- Sync: one source file → distribute to all three tool files. Pre-commit hook or CI