Copilot Instructions Not Working? 9 Fixes for copilot-instructions.md

Published 2026-11-01 · 6 min read · by AgentKit Co

You wrote a .github/copilot-instructions.md, and Copilot still uses npm instead of pnpm, or the code review ignores your rules. The cause is usually on a short list: the feature you're using doesn't read that kind of file, the file is in the wrong place, a pattern doesn't match, a setting is off, or two files disagree.

Everything here was checked on 2026-11-01 against GitHub's repository custom instructions guide, GitHub's support table for custom instructions and VS Code's custom instructions docs. Copilot changes often, so re-check anything you depend on.

1. Check whether it loaded at all

Don't guess. In Copilot Chat, expand the References list at the top of a response and look for .github/copilot-instructions.md. GitHub's guide says the file is listed there whenever chat used it.

In VS Code, run Chat: Open Customizations from the Command Palette and check the file appears for the agent you selected. That proves it was found, not that it was followed. For loading errors, VS Code's docs point to Developer: Open Agent Debug Logs.

2. That Copilot feature doesn't read that file

This is the most common surprise. Support differs by feature and by editor. A few examples from GitHub's support table (checked 2026-11-01):

So a path-specific file that works for the cloud agent can do nothing in GitHub.com chat, and VS Code's code review only sees the repo-wide file. Also note VS Code's docs: custom instructions are not used for inline suggestions as you type. They apply to chat and agent requests.

3. The path or name is slightly wrong

The repo-wide file must be exactly .github/copilot-instructions.md, in the .github folder at the repository root. Not docs/, not .github/copilot/, not copilot-instruction.md.

Path-specific files must end in .instructions.md and live in or below .github/instructions/. Subfolders are fine (.github/instructions/backend/api.instructions.md), but api.md or api.instructions.txt is ignored.

4. The applyTo pattern doesn't match

Path-specific files need frontmatter with applyTo, a glob relative to the repository root:

---
applyTo: "**/*.ts,**/*.tsx"
---
Use the shared `apiClient` from `src/lib/api.ts` for every HTTP call.

Three mistakes show up a lot:

• *.py only matches the root folder. GitHub's examples spell it out: *.py matches .py files in the current directory, and **/*.py matches them everywhere. Use src/**/*.py for one tree.
• A space-separated list. Multiple patterns are separated by commas inside one string.
• The file isn't being edited. In VS Code, a file is attached automatically when its pattern matches a file the agent creates or modifies. Asking a general question in chat may not touch a matching file. VS Code also lets the agent load a file on demand when its description matches the task, so add one:

---
description: 'Use when creating or updating Python unit tests.'
applyTo: '**/*.py'
---

5. excludeAgent is hiding it

GitHub supports an excludeAgent key with "code-review" or "cloud-agent". A file with excludeAgent: "code-review" is only read by the cloud agent, so code review will never use it. If you copied a template, look for this line.

6. A VS Code setting is off

For the Local harness in VS Code, the docs tie discovery to settings. Check these in Settings:

• github.copilot.chat.codeGeneration.useInstructionFiles for .github/copilot-instructions.md
• chat.includeApplyingInstructions for pattern-based .instructions.md files
• chat.includeReferencedInstructions for instructions you link from other files
• chat.useAgentsMdFile for a root AGENTS.md (on by default)
• chat.useNestedAgentsMdFiles for nested AGENTS.md files, which the docs call experimental and off by default
• github.copilot.chat.organizationInstructions.enabled for organization instructions

Also check which agent harness the chat is using. VS Code's docs say each harness has its own discovery rules, and Copilot CLI and the GitHub Copilot app don't inherit editor settings such as chat.instructionsFilesLocations. Keep files in the native folders (.github/instructions) rather than a custom location.

7. Code review reads the PR branch, and the toggle may be off

Two things catch people with Copilot code review on GitHub.com:

• It reads instructions from the head branch, the branch with your changes, not the base branch. Changing the file on main doesn't affect a review of an older feature branch until that branch has the change. The upside: you can test new instructions in the same pull request.
• Custom instructions for review can be switched off in the repository's settings under Copilot, then Code review: "Use custom instructions when reviewing pull requests". It's on by default, so check it if someone changed it.

8. Two sources disagree

Copilot doesn't pick one file. Personal, repository and organization instructions can all apply, and GitHub's guide says all relevant sets are sent. On GitHub.com chat, personal instructions have the highest priority. VS Code's docs go further: sources are additive, and you shouldn't rely on any order to settle a conflict.

So when one rule is ignored, look for its opposite in your personal instructions, an AGENTS.md, a CLAUDE.md, an organization instruction or your own prompt, and delete the contradiction at its source.

9. The rule is too long or too vague

GitHub's own advice is short, self-contained statements, because the file is sent with every chat message. Its onboarding prompt for the cloud agent caps instructions at two pages and says they must not be task-specific. "Write clean code" can't be checked. "Run pnpm test --filter web after changing anything in apps/web" can. VS Code's tips add: say why a rule exists and show a preferred and an avoided example.

And instructions are guidance, not enforcement. If something must never happen, back it with a CI check, a branch rule or a pre-commit hook.

A quick checklist

1. The file shows up under References or in Chat: Open Customizations (fix 1).
2. The feature you're using supports that file type (fix 2).
3. The path is exactly .github/copilot-instructions.md or .github/instructions/**/*.instructions.md (fix 3).
4. applyTo uses **/ and commas, and you're editing a matching file, or the file has a description (fix 4).
5. No excludeAgent line is hiding it (fix 5).
6. The VS Code settings for instruction files are on for your harness (fix 6).
7. For code review, the head branch has the file and the review toggle is on (fix 7).
8. No other source says the opposite (fix 8).
9. Each rule is short and names a concrete command or check (fix 9).

Start from a working file

Our free AGENTS.md generator builds a starting copilot-instructions.md in your browser, plus matching AGENTS.md, CLAUDE.md, Cursor, GEMINI.md and Kiro files so the tools can't drift apart. For copy-paste files, see copilot-instructions.md examples. The AI Coding Agent Config Kit adds 12 stack templates, 3 Copilot instruction files and 12 prompts that audit and test them.

Other tools: AGENTS.md not working, CLAUDE.md not working and Cursor rules not working.

Sources: GitHub Docs, Adding repository custom instructions and Support for different types of custom instructions; VS Code, Use custom instructions in VS Code (all checked 2026-11-01). AgentKit Co is not affiliated with GitHub, Microsoft or the other tools named. This guide was written with AI assistance and checked against the pages above.

Keep reading