Copilot custom instructions: files, paths and AGENTS.md

Copilot custom instructions are Markdown files that GitHub Copilot adds to your requests automatically: .github/copilot-instructions.md for the whole repository, .github/instructions/**/*.instructions.md files scoped to paths with applyTo, and agent files such as AGENTS.md. Personal and organization instructions sit on top. Which ones apply depends on the Copilot feature and editor.

# Project Overview

This project is a web application that allows users to manage their tasks and to-do lists. It is built using React and Node.js, and uses MongoDB for data storage.

## Folder Structure

- `/src`: Contains the source code for the frontend.
- `/server`: Contains the source code for the Node.js backend.
- `/docs`: Contains documentation for the project, including API specifications and user guides.

## Libraries and Frameworks

- React and Tailwind CSS for the frontend.
- Node.js and Express for the backend.
- MongoDB for data storage.

## Coding Standards

- Use semicolons at the end of each statement.
- Use single quotes for strings.
- Use function based components in React.
- Use arrow functions for callbacks.

## UI guidelines

- A toggle is provided to switch between light and dark mode.
- Application should have a modern and clean design.

Applies to: GitHub Copilot on GitHub.com, IDEs and Copilot CLI, GitHub Docs as of October 2, 2026. Last checked: October 2, 2026.

That file is GitHub’s own example of a .github/copilot-instructions.md, from About customizing GitHub Copilot responses: a project overview, folder structure, libraries and coding standards.

On this page

Which types of custom instructions are there?

Sources: response customization and adding repository custom instructions. GitHub notes that “due to the non-deterministic nature of AI, Copilot may not always follow your custom instructions in exactly the same way every time”.

Where does each type apply?

GitHub’s support matrix lists which feature reads which files. A condensed version:

Copilot cloud agent reads repository-wide, path-specific and agent instructions in every listed IDE as well. Eclipse code review does not support custom instructions.

How do I create .github/copilot-instructions.md?

From GitHub’s how-to:

1. In the root of your repository, create .github/copilot-instructions.md. Create the .github directory if it does not exist.
2. Add natural language instructions in Markdown. Whitespace between instructions is ignored, so one paragraph, one instruction per line or blank-line-separated blocks all work.

You can also ask Copilot cloud agent to write the file: go to github.com/copilot/agents, pick the repository and paste the onboarding prompt from the how-to page. The agent opens a draft pull request with the instructions and adds you as a reviewer. GitHub’s overview page gives a shorter version of that prompt:

Onboard this repository to Copilot cloud agent by adding a
.github/copilot-instructions.md file. Include information about project
structure, coding conventions, the test framework, and how to build and
run the project.

How do path-specific instructions work?

Path-specific files apply only when Copilot works on a matching file. If a repository-wide file also exists, both are used (steps):

1. Create .github/instructions (subdirectories are allowed).

2. Name each file NAME.instructions.md; the name must end with .instructions.md.

3. Start it with frontmatter containing applyTo and a glob:

   ---
   applyTo: "app/models/**/*.rb"
   ---
   

   Separate several patterns with commas:

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

4. Optionally add excludeAgent with "code-review" or "cloud-agent" to keep one of them from reading the file. This file is read only by cloud agent:

   ---
   applyTo: "**"
   excludeAgent: "code-review"
   ---
   

5. Write the instructions in natural language below the frontmatter.

Glob examples from the docs: **/*.py matches .py files in all directories; src/*.py matches src/foo.py but not src/foo/bar.py; src/**/*.py matches both. On GitHub.com, path-specific instructions are currently supported only for Copilot cloud agent and Copilot code review.

How does Copilot use AGENTS.md?

The how-to says you can create “one or more AGENTS.md files, stored anywhere within the repository”, and “the nearest AGENTS.md file in the directory tree will take precedence”. It points to the agentsmd/agents.md repository for the format. Instead of AGENTS.md, you can use a single CLAUDE.md or GEMINI.md in the repository root.

Two limits from the docs:

• Agent instructions “are currently not supported by all Copilot features”. Copilot code review on GitHub.com reads AGENTS.md but not CLAUDE.md or GEMINI.md, and Copilot Chat on GitHub.com reads none of them.
• In VS Code, AGENTS.md files outside the workspace root are turned off by default; the IDE how-to links to the VS Code docs for the setting.

The same AGENTS.md file is read by other agents too; see what is Codex for how OpenAI’s agent uses it and our CLAUDE.md best practices for Claude Code’s file.

Where does Copilot CLI look for instructions?

The CLI page lists these locations. Repository and agent files are found in the repository root, the current working directory, the directories between them, and directories on the path of a file the CLI is working on.

With COPILOT_HOME set, the CLI uses that directory instead of $HOME/.copilot. Other CLI details from the same page:

• /instructions shows the files found for the session and lets you turn individual files on or off.
• In .github/copilot-instructions.md, AGENTS.md or CLAUDE.md, @ followed by a relative path includes another file. Referenced files must stay inside the repository; absolute paths and ~/ paths are not loaded, and references are not expanded in GEMINI.md or *.instructions.md.
• The CLI combines all applicable files and removes identical duplicates, but “does not define a general precedence order between these files”. Avoid conflicting instructions.
• Edits are not picked up by a running session. Exit and resume (for example copilot --continue) or start a new session with /new.

Which instructions win when several apply?

All relevant sets are sent to Copilot, with this order of precedence on GitHub (precedence):

1. Personal instructions
2. Repository instructions: path-specific files, then .github/copilot-instructions.md, then agent instructions such as AGENTS.md
3. Organization instructions

What should the instructions say?

GitHub recommends short, self-contained statements that apply to most requests, since they are sent with every chat message: a project overview, the folder structure, coding standards and conventions, and the tools, libraries and frameworks with their versions. In large repositories, GitHub warns that requests to consult external resources, to answer in a particular style or to always give a certain level of detail may not work as intended. Its example of instructions that may fail:

Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code.

Use @terminal when answering questions about Git.

Answer all questions in the style of a friendly colleague, using informal language.

Answer all questions in less than 1000 characters, and words of no more than 12 characters.

For code review, GitHub’s code review tutorial suggests keeping any one instruction file to about 1,000 lines at most, using headings and bullet points, and copying external standards into the file, since code review does not follow external links.

How do I check or turn off custom instructions?

• Copilot Chat on GitHub.com and in VS Code: expand the references of a response; .github/copilot-instructions.md is listed when it was used.
• VS Code: open Settings, search instruction file and toggle Code Generation: Use Instruction Files (IDE how-to).
• Copilot code review: in the repository go to Settings > Copilot > Code review and toggle “Use custom instructions when reviewing pull requests”. The how-to notes that code review reads instructions from the pull request’s head branch, so changes to them can be tested in the same pull request.
• Copilot CLI: use /instructions.

Repository files can also carry hooks for agent runs; see Copilot hooks.