What is copilot-instructions.md?

copilot-instructions.md meaning

`copilot-instructions.md` is GitHub Copilot's repository custom instructions file. You place it at `.github/copilot-instructions.md` in your repo, and Copilot Chat, the coding agent, and code review start applying it automatically. It works like a custom ruleset or style guide written in plain Markdown that Copilot reads and follows across the whole repository.

Where the file lives

The main file goes in the `.github` folder at your repository root:

.github/
  copilot-instructions.md          # repo-wide
  instructions/
    frontend.instructions.md       # path-specific
    api.instructions.md

The repo-wide file applies to every request. Path-specific `.instructions.md` files under `.github/instructions` use YAML frontmatter to declare which files or folders they apply to, so you can give different rules to different parts of the codebase.

What to include

• Language, framework, and version preferences
• Code style and formatting rules
• Testing expectations
• Project structure and important paths
• Patterns to follow and anti-patterns to avoid

Instructions are natural-language Markdown. Whitespace is ignored, so you can write one instruction per line or group them under headings for readability.

A short example

# Copilot instructions

- This is a React + TypeScript app.
- Use functional components and hooks.
- Write tests with Vitest for new logic.
- Prefer named exports.
- Do not edit files in `generated/`.

Why custom instructions help

Without instructions, Copilot guesses your conventions from the surrounding code, which is inconsistent. A clear copilot-instructions.md makes suggestions match your standards, improves Copilot code review feedback, and reduces the edits you make after accepting a suggestion. It is committed to the repo, so the whole team gets the same behavior.

copilot-instructions.md vs other agent files

This file is the GitHub Copilot equivalent of CLAUDE.md, GEMINI.md, and Cursor rules. Many teams also keep a cross-tool AGENTS.md. See how they compare in the guide to AI agent instruction files.

Edit it with a live preview

Write your instructions in the Markdown Docs online editor and preview the formatting, or download Markdown Docs to edit `.md` files on Windows.

Related references

• GitHub Docs: repository custom instructions official Copilot guidance.
• GitHub Changelog: .instructions.md support path-specific instructions.