Using Custom Instructions

Custom instructions enable you to apply team-specific coding standards, best practices, and framework patterns automatically to your GitHub Copilot experience. Instructions are stored as .instructions.md files and apply contextually based on file patterns.

What are Custom Instructions?

Custom instructions are markdown files that provide guidance to GitHub Copilot for specific file types, languages, or project contexts. They help ensure:

Consistency - All team members follow the same coding standards
Best Practices - Framework-specific patterns are automatically applied
Quality - Code meets organizational requirements
Context - Copilot understands your project’s unique conventions

Instructions automatically apply to Copilot’s behavior - no manual activation needed!

Installing Custom Instructions

One-Click Install
Manual Installation

Browse the Instructions Catalog and click the install button:

VS Code: Click the VS Code install badge
VS Code Insiders: Click the VS Code Insiders install badge

The instruction file will be automatically added to your workspace.

Download the file

Navigate to the instructions/ directory and download the desired *.instructions.md file.

Choose installation location

Install instructions in one of these locations:

Project-wide: .github/copilot-instructions.md (single file)
Organized: .github/instructions/my-rules.instructions.md (multiple files)
Root directory: copilot-instructions.md (legacy)

Verify installation

Copilot will automatically detect and apply the instructions when you work with matching files.

Instruction File Structure

Every instruction file follows this structure:

---
description: 'Brief description of the instructions'
applyTo: '**/*.cs, **/*.ts'  # File patterns
---

# Instruction Title

## Guidelines

Detailed coding standards and practices...

Frontmatter Field Requirements

description (required): Wrapped in single quotes, not empty
applyTo (required): File patterns using glob syntax (e.g., '**.js, **.ts')
File naming: Use lowercase with hyphens (e.g., csharp-coding.instructions.md)

File Pattern Matching

The applyTo field uses glob patterns to determine when instructions activate:

---
applyTo: '**/*.cs'
---
Applies to all C# files

How Instructions Apply

Instructions automatically activate based on context:

File Match

When you open or edit a file, Copilot checks the applyTo pattern for all instructions in your workspace.

Context Loading

Matching instructions are loaded into Copilot’s context, influencing completions and chat responses.

Automatic Application

Copilot follows the guidelines when:

Generating code completions
Answering questions in chat
Refactoring code
Creating new files

Common Instruction Patterns

Language Standards
Framework Patterns
Security & Quality
Project-Specific

Define coding conventions for specific languages:

---
description: 'C# coding standards'
applyTo: '**/*.cs'
---

# C# Development

## Naming Conventions
- Use PascalCase for classes, methods, and properties
- Use camelCase for local variables and private fields
- Prefix interfaces with "I" (e.g., IUserService)

## Formatting
- Use file-scoped namespace declarations
- Always use `is null` instead of `== null`
- Prefer pattern matching and switch expressions

Enforce framework-specific best practices:

---
description: 'Angular development standards'
applyTo: '**/*.ts, **/*.html'
---

# Angular Development

## Component Structure
- Use OnPush change detection by default
- Implement OnDestroy and unsubscribe from observables
- Use standalone components with provideHttpClient

## State Management
- Use signals for reactive state
- Avoid nested subscriptions

Embed security and quality checks:

---
description: 'Security best practices'
applyTo: '**/*.js, **/*.ts, **/*.py'
---

# Security Standards

## Input Validation
- Always validate and sanitize user input
- Use parameterized queries to prevent SQL injection
- Validate file uploads (type, size, content)

## Authentication
- Never store passwords in plain text
- Use bcrypt with salt for password hashing
- Implement rate limiting for auth endpoints

Document your unique project conventions:

---
description: 'Project API conventions'
applyTo: 'src/api/**/*.ts'
---

# API Development Standards

## Error Handling
- Use AppError class for all errors
- Return standard error format: { code, message, details }
- Log errors with correlation IDs

## Response Format
- All responses use { success, data, error } structure
- Include pagination metadata for list endpoints

Real Examples from the Repository

Here are popular instructions from awesome-copilot:

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

# C# Development

- Always use the latest C# version (C# 14)
- Follow PascalCase for public members, camelCase for private
- Prefix interfaces with "I"
- Use file-scoped namespaces
- Trust null annotations - don't add null checks unnecessarily

Organizing Multiple Instructions

For projects with many instructions:

Single File Approach

Combine all instructions in .github/copilot-instructions.md:

# TypeScript Standards
Apply to: **/*.ts

[TypeScript rules here]

---

# React Standards
Apply to: **/*.tsx

[React rules here]

Pros: Simple, one file to manage
Cons: Can become large, harder to maintain

Multi-File Approach (Recommended)

Create separate files in .github/instructions/:

.github/instructions/
  ├── typescript.instructions.md
  ├── react.instructions.md
  ├── testing.instructions.md
  └── security.instructions.md

Pros: Organized, easier to maintain, reusable
Cons: Multiple files to track

Best Practices

Keep Instructions Focused

Create separate instruction files for different concerns
Use specific applyTo patterns to avoid conflicts
Keep instructions concise and actionable
Avoid duplicating framework documentation

Make Instructions Actionable

Good:

- Use PascalCase for class names
- Implement IDisposable for unmanaged resources

Bad:

- Write good code
- Follow best practices

Version-Specific Guidance

When referencing frameworks, specify versions:

## React 18+ Features
- Use Suspense for data fetching
- Implement useTransition for non-urgent updates
- Use useId for unique IDs in SSR

Creating Your Own Instructions

To create custom instructions for your team:

Identify patterns

Review your codebase and identify common patterns, conventions, and frequently violated rules.

Create instruction file

Create a new .instructions.md file with proper frontmatter:

---
description: 'Your team standards'
applyTo: '**/*.ext'
---

# Standards
[Your rules here]

Test and iterate

Test with Copilot, refine based on results, and share with your team.

Troubleshooting

Instructions not applying

Verify file is in .github/instructions/ or .github/copilot-instructions.md
Check applyTo pattern matches your files
Ensure frontmatter YAML is valid
Reload VS Code window

Conflicting instructions

More specific applyTo patterns take precedence
Later instructions override earlier ones
Consider combining related instructions

Browse All Instructions
Custom Agents - Specialized AI personas
Agent Skills - Self-contained capabilities
Contributing Guide

Overview

Installation

Usage

Using Custom Instructions

Using Custom Instructions

What are Custom Instructions?

Installing Custom Instructions

Instruction File Structure

File Pattern Matching

How Instructions Apply

Common Instruction Patterns

Real Examples from the Repository

Organizing Multiple Instructions

Best Practices

Creating Your Own Instructions

Troubleshooting

Build docs developers (and LLMs) love

Overview

Installation

Usage

​Using Custom Instructions

​What are Custom Instructions?

​Installing Custom Instructions

​Instruction File Structure

​File Pattern Matching

​How Instructions Apply

​Common Instruction Patterns

​Real Examples from the Repository

​Organizing Multiple Instructions

​Best Practices

​Creating Your Own Instructions

​Troubleshooting

​Related Resources

Build docs developers (and LLMs) love

Using Custom Instructions

What are Custom Instructions?

Installing Custom Instructions

Instruction File Structure

File Pattern Matching

How Instructions Apply

Common Instruction Patterns

Real Examples from the Repository

Organizing Multiple Instructions

Best Practices

Creating Your Own Instructions

Troubleshooting

Related Resources