Copilot instructions: files, scope, and discovery

Start with the intended client

Copilot custom instructions are persistent project guidance, not a replacement for every task prompt. The GitHub CLI guide documents repository-wide, modular and user-level files. In the CLI, user files live under the Copilot home directory; COPILOT_HOME can relocate it. Applicable guidance is combined, so remove contradictions rather than assuming a universal file precedence.

The VS Code guide distinguishes the selected agent harness from its Local agent. A CLI observation is not a VS Code observation. That guide also excludes inline suggestions from custom-instruction behavior. Verify the selected client and session before copying a troubleshooting result between them.

# .github/copilot-instructions.md
Keep changes confined to the requested feature.
Record which validation command ran and its result.
Do not claim a test passed when it was not executed.

These three lines are our example, not a vendor template. Scope-specific guidance should describe a checkable action. Avoid credentials and private customer data in shared instruction files.

Nine actual discovery captures

Each fixture had a fresh Git repository and its own Copilot home. We removed token, API-key, secret and additional-instruction-directory environment variables from the child process. The only tested Copilot operation was instruction list --json; stdin was closed. We did not sign in, submit a prompt, enable a paid plan, or ask a model to generate anything.

Every process returned exit zero with empty stderr. Counts above come from the length of each actual JSON array, not from counting fixture files. We did not receive token or billing counters from this command and do not turn their absence into a measured dollar amount.

Observation CSV Complete capture envelopes Version capture

Three boundaries the outputs make visible

Discovery is broader than a matching request

Cases 03 and 09 both listed the same TypeScript pattern. The latter repository contained no matching TypeScript file at all. A listing therefore cannot answer whether the rule was attached to a particular request. Our experiment ends before that step. To test attachment, retain the task, the affected filename, the client session and its instruction evidence separately.

"type": "vscode",
"sourcePath": ".github\\instructions\\typescript.instructions.md",
"defaultDisabled": false,
"applyTo": ["src/**/*.ts"]

This is an exact field excerpt from the CLI's output. The vscode value is its source-type label; no VS Code process executed this test. Likewise, defaultDisabled: false is a discovery field, not proof that the model read the file.

Two source entries do not establish two copies in the prompt

Case 08 returned the user entry and repository entry even though their contents were byte-identical. We counted sources, not prompt copies. The documented instruction-combination behavior and this source listing describe different stages. Prompt deduplication, the order of instructions and the winner of a conflict remain untested here.

A repair needs its own evidence

Cases 06 and 07 contain the same frontmatter and body; only the filename ending differs. The first produced an empty array, the second one source. They ran in separate fresh repositories. This supports a filename diagnosis for these fixtures, not a claim about hot reload, all possible filenames, or another client's settings. Keep the failed record rather than replacing it with the repaired result.

Replay the fixture, not our assertion

The downloadable script embeds all nine fixtures, creates disposable local Git repositories and saves exact stdout and stderr. It invokes the official installed CLI through Node. It neither installs software nor performs login. Supply an absolute path to your own installed @github/copilot/npm-loader.js. Without an output argument it creates a fresh system temporary directory and prints its location.

Replay script Fixture contents

node copilot-instructions-replay.mjs C:\path\to\node_modules\@github\copilot\npm-loader.js

# The actual command inside each isolated fixture:
copilot instruction list --json

The JSONL file is an envelope per run, including arguments, fixture contents, timestamps, exit status and complete stdout/stderr strings. The original source paths remain in the captures. It is not a reconstructed example or a simulated loader. CSV is only the summary; the JSON output is the primary observation. Compare your version capture before interpreting a difference.

We tested discovery only on CLI 1.0.91. Authentication, instruction attachment, model compliance, managed/organization instructions and conflicts during actual generation remain Untested. The CLI reference also notes limitations for plugin-contributed sources in this listing. Our fixtures contain no plugins; they do not prove that this command describes every instruction in every live session.

Sources and limits

• GitHub CLI instructions: supported locations and conditional guidance.
• GitHub CLI command reference: instruction listing and its limitations.
• VS Code instructions: client-specific discovery and verification.

Sources checked 2026-10-03. The nine version-pinned captures, fixture controls and replay method are our original material, not a model-quality benchmark. SpecMatter is not affiliated with GitHub or Microsoft.

Shared agent instructionsCursor rule testsClaude rule boundariesSpec-driven workflow