GitHub Copilot custom instructions: copilot-instructions.md, paths and AGENTS.md

GitHub Copilot custom instructions are Markdown files Copilot adds to your requests automatically. Put repository-wide rules in .github/copilot-instructions.md, file-specific rules in .github/instructions/NAME.instructions.md with an applyTo glob, and agent rules in AGENTS.md, which Copilot's cloud agent, code review and CLI also read.

This guide covers each file type, where each one works, and how to write instructions Copilot can follow. It is based on GitHub's custom instructions overview and related GitHub Docs pages, read on 24 October 2026.

What types of GitHub Copilot custom instructions are there?

GitHub groups instructions by who they apply to:

Organization instructions need a Copilot Business or Copilot Enterprise subscription, and GitHub says they are currently supported only for Copilot Chat, code review and cloud agent on GitHub.com.

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

1. In the root of your repository, create .github/copilot-instructions.md. Create the .github folder if it does not exist.
2. Write your instructions in plain Markdown.
3. Save. GitHub's repository instructions page says the instructions are available as soon as you save the file.

GitHub notes that "Whitespace between instructions is ignored," so one paragraph, one line per rule, or blank lines between them all work. A short example:

# Project overview
A task manager web app. React and Tailwind on the frontend, Node.js and Express on the backend, PostgreSQL for data.

## Build and test
- Install with `npm ci`. Run `npm test` and `npm run lint` before you finish a change.

## Conventions
- Use TypeScript strict mode and function components.
- Use early returns instead of nested if blocks.
- Put new API routes in src/server/routes, one file per resource.

You can also ask Copilot cloud agent to write a first draft. GitHub's page provides an onboarding prompt; the agent opens a draft pull request with the file and adds you as a reviewer.

How do path-specific instructions work?

Path-specific files keep your main file short by loading rules only for matching files.

1. Create .github/instructions/. Subfolders are allowed.
2. Add a file whose name ends in .instructions.md, such as react.instructions.md.
3. Start it with frontmatter that sets applyTo to one or more globs, separated by commas.

---
applyTo: "**/*.ts,**/*.tsx"
---
Use named exports. Co-locate tests as Component.test.tsx next to each component.

Glob examples from GitHub's docs:

• ** or **/* matches every file in every folder.
• *.py matches .py files in the current folder only.
• src/**/*.py matches .py files anywhere under src.
• **/subdir/**/*.py matches .py files in any subdir folder at any depth.

When a path-specific file matches and .github/copilot-instructions.md also exists, Copilot uses both. An optional excludeAgent key set to "code-review" or "cloud-agent" hides the file from one of those two features; without it, both use the file.

On GitHub.com, path-specific instructions currently work only for Copilot cloud agent and Copilot code review. In IDEs, support varies, as the next section shows.

Does GitHub Copilot support AGENTS.md?

Yes. GitHub calls these agent instructions. You can keep one or more AGENTS.md files anywhere in the repository, and "the nearest AGENTS.md file in the directory tree will take precedence." Alternatively, Copilot accepts a single CLAUDE.md or GEMINI.md in the repository root. Copilot code review also reads REVIEW.md.

That means one AGENTS.md can serve Copilot, Codex, Cursor and other agents. The AGENTS.md guide covers what to put in it, and the CLAUDE.md guide covers Claude Code's file.

Support differs by surface. This summary comes from GitHub's support reference:

The cloud agent reads all three types from every IDE that offers it. Code review inside IDEs reads fewer: VS Code and Visual Studio only use the repository-wide file. In VS Code, AGENTS.md files outside the workspace root are off by default.

How do personal instructions and precedence work?

Personal instructions on GitHub.com apply only to Copilot Chat on the website. Open Copilot Chat, click your profile picture in the bottom left, choose Personal instructions, and add rules such as "Always provide examples in TypeScript."

For Copilot Chat on GitHub.com, the order from highest to lowest priority is:

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

All relevant sets are still sent to Copilot, so avoid rules that contradict each other. GitHub says most other clients, including Copilot CLI, VS Code and Visual Studio, combine applicable files without a general precedence order.

How does Copilot CLI load instructions?

The Copilot CLI instructions page lists extra locations:

• $HOME/.copilot/copilot-instructions.md and $HOME/.copilot/instructions/**/*.instructions.md for personal rules across repositories (COPILOT_HOME changes the folder).
• .github/copilot-instructions.md, AGENTS.md, CLAUDE.md (also .claude/CLAUDE.md) and GEMINI.md, found in the repository root, the current folder and folders in between.
• Folders named in COPILOT_CUSTOM_INSTRUCTIONS_DIRS, separated by commas.

The /instructions command shows which files the session found and lets you turn individual files off. In .github/copilot-instructions.md, AGENTS.md or CLAUDE.md, an @ followed by a relative path pulls in another file from the repository.

What are Copilot prompt files?

Custom instructions apply to every request. Prompt files are the opposite: reusable Markdown templates you run only when you pick them. They use the .prompt.md extension and usually live in .github/prompts/. They can include input variables and extra context, such as links to other files in the repository.

GitHub's customization cheat sheet marks prompt files as supported in VS Code and Visual Studio and in preview in JetBrains IDEs and Xcode. They are not available on GitHub.com or in Copilot CLI. Typical uses: "generate unit tests for this file," "write a README," or a security review checklist. Anything you would otherwise paste into chat every week is a good candidate.

How do you check and turn off instructions?

• Check. In Copilot Chat, expand the References list on a response. If repository instructions were used, .github/copilot-instructions.md is listed.
• Turn off in VS Code. Open Settings, search for instruction file, and clear Code Generation: Use Instruction Files. This only affects you.
• Turn off for code review. In the repository, go to Settings, then Copilot, then Code review, and switch off "Use custom instructions when reviewing pull requests."

When Copilot reviews a pull request, it reads instructions, agent instructions and skills from the head branch, so you can test changes to your instructions in the same pull request.

Tips for writing Copilot instructions that work

GitHub's advice is to write "short, self-contained statements." Because the repository file is sent with every chat message, keep it to rules that apply to most requests:

• Describe the project, its stack and versions.
• List build, test and lint commands Copilot should run.
• State naming, formatting and error handling conventions.
• Move rules for one language or folder into a path-specific file.

GitHub also notes that, because AI is non-deterministic, Copilot may not follow your instructions the same way every time. Instructions guide output; they do not enforce policy. For standing rules in other editors, compare Cursor rules and the Codex CLI guide.

Keep your prompts and skills in one place

Instruction files belong in each repository, but the prompts you reuse across projects need a home of their own. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name}} blanks you fill in each time and Cmd+K search. To turn a prompt into a skill folder for Claude Code, Codex or Cursor, use the free SKILL.md generator.