Referencing multiple Instruction MDs conditionally.

[aditya-css]

Select Topic Area

Question

Copilot Feature Area

Copilot Agent Mode

Body

The copilot-instructions.md file gets too long and I would like it to be spilt into multiple files based on certain section. The separated file should only be referenced if a prompt related to it is given.

How can I achieve this? I am aware about changing settings.json file and adding all the separated md files in codeGeneration settings, but that will make all the files to be referenced everytime.

Also, is it a good idea to separate out the copilot-instructions.md file or having a large one is okay?

[ahmetkutay]

Hi @aditya-css ,

You can do your research in this page ( https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?tool=vscode ). They explained it clearly and It helps your problem.

[douglasg14b]

I isn't clear though, it shows you how, and then says:

For example, the following instructions may not have the intended results:

With no further explanation about why. This is crazy confusing :/

[aditya-css]

Hey @ahmetkutay ,
Thanks for responding. But, I am aware of .github/copilot-instructions.md and what I want is how to split it into multiple files and refer those only as and when required.

[ahmetkutay]

Hello again,
Oh I see, then the answer of your question is currently GitHub Copilot does NOT support splitting. You can split it and refer the other md's but still all works together.
.github/copilot-instructions.md is global and always included, so splitting it into multiple files and expecting Copilot to selectively load them automatically is not supported yet

The option you can do:

• Use filename.prompt.md files for selective context
• Manually load or reference specific prompt files for detailed or section-specific instructions

[karlismelderis-mckinsey]

refer the other md's but still all works together
we tried to reference our existing developer documentation (even tiny cherry-picked and tuned for CoPilot) but CoPilot failed to use these instructions

is there any working example where CoPilt PR review instructions works with MD files referenced?

[aditya-css]

Here's what I did at the end. Split the main copilot-instructions.md file into multiple *.instructions.md files and place those in an instructions folder. Now I add a reference to particular file this way: For Xyz details, refer [Xyz instruction file] (instructions/xyz.instructions.md).

[theophanemayaud]

I'm trying vs code again after using cursor for a while, and trying to migrate my cursor agent rules to copilot instructions. Thanks for posting about your solution as the docs are really unclear for advanced use.

Like: if I want to have multiple instruction files, should I still use the "single" file ?

Also, the docs don't even specifically explain that you can indeed create multiple as long as the suffix is .instructions.md, they just say "Create one or more .instructions.md files, adding natural language instructions to the file(s).", which lead me to believe that I could either:

• create multiple such files in different sub directories within the project
• create multiple files in the root/.github/instructions/ folder with the .instructions.md suffix, or as you put it, multiple *.instructions.md files !

So is it indeed only possible to create multiple instruction files in the root/.github/instructions/ of a project, and not throughout the repo as cursor does ? So I guess I have to re create all my cursor rules in root/.github/instructions/ instead of the respective folders they apply to, and use the applyTo to specify which folders they apply to...

But now: how are they discovered/passed to the agent ? If the agent touches any file within the apply to ? Or... only when manually accessed ? And can the agent self discover these rules like in cursor, where you define a brief description that is, from my understanding, always passed as a tool to the agent so if it seems like it needs more details along what that description is, it can pull the full file before working...

In general those docs need more details for advanced uses !

Now I add a reference to particular file this way: For Xyz details, refer [Xyz instruction file] (instructions/xyz.instructions.md)

Do you mean that you add this reference in the "single" copilot-instructions.md file ? So that this "main/single" entrypoint for the agent, which is always included, helps it discover optional other instruction files ?