How to Create Custom GitHub Copilot Instructions by File Pattern in 2025

GitHub Copilot's customization capabilities have evolved significantly, and one of the most powerful features for teams is the ability to create custom instructions that apply automatically based on file patterns. Instead of manually configuring Copilot for each file type, you can define coding standards, naming conventions, and best practices that activate automatically.

This guide walks you through creating and deploying file pattern-based instructions in your GitHub Copilot setup.

What Are File Pattern Instructions?

File pattern instructions are coding standards and guidelines that GitHub Copilot applies automatically when you open or work with files matching specific patterns. For example:

• *.tsx files get React-specific best practices
• *.test.ts files get testing framework conventions
• docs/** files get documentation formatting rules
• src/api/** files get API endpoint standards

Instead of repeating instructions for every file, you define them once and Copilot enforces consistency across your entire codebase.

Understanding the Instruction Structure

GitHub Copilot instructions are YAML-based configurations stored in your .copilot directory or project settings. The basic structure looks like this:

name: "React Component Standards"
pattern: "src/components/**/*.tsx"
description: "Enforce React best practices for component files"
instructions: |
  - Use functional components with hooks
  - Keep components under 200 lines
  - Export components as named exports
  - Use TypeScript strict mode
  - Add JSDoc comments for props

Each instruction file targets specific file patterns using glob syntax, making it easy to apply different standards to different parts of your codebase.

Step-by-Step Setup Guide

Step 1: Create Your Instructions Directory

First, create a .copilot/instructions directory in your repository root:

mkdir -p .copilot/instructions

This directory will contain all your custom instruction files. GitHub Copilot looks for this standard location automatically.

Step 2: Define Instructions by File Pattern

Create a new YAML file for each set of related patterns. For example, create react-components.yaml:

name: "React Component Guidelines"
patterns:
  - "src/components/**/*.tsx"
  - "src/components/**/*.jsx"

instructions: |
  Follow these React component patterns:

  1. Use functional components exclusively
  2. Export as named exports: export function ComponentName() {}
  3. Place prop interfaces above the component:
     interface ComponentProps {
       title: string;
       onClose?: () => void;
     }
  4. Keep components focused - max 150 lines of JSX
  5. Use custom hooks for shared logic
  6. Add error boundaries for error handling
  7. Memoize callbacks with useCallback for event handlers
  8. Document complex prop relationships with comments

Create another file for API routes (api-endpoints.yaml):

name: "API Endpoint Standards"
patterns:
  - "src/api/**/*.ts"
  - "src/pages/api/**/*.ts"

instructions: |
  API endpoints must follow:

  1. Include proper HTTP method guards (GET, POST, etc.)
  2. Validate all input with Zod or io-ts
  3. Return consistent response format:
     { success: boolean, data?: any, error?: string }
  4. Include proper error handling with try-catch
  5. Add rate limiting for public endpoints
  6. Document with JSDoc including status codes
  7. Use environment variables for configuration

Step 3: Add Test File Conventions

Create testing-standards.yaml for your test files:

name: "Testing Standards"
patterns:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"

instructions: |
  Test files must follow:

  1. Use describe blocks to organize related tests
  2. Use clear test names describing the behavior: "should return error when input is invalid"
  3. Follow AAA pattern: Arrange, Act, Assert
  4. Keep tests under 30 lines when possible
  5. Mock external dependencies
  6. Test error cases, not just happy paths
  7. Use beforeEach for common setup
  8. Avoid test interdependencies

Step 4: Configure Instructions in Copilot Settings

If using GitHub Copilot in VS Code, create or update .copilot/copilot.json:

{
  "instructionsPath": ".copilot/instructions",
  "autoApplyPatterns": true,
  "ignorePatterns": [
    "node_modules/**",
    "dist/**",
    ".git/**"
  ],
  "enableFilePatternMatching": true
}

Pattern Matching Syntax Reference

| Pattern | Matches | Example | |---------|---------|----------| | **/*.tsx | All TypeScript React files | src/components/Button.tsx | | src/components/** | All files in components directory | src/components/index.ts | | src/api/[name]/route.ts | Next.js API routes | src/api/users/route.ts | | src/**/*.{ts,tsx} | TypeScript files in src | src/utils/helpers.ts | | **/*.test.ts | All test files with .test | __tests__/utils.test.ts | | !src/generated/** | Exclude generated files | Excludes src/generated/ |

Best Practices for File Pattern Instructions

1. Keep Instructions Specific and Actionable Instead of vague guidance, provide concrete examples:

❌ Bad: "Write clean code" ✅ Good: "Use const for variables that don't change, let for loop counters"

2. Avoid Overlapping Patterns If two instruction files match the same file, conflicts can occur. Use specific patterns:

# Good: Specific pattern
patterns:
  - "src/components/ui/**/*.tsx"

# Avoid: Too broad
patterns:
  - "**/*.tsx"

3. Test Instructions with Real Files After adding instructions, open a matching file in your editor and verify Copilot applies the guidelines.

4. Use Team Conventions Before creating instructions, align with your team on standards. Document them in a CONTRIBUTING.md file alongside your instructions.

5. Version Control Your Instructions Commit .copilot/instructions to your repository so all team members receive the same customizations.

Common Patterns by Project Type

Next.js Project Structure

patterns:
  - "src/components/**/*.tsx"
  - "src/app/**/*.tsx"
  - "src/api/**/*.ts"

Django/Python Backend

patterns:
  - "app/**/*.py"
  - "tests/**/*.py"
  - "api/serializers.py"

Full-Stack Monorepo

patterns:
  - "packages/web/**/*.tsx"
  - "packages/api/**/*.ts"
  - "packages/shared/**/*.ts"

Troubleshooting File Pattern Instructions

Patterns not matching:

• Verify glob syntax is correct (test with glob testers)
• Ensure .copilot directory is at repository root
• Restart VS Code to reload configuration

Instructions not applying:

• Check that file matches at least one pattern
• Verify enableFilePatternMatching is true in config
• Copilot may cache patterns; clear cache and restart

Too many instructions firing:

• Review pattern specificity
• Use ignorePatterns for generated or vendor code
• Combine related patterns into single file

Leveraging the Awesome Copilot Collection

The GitHub awesome-copilot repository provides pre-built instruction templates you can reference or adapt. Browse the instructions section for community-contributed patterns matching your stack.

You can also install pre-configured instruction bundles using the Copilot CLI:

copilot plugin install react-best-practices@awesome-copilot

Next Steps

Once you've set up file pattern instructions:

1. Create instructions for your primary file types (components, utils, tests)
2. Share with your team via version control
3. Monitor and refine based on actual Copilot suggestions
4. Layer with skills and agents for advanced workflows
5. Document in your CONTRIBUTING guide so new developers understand conventions

File pattern instructions are the foundation of a well-configured Copilot setup that scales across your entire team's codebase.