How to Create a Copilot Instructions File and Test It

The copilot instructions file is .github/copilot-instructions.md, a Markdown file in the .github directory at the root of your repository. GitHub Copilot reads it automatically and adds its contents to every request made in the context of that repository. The build commands, layout notes, and conventions you'd otherwise paste into each prompt get written once.

To create it: add the .github directory if it doesn't exist, create copilot-instructions.md inside it, write your instructions in plain English, and commit. There's nothing to switch on for most features. GitHub's repository custom instructions page says the instructions are used as soon as the file is saved. The template below gives you something to commit today, and a later section shows where Copilot tells you it actually read the file.

Where the copilot instructions file lives and what it's called#

The name and location are fixed. Copilot looks for exactly this path, relative to the repository root:

.github/copilot-instructions.md

A few format facts, all from GitHub's docs as of October 18, 2026:

• Markdown with natural language inside. No frontmatter, no schema, no reserved keywords. Headings and bullets are for the humans maintaining it.
• Whitespace between instructions is ignored. One paragraph, one instruction per line, or blank-line-separated blocks all work. Pick whatever your team will keep up to date.
• It's one of three instruction types. Repository-wide instructions go in this file. Path-specific instructions go under .github/instructions/. Agent instructions go in AGENTS.md. Both of the others get their own section below.

Everything here describes how Copilot uses the file on GitHub.com: Copilot cloud agent, Copilot code review, and Copilot Chat. Setup for the same file inside an IDE is documented on a separate page that GitHub links from the top of the repository custom instructions page. Check that one for VS Code or Visual Studio before assuming the behavior is identical.

A working copilot-instructions.md template#

Here's a file you can copy, replace the specifics, and commit. It's written for a fictional Node.js service, but the shape works for any stack.

# Copilot instructions

## What this repository is
Billing API for the Acme web app. One Node.js and TypeScript service,
deployed as a single container, backed by PostgreSQL. No frontend code
lives here.

## Build, test, and validate
Always run `npm ci` before anything else. `npm install` rewrites the
lockfile and CI will reject the change.

- Build: `npm run build` compiles TypeScript into `dist/`.
- Unit tests: `npm test`. No database needed.
- Integration tests: `npm run test:integration`. Requires
  `docker compose up -d db` first.
- Lint and format: `npm run lint`, then `npm run format:check`. CI runs
  both and fails on warnings.

The workflow in `.github/workflows/ci.yml` runs lint, build, and both test
suites on every pull request. `npm run ci` replicates it locally.

## Layout
- `src/routes/` HTTP handlers, one file per resource. Keep them thin.
- `src/services/` business logic. Most changes land here.
- `src/db/` query helpers; migrations live in `src/db/migrations/`.
- `test/` mirrors `src/`.
- `tsconfig.json`, `eslint.config.js`, and `vitest.config.ts` sit at the root.

## Conventions
- Throw `AppError` from `src/errors.ts`, never plain strings or `Error`.
- A schema change needs a migration file and an update to `src/db/schema.ts`.
- Every new route gets a test in the matching `test/` path.

Trust these instructions. Search the codebase only if something here is
missing or turns out to be wrong.

The shape isn't arbitrary. GitHub's own generator prompt, covered in a later section, asks Copilot to write down four things: what the repository does and what it's built with, how to bootstrap, build, test, lint, and run it, where the major pieces live, and what checks run before merge. It also asks for a closing line telling the agent to trust the file and only search when something is missing or wrong. Those are the facts that stop a cloud agent from guessing at commands and opening a pull request that fails CI.

Two constraints from that same prompt apply just as well to hand-written files. Keep it to roughly two pages, and keep it general: nothing about the ticket you're working on this week. Use firm language where it matters. GitHub's example is "always run npm install before building", and that style tells the agent which steps are optional and which aren't.

Where the instructions apply on GitHub#

GitHub's docs describe repository-wide instructions as applying to all requests made in the context of the repository. On GitHub.com that means:

• Copilot cloud agent. When Copilot works on a prompt and opens a pull request, it reads the file.
• Copilot code review. Reviews use the file by default. The toggle is in the repository's Settings, under Copilot, then Code review, labeled "Use custom instructions when reviewing pull requests". Turning it off disables custom instructions for every review in that repository.
• Copilot Chat. At github.com/copilot, attach the repository to the conversation and the instructions are included in the request.

