skip to content

How do you write a GitHub Copilot path-specific .instructions.md file with applyTo, and when does Copilot include it?

level: middleimportance: should knowfreq 12%

answer

  1. rules for some files only
  2. a folder under .github
  3. file-name suffix is mandatory
  4. glob in YAML frontmatter
  5. description loads it on demand

basics

~10 s

Create .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 s

Path-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
markdown
---
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

for a junior

Recall the location .github/instructions, the mandatory .instructions.md suffix and that applyTo in the frontmatter holds the glob.

for a middle

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.

for a senior

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.

for a principal

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.