Skip to main content

​
What are Custom Instructions?

Custom instructions are markdown files that provide context-aware guidance to GitHub Copilot. They automatically apply coding standards, best practices, and project-specific conventions when working with files that match specific patterns.
Instructions help GitHub Copilot understand your project’s conventions without needing to repeat them in every prompt.

​
How Instructions Work

Instructions use file pattern matching to automatically activate when you’re working with specific file types. When an instruction file matches your current context, its guidelines are applied to Copilot’s suggestions.

​
Example Flow

  1. You open a file: components/Button.tsx
  2. Copilot checks for instructions that match **/*.tsx
  3. The React and TypeScript instructions automatically apply
  4. Copilot generates code following your project’s React patterns

​
Instruction File Format

Every instruction file follows a standard format with YAML frontmatter and markdown content.

​
Required Frontmatter

---
description: 'Brief description of what this instruction provides'
applyTo: '**/*.ts, **/*.tsx'
---
​
description
string
required
A clear, concise description of the instruction’s purpose. Must be wrapped in single quotes.
​
applyTo
string
required
File patterns that trigger this instruction. Supports glob patterns and comma-separated values.

​
File Content

After the frontmatter, write your instructions in markdown. Include:
  • Coding standards - Naming conventions, formatting rules
  • Best practices - Recommended patterns and approaches
  • Project structure - How to organize code and files
  • Common patterns - Reusable code examples
  • Testing guidelines - How to write and structure tests

​
Understanding applyTo Patterns

The applyTo field uses glob patterns to match files. Here are common patterns: 
applyTo: '**/*.py'
Applies to all Python files in the project.
applyTo: '**/*.ts, **/*.tsx, **/*.js, **/*.jsx'
Applies to TypeScript and JavaScript files (including JSX/TSX).
applyTo: '**/*.razor, **/*.razor.cs, **/*.razor.css'
Applies to Blazor component files and their code-behind/styles.
applyTo: '**'
Applies to all files in the project (use for universal guidelines like accessibility).
applyTo: '**/*.tf'
Applies to Terraform configuration files.

​
Pattern Matching Rules

  • ** - Matches any directory at any level
  • * - Matches any characters except directory separator
  • *.ext - Matches files with specific extension
  • Multiple patterns are comma-separated

​
Real-World Examples

​
C# Development Instructions

---
description: 'Guidelines for building C# applications'
applyTo: '**/*.cs'
---

​
React Development Instructions

---
description: 'ReactJS development standards and best practices'
applyTo: '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss'
---

​
Accessibility Instructions

---
description: "Guidance for creating more accessible code"
applyTo: "**"
---

​
Installation and Usage

​
Using VS Code Install Buttons

Most instructions in the Awesome GitHub Copilot repository include install buttons:
1

Click Install Button

Click the VS Code or VS Code Insiders badge next to the instruction you want
2

Confirm Installation

VS Code will prompt to install the instruction file
3

Automatic Activation

The instruction will automatically apply when working with matching files

​
Manual Installation

You can also manually add instructions to your project:
1

Download the File

Download the *.instructions.md file from the repository
2

Create Instructions Directory

Create .github/instructions/ in your workspace if it doesn’t exist
3

Add the File

Copy the instruction file to .github/instructions/
4

Verify Activation

Open a file matching the applyTo pattern to verify the instruction applies

​
Global Instructions

For workspace-wide instructions, use the special file: 
.github/copilot-instructions.md
This file applies to all files and interactions with Copilot in your workspace.

​
Best Practices for Writing Instructions

Be Specific

Provide concrete examples and clear rules rather than vague guidelines

Stay Focused

Keep instructions relevant to the file types they target

Use Examples

Include code snippets showing the preferred patterns

Explain Why

Include rationale for important decisions and patterns

​
Structure Your Instructions

Good instructions typically include:
  1. Project Context - Technology stack, versions, frameworks
  2. Development Standards - Architecture, patterns, conventions
  3. Code Style - Formatting, naming, organization
  4. Testing Guidelines - How to write and structure tests
  5. Security & Performance - Important considerations
  6. Examples - Real code showing preferred patterns

​
Common Use Cases

Apply React, Angular, Vue, or other framework best practices automatically when working with those files.
Enforce language-specific patterns like C# naming conventions, Python PEP 8 compliance, or Java code style.
Guide Terraform, Bicep, or CloudFormation generation with security and maintainability standards.
Ensure consistent test structure, naming, and coverage requirements across your codebase.
Apply WCAG compliance and accessibility best practices to UI code automatically.
Enforce security patterns, input validation, and OWASP guidelines in your code.

​
Next Steps

Browse the Catalog

Explore available instructions organized by technology

Create Your Own

Learn how to create custom instructions for your projects

Build docs developers (and LLMs) love

Get started for freeTalk to us