GitHub Copilot custom instructions

The files at a glance

copilot-instructions.md

The repository instructions docs ask for one thing: a markdown file at .github/copilot-instructions.md containing "natural language instructions". There is no frontmatter and no required heading. "Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility." The file takes effect "as soon as you save the file(s)."

The guidance on content is the same across GitHub's pages: instructions "should be short, self-contained statements" and "because the instructions are sent with every chat message, they should be broadly applicable to most requests you will make in the context of the repository." The suggested shape is an overview of the project, the coding standards, and the tools and frameworks with versions. GitHub's own example is short:

# 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.

## 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.

The docs also list instructions that "may not have the intended results" in a large repository: asking Copilot to consult an external resource, to answer in a particular style, or to keep every answer under a length. Put facts in the file, not personality.

If you would rather not write it by hand, the cloud agent can draft one: the docs give a prompt to paste at github.com/copilot/agents, and Copilot opens a pull request with the file. The prompt itself is worth reading because it says what GitHub thinks the file is for: build and test commands "validated by running", project layout, the checks that run before merge, and two limits, "Instructions must be no longer than 2 pages" and "must not be task specific."

Path-specific .instructions.md files

Rules that only matter for some files go in .github/instructions/. "The file name must end with .instructions.md", subdirectories are allowed, and the YAML frontmatter carries the applyTo glob:

---
applyTo: "**/*.ts,**/*.tsx"
---
- Validate every request body with the zod schemas in src/api/schemas.
- New handlers get a test in tests/api/.

Several patterns are separated by commas inside one string. The docs' glob examples: *.py matches .py files in the root only, **/*.py matches them at any depth, src/*.py is one level, src/**/*.py any depth under src, and **/subdir/**/*.py matches any subdir folder anywhere. When a path-specific file matches and a repository-wide file also exists, "the instructions from both files are used."

One more key is documented on GitHub.com: excludeAgent, with the value "code-review" or "cloud-agent", keeps the file away from that feature. "If the excludeAgent keyword is not included in the front matter block, both Copilot code review and Copilot cloud agent will use your instructions."

VS Code's custom instructions docs add two optional keys for the same files: name ("Display name shown in the UI. Defaults to the file name") and description ("Describes the tasks for which the file is relevant. Include it for on-demand discovery"). In VS Code, applyTo is relative to the workspace root, ** matches all files, and "if you omit both description and applyTo, attach the file manually when you want to use it." On GitHub.com the frontmatter with applyTo is described as required. The safe rule: always set applyTo.

Prompt files

Prompt files are different in kind. They are not applied automatically; you run them. VS Code's prompt files docs describe them as "slash commands" that "encode" a common task "as standalone Markdown files that you can invoke directly in chat." They live in .github/prompts (workspace) or your VS Code profile (user), end in .prompt.md, and run when you type / plus the name, run Chat: Run Prompt, or press the play button on the open file.