When more than one instruction source exists, the priority order is personal instructions first, then repository instructions, then organization instructions. All relevant sets are still sent to Copilot. A repository file doesn't silence a conflicting personal instruction; both arrive, and GitHub's advice is to avoid conflicts rather than count on precedence.

Code review has one more rule that's easy to miss. Copilot reads custom instructions, agent instructions, and agent skills from the head branch of the pull request, not the base branch. Push a change to .github/copilot-instructions.md on your feature branch, and the review of that same pull request uses it. There's no need to merge first.

Path-specific instructions files#

Repository-wide instructions apply everywhere. For rules that only make sense in part of the tree, GitHub supports a second type: files named NAME.instructions.md in or below .github/instructions/, with an applyTo glob in a frontmatter block.

---
applyTo: "**/*.ts,**/*.tsx"
---

Use strict TypeScript. Never use `any`; prefer `unknown` plus a type guard.
Export one component per file and co-locate its test as `Name.test.tsx`.

The rules for these files:

• The file name must end with .instructions.md. The NAME part is yours; use it to say what the file is for.
• The frontmatter comes first and must contain applyTo. Separate multiple patterns with commas.
• Subdirectories under .github/instructions/ are fine for organizing.
• An optional excludeAgent key, set to either "code-review" or "cloud-agent", keeps the file away from one of the two. Leave it out and both use the file.
• If a path-specific file matches and the repository-wide file also exists, Copilot uses both.
• On GitHub.com, path-specific instructions are currently only supported for Copilot cloud agent and Copilot code review, as of October 18, 2026. Don't expect them in Copilot Chat there.

GitHub's docs give these glob examples:

Before committing a pattern, it helps to check it against a few real paths. This script mirrors the documented examples above. It's an approximation for sanity-checking, not GitHub's matcher, so the table stays the authority.

import re

def glob_to_regex(pattern):
    out, i = '', 0
    while i < len(pattern):
        if pattern.startswith('**/', i):
            out += '(?:.*/)?'   # zero or more directories
            i += 3
        elif pattern.startswith('**', i):
            out += '.*'
            i += 2
        elif pattern[i] == '*':
            out += '[^/]*'      # anything except a path separator
            i += 1
        elif pattern[i] == '?':
            out += '[^/]'
            i += 1
        else:
            out += re.escape(pattern[i])
            i += 1
    return re.compile('^' + out + '$')

def matches(apply_to, path):
    patterns = [p.strip() for p in apply_to.split(',')]
    return any(glob_to_regex(p).match(path) for p in patterns)

cases = [
    ('**/*.ts,**/*.tsx', 'src/app/page.tsx'),
    ('**/*.ts,**/*.tsx', 'src/app/page.js'),
    ('*.py', 'setup.py'),
    ('*.py', 'src/setup.py'),
    ('src/*.py', 'src/foo.py'),
    ('src/*.py', 'src/foo/bar.py'),
    ('src/**/*.py', 'src/foo/bar/baz.py'),
    ('**/subdir/**/*.py', 'deep/parent/subdir/nested/qux.py'),
    ('**/subdir/**/*.py', 'foo.py'),
]
for apply_to, path in cases:
    verdict = 'match' if matches(apply_to, path) else 'no match'
    print(f'{apply_to:22} {path:36} {verdict}')

If your team also uses Cursor, the same idea of scoping rules by file type is covered in setting up Cursor rules for specific file types.

Copilot instructions file vs AGENTS.md#

The third instruction type is for agents. You can put one or more AGENTS.md files anywhere in the repository, and when Copilot is working, the nearest AGENTS.md in the directory tree takes precedence. As an alternative, a single CLAUDE.md or GEMINI.md in the repository root is also read. The format is described in the agents.md repository.

My recommendation on choosing:

