Configure GitHub Copilot Custom Instructions

I set up Copilot instructions on a CDK project and went looking for confirmation that the structure actually matched GitHub’s model, rather than carrying over an assumption from Claude Code. Claude Code works by walking the directory tree and picking up any CLAUDE.md it finds in the current or parent folder - drop a file next to the code it should govern, and Claude finds it. Copilot has no equivalent “drop a file in the folder” convention. It centralises everything under .github/ instead, and scopes by path through frontmatter rather than by file location.

Here’s the order I’d actually set it up in, in VS Code, from a blank repo.

1. Create the repo-wide file

.github/copilot-instructions.md is the one file every Copilot Chat request sees, regardless of which file is open. VS Code picks it up automatically from the workspace on disk - no setting to enable, no reference needed in chat.

A minimal version covers project overview, conventions, how to add something new, the deploy command, and comment style:

# Project name

AWS CDK v2 (Python) infrastructure. `app.py` registers all stacks.

## Conventions

- Stack and construct IDs use PascalCase; file names use snake_case
- Every stack takes `env` and `config` as constructor arguments
- Tag every stack with `Environment` and `Owner`

## Adding a new stack

1. Create `cdk_app/<area>/<name>_stack.py`
2. Register it in `app.py`
3. Add a README entry under `cdk_app/<area>/`

## Deploying

Run `cdk deploy --require-approval never -c env=dev` from the project root.

## Comments

Explain why, not what - skip a comment that just restates the line below it.

Anything that would otherwise repeat across every path-scoped file belongs here instead - it’s worth getting right before anything else, since on its own it already covers most of what a project needs.

2. Add path-scoped files where conventions diverge

.github/instructions/*.instructions.md is for subtrees where the repo-wide file falls short:

• A module with hard architectural constraints that don’t apply anywhere else
• A CI pipeline format every file in ci/ has to follow exactly
• A subsystem mid-redesign, where the assistant needs to know what’s actually built versus just planned

Each file starts with frontmatter declaring where it applies:

---
applyTo: "src/payments/**"
---

The glob syntax:

When the glob matches the file currently open or being edited, this file loads alongside the repo-wide one - not instead of it.

Reach for a path-scoped file only when the guidance would be wrong outside that subtree - not just because it’s specific to it.

You can exclude a path-scoped file from a particular Copilot surface with excludeAgent, useful if a file is tuned for Chat suggestions but shouldn’t influence Copilot code review:

---
applyTo: "src/payments/**"
excludeAgent: "code-review"
---

3. Decide on AGENTS.md - probably not yet

AGENTS.md is a cross-tool standard - read by Copilot, Codex, and other AI coding tools, not just Copilot. Support varies by surface, and all of it coexists with copilot-instructions.md and instructions/*.instructions.md rather than replacing them:

• Copilot coding agent - reads a root AGENTS.md plus nested ones per subtree
• Copilot code review - reads a root-level AGENTS.md
• VS Code - lists it alongside copilot-instructions.md and CLAUDE.md as a recognised source

What’s undocumented is precedence - when CLAUDE.md, AGENTS.md, and copilot-instructions.md all exist at once, whether they’re merged, layered, or something else. That’s reason enough to leave an established .github/instructions/ setup alone for now rather than migrate it onto AGENTS.md.

Resources

• Adding custom instructions for GitHub Copilot
• Your first custom instructions
• Copilot coding agent now supports AGENTS.md custom instructions
• Copilot code review: path-scoped custom instruction file support
• Copilot code review: AGENTS.md support and UI improvements

Notes