How to Write copilot-instructions.md for GitHub Copilot

What Is copilot-instructions.md?

GitHub Copilot's copilot-instructions.md is a markdown file that provides project-level context to Copilot's code completions and chat responses. It lives at .github/copilot-instructions.md — inside the .github directory alongside your workflows, issue templates, and other GitHub configuration.

When Copilot detects this file in your repository, it reads the instructions before generating suggestions. This means every code completion, chat response, and inline suggestion is informed by your project-specific conventions. Without it, Copilot relies entirely on the surrounding code and its training data.

The feature was introduced as part of GitHub's push to make Copilot more customizable at the organization and project level. It's supported in VS Code, JetBrains IDEs, and GitHub.com's Copilot chat — anywhere Copilot operates with access to your repository.

File Format and Placement

The file must be placed at exactly .github/copilot-instructions.md. Not in the repo root, not in a copilot/ directory, not with a different name. The .github/ directory must already exist (it typically does if you use GitHub Actions or issue templates).

The format is standard markdown. You can use headers, bullet lists, numbered lists, and inline code. However, Copilot's instruction processing is optimized for concise, direct statements rather than lengthy prose. Think of each instruction as a single, actionable directive.

Keep the file under 100 lines. Copilot processes instructions differently than Claude Code or Cursor — it's designed for shorter, more focused instruction sets. If you need extensive rules, prioritize the most impactful ones and leave formatting/style rules to your linter.

1. 1Create the .github/ directory if it doesn't exist: mkdir -p .github
2. 2Create the file: touch .github/copilot-instructions.md
3. 3Add your instructions in markdown format
4. 4Commit and push to your repository
5. 5Copilot will read the file on your next interaction

Writing Effective Copilot Instructions

Copilot responds best to short, declarative statements. Unlike CLAUDE.md where you can write multi-paragraph explanations with examples, Copilot instructions work best as a focused list of preferences and constraints.

Lead with your most important rules. Copilot weights instructions roughly in order, so put critical conventions — framework choices, language patterns, security rules — at the top. Put nice-to-have preferences at the bottom.

Be specific about your stack. 'This is a Next.js 16 project using the App Router, TypeScript strict mode, Tailwind CSS, and Drizzle ORM with PostgreSQL' in one sentence gives Copilot more actionable context than five paragraphs of explanation. Copilot excels at applying stack-specific patterns once it knows what stack you're using.

Focus on decisions, not formatting. Copilot's completions are already influenced by the surrounding code's formatting. Your instructions should address higher-level decisions: which library to prefer, what error handling pattern to use, which API patterns to follow.

Examples for Common Stacks

For a TypeScript/Next.js project, effective instructions might include: 'Use React Server Components by default. Only use "use client" for interactive components. Prefer named exports. Use Zod for all input validation. Fetch data in server components, never with useEffect. Use Tailwind utility classes, never custom CSS.'

For a Python/Django project: 'Use Django REST Framework for all API endpoints. Use type hints on all function signatures. Use Pydantic or Django serializers for validation, never manual dict parsing. Always use Django's ORM, never raw SQL. Write tests with pytest, not unittest.'

For a Go project: 'Handle errors explicitly — always check returned errors. Wrap errors with fmt.Errorf and %w. Use context.Context as the first parameter in functions that do I/O. Write table-driven tests. Keep interfaces small, 1-3 methods maximum.'

Notice the pattern: each instruction is one sentence, states a clear preference, and is specific enough that there's no ambiguity. This format aligns with how Copilot processes instructions most effectively.

How It Compares to CLAUDE.md and .cursorrules

All three files serve the same purpose but with different strengths. Copilot instructions are the most constrained: single file, flat structure, best with short statements. CLAUDE.md is the most flexible: hierarchical, full markdown, conditional rules. .cursorrules sits in between.

Copilot's strength is its integration with the GitHub ecosystem. If your team already uses GitHub Actions, Codespaces, and GitHub's PR workflow, copilot-instructions.md fits naturally. The file lives in .github/ alongside everything else, and Copilot reads it across VS Code, JetBrains, and GitHub.com.

The practical limitation is scope. Copilot instructions influence completions and chat, but they don't have the deep context window that Claude Code gets from CLAUDE.md. For complex projects with nuanced conventions, you may find that CLAUDE.md or .cursorrules can encode more sophisticated rules.

For teams using multiple AI tools, the advice is the same as always: maintain a canonical rule source and generate tool-specific files. The core rules (security, patterns, framework choices) are the same — only the format and level of detail differ per tool.

• copilot-instructions.md: Concise, GitHub-native, single file, best for direct statements
• CLAUDE.md: Rich markdown, hierarchical, conditional rules, deepest context processing
• .cursorrules: Middle ground, imperative statements, growing Cursor Rules directory support
• Overlap: Core rules (security, stack, patterns) are identical across all three

Managing Instructions Across Repos

The same multi-repo drift problem applies to copilot-instructions.md as it does to CLAUDE.md and .cursorrules. If you have 20 repos, you'll have 20 copies of similar instructions that gradually diverge.

GitHub offers organization-level Copilot settings that provide baseline instructions across all repos. This is useful for universal rules (security patterns, language preferences) but doesn't replace per-repo instructions for project-specific context.

For centralized management, tools like RuleSync can generate copilot-instructions.md alongside CLAUDE.md and .cursorrules from the same rule source. Write your rules once, assign them to repos, and the CLI outputs the correct file format for each tool your team uses.