• Use copilot-instructions.md when Copilot is the main tool. It's one file, in a fixed place, and it's the one Copilot Chat lists as a reference so you can verify it.
• Use AGENTS.md when several agents from different vendors work in the repository, or when a monorepo needs different guidance per directory. The nearest-file rule gives you per-package instructions without globs.
• Keeping both is fine. GitHub lists all three types as supported. Put the build and layout facts in one place and keep the other short, because the official page doesn't spell out how the two are merged and you don't want them disagreeing.

If you already maintain a CLAUDE.md and need to show auditors what instructions your AI tools receive, exporting Claude instructions for enterprise audits covers that side.

How to confirm Copilot is reading the file#

This is the part people usually skip and then wonder why nothing changed. There's one documented, visible signal:

1. Open Copilot Chat at github.com/copilot.
2. Attach the repository that contains the file.
3. Ask anything about the code.
4. At the top of the response, expand the list of references. If .github/copilot-instructions.md is listed, the instructions were used. Clicking it opens the file.

If it isn't listed, check the two usual causes: the path is exactly .github/copilot-instructions.md, and the repository is actually attached to the conversation.

For code review, confirm the "Use custom instructions when reviewing pull requests" setting is on, then put your instructions change on the head branch and request a review on that pull request. For the cloud agent, the official page doesn't list a separate indicator, so the Chat references check is the reliable test. One hint that you're set up: the first time you create a pull request with the cloud agent in a repository, Copilot leaves a comment with a link to generate instructions automatically. If you've already written the file, you can ignore that link.

Generating the file with Copilot cloud agent#

Writing the file by hand is faster for a small project. For a large or unfamiliar codebase, GitHub offers a generator built on the cloud agent:

1. Go to the agents tab at github.com/copilot/agents. It's also reachable from the Copilot button next to the search bar on any GitHub page, then Agents in the sidebar.
2. In the dropdown on the prompt field, select the repository.
3. Paste the onboarding prompt from GitHub's repository custom instructions page. It tells the agent to inventory the repository, run the build and test commands to validate them, and write everything up in no more than two pages without task-specific content.
4. Press Enter.

Copilot starts a session, creates a draft pull request, writes the instructions, pushes them, and adds you as a reviewer. Treat the result as a first draft. The prompt asks the agent to record errors and workarounds it hit, which is valuable, but it also asks it to fill remaining space with file listings and README contents. Trim those if they push the file past the point where a human will keep it current.

Common mistakes and gotchas#

• Wrong file name or folder. copilot-instructions.md in the repository root, copilot_instructions.md, or .github/copilot-instructions.txt are all ignored. The path is .github/copilot-instructions.md, exactly.
• Path-specific file without the suffix. typescript.md in .github/instructions/ does nothing. It has to be typescript.instructions.md, with the applyTo frontmatter at the start of the file.
• Expecting path-specific instructions in Copilot Chat on GitHub.com. They're currently only supported for the cloud agent and code review there. Put rules you need in Chat into the repository-wide file.
• Task-specific content. "Fix the flaky checkout test" belongs in an issue, not in a file attached to every request. GitHub's generator prompt explicitly forbids task-specific instructions, and the same logic applies to hand-written ones.
• Conflicting layers. Personal, repository, and organization instructions are all sent together. If a personal instruction says tabs and the repository says spaces, you've handed Copilot a contradiction. Fix the conflict instead of hoping priority sorts it out.
• Testing code review changes on the wrong branch. Reviews read instructions from the head branch. Editing the file on main won't affect an open pull request's next review until that branch contains the change.
• The code review toggle is off. It's on by default, but someone may have switched it. The setting is per repository, under Settings, Copilot, Code review.
• Describing instead of instructing. "Our CI is sometimes slow" doesn't help. "Always run npm ci before npm run build" does.

Quick reference#

Checklist before you commit:

• The file is at .github/copilot-instructions.md and nowhere else.
• It says what the repository is, how to build and test it, where things live, and what CI checks.
• Commands use firm language: always, never, before.
• Nothing in it is about a single task.
• It ends with an instruction to trust the file and search only when something is missing.
• Any path-specific files end in .instructions.md and start with applyTo frontmatter.
• You've opened Copilot Chat with the repository attached and seen the file in the response references.
• The current version of GitHub's repository custom instructions page still matches what you rely on, because supported features change.

Quick answers