Copilot Instructions: copilot-instructions.md Guide
November 11, 2026 · 11 min read
Copilot Instructions: Write copilot-instructions.md for GitHub Copilot
Copilot instructions are Markdown files that tell GitHub Copilot, GitHub's AI coding assistant, how your project works. You put repository-wide rules in .github/copilot-instructions.md and scope extra rules to paths with .instructions.md files. Copilot then adds them to chat, agent and code review requests, so you stop repeating build commands and conventions.
What Are Copilot Instructions For?
Without instructions, Copilot has to work out your project's conventions on each request. GitHub Copilot instructions fill that gap with what a new teammate learns on day one. They cover how to build and test, which libraries you've standardized on and which folders to leave alone.
GitHub's docs describe three kinds of repository instructions:
- Repository-wide: one
.github/copilot-instructions.mdfile that applies to every request made in the context of the repo. - Path-specific: one or more
NAME.instructions.mdfiles in or below.github/instructions, each applying only to files that match itsapplyTopattern. - Agent instructions:
AGENTS.mdfiles anywhere in the repo, or a singleCLAUDE.mdorGEMINI.mdat the root.
There are also personal and organization instructions, but those live outside your repo, in GitHub settings or in your home folder. Two scoping notes before you start. First, these files don't change inline suggestions as you type; they feed chat, agents and review. Second, Microsoft 365 Copilot is a different product with its own personalization settings. This page covers GitHub Copilot only.
How Do You Set Up copilot-instructions.md?
To create a Copilot instructions file by hand, follow GitHub's repository instructions guide:
- Create a
.githubfolder at the root of your repository if it doesn't exist. - Add a file named
copilot-instructions.mdinside it. - Write your instructions in plain Markdown. GitHub ignores whitespace between instructions, so one paragraph, one rule per line or blank-line-separated blocks all work.
- Save the file, then commit and push it. Copilot can use it as soon as it's saved, and pushing makes it available to your team and to Copilot on GitHub.com.
You can also let Copilot draft it. GitHub's docs give an onboarding prompt you paste into the agents tab at github.com/copilot/agents after picking the repo. Copilot cloud agent then explores the codebase and opens a draft pull request with the file for you to review.
If you'd rather start from a template, our CLAUDE.md generator also outputs a .github/copilot-instructions.md from a short form about your project, ready to copy into your repo. Since the file is GitHub Flavored Markdown, the GitHub Markdown cheat sheet covers the syntax you'll need.
copilot-instructions.md Examples: A File You Can Copy
Here's a realistic GitHub Copilot instructions file for a Python API with a React admin panel. It's short on purpose.
# Copilot instructions
FastAPI service with a PostgreSQL database and a React admin app in web/.
## Build and test
- Install dependencies with `uv sync`
- Run the test suite with `uv run pytest -q`
- Run `uv run ruff check .` before proposing a commit
- Frontend: `cd web && npm ci && npm test`
## Conventions
- Python 3.12, type hints on every function
- Use SQLAlchemy 2.0 style queries (`select()`), never the legacy Query API
- Routes return Pydantic models, not dicts
- New endpoints need a test in tests/api/
## Project layout
- app/api: route handlers
- app/models: ORM models
- app/services: business logic, called by routes
- migrations/: Alembic migrations, generated only
## Avoid
- Don't edit files in migrations/ by hand
- Don't add a dependency without saying why in the PR
Each block answers a question the agent would otherwise burn time on. The summary line sets context. The build section gives exact commands, which Copilot can run and check. Conventions name the specific API or pattern to use, and the layout map tells it where new code belongs. To draft that map, print the repo's directory tree with the tree command and keep only the folders that matter.
We prefer short, imperative rules backed by a command over paragraphs of style advice. If a formatter or linter already enforces a rule, leave it out and let the tool do the enforcing. VS Code's guidance says the same: don't duplicate rules your formatters already check.
A few things don't belong in Copilot instructions at all. Keep out secrets and tokens, since the file is committed with your code. Skip one-off task requests too, because the file applies to every request. Long excerpts from other docs waste space, so keep them in your Markdown documentation and link to it instead. VS Code notes that a link doesn't guarantee the linked file reaches the model, though.
Here's a trimmed version of that file in our editor. Edit the stack details for your own project and watch the preview update.
The preview shows roughly how GitHub displays the file to humans. Copilot gets the file's text and ignores whitespace between instructions, so the formatting mostly helps the people maintaining it.
Path-Specific Instructions with applyTo and excludeAgent
Path-specific Copilot custom instructions keep frontend rules out of backend requests. Create .github/instructions/, add files whose names end in .instructions.md, and start each with a YAML front matter block. Subfolders inside .github/instructions are allowed, so you can group files by language or team.
---
applyTo: "**/*.ts,**/*.tsx"
excludeAgent: "code-review"
---
- Use function components and hooks, never class components
- Fetch data through the hooks in web/src/api, not with raw fetch calls
- Every new component gets a test next to it
The applyTo value takes one or more glob patterns separated by commas. The excludeAgent key is optional and accepts "code-review" or "cloud-agent". In this example, Copilot cloud agent uses the rules but Copilot code review skips them. Leave the key out and both use the file.
GitHub's docs list how the globs match:
*matches all files in the current directory.**or**/*matches all files in all directories.src/*.pymatchessrc/foo.pybut notsrc/foo/bar.py.src/**/*.pymatches Python files at any depth undersrc.**/subdir/**/*.pymatches Python files inside anysubdirfolder, at any depth.
When a path file matches and a repo-wide file exists, Copilot uses both. In VS Code, an .instructions.md file can also carry name (a display label) and description fields. For the front matter syntax itself, see our Markdown front matter guide. Our editor's preview doesn't render YAML front matter, which is why this example appears as code only.
Which Copilot Surfaces Read Which Instruction File?
Support for Copilot instructions differs by surface, and path-specific files don't work everywhere. The table condenses GitHub's custom instructions support reference as of November 2026. A dash means the reference doesn't list that type.
| Surface | copilot-instructions.md | .instructions.md files | Agent files |
|---|---|---|---|
| GitHub.com Copilot Chat | Yes | - | - |
| GitHub.com cloud agent | Yes | Yes | AGENTS.md, CLAUDE.md, GEMINI.md |
| GitHub.com code review | Yes | Yes | AGENTS.md, CLAUDE.md, GEMINI.md, REVIEW.md |
| VS Code Chat | Yes | Yes | AGENTS.md |
| Visual Studio Chat | Yes | Yes | - |
| JetBrains IDEs Chat | Yes | Yes | - |
| Eclipse Chat | Yes | - | - |
| Xcode Chat | Yes | Yes | - |
| Copilot CLI | Yes | Yes | AGENTS.md, CLAUDE.md, GEMINI.md |
A few details matter in practice. Code review started from VS Code or Visual Studio reads only the repo-wide file. Eclipse's code review doesn't support custom instructions at all.
On GitHub.com, code review reads instructions from the pull request's head branch, so you can test an edit to the file in the same PR. You can switch this off in the repository under Settings, then Copilot, then Code review, with the toggle labeled "Use custom instructions when reviewing pull requests".
VS Code and Visual Studio Settings for Copilot Instructions
In VS Code, run Chat: Open Customizations from the Command Palette and open the Instructions tab. Select the plus button next to Workspace to create a project file, or next to User for personal rules. With Copilot chosen as the agent, VS Code reads .github/copilot-instructions.md or AGENTS.md, plus .github/instructions/**/*.instructions.md. Personal files go in ~/.copilot/copilot-instructions.md and ~/.copilot/instructions/.
The VS Code custom instructions reference lists the settings that control which instruction files VS Code's built-in agent loads:
github.copilot.chat.codeGeneration.useInstructionFilesincludes.github/copilot-instructions.md.chat.includeApplyingInstructionsincludes matching.instructions.mdfiles.chat.useAgentsMdFileincludes a workspace-rootAGENTS.md.chat.useNestedAgentsMdFilesdiscovers nestedAGENTS.mdfiles. It's experimental and off by default.chat.instructionsFilesLocationsadds extra folders to search.
Older settings-based code and test generation instructions are deprecated, so move those rules into files. Copilot CLI doesn't inherit editor settings. For Markdown preview and extensions in the editor itself, see our VS Code Markdown guide.
Visual Studio needs one checkbox. Per Microsoft Learn, go to Tools, then Options, then GitHub, then Copilot, then Copilot Chat. Tick the option to load custom instructions from .github/copilot-instructions.md files. Visual Studio also reads personal preferences from %USERPROFILE%/copilot-instructions.md.
How Do You Know Copilot Used Your Instructions?
To check whether your Copilot instructions were used on GitHub.com, expand the references list at the top of a Copilot Chat response. If .github/copilot-instructions.md appears there, Copilot included it, and you can click it to open the file. Visual Studio shows the same file in the response's References list.
VS Code splits the check in two. First confirm the file shows up under Instructions in the Customizations editor, which proves discovery. Then start a new chat, ask for a small change without restating the rules, and look for the file in the response's References. VS Code's docs warn that References show inclusion, not compliance.
Precedence depends on where you are. On GitHub.com, personal instructions rank highest, then repository, then organization, but Copilot receives all of them together. VS Code's reference says no precedence rule applies across all the agents it can run. The safe move is the same everywhere: don't write rules that contradict each other.
There's a real limitation here. Copilot instructions are context, not enforcement, and Copilot can still ignore a rule. Keep anything that must never happen in CI checks, linters and branch protection, and treat the file as guidance.
copilot-instructions.md vs AGENTS.md
Copilot reads both files on several surfaces, so the two can sit side by side in one repo. AGENTS.md is a cross-agent format that other coding agents also read. On GitHub.com, the nearest AGENTS.md in the directory tree takes precedence, and a single root CLAUDE.md or GEMINI.md counts as an alternative. Our AGENTS.md guide and CLAUDE.md file explainer cover where those files live and how to write them.
Our rule of thumb: put guidance every agent should follow in AGENTS.md. Keep Copilot-only details, such as excludeAgent scoping or review-specific rules, in your GitHub Copilot instructions file and path files. Whatever you do, don't paste the same rules into both, because the copies drift apart over time.
Good Copilot instructions are short, specific and checked into the repo next to the code they describe. Start with build and test commands, add the conventions Copilot keeps getting wrong, and scope the rest with applyTo. Draft yours in the editor and check the headings and lists in the live preview. Then download the .md file, rename it to copilot-instructions.md and commit it to .github/.