Understanding prompt files, instructions, and context layers
Understanding prompt files, instructions, and context layers
GitHub Copilot offers three distinct written customization types that look similar on the surface — they’re all Markdown files stored in your repository. But they differ fundamentally in when they activate, where they land in the prompt assembly, and how the model treats their content.
Choosing the wrong type is one of the most common prompt engineering mistakes. You write detailed coding standards in a prompt file (which disappears after one use) when they should be in an instruction file (which persists across every request). Or you create an instruction file for a one-time code review workflow that should be a prompt file. Understanding the conceptual distinctions prevents these mistakes.
This article explains what each type is, how they compose together in a single request, and how to decide which one fits your situation.
Table of contents
- 🎯 The three written customization types
- 📝 Prompt files: reusable on-demand commands
- 📚 Instruction files: persistent background rules
- 📁 Context files: background knowledge
- 🏗️ How they compose in a single request
- 🔍 Scope hierarchy: global, workspace, and path-specific
- ✅ Decision framework: which type to use
- ⚠️ Common mistakes and how to avoid them
- 🎯 Conclusion
- 📚 References
🎯 The three written customization types
Before diving into each type, here’s a side-by-side comparison:
| Aspect | Prompt files | Instruction files | Context files |
|---|---|---|---|
| Extension | .prompt.md |
.instructions.md |
.md (any) |
| Location | .github/prompts/ |
.github/instructions/ |
.copilot/context/ |
| Activation | On-demand (/command) |
Automatic (file pattern match) | Automatic (semantic search) |
| Assembly position | User prompt | System prompt | Indexed for retrieval |
| Persistence | Single request | Every request (when pattern matches) | Available when relevant |
| Authority | User-level suggestion | System-level rule | Background reference |
| Tool control | ✅ Full (tools: in YAML) |
❌ None | ❌ None |
| Model routing | ✅ Yes (model: in YAML) |
❌ No | ❌ No |
| Cross-platform | ❌ VS Code only | ⚠️ VS Code + GitHub.com | ❌ Semantic search only |
📝 Prompt files: reusable on-demand commands
A prompt file (.prompt.md) is a reusable command you invoke explicitly in chat. Think of it as a saved message template — when you type /review-code, VS Code injects the prompt file’s content into your user prompt alongside your message.
What makes prompt files unique
On-demand activation. Prompt files don’t run automatically. You invoke them by typing /promptName in VS Code or #promptName in Visual Studio. This gives you control over when the content is included.
User prompt position. Prompt file content lands in the user prompt (not the system prompt). The model treats it as something the user is asking, not as a built-in rule. This means the model follows prompt files cooperatively but not with the same authority as system-level instructions.
Tool and model control. Prompt files are the only written customization type that can specify tools: and model: in their YAML frontmatter. This lets you create workflows that are locked to specific capabilities:
---
description: Security review with read-only tools
mode: agent
model: claude-sonnet-4
tools:
- codebase
- problems
- changes
---
Review this code for security vulnerabilities.
Focus on: authentication, authorization, input validation.Variable substitution. Prompt files support variables that inject dynamic context:
| Variable | What it provides |
|---|---|
${selection} |
Currently selected text in the editor |
${file} |
Full path of the current file |
${fileBasename} |
Filename without path |
${workspaceFolder} |
Root folder of the workspace |
${input:name} |
Prompts the user for input at runtime |
${input:name:placeholder} |
User input with placeholder text |
When to use prompt files
- Repeatable workflows — code reviews, refactoring passes, test generation
- Task-specific operations — “generate a migration script,” “review this PR”
- Model-specific tasks — use
model:to route complex reasoning tasks to reasoning models - Constrained operations — use
tools:to restrict what the model can do during the task
📚 Instruction files: persistent background rules
An instruction file (.instructions.md) defines rules that automatically apply whenever you work with matching files. Unlike prompt files that you invoke explicitly, instruction files work silently in the background.
What makes instruction files unique
Automatic activation. Instruction files use an applyTo glob pattern to match files. When you’re editing a TypeScript file and you have an instruction file with applyTo: "**/*.ts", that instruction file is automatically included in every request — no explicit invocation needed.
System prompt position. Instruction content lands in the system prompt (layer 5 of the assembly architecture). The model treats it as built-in rules, not as a user suggestion. This gives instructions stronger authority than prompt files.
Silent operation. Users don’t see instruction content in the chat. It’s injected behind the scenes. This makes instructions ideal for coding standards and conventions that should always apply without requiring explicit invocation.
The copilot-instructions.md special case. The file at .github/copilot-instructions.md is the repository-wide instructions file. It’s always injected last in the instruction layer, giving it the final word on project conventions. Both VS Code and Visual Studio support this file.
Scope patterns
Instruction files support glob patterns that range from broad to highly specific:
| Pattern | Scope | Example use case |
|---|---|---|
**/* |
Everything | General project conventions |
**/*.ts |
All TypeScript files | TypeScript coding standards |
**/*.test.ts |
All test files | Testing conventions and patterns |
src/api/** |
Specific directory | API design rules |
**/*.md |
All Markdown files | Documentation standards |
Multiple patterns can be combined with commas: applyTo: "**/*.ts,**/*.tsx".
When to use instruction files
- Coding standards — naming conventions, formatting rules, language-specific patterns
- Framework guidelines — React component conventions, API design rules
- Security requirements — authentication checks, input validation rules
- Documentation standards — comment styles, README structure requirements
📁 Context files: background knowledge
Context files are Markdown documents stored in .copilot/context/ (or similar directories) that provide background knowledge Copilot can draw from. They don’t activate through explicit invocation or pattern matching — instead, Copilot’s semantic search indexes them and retrieves relevant content when your prompt matches.
What makes context files unique
Passive availability. Context files don’t inject into every request or require explicit invocation. They sit in the background, available when Copilot’s retrieval system determines they’re relevant to your current question.
Rich reference material. Context files are ideal for content that’s too detailed for instruction files but too static for prompt files: API contracts, data schemas, architecture decisions, code patterns, troubleshooting guides.
No file type restrictions. Unlike prompt files (.prompt.md) and instruction files (.instructions.md), context files are regular Markdown. They don’t need special extensions or YAML frontmatter. Copilot indexes them based on content, not file type.
When to use context files
- Architecture documentation — system diagrams, design decisions, component responsibilities
- API contracts — endpoint specifications, data schemas, interface definitions
- Code patterns — approved patterns, anti-patterns, migration guides
- Troubleshooting knowledge — known issues, workarounds, debugging procedures
- Onboarding material — project overview, setup guides, team conventions
🏗️ How they compose in a single request
When you’re working in VS Code with instruction files, invoke a prompt file, and Copilot retrieves relevant context, all three types compose together in a single request:
┌─────────────────────────────────────────────────────────────────┐
│ SYSTEM PROMPT │
│ ├── Built-in layers (identity, tools, formatting) │
│ ├── .instructions.md files (matching current file's patterns) │
│ ├── copilot-instructions.md (always last) │
│ └── .agent.md body (if custom agent is active) │
├─────────────────────────────────────────────────────────────────┤
│ USER PROMPT │
│ ├── .prompt.md body (if you invoked a /command) │
│ ├── Retrieved context files (if semantically relevant) │
│ ├── Environment and workspace info (auto-generated) │
│ ├── Attached files (#file: references) │
│ └── Your typed message │
└─────────────────────────────────────────────────────────────────┘Composition rules
- Instructions set the baseline. They define what the model should always do (coding standards, security rules, formatting requirements). Every request includes them.
- Prompt files add the task. They define what the model should do right now. They’re additive — the model follows both the instructions and the prompt file.
- Context files provide depth. When the model needs background knowledge to complete the task, Copilot retrieves relevant context automatically.
- No conflicts — additive only. If an instruction says “use camelCase” and a prompt file says “review for naming conventions,” there’s no conflict. The model uses camelCase while reviewing for naming conventions. However, contradictory rules (one file says “use semicolons,” another says “no semicolons”) confuse the model — consistency across your customization files matters.
Token budget implications
Each customization type consumes tokens from the context window:
| Type | Token cost pattern |
|---|---|
| Instruction files | Paid on every request (they’re always injected) |
| Prompt files | Paid once per invocation (only when you use /command) |
| Context files | Paid on demand (only when Copilot retrieves them) |
This means verbose instruction files are expensive — they consume tokens on every single request, even when they’re not relevant to your current task. Keep instructions concise and use applyTo patterns to limit when they activate. For detailed content, use context files that are retrieved only when needed.
🔍 Scope hierarchy: global, workspace, and path-specific
All three customization types support multiple scope levels:
Instruction file scopes
| Scope | Location | Availability |
|---|---|---|
| User-level | VS Code profile instructions/ folder |
All your workspaces |
| Workspace-wide | .github/copilot-instructions.md |
This repository |
| Path-specific | .github/instructions/*.instructions.md with applyTo |
Files matching the pattern |
Prompt file scopes
| Scope | Location | Availability |
|---|---|---|
| User-level | VS Code profile prompts/ folder |
All your workspaces (personal) |
| Workspace-level | .github/prompts/*.prompt.md |
This repository (shared via Git) |
Context file scope
| Scope | Location | Availability |
|---|---|---|
| Workspace-level | .copilot/context/ and subdirectories |
This repository |
Precedence
When multiple files at different scopes apply to the same request:
- Instructions: All matching files are included.
copilot-instructions.mdis always last (highest precedence for project-wide rules). - Prompt files: Only the explicitly invoked prompt file is included. Scope doesn’t create precedence — you choose which prompt to run.
- Context files: Copilot retrieves the most semantically relevant files, regardless of directory depth.
✅ Decision framework: which type to use
Use this decision tree to choose the right customization type:
What are you trying to accomplish?
│
├─ "I want rules that always apply to certain files"
│ └─ → Instruction file (.instructions.md) with applyTo pattern
│
├─ "I want a reusable workflow I can run on demand"
│ └─ → Prompt file (.prompt.md) in .github/prompts/
│
├─ "I want Copilot to know about my architecture/schemas/patterns"
│ └─ → Context file (.md) in .copilot/context/
│
├─ "I want project-wide conventions for all files"
│ └─ → copilot-instructions.md in .github/
│
└─ "I want to combine all of these"
└─ → Use all three! They compose additively.Quick reference
| Situation | Use |
|---|---|
| Coding standards for TypeScript files | Instruction file with applyTo: "**/*.ts" |
| Code review workflow | Prompt file invoked on demand |
| API schema documentation | Context file in .copilot/context/ |
| “Always use async/await” rule | Instruction file (project-wide or language-specific) |
| “Generate a migration script” template | Prompt file with ${input:} variables |
| Architecture decision records | Context files in .copilot/context/architecture/ |
| Security checklist for PRs | Prompt file (invoked when reviewing PRs) |
| Framework-specific component patterns | Instruction file for component file patterns |
⚠️ Common mistakes and how to avoid them
Mistake 1: putting coding standards in prompt files
Symptom: You define coding standards in a .prompt.md file, but the model doesn’t follow them unless you explicitly invoke the prompt every time.
Why it happens: Prompt files inject into the user prompt on demand. If you don’t invoke /my-standards, they’re not included.
Fix: Move coding standards to .instructions.md files with appropriate applyTo patterns. They’ll be injected automatically into every relevant request.
Mistake 2: overloading instruction files
Symptom: Copilot responses become slow or inconsistent. The model seems confused about which rules to follow.
Why it happens: Too many instruction files with overlapping or broad patterns. Every matching instruction is injected into every request, consuming tokens and potentially contradicting each other.
Fix: Keep instruction files focused and use specific applyTo patterns. Review your instruction files periodically — if two instructions overlap, merge them or narrow their patterns.
Mistake 3: duplicating content across types
Symptom: The same information appears in an instruction file, a prompt file, and a context file. Updates become a maintenance burden.
Why it happens: Uncertainty about which type to use leads to “just put it everywhere.”
Fix: Each piece of content belongs in exactly one place. Use the decision framework above to determine the right type, then link to it from other files instead of duplicating.
Mistake 4: ignoring assembly position
Symptom: A prompt file’s instructions seem to “lose” to contradictory guidance in instruction files.
Why it happens: Instructions land in the system prompt (higher authority). Prompt files land in the user prompt (lower authority). When they conflict, the system prompt usually wins.
Fix: Don’t create contradictions between instruction files and prompt files. If a prompt file needs to override a rule, make it explicit: “For this task, override the usual naming convention and use snake_case instead.”
🎯 Conclusion
Prompt files, instruction files, and context files form the written customization layer of GitHub Copilot. They look similar — they’re all Markdown — but they differ in activation, assembly position, and authority. Understanding these differences is the foundation for building a coherent customization stack.
Key takeaways
- Prompt files are on-demand commands that inject into the user prompt. Use them for reusable workflows, task-specific operations, and tool-constrained tasks.
- Instruction files are automatic rules that inject into the system prompt. Use them for coding standards, framework guidelines, and persistent conventions.
- Context files are passive knowledge that Copilot retrieves when relevant. Use them for architecture docs, schemas, and reference material.
- All three types compose additively in a single request — instructions set the baseline, prompts add the task, and context provides depth.
- Token costs differ — instructions are paid on every request, prompts once per invocation, and context only when retrieved.
Next steps
- How Copilot assembles and processes prompts — understand the assembly architecture these types plug into
- How to structure content for Copilot prompt files — practical how-to for writing effective prompt files
- How to structure content for Copilot instruction files — practical how-to for writing effective instruction files
📚 References
GitHub Copilot Documentation — Repository Instructions [📘 Official] Official GitHub documentation for customizing Copilot with repository-level instructions. Covers prompt files, instruction files, and AGENTS.md configuration. Essential for understanding the official specification for all three written customization types.
VS Code Copilot Customization Overview [📘 Official] Microsoft’s comprehensive guide to customizing GitHub Copilot in VS Code. Covers the distinction between prompt files, instruction files, and agents — including their activation patterns, scoping, and configuration options.
VS Code Copilot Chat Documentation [📘 Official] Official documentation for Copilot Chat features including slash commands, context variables, and the semantics of how prompt files are invoked via /command syntax.
How to use GitHub Copilot: Prompts, tips, and use cases [📘 Official] Official GitHub documentation covering prompt engineering best practices, effective communication patterns with Copilot, and real-world use cases for all customization types.