Maximizing GitHub Copilot with Instruction Files

If you're using GitHub Copilot in Visual Studio Code, you've likely experienced having to repeatedly tell Copilot about your project's coding standards or architecture preferences. It can get tedious to include these details in every prompt. Thankfully, there's a better way: instruction files!

What Are GitHub Copilot Instruction Files?

Instruction files allow you to define coding standards, project requirements, and tech preferences in centralized Markdown files. These instructions are automatically included in every GitHub Copilot interaction, eliminating the need to repeatedly specify the same context.

As shown in the screenshot above, instruction files are typically stored in the .github folder of your repository, with specialized instruction files organized in the .github/instructions subfolder.

There are two primary types of instruction files:

1. .github/copilot-instructions.md: A single file that applies to your entire workspace
2. .github/instructions/*.instructions.md: Multiple specialized instruction files for different contexts

Why Use Instruction Files?

The power of instruction files lies in their ability to be automatically included in your context. This means:

• Consistency: All generated code follows the same standards
• Efficiency: No need to repeat yourself in prompts
• Team Alignment: Everyone uses the same instructions when interacting with Copilot
• Project-Specific Knowledge: Include architecture details specific to your codebase

Setting Up .github/copilot-instructions.md

The simplest way to get started is with a centralized instruction file:

1. Create a .github directory at the root of your project (if it doesn't exist)
2. Create a copilot-instructions.md file inside it
3. Enable the setting in VS Code:
   • Set github.copilot.chat.codeGeneration.useInstructionFiles to true

Here's an example of what your instruction file might contain for an iOS project:

# iOS Project Structure and Architecture

## Project Overview
- This is an iOS app using Swift and SwiftUI
- We follow the MVVM architecture pattern throughout the app

## Project Structure
- /App: Contains app entry point and lifecycle management
- /Features: Organized by feature modules (Auth, Home, Profile, Settings)
- /Services: Network, storage, and other shared services
- /Models: Domain models and data structures
- /Common: Shared components, extensions, and utilities

## Dependencies
- We use Swift Package Manager for dependency management
- SwiftLint is configured for code quality enforcement
- Swift Testing for unit testing

Now Copilot will understand your project context and architecture whenever generating code for your project!

Creating Specialized Instructions

For larger projects, you might want different instructions for different file types or components. This is where .instructions.md files come in.

Create a .github/instructions directory and add specialized instruction files like:

---
applyTo: "**/*.swift"
---

# Swift Coding Standards

## Code Style
- 2 spaces, no tabs
- Maximum line length of 120 characters
- Add blank line after imports and between type definitions

## Swift Best Practices
- Prefer let over var when variable won't change
- Use Swift's type inference where it improves readability
- Avoid force unwrapping (!) of optionals
- Use guard for early returns and unwrapping
- Prefer struct over class for model objects

The applyTo property uses glob patterns to specify which files these instructions apply to. This allows you to have different standards for different file types.

Instruction Files in Action

Let's say you want Copilot to generate a SwiftUI view. Without instruction files, you'd have to specify your coding preferences each time:

Without instructions:

Generate a SwiftUI view for displaying user profile information. 
Follow our coding standards with camelCase for properties, 
PascalCase for type names, use MVVM pattern, extract reusable 
components, add documentation comments, and implement proper 
error handling for API calls.

With instructions:

Generate a SwiftUI view for displaying user profile information.

The second prompt is much simpler, yet Copilot will still follow all your specified standards because it has access to your instruction files!

Tips for Effective Instruction Files

1. Keep instructions short and focused: Each instruction should be a single, simple statement
2. Organize by concern: Create separate instruction files for different aspects
3. Be specific: Clearly define what you want
4. Update regularly: As your project evolves, keep your instruction files current

Additional Resources

Github Copilot Instruction Files