Why GitHub Copilot Ignores Your Instructions File

When GitHub Copilot ignores .github/copilot-instructions.md, one of two things has happened: the file was never sent with the request, or it was sent and something else won. Expand References on the chat response. If the file is not listed, Copilot did not use it, and the cause is the path, a setting, the agent you picked, or a surface that does not read that file. If it is listed, the cause is how the instructions are written or another file that says something different. And if you were expecting it to shape the grey suggestions that appear as you type, it never will: custom instructions do not apply to inline suggestions.

First: was the file used?

• Copilot Chat, in VS Code or on GitHub.com: expand References at the top of a response. GitHub says that whenever repository instructions are used, the file is added there as a reference.
• VS Code, when the file is not listed: open the Chat view’s context menu and choose Diagnostics. It shows which instruction files were discovered and any errors in them, such as broken frontmatter.
• VS Code, to see the exact text sent: Developer: Show Chat Debug View, from the Command Palette, shows the system and user prompts with the instructions that went in.
• Copilot CLI: run /instructions to list the files found for the session and turn individual ones on or off.
• Copilot code review: open a small pull request that should trigger a rule, and ask for a review.

VS Code’s troubleshooting guide↗ (opens in a new tab) sorts the Diagnostics results into missing, containing errors, and loaded but not applied, which maps neatly onto the sections below.

Not used: wrong name or wrong place

• Repository-wide: exactly .github/copilot-instructions.md, at the root of the repository or workspace folder you opened. copilot-instruction.md, .github/instructions.md or a copy in docs/ are never read.
• Path-specific: files must be in .github/instructions/ (subfolders are fine) and end in .instructions.md. testing.md in that folder is ignored.
• Opened the wrong folder: if VS Code is open on a parent folder or a subfolder of the repository, the file is not where it looks. Open the repository root.
• Code review: Copilot reads instructions from the pull request’s head branch, so a fix to the file on main does not reach a review of a branch cut before it.
• Copilot CLI: edits to instruction files are not picked up by a session that is already running. Exit and start a new one.

Not used: a setting is off

For VS Code’s built-in Local agent, instruction files are controlled by settings. According to VS Code’s custom instructions page↗ (opens in a new tab), these are the ones to check:

• github.copilot.chat.codeGeneration.useInstructionFiles: whether .github/copilot-instructions.md is picked up at all.
• chat.useAgentsMdFile and chat.useClaudeMdFile: whether AGENTS.md and CLAUDE.md are read.
• chat.useNestedAgentsMdFiles: nested AGENTS.md files in subfolders. Off by default.
• chat.includeApplyingInstructions: pattern-based instruction files.
• chat.instructionsFilesLocations: now deprecated. If you moved your instruction files to a custom folder with it, move them back to .github/instructions/.

Check the workspace settings as well as your user settings; a committed .vscode/settings.json can turn one off for everyone. On GitHub.com, code review has its own switch: repository Settings, Copilot, Code review, “Use custom instructions when reviewing pull requests”.

Not used: the wrong agent in VS Code

VS Code now runs a chat session through an agent harness you pick with the Session Target control: Local, Copilot, Claude, Codex or Cloud. The settings above apply to the Local agent. The others follow their own discovery rules. A Copilot session reads .github/copilot-instructions.md, AGENTS.md and .github/instructions/. A Claude session reads CLAUDE.md and .claude/rules/, not your Copilot file. A Cloud session runs against the repository on GitHub, so it sees what is pushed, not what is unsaved in your editor. If instructions work in one session and not in the next, check which target is selected before anything else.

Loaded but not applied: applyTo does not match

A path-specific file applies only when its applyTo glob matches. The globs are relative to the repository root, and they are stricter than people expect:

---
applyTo: "**/*.py"
description: "Python style and test rules for this service"
---
- Type-hint every public function.
- Tests use pytest fixtures from tests/conftest.py; do not build data inline.

