How to write GitHub Copilot custom instructions: copilot-instructions.md and path-specific files

Guide · checked against the docs on Oct 15, 2026

Custom instructions are notes that GitHub Copilot reads along with your request, so it follows your project's rules without you repeating them. This guide covers the three kinds of repository instructions, how to scope instructions to certain files with applyTo, and which Copilot features read which file. Everything here comes from GitHub's docs on adding repository instructions and its support table, read on October 15, 2026.

Not affiliated with or endorsed by GitHub or Microsoft. Check GitHub's current docs before relying on these details.

Our tool page: GitHub Copilot

The three kinds of repository instructions

GitHub's docs say "Copilot on GitHub supports three types of repository custom instructions":

For agent files, "the nearest AGENTS.md file in the directory tree will take precedence." The docs add: "Alternatively, you can use a single CLAUDE.md or GEMINI.md file stored in the root of the repository." For more on AGENTS.md, see our AGENTS.md and CLAUDE.md guide.

Repository-wide: copilot-instructions.md

The docs' steps: "In the root of your repository, create a file named .github/copilot-instructions.md." Then "Add natural language instructions to the file, in Markdown format." Formatting is flexible: "Whitespace between instructions is ignored".

<!-- .github/copilot-instructions.md (NOT TESTED) -->
This is a TypeScript project. Run `npm test` before proposing changes.
Use named exports. Don't edit files in `dist/`.

You don't have to write it yourself. The docs say "you can ask Copilot cloud agent to generate one for you". GitHub gives a ready-made prompt for this on the same docs page.

Path-specific: NAME.instructions.md with applyTo

These files apply only to matching files. The docs say "The file name must end with .instructions.md." and "At the start of the file, create a frontmatter block containing the applyTo keyword. Use glob syntax to specify what files or directories the instructions apply to."

---
applyTo: "**/*.ts,**/*.tsx"
---
Use strict TypeScript. Prefer `unknown` over `any`.

(NOT TESTED. The applyTo line is the docs' own example.) To use more than one pattern, "separate them with commas."

If a file matches and there's also a repository-wide file, "the instructions from both files are used."

You can also keep a file away from one GitHub agent. The docs say to "add the excludeAgent keyword to the frontmatter block. Use either "code-review" or "cloud-agent"."

One limit worth knowing: "Currently, on GitHub.com, path-specific custom instructions are only supported for Copilot cloud agent and Copilot code review."

Which Copilot features read which file

This is from GitHub's support table, for GitHub.com and VS Code. "Yes" means the table lists that kind for that feature.

The table also covers Visual Studio, JetBrains IDEs, Eclipse, Xcode and Copilot CLI. Check it for your editor. For example, it says that in Eclipse, for Copilot code review, "Custom instructions are currently not supported."

Checking that instructions were used

The docs say instructions "are available for use by Copilot as soon as you save the file(s)." In Copilot Chat on GitHub.com, "the instructions file is added as a reference for the response that's generated." You can check by expanding the references at the top of the response.

If you set several kinds, all of them reach Copilot: "Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last. However, all sets of relevant instructions are provided to Copilot." GitHub suggests you "try to avoid providing conflicting sets of instructions."

For code review, there's one more detail: "Copilot reads repository custom instructions, agent instructions, and agent skills from the head branch (the branch with your changes), not the base branch."

Keep secrets out

Instruction files sit in your repo and get sent to Copilot along with your requests. Never put keys or passwords in them. See our guide to keeping secrets safe with AI coding tools. If you also use Cursor, its rules work in a similar way. See our Cursor rules guide.

Not affiliated with or endorsed by GitHub or Microsoft. Check GitHub's current docs before relying on these details.