The frontmatter is optional. The documented keys are name, description, argument-hint, agent (ask, agent, plan or a custom agent's name), model and tools. The body can reference files with markdown links relative to the prompt file, with #file:, or from your home folder with ~/; tools with #tool:name; and user input with ${input:variableName}.

---
name: new-endpoint
description: Scaffold an API endpoint with its test
agent: agent
argument-hint: endpoint name and HTTP method
---
Create the endpoint ${input:name} following [the API conventions](../instructions/api.instructions.md).
Add a test in tests/api/ and run it.

Two status notes. GitHub lists prompt files as public preview and available in "VS Code, Visual Studio, and JetBrains IDEs" only. VS Code goes further: "Prompt files are deprecated for Agent Host sessions and aren't loaded by Agent Host. They continue to work with the Local agent for now, but the Local agent will be removed in a future release", and it recommends converting them to agent skills. If you are starting fresh, a skill (a SKILL.md) is the longer-lived format; see is my SKILL.md valid.

Chat modes have been renamed too. VS Code's custom agents docs say "Custom agents were previously known as custom chat modes" and "If you have existing .chatmode.md files, rename them to .agent.md." Custom agents live in .github/agents in the workspace, and VS Code treats any .md file in that folder as one.

Where each file applies

Support is uneven across surfaces, and the honest answer is a table. This condenses GitHub's support reference (repo = copilot-instructions.md, path = .instructions.md, agent = AGENTS.md, CLAUDE.md, GEMINI.md):

Three details from the docs that change how you test:

• In Copilot Chat on GitHub.com, repository instructions apply when you add the repository "as an attachment" to the conversation.
• Code review reads instructions "from the head branch (the branch with your changes), not the base branch", so a pull request that edits the instructions is reviewed with the new version.
• VS Code: "Custom instructions are not taken into account for inline suggestions as you type in the editor." They are for chat and agents, not completions.

In VS Code the local agent only reads .github/copilot-instructions.md when github.copilot.chat.codeGeneration.useInstructionFiles is on; chat.useAgentsMdFile and chat.useClaudeMdFile switch AGENTS.md and CLAUDE.md support. On GitHub.com, repository custom instructions for code review can be disabled per repository (Settings, Copilot, Code review).

Precedence when several apply

GitHub's concept page gives the order, highest first: personal instructions; path-specific instructions; repository-wide instructions; agent instructions; organization instructions. The sentence after the list is the important one: "However, all sets of relevant instructions are provided to Copilot." Nothing is dropped, so a contradiction between two files is a contradiction in the prompt. The advice is "try to avoid providing conflicting sets of instructions", and VS Code's version is to resolve conflicts "at the source" because "discovery and merge behavior can differ by harness."

Limits, and what the docs leave open

• File size: no hard byte or token limit. GitHub's code review guide gives a best practice: "Limit any single instruction file to a maximum of about 1,000 lines. Beyond this, the quality of responses may deteriorate." The other numbers are GitHub's "no longer than 2 pages" in the generation prompt and VS Code's "keep your instructions short and self-contained."
• Number of files: "one or more" .instructions.md files; no maximum given.
• Reliability: "Due to the non-deterministic nature of AI, Copilot may not always follow your custom instructions in exactly the same way every time they are used." Instructions are context, not enforcement; use branch protection and CI for anything that must hold.
• Nested AGENTS.md: on GitHub.com "the nearest AGENTS.md file in the directory tree will take precedence"; in VS Code nested files are experimental and off by default (chat.useNestedAgentsMdFiles).
• Organization instructions: GitHub.com chat, code review and cloud agent only, and only on Business or Enterprise.

Best practices

• Keep copilot-instructions.md to facts most requests need: what the project is, how to build and test, the conventions a linter does not enforce
• Move rules for one language or folder into .instructions.md files with an applyTo glob, one concern per file
• Quote the applyTo value; a bare **/*.ts is valid YAML but a bare *.ts is not (a leading * is a YAML alias)
• Write rules a reviewer could check: exact commands, exact paths, exact names
• No contradictions between personal, path, repository, agent and organization instructions: all of them are sent
• If other agents work in the repository, keep the shared facts in AGENTS.md and let Copilot read it too; see AGENTS.md vs CLAUDE.md
• Test in a fresh chat with a task the rule should change, and check References in the response to confirm the file was used
• Read the raw file for anything hidden before you merge someone else's instructions; see hidden instructions in AGENTS.md

The browser checker takes copilot-instructions.md only. The Claude Code plugin also reads .instructions.md and .prompt.md files: it warns when an .instructions.md has no applyTo, lists frontmatter keys Copilot does not read, and reports when each file loads.

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis

Sources, read on 14 October 2026: GitHub Docs, Adding repository custom instructions for GitHub Copilot, About customizing GitHub Copilot responses, Support for different types of custom instructions and Using custom instructions to unlock the power of Copilot code review; VS Code docs, Use custom instructions in VS Code, Use prompt files in VS Code and Custom agents in VS Code. Quotes are exact. Support tables change often; check the reference page for your surface. Related: Cursor rules, GEMINI.md for Gemini CLI, CLAUDE.md best practices.