• *.py matches Python files in the root only. GitHub’s guide to repository instructions↗ (opens in a new tab) is explicit: use **/*.py for every folder, and src/**/*.py for everything under src.
• Several patterns go in one quoted string, separated by commas: "**/*.ts,**/*.tsx".
• In VS Code, a file is attached when applyTo matches a file the agent creates or modifies. Asking a question about a file without changing it may not bring the rules in. A clear description lets the agent load the file when the task fits, and you can always attach it by hand.
• A file with neither applyTo nor description is applied only when you attach it yourself.
• excludeAgent: "code-review" or "cloud-agent" hides the file from that agent on purpose. Check nobody added it.
• On GitHub.com, only the cloud agent and code review read path-specific files. Copilot Chat on GitHub.com uses the repository-wide file only.

Loaded but ignored: another file disagrees

Instruction sources add up; they do not override each other. VS Code says outright that you should not rely on file order or precedence to settle a conflict. GitHub gives personal instructions the highest priority, then repository, then organisation, but all of them are sent. The Copilot CLI combines every file it finds, removes exact duplicates, and defines no order at all. So when AGENTS.md says npm and copilot-instructions.md says pnpm, the model may follow either. Find the rule in every file, including your personal instructions, and keep it in one. Which surface reads AGENTS.md, and which AGENTS.md wins when there are several, is in does GitHub Copilot support AGENTS.md.

Loaded but ignored: too long or too vague

GitHub’s code review tutorial↗ (opens in a new tab) lists the usual causes when a loaded file makes no difference: the file is too long, the language is vague, a path-specific file has no applyTo, or instructions conflict. It suggests about 1,000 lines as the most a single file should hold, and far less works better. For code review in particular, some instructions are simply not supported:

• Changing how comments look, such as bold text for critical issues or emoji.
• Changing the pull request overview, blocking a merge or writing a changelog.
• Following a link to standards held elsewhere. Code review does not open it; paste the rules in.
• Wishes such as “be more accurate” or “do not miss anything”, which add noise and change nothing.

One older piece of advice is out of date: code review used to stop reading an instructions file after 4,000 characters, and GitHub removed that limit↗ (opens in a new tab) in June 2026. A long file is now read in full, which is not the same as being followed. What a short, specific file looks like is in copilot-instructions.md examples.

Not used: the surface does not read that file

• Inline suggestions as you type: no custom instructions at all.
• Code review in VS Code and Visual Studio: the repository-wide file only. In Eclipse, code review does not support custom instructions.
• Copilot Chat on GitHub.com: repository-wide, personal and organisation instructions; no path-specific files and no AGENTS.md.
• Copilot CLI and the cloud agent: the widest support, including AGENTS.md, CLAUDE.md and GEMINI.md.

Organisation instructions not showing

Organisation owners set these in the organisation’s settings, under Copilot, Custom instructions. GitHub’s organisation instructions page↗ (opens in a new tab) lists three places they are used: Copilot Chat, code review and the cloud agent, all on GitHub.com. VS Code can also pick them up in supported sessions when github.copilot.chat.organizationInstructions.enabled is on. If a colleague sees them and you do not, compare that setting and which organisation your Copilot access comes from.

Rules that must never be broken

Instructions are guidance a model tries to follow, not enforcement. “Never push to main” belongs in branch protection; “every change passes the tests” belongs in a required status check. Keep the line in the instructions file so Copilot gets it right first time, and let the repository settings catch it when it does not.

Instructions say how; the board says what

A common reason a file grows until Copilot stops following it is that it has become a to-do list: this week’s bug, the migration in progress, who to ask. That belongs on a board, not in a file sent with every request. With fenbs connected to Copilot over MCP, one line does the job: “Before starting, read the task you were given with fenbs_get_item; when you stop, comment on it with what changed.” The work list stays current, and every change the assistant makes is recorded in the board’s history under its name.