Using instruction files with applyTo

[finfin]

https://code.visualstudio.com/docs/copilot/copilot-customization#_use-instructionsmd-files

To use an instructions file for a chat prompt, you can either:

In the Chat view, select Add Context > Instructions and select the instruction file from the Quick Pick.
Run the Chat: Attach Instructions command from the Command Palette (⇧⌘P) and select the instruction file from the Quick Pick.
Configure the applyTo property in the instruction file header to automatically apply the instructions to specific files or folders.

Custom instruction is wonderful. But if we have to manually add instruction to the context, the use of applyTo is somewhat limited. (Also, in current flow, I'm having hard time finding out which instruction is filtered out by applyTo )

What if we can combine 'applyTo' and settings.json for more automatic instruction selecting? Like

"github.copilot.chat.codeGeneration.instructions": [ ..., { "file": ".github/instructions/**.md" // all instruction is used by default, filtered by applyTo } ],

[aeschli]

There are currently several ways that custom instructions to be added:

1. files from the setting github.copilot.chat.codeGeneration.instructions. These are always added, the applyTo header is not relevant
2. The .github/copilot-instructions.md file: Always added (unless setting is disabled), the applyTo header is not relevant
3. all the instruction files that are located at the location(s) defined by chat.instructionsFilesLocations (default: .github/instructions). You create these with New Instructions File and manage with Attach Instructions Files. These instructions support the applyTo

The instructions files from 3. can either be manually attached or automatically attached. They are automatically added based on the the applyTo If you add them manually the applyTo has no relevance, there's no filtering on manually added instructions

So for what you suggest we already do, The setting is not needed for that. Just place your instructions in github/instructions and set applyTo

[finfin]

There are currently several ways that custom instructions to be added:

1. files from the setting github.copilot.chat.codeGeneration.instructions. These are always added, the applyTo header is not relevant
2. The .github/copilot-instructions.md file: Always added (unless setting is disabled), the applyTo header is not relevant
3. all the instruction files that are located at the location(s) defined by chat.instructionsFilesLocations (default: .github/instructions). You create these with New Instructions File and manage with Attach Instructions Files. These instructions support the applyTo

The instructions files from 3. can either be manually attached or automatically attached. They are automatically added based on the the applyTo If you add them manually the applyTo has no relevance, there's no filtering on manually added instructions

So for what you suggest we already do, The setting is not needed for that. Just place your instructions in github/instructions and set applyTo

Wonderful to know that. Seems I'm need to read the document more thoroughly.

But after some experiment I'm having trouble making method 3 to work.

1. I put some instruction file in .github/shared/instructions
2. configure setting.json as following

{

  "chat.instructionsFilesLocations": {
    ".github/instructions": true,
    ".github/shared/instructions": true
  },
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,
  ...others
}

3. have two instructions:

.github/shared/instructions/angular-apps.instructions.md :

--
applyTo: "libs/**"
--
... libs instructions

.github/shared/instructions/angular-libs.instructions.md :

--
applyTo: "apps/**"
--
... apps instructions

4. when I run command on the file under both libs and apps they did not appear to use my custom instruction as reference

[brutuscat]

Same issue here. only the copilot-instructions.md is picked up automatically.

Version: 1.100.2 Commit: 848b80aeb52026648a8ff9f7c45a9b0a80641e2e Date: 2025-05-14T21:47:40.416Z Electron: 34.5.1 ElectronBuildId: 11369351 Chromium: 132.0.6834.210 Node.js: 20.19.0 V8: 13.2.152.41-electron.0 OS: Darwin arm64 24.5.0

I found that the custom instructions in the directory only work if I call the @workspace participant. Otherwise it will only take the copilot named ones.

[brutuscat]

I also want to add that according to the docs: https://code.visualstudio.com/docs/copilot/copilot-customization#_use-instructionsmd-files

there should be an "add instruction" command but there is none....

The @workspace cannot be recalled in agent mode neither...

[kubasejdak]

Same here. I defined custom instruction file .github/instructions/python.instructions.md with applyTo: "**/*.py" and it was not used automatically when Python files were edited. When I changed it to applyTo: "**" then it was, but then it beats the purpose of applyTo.

I'm using VSCode Insiders with prerelease version of copilot extension:

[markgoho]

yes!

as far as I can tell, only applyTo: '**' is properly being picked up....any other file glob is not working at all

[aeschli]

https://github.com/microsoft/vscode/pull/250754 fixes apply patterns with comma (/*.ts,/.tsx) and apply patterns with folder segments that do not start with **: someFolder/**/*.ts

[atachh]

@aeschli unfortunately this didn't solve the issue for me even in version 1.101.0. The rest of the team has instructions working but not me.

What I tried:

1. Fresh re-install of VSCode
2. Disable all extensions other than Copilot and Copilot Chat
3. Try in a new workspace

I offered more context in #249886, all of it is still relevant. Only .github/copilot-instructions.md works for me, not even instructions with applyTo: '**'

[aeschli]

@atachh Just to verify

• when you run Configure Instructions you see the instruction file
• the instruction file has applyTo: '**' or applyTo: **
• it is not picked up when running a prompt

[GeekTrainer]

Not OP but I can confirm I'm having the same issue. Using applyTo: ** or applyTo: '**' does not cause Chat to discover the file (let alone other patterns). Using VS Code stable, and Configure Instructions does show the file

[atachh]

@aeschli Can confirm on all three points

[aeschli]

Please also check that chat.promptFiles is enabled. It is enabled by default, but organizations can decide to turn it off by default.

[atachh]

Tried enabling, didn't help unfortunately

[r-marmitt]

@aeschli

I believe there may be some confusion about how to use it.

I can confirm: in version 1.102.0-insider, the instruction was added correctly.

However (and this is where I believe the confusion lies), if I simply ask the agent to implement something — including creating the file inside this directory where applyTo should be used — the instruction file will not be considered.

At the very least, the path where the file should be created needs to be provided as context for the agent to use "applyTo" correctly.

Insider: Version: 1.102.0-insider (user setup) Commit: dd48c7f264782fc16486381e8792f79a3f7a19fa Date: 2025-06-16T05:04:17.418Z Electron: 35.5.1 ElectronBuildId: 11727614 Chromium: 134.0.6998.205 Node.js: 22.15.1 V8: 13.4.114.21-electron.0 OS: Windows_NT x64 10.0.19045

[markgoho]

There is a confusing distinction between instruction files and codegen instructions

.instructions.md files seem to be purposed towards adding information to a given prompt when files matching the glob (via applyTo) are in the context window.

Example with file in context window matching applyTo globs in instructions fies

I've got a file open called app.component.ts and I prompt Agent: add a new class property to this class for storing a list of users, the interface of this property should be { name: string; age: number }

Agent properly brings in instructions files:

and I end up with protected readonly cxUsers = signal<User[]>([]); added to my component, great!

Example using codeGeneration instructions with no files in context window

add a new angular component in #file:app that manages users, it should have a single class property for storing a list of users, the interface of this property should be { name: string; age: number }

Note: none of the instructions files are added because I haven't added a file to the context window that matches any of the applyTo of any of the instructions files.

How does Copilot decide how to create this new code? Well, for sure the copilot-instructions.md is always added to prompts. Beyond that, for new code that's generated that isn't adding code to an existing file in the context window (would trigger .instructions.md files to be added if they match applyTo) it relies on the github.copilot.chat.codeGeneration.instructions setting in your VS Code settings.

Example using files in context window matching applyTo instructions files

in .vscode/settings.json I have this reference (these are the same instructions that would be automatically included for editing files that match *.component.ts

"github.copilot.chat.codeGeneration.instructions": [
  {
    "file": ".github/instructions/angular-component-class.instructions.md"
  }
]

and I give Copilot a prompt like: add a new angular component in the user-management app that manages users, it should have a single class property for storing a list of users, the interface of this property should be { name: string; age: number }

You can see Copilot correctly adds the instructions (along with copilot-instructions as it always does)

Summary

There is confusion over how and when custom instructions are provided to Copilot. The quick difference is:

• copilot-instructions.md - always added to every prompt
• .instructions.md - added when files matching applyTo are in the current context window
• github.copilot.chat.codeGeneration.instructions - added to all new code generation requests, no filtering by file glob matching

Recommendation

• Create your .instructions.md files using the applyTo metadata to ensure they're selectively added to prompts when those files are in Copilot's context window
• Add all of these instructions files to the array of files under github.copilot.chat.codeGeneration.instructions so they'll also always be added when generating new code

Of course this recommendation leads to potentially way more tokens being used per prompt because you're now automatically including all instructions with every prompt. I don't know if it's possible to selectively add codeGen instructions based on file glob because the prompt comes before Copilot knows which files it'll be creating or even editing.

But then, if we're passing all codeGen instructions on every prompt....

❓ what exactly is the use case for .instructions.md with applyTo ❓

[brutuscat]

I wanted to confirm that this is working for me since the last update:

Version: 1.101.0 Commit: dfaf44141ea9deb3b4096f7cd6d24e00c147a4b1 Date: 2025-06-11T15:00:50.123Z Electron: 35.5.1 ElectronBuildId: 11727614 Chromium: 134.0.6998.205 Node.js: 22.15.1 V8: 13.4.114.21-electron.0 OS: Darwin arm64 24.5.0

when working with the agent or the ask modes, the "applyto" filters properly based on the files I added to the context. I can also see it working when using the current file as the selection.

[brutuscat]

in my case, what I did is to have:

• a very general code instructions in .github/copilot-instructions.md
• in my case, NX added its own instructions in .github/instructions/nx.instructions.md
• I have my own "testing" file with its applyto,
• angular one too
• and other instructions to set context for different modules that use specific libraries for context all with applyto on directories or wildcards files
• the only setting I have set is "github.copilot.chat.testGeneration.instructions" where I added the testing instructions file.
• I am thinking about adding a general one for the review setting too...

[atachh]

Managed to find the cause for my specific problem, bug reported in #251819

[thdoan]

GPT 4.1 gave me these instructions to specify more than one applyTo pattern:

However, following the instructions gave me these errors in the console:

Anyone figure out how to match multiple filetypes?

[markgoho]

@thdoan this is well-documented

---
applyTo: "**/*.ts,**/*.tsx"
---

[Alanoll]

There is a confusing distinction between instruction files and codegen instructions

.instructions.md files seem to be purposed towards adding information to a given prompt when files matching the glob (via applyTo) are in the context window.

(snipped the rest of the post above)

What's fun about this, is that the latest documation at instruction files marks both Code Generation and Test Generation as deprecated, and to use copilot-instructions.md or .instructions.md instead.

With copilot-instructions.md, then all of the code generation instructions are sent every Copilot request, not just when matching an applyTo or performing code generation.

With .instructions.md, we're back to the problem of on first generation, there is no matching file for the applyTo to get it automatically included.

If you were doing test generation, what is an applicable applyTo? The extension of the test file, or the extension of the file under test? If it's the file under test, I don't want test generation instructions sent on every copilot request (e.g. extension of .ts), because that'll waste token space, and possibly confuse the AI with unneeded instructions.

It seems at least for test generation, the solution is to have an .instructions.md file, and manually select it using the new gear button on the chat window added in v1.102. That less than ideal when I could before just use /test and have them auto included via settings (I still can, but since it's deprecated, I'm trying to work out the new flow)

[dslatkin]

For anybody trying to get their glob patterns working with file paths that have literal square brackets in them, like if you'd want to match src/routes/post/[id]/+page.svelte (common in SvelteKit projects), then you need to use a single character class to escape both the opening and/or closing square brackets. Using a backslash does not escape it.

In other words, the following front matter is needed to match all files under a directory like src/routes/post/[id]/:

---
applyTo: src/routes/post/[[]id[]]/**
---

Hope this saves someone else some pain. VS Code uses its own glob matching algorithm.^[1][2]

[aeschli]

See https://code.visualstudio.com/docs/editor/glob-patterns#:~:text=VS%20Code%20supports%20the%20following%20glob%20syntax%3A%20%5B%5D,will%20match%20paths%20with%20both%20slash%20and%20backslashes. for the glob syntax that we support.

[utapyngo]

I would like the instruction files with applyTo: "/home/.../.../**" be included to all chats started in a workspace that's inside the specified directory, even if no files are attached to the chat. Should I open a new issue?

Now I have to specify "**" and symlink the same instructions file to .github/instructions in multiple projects.

[alexgoldschmidt]

I'm having the same issue:

I have a .instructions.md file at .github/instructions with an applyTo filter

I have a yml file in my context window, but only the copilot-instructions are picked up

[aeschli]

@alexgoldschmidt Can you follow the instructions here to find out more? https://github.com/microsoft/vscode/wiki/Copilot-Issues#custom-instructions-logs

[vkimone]

@alexgoldschmidt Your file hasn’t been added to the context window yet. You’ll need to manually add it by clicking the (+) button next to the file shown in the context window. It seems that VS Code was updated to prevent unnecessary files from being automatically added to the context window.