Instructions for the copilot-instructions.md file vs .github/instructions confusing

[mojzis-nano]

Select Topic Area

Question

Copilot Feature Area

VS Code

Body

In the github docs about custom instructions, it reads:

VS Code supports either:

A single .github/copilot-instructions.md custom instructions file stored in the repository
One or more .instructions.md files stored within .github/instructions

while the VS Code instructions seem to suggest its ok to have both.

You can also create one or more .instructions.md files to store custom instructions for specific tasks.

I am inclined to believe that since even the github instructions suggests that for some use cases only the "main file" works, the VS code instructions are probably right, but I also feel like I saw a few cases where the instructions seemed to be ignored, so maybe its not that ?

[ikrishanaa]

You can use both formats, and they serve slightly different purposes:

.github/copilot-instructions.md -› repository-wide defaults.

.github/instructions/*.instructions.md -›task-specific overrides.

Copilot merges them at runtime, so the global file provides a baseline while the scoped files refine behavior for certain areas.

Example:

.github/
 ├─ copilot-instructions.md      # global defaults
 └─ instructions/
     ├─ tests.instructions.md    # test-specific rules
     └─ docs.instructions.md     # docs-specific rules

keep general guidance in copilot-instructions.md, and only add .instructions.md files when you need more granular control.

[mojzis-nano]

ok, rereading the whole and chatting with an LLM, i realized the issue is that somehow it looks like either or (which would mean exclusivity), but in reality its just either, meaning both. I am wondering whether I am the only one confused, I think it might make sense to change the wording, maybe just "both" instead of "either" ?

[ikrishanaa]

You're absolutely right the confusion comes directly from the wording in the documentation. "Either" definitely implies exclusivity, so I'm sure you are not the only person who was confused by it.

Suggesting a change to the docs is a fantastic idea. That would be a valuable contribution to help prevent this confusion for others in the future.