How do you write a GitHub Copilot path-specific .instructions.md file with applyTo, and when does Copilot include it?
answer
- rules for some files only
- a folder under .github
- file-name suffix is mandatory
- glob in YAML frontmatter
- description loads it on demand
basics
~10 sCreate .github/instructions/NAME.instructions.md with YAML frontmatter whose applyTo holds one or more comma-separated globs. Copilot adds it, alongside the repository-wide file, when the file it is working on matches.
solid answer
~40 sPath-specific instructions are Markdown files whose names end in `.instructions.md`, stored in or below `.github/instructions` (subfolders are allowed). The frontmatter's `applyTo` key holds a glob, or several separated by commas, such as `"**/*.ts,**/*.tsx"`. When the file Copilot is working on matches, its instructions are used together with `.github/copilot-instructions.md`, not instead of it. In VS Code the file is attached automatically when `applyTo` matches a file the agent creates or modifies; a `description` lets the agent load it on demand, and a file with neither must be attached manually. Support differs by surface: on GitHub.com only the cloud agent and code review use path-specific files, not Copilot Chat.
code
markdown · 8 lines---
applyTo: "**/*.test.ts,**/*.spec.ts"
---
# Test conventions
- Use the shared fixtures in `test/fixtures` instead of building data inline.
- Name tests after the behaviour: `returns 404 when the order is missing`.
- Never call the real email provider; use the stub client.go deeper
Recall the location .github/instructions, the mandatory .instructions.md suffix and that applyTo in the frontmatter holds the glob.
Explain glob semantics such as src/.py versus src/**/.py, comma-separated patterns, that matching files add to the repository-wide file, and VS Code's applyTo, description and manual modes.
Show you debug an ignored file by checking suffix, glob and surface support, knowing GitHub.com Chat and VS Code code review skip path-specific files.
Decide how a large repository splits guidance between one broad file and many narrow ones, balancing token cost on every request against rules that leak into unrelated code.
## Why path-specific files exist A repository-wide `.github/copilot-instructions.md` travels with every request. Rules that only matter for some files, such as test conventions, a frontend framework's patterns or a migration folder's constraints, bloat that file and leak into unrelated work. **Path-specific custom instructions** solve this: each file carries rules plus a glob saying which files they apply to. ## Writing one 1. Create `.github/instructions` if it does not exist. Subdirectories are allowed, so you can group files by team, language or module. 2. Name the file `NAME.instructions.md`, where `NAME` describes its purpose. The suffix is mandatory: a file called `api-rules.md` in that folder is not a path-specific instructions file. 3. Start it with a YAML frontmatter block containing `applyTo`, a glob that VS Code resolves relative to the workspace root. Separate several patterns with commas. 4. Write the instructions below the frontmatter in natural-language Markdown. VS Code adds two optional frontmatter fields: `name`, a display name, and `description`, which describes the tasks the file is relevant to. On GitHub.com the documented optional key is `excludeAgent`, which keeps the file away from either the cloud agent or code review. ## Reading the globs correctly The glob semantics are the usual source of "it never applies" bugs. GitHub's documentation gives these cases: | Pattern | Matches | |---|---| | `*` | all files in the current directory | | `**` or `**/*` | all files in all directories | | `*.py` | `.py` files in the current directory only | | `**/*.py` | `.py` files in every directory | | `src/*.py` | `src/foo.py`, but not `src/foo/bar.py` | | `src/**/*.py` | `.py` files at any depth under `src` | | `**/subdir/**/*.py` | `.py` files under any `subdir` directory, at any depth | So `src/*.py` silently skips nested packages; `src/**/*.py` is what most people mean. ## When Copilot includes it - **Match plus repository-wide file**: if the path matches the file Copilot is working on and `.github/copilot-instructions.md` also exists, the instructions from **both** files are used. Path-specific rules add to the broad file; they do not replace it. - **VS Code, by pattern**: the file is attached automatically when its `applyTo` matches a file the agent creates or modifies. This relies on `chat.includeApplyingInstructions`, default `true`. - **VS Code, by task**: a file with a clear `description` can be loaded by the agent on demand when the task matches, even without a matching file. - **VS Code, manually**: a file with neither `applyTo` nor `description` is used only when you attach it to a request. ## Which surfaces honour it Support is not uniform, which matters when a rule appears to be ignored: - Copilot cloud agent and Copilot code review on GitHub.com read path-specific files; the GitHub.com page notes these are currently the only GitHub.com features that do. - **Copilot Chat on GitHub.com does not** read them; it uses repository-wide, personal and organization instructions. - VS Code's Copilot Chat and agent read them, while code review run from VS Code reads only the repository-wide file according to GitHub's support table. - Copilot CLI reads them and includes one only when its `applyTo` matches a file the CLI is working with. ## Practical checks When a path-specific file never shows up, confirm the `.instructions.md` suffix, the location under `.github/instructions`, and that the glob matches the actual path the agent touched. In VS Code, expand **References** on the response, or open the Agent Customizations editor with **Chat: Open Customizations** to see whether the file was discovered. Keep each file focused on one area; several small files with distinct globs are easier to reason about than one file with a wide glob that drags its rules into unrelated work. ## A worked layout A repository with a TypeScript frontend, a Python service and shared test rules might carry: - `.github/copilot-instructions.md`: always on (build, test, error handling) - `.github/instructions/frontend/react.instructions.md`: `applyTo: "web/**/*.tsx"` - `.github/instructions/backend/api.instructions.md`: `applyTo: "service/**/*.py"` - `.github/instructions/tests.instructions.md`: `applyTo: "**/*.test.ts,**/test_*.py"` When the agent edits `service/orders/views.py`, it gets the repository-wide file plus `api.instructions.md`; the React and test rules stay out of that request. When it edits `web/cart/Cart.test.tsx`, the React file applies because `web/**/*.tsx` matches, but the test file does not: `**/*.test.ts` does not match a `.tsx` extension. Globs match exactly what they say, so check each pattern against real paths rather than assuming a folder or a file family is covered.
- In VS Code, an .instructions.md file has a description but no applyTo. When does Copilot use it?Only when the agent judges it relevant: VS Code lets the agent load an instructions file on demand when its description matches the current task. Without applyTo it is never attached automatically by file pattern, and a file with neither field must be attached manually to a request.
- Your path-specific file works for the cloud agent but Copilot Chat on GitHub.com never follows it. Is the glob wrong?Not necessarily. GitHub's support table lists path-specific instructions for the cloud agent and code review on GitHub.com, but not for Copilot Chat there, which reads repository-wide, personal and organization instructions. A rule that Chat must follow on GitHub.com belongs in .github/copilot-instructions.md.
- Any Markdown file inside .github/instructions is picked up automatically.
- applyTo accepts only one glob, so you need one file per extension.
- src/*.py also matches Python files in subfolders of src.
- A matching path-specific file replaces the repository-wide instructions for that request.
- Copilot Chat on GitHub.com applies path-specific instruction files too.