File-Specific Instructions (.instructions.md)

Guidelines loaded on-demand when relevant to the current task, or explicitly when files match a pattern.

Locations

Path	Scope
`.github/instructions/*.instructions.md`	Workspace
`<profile>/instructions/*.instructions.md`	User profile

Frontmatter

---
description: "<required>"    # For on-demand discovery—keyword-rich
name: "Instruction Name"     # Optional, defaults to filename
applyTo: "**/*.ts"           # Optional, auto-attach for matching files
---

Discovery Modes

Mode	Trigger	Use Case
On-demand (`description`)	Agent detects task relevance	Task-based: migrations, refactoring, API work
Explicit (`applyTo`)	Files matching glob in context	File-based: language standards, framework rules
Manual	`Add Context` → `Instructions`	Ad-hoc attachment

Template

---
description: "Use when writing database migrations, schema changes, or data transformations. Covers safety checks and rollback patterns."
---
# Migration Guidelines

- Always create reversible migrations
- Test rollback before merging
- Never drop columns in the same release as code removal

Note the "Use when..." pattern in the description—this helps on-demand discovery.

Explicit File Matching (optional)

Use applyTo when the instruction applies to specific file types or folders:

applyTo: "**/*.py"                      # All Python files
applyTo: ["src/**", "lib/**"]           # Multiple patterns (OR)
applyTo: "src/api/**/*.ts"              # Specific folder + extension

Applied when creating or modifying matching files, not for read-only operations.

Core Principles

Keyword-rich descriptions: Include trigger words for on-demand discovery
One concern per file: Separate files for testing, styling, documentation
Concise and actionable: Share context window—keep focused
Show, don't tell: Brief code examples over lengthy explanations

Anti-patterns

Vague descriptions: "Helpful coding tips" doesn't enable discovery
Overly broad applyTo: "**" with content only relevant to specific files
Duplicating docs: Copy README instead of linking
Mixing concerns: Testing + API design + styling in one file

2.4 KiB Raw Blame History