Why Copilot CLI ignores your AGENTS.md, and how to see what loaded

AGENTS.md is one of several instruction files GitHub Copilot CLI loads, and not the one that wins. The CLI reads its own instruction files plus Claude's and Gemini's, then combines everything applicable into the prompt with no precedence order between them. A rule in AGENTS.md can therefore sit beside a conflicting rule from another file, and nothing in the loader decides between them.

The sources are CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, path-scoped *.instructions.md files (files that apply only to matching paths), .claude/rules, and user-level files under ~/.copilot. Everything applicable is combined into the prompt.

The docs describe no warning when a file was never found, or when the copy in the running process is older than the file on disk. So a rule that seems ignored raises three separate questions: was the file discovered, is this process's copy current, and did the model receive it and choose otherwise? Most people ask the model, which answers none of them.

Run copilot --version first. The loader has changed several times; advice for an older build sends you looking in the wrong place.

Checked against GitHub's Copilot CLI documentation on 27 October 2026.

Status, 27 October 2026: the docs say all applicable files are combined, identical copies are removed, and there is no general precedence order. They also say an edit takes effect after you exit and resume or start a new session. An open report says that is not enough on some builds: even a brand-new session in the same process can see a stale file until the process restarts (#812, open, updated 18 August 2026).

Check the version first#

The current release is 1.0.104 (27 October 2026). Four releases changed this behaviour enough to matter: 0.0.385 replaced priority-based fallbacks with combining; 1.0.11 added discovery at every level from the working directory up to the Git root; 1.0.36 fixed files under a gitignored .github/; 1.0.89 added .claude/rules. The changelog has the rest.

Three failures that look the same#

Where Copilot CLI looks for instruction files#

The custom instructions page lists these locations.

"Standard locations" is wider than the repository root. It means the repository root, the current working directory, the directories between them, and directories nested in the path of a file the agent touches. That is how a monorepo can have a root file and a service-level file at once.

The command reference summarises several of these files as "in Git root and cwd". The custom instructions page is the fuller description; if a subdirectory file is not loading, test from that subdirectory before trusting the shorter table.

A *.instructions.md file with applyTo is not added at startup; it is added when the agent reads or edits a matching file. It can be absent from /env and still apply later, and it stays cheap until it matches.

In .github/copilot-instructions.md, AGENTS.md, and CLAUDE.md, a line beginning with @ includes another file. Imports nest and are not expanded in GEMINI.md or *.instructions.md; use relative paths.

These are CLI checks. The VS Code integration has its own loader and workspace view, so a file that loads in one surface is not proof for the other (#489, closed as fixed in February 2026).

All applicable files are combined, and none of them wins#

The docs say Copilot CLI combines instructions from all applicable files, removes identical duplicates, and "does not define a general precedence order between these files". There is no rule that the nearest file wins, and none that the repository file beats the user file.

If a root AGENTS.md says "use npm" and a service-level file says "use pnpm", both sentences can be in the prompt. Directory depth does not decide which one the model follows. Put a rule in one place; if a nested file must contradict a broader one, delete the broader sentence or make the scope explicit. Only identical copies are deduplicated, so near-duplicates both stay.

This is the current model, not a bug. The changelog records the switch in 0.0.385, and #713 was closed as completed in April 2026.

Why your file never loaded#

If /instructions does not list it, these are the usual causes.

• You started in the wrong directory. Discovery covers the repository root to the current directory, plus files the agent touches. A sibling subtree is not on that path; start where the rules apply.
• .github is gitignored. Older builds silently skipped files under an ignored .github/; 1.0.36 fixed it (#1981, closed as completed in April 2026). Check with git check-ignore -v.github/copilot-instructions.md.
• COPILOT_CUSTOM_INSTRUCTIONS_DIRS adds only two filenames. It covers AGENTS.md and *.instructions.md. A canonical .github/copilot-instructions.md or CLAUDE.md there is not added, which is the reported behaviour at 1.0.54 (#3507, open). Put the content in an AGENTS.md there, or start with -C <directory>.
• Your global file is in the wrong place. The documented user-level files are ~/.copilot/copilot-instructions.md and ~/.copilot/instructions/**/*.instructions.md. A ~/.copilot/AGENTS.md, or an AGENTS.md inside ~/.copilot/instructions/, is ignored; the same report notes the silence in its Related section (#4822, open, updated 18 September 2026). An open report says /env can list user-level sources the docs do not describe, so check your build (#3983, open, updated 11 July 2026).
• COPILOT_HOME points somewhere else. It replaces the whole ~/.copilot path. Run echo $COPILOT_HOME in the same shell that launches copilot.
• A wrapper passes --no-custom-instructions. The flag disables AGENTS.md and related files. Check aliases and scripts, not just the command you typed.
• A symlinked config directory is importing a foreign file. An open report describes discovery following resolved symlinks and walking every ancestor, so a dotfiles repository's AGENTS.md can arrive in an unrelated project when the agent reads a file under ~/.copilot (#4822, open, observed on 1.0.83).
• A subagent is the thing ignoring you. A custom agent running as a subagent (a helper agent the main agent starts with its own context) does not receive repository instructions unless its frontmatter sets include-custom-instructions: true. The custom agents guide has the inheritance rules.

Why editing the file did nothing#

The docs say to exit the session and then resume it or start a new one. In practice, the unit that holds the old text is the process.

An open report tested this on Copilot CLI 1.0.80 and the Copilot app 1.1.10: a new session in the same running process still saw the previous AGENTS.md, and only a full restart picked up the edit (#812). That matches the report's conclusion: the process, not the session, held the stale copy.

So after editing: quit the CLI completely, start it again, then use copilot --continue or /resume. Do not use /new as the test; a new session in the same process is exactly the case the report says can stay stale. If the same file works in a fresh copilot -p run but not in your open interactive session, the difference is the process, not the file.

Prove what loaded#

Use the surface's own inventory. Do not ask the model what it was sent.

/instructions lists the instruction files discovered for the session and lets you toggle individual ones. The quickest check that it is there.

/env shows the loaded environment: instructions, MCP servers (external tool servers), skills (reusable task instructions), agents, hooks (scripts that run at session events), plugins, LSPs (language servers), and extensions. It shows paths, which is how you catch a symlink or a COPILOT_HOME surprise.

copilot instruction list --json runs outside a session and lists the sources discovered for the current working directory. Each entry has id, label, location, type, sourcePath, defaultDisabled, and applyTo when relevant. One caveat from the docs: plugin-contributed instructions are resolved against your global user settings only, so something enabled by a trusted repository or by managed settings can be missing here while a live session applies it. Use /instructions for that case.

/context shows the instruction block's token cost as its own category, separate from the system prompt (1.0.60 and later). It proves the instructions occupy context, not their source. A large bucket with small files points at an imported or plugin-contributed file.

The log is the last resort. /session prints the current session's log path, and logs live under ~/.copilot/logs/process-{timestamp}-{pid}.log. Start with copilot --log-level=debug and search for instruction source paths. The open symlink report was confirmed this way.

Asking the model is not a check. A model sees the prompt, not the loader. It will say it read your AGENTS.md because that is a reasonable thing to say, then find the rule only after you tell it to open the file. That pattern runs through the early reports on #713: a file being in the prompt and the model having noticed it are different facts.

If it loaded and still isn't followed#

• Two rules disagree. Remove one. With no precedence order, a contradiction is a coin toss that changes with the model and the phrasing.
• The file is too long or the rule is vague. Long files dilute the rules that matter. Keep the root file to what a new colleague needs in the first hour, and make each rule checkable: "Run pnpm test before every commit", not "write clean code".
• The session is long. A rule you stated only in the conversation can fade after compaction, when older turns are replaced by a summary. The docs do not say whether repository instruction files are re-read after compaction, so restate the constraint in the current-state prompt and check it; the compaction guide covers what survives.
• The rule is a safety boundary. Instructions are text in a prompt, not a permission system. If a command must never run, deny it with permissions; if an action must always happen, use a hook (a script the CLI runs at a session event). See the permissions guide and the hooks guide.

Where to go next#

• Copilot CLI guides — the rest of the set.
• Why Copilot CLI keeps asking for permission — when a rule needs to be enforced rather than requested.
• Custom agents in Copilot CLI — when the agent ignoring the instructions is a subagent.
• Context compaction — when the rule was followed at first and faded later.
• One AGENTS.md for every coding agent and how long it can be — sharing one file across tools, and the size each agent documents.