GitHub Copilot Instructions: Complete Guide to copilot-instructions.md

GitHub Copilot custom instructions let you shape how Copilot generates code, answers questions, and reviews pull requests across your entire repository. The key to this is a single file: .github/copilot-instructions.md. This guide covers everything you need to know about writing effective copilot instructions -- from basic syntax to advanced patterns for different frameworks.

If you've used Cursor rules or CLAUDE.md, you already understand the concept. Copilot instructions are GitHub's equivalent: a way to give your AI assistant persistent, project-specific context.

What Is copilot-instructions.md?

The copilot-instructions.md file is a Markdown document that provides custom instructions to GitHub Copilot. When present in your repository, Copilot automatically reads it and applies the instructions to every interaction -- inline code completions, Copilot Chat responses, pull request reviews, and Copilot Workspace sessions.

Think of it as onboarding documentation for your AI pair programmer. Instead of repeatedly telling Copilot "we use TypeScript strict mode" or "always handle errors with our custom Result type," you write it once in copilot-instructions.md and it applies everywhere.

Key characteristics

• Automatic loading -- Copilot reads the file without any configuration or opt-in
• Plain Markdown -- no special syntax, YAML frontmatter, or schema required
• Repository-scoped -- instructions apply to everyone using Copilot on that repo
• Works across surfaces -- editor completions, Chat, PR reviews, and Workspace
• Version controlled -- lives in your repo, reviewed in PRs like any other code

File Location

The copilot-instructions.md file must be placed at a specific path in your repository:

your-project/
  .github/
    copilot-instructions.md    ← GitHub Copilot custom instructions
    workflows/
    ISSUE_TEMPLATE/
  src/
  package.json

The path is always .github/copilot-instructions.md at the root of your repository. This follows the established GitHub convention of storing repository configuration in the .github directory alongside Actions workflows, issue templates, and funding files.

Syntax and Structure

The copilot-instructions.md file uses standard Markdown. There is no required schema or frontmatter -- just write natural language instructions organized with headings, lists, and code blocks.

Basic structure

# Copilot Instructions

## Project Overview
Brief description of the project, its purpose, and tech stack.

## Code Style
- Use consistent naming conventions
- Prefer specific patterns over others
- Follow established project conventions

## Architecture
Describe how the codebase is organized and key architectural decisions.

## Testing
How tests should be written, what framework to use, coverage expectations.

## Things to Avoid
Patterns, libraries, or approaches that should not be used.

Writing effective instructions

The best GitHub Copilot custom instructions are specific, actionable, and concise. Here are the principles that make instructions effective:

• Be explicit -- "Use named exports" is better than "follow good export practices"
• Show, don't just tell -- include short code examples for complex patterns
• Prioritize -- put the most important instructions first; Copilot weighs earlier content more heavily
• Stay current -- update instructions when your conventions change
• Keep it focused -- aim for under 200 lines; overly long instructions dilute the important parts

Example Instruction Files

Here are complete copilot-instructions.md examples for popular frameworks. Use these as starting points and customize for your project. You can also browse ready-made instructions in the Skills library and test them in the Playground.

React + TypeScript

# Copilot Instructions

## Stack
React 19, TypeScript 5.5, Vite, TanStack Query, Tailwind CSS 4.

## Code Style
- Use functional components with arrow functions
- Prefer named exports over default exports
- Use TypeScript strict mode -- no `any` types
- Colocate component files: Component.tsx, Component.test.tsx, Component.module.css

## Patterns
- State management: use React context + useReducer for app state, TanStack Query for server state
- Forms: use react-hook-form with zod validation schemas
- API calls: always go through the api/ layer, never fetch directly in components
- Error boundaries: wrap route-level components with ErrorBoundary

## Naming
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Types: PascalCase with no prefix (User, not IUser or TUser)

## Testing
- Use Vitest + Testing Library
- Test behavior, not implementation
- Every component needs at least a render test

Python + FastAPI

# Copilot Instructions

## Stack
Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2, PostgreSQL.

## Code Style
- Follow PEP 8 with 88-char line length (Black formatter)
- Use type hints everywhere -- no untyped function signatures
- Prefer dataclasses or Pydantic models over plain dicts
- Use pathlib.Path instead of os.path

## Architecture
- app/api/routes/ - Route handlers (thin, delegate to services)
- app/services/ - Business logic
- app/models/ - SQLAlchemy models
- app/schemas/ - Pydantic request/response schemas
- app/core/ - Config, security, dependencies

## Patterns
- Dependency injection via FastAPI Depends()
- All DB operations go through async sessions
- Return Pydantic models from routes, never raw dicts
- Use HTTPException for error responses with detail messages

## Testing
- Use pytest with pytest-asyncio
- Fixtures in conftest.py, one per directory level
- Test API endpoints with httpx AsyncClient

Next.js App Router

# Copilot Instructions

## Stack
Next.js 15 (App Router), TypeScript, Prisma, NextAuth v5, Tailwind CSS.

## Architecture
- app/ - App Router pages and layouts
- app/api/ - Route handlers
- lib/ - Shared utilities, DB client, auth config
- components/ - Reusable UI components (client and server)
- Server components by default; add "use client" only when needed

## Patterns
- Data fetching: use server components with async/await, not useEffect
- Mutations: use server actions with "use server"
- Auth: check session in middleware.ts and server components
- Database: always use Prisma client from lib/db.ts

## Conventions
- File naming: kebab-case for routes, PascalCase for components
- Use next/image for all images
- Use next/link for all internal navigation
- Metadata: export metadata object from each page.tsx

## Avoid
- Do not use the Pages Router -- this project uses App Router exclusively
- Do not use getServerSideProps or getStaticProps
- Do not install axios -- use native fetch

Go + Chi Router

# Copilot Instructions

## Stack
Go 1.22, Chi router, pgx (PostgreSQL), sqlc for queries, slog for logging.

## Code Style
- Follow Effective Go and Go Code Review Comments
- Use table-driven tests
- Error wrapping: fmt.Errorf("functionName: %w", err)
- No naked returns

## Project Structure
- cmd/ - Entry points (cmd/api/main.go)
- internal/ - Private application code
- internal/handler/ - HTTP handlers
- internal/service/ - Business logic
- internal/repository/ - Database layer (sqlc generated)
- internal/middleware/ - HTTP middleware

## Patterns
- Handlers accept (w http.ResponseWriter, r *http.Request)
- Use context.Context for cancellation and request-scoped values
- Dependency injection via struct fields, not globals
- JSON responses with a respond() helper, not manual encoding

## Avoid
- Do not use global variables or init() functions
- Do not use panic for error handling
- Do not use external ORM libraries -- use sqlc

Rust + Axum

# Copilot Instructions

## Stack
Rust (stable), Axum 0.8, SQLx, Tokio, Serde.

## Code Style
- Run clippy with all warnings as errors
- Use thiserror for library errors, anyhow for application errors
- Prefer &str over String in function parameters when possible
- Use #[derive] for common traits: Debug, Clone, Serialize, Deserialize

## Architecture
- src/routes/ - Axum route handlers
- src/models/ - Database models and domain types
- src/services/ - Business logic
- src/error.rs - Unified error type with IntoResponse

## Patterns
- Extract shared state with Axum's State extractor
- Use tower middleware for auth, logging, CORS
- Database queries with sqlx::query_as! macro for compile-time checking
- Return Result<Json<T>, AppError> from all handlers

## Testing
- Use #[tokio::test] for async tests
- Integration tests in tests/ directory with test database
- Use testcontainers for database setup

Laravel + PHP

# Copilot Instructions

## Stack
PHP 8.3, Laravel 11, Livewire 3, Filament for admin, MySQL 8.

## Code Style
- Follow PSR-12 coding standard
- Use PHP 8.3 features: typed properties, enums, match expressions, readonly classes
- Strict types in every file: declare(strict_types=1)

## Architecture
- Follow Laravel conventions for directory structure
- Form Requests for validation (never validate in controllers)
- Actions pattern for complex business logic (app/Actions/)
- Eloquent for database, no raw queries except in performance-critical paths

## Patterns
- Use route model binding for resource routes
- Queue heavy operations with Laravel jobs
- Events and listeners for side effects (email, notifications)
- Use Laravel's built-in auth scaffolding, not custom auth

## Avoid
- Do not use DB facade for queries -- use Eloquent models
- Do not put business logic in controllers -- extract to Actions
- Do not use env() outside of config files

Comparison: Instruction Files Across AI Editors

Every major AI coding tool has its own version of project-level instructions. Here's how copilot-instructions.md compares to CLAUDE.md, .cursorrules, and .windsurfrules.

Converting Between Formats

Because all four major instruction file formats use Markdown (or plain text that is effectively Markdown), converting between them is straightforward. The core content -- coding conventions, architecture descriptions, patterns, and rules -- transfers directly.

From .cursorrules to copilot-instructions.md

1. Copy the contents of your .cursorrules file
2. Create .github/copilot-instructions.md and paste
3. Remove any Cursor-specific references (e.g., "when using Cursor Chat")
4. Add Markdown headings if the original used flat text

From CLAUDE.md to copilot-instructions.md

1. Copy the relevant sections from your CLAUDE.md
2. Remove Claude Code-specific directives (hooks config, slash commands, skill references)
3. Keep project overview, conventions, patterns, and avoidance rules
4. Save as .github/copilot-instructions.md

From copilot-instructions.md to other formats

The reverse is equally simple. Copy the content and place it in the target file location. For Claude Code, you may want to add build/test commands and hook configuration. For Cursor, add any rule-specific metadata if using the .cursor/rules/ directory format.

You can also use the Skills Playground to preview how your instructions will look across different formats, or browse the Skills library for pre-built instruction sets you can adapt.

Copilot Instructions vs Extensions vs Custom Agents

GitHub's Copilot ecosystem includes several ways to customize behavior. Understanding which to use when is important:

copilot-instructions.md (passive context)

Always-on instructions that shape every Copilot interaction. Use this for coding conventions, project structure, patterns, and rules. No setup beyond creating the file. This is where most teams should start.

Copilot Extensions (active tools)

Extensions add new capabilities to Copilot Chat via @mentions. For example, @sentry can look up error details, or @docker can help with container configuration. Extensions call external APIs and return results to Copilot. Use these when you need Copilot to interact with external services.

Custom Copilot agents

Agents are a more advanced form of extension that can maintain state, execute multi-step workflows, and take autonomous actions. They are invoked in Copilot Chat and can perform tasks like creating issues, running deployments, or orchestrating complex changes. These are similar in concept to MCP servers in the Claude Code ecosystem.

Best Practices

1. Keep instructions under 200 lines

Copilot's context window is limited. Lengthy instruction files dilute the most important rules. Focus on conventions that differ from common defaults -- you don't need to tell Copilot to "write clean code."

2. Use concrete examples over abstract rules

Instead of "follow good error handling practices," show a short code example of how your project handles errors. Copilot responds better to patterns it can match than to abstract guidelines.

3. Update instructions in PRs

Treat your copilot-instructions.md like code. When you change conventions -- adopting a new library, deprecating a pattern, restructuring directories -- update the instructions in the same PR. This keeps the instructions in sync and makes the change reviewable.

4. Structure with clear headings

Use Markdown headings (##) to organize sections. This helps both Copilot parse the document and human developers skim it. Recommended sections: Project Overview, Code Style, Architecture, Patterns, Testing, and Things to Avoid.

5. Include "avoid" rules

Explicitly stating what not to do is often more valuable than stating what to do. If you've migrated away from a library or pattern, add it to an Avoid section so Copilot doesn't suggest the old approach.

6. Coordinate with your team

Since copilot-instructions.md affects everyone on the repo, discuss changes with your team. A good practice is to require PR reviews for instruction file changes, just like you would for CI configuration. For a deeper look at team AI coding workflows, see the best practices guide.

7. Layer organization + repo instructions

Use organization-level instructions (in your org's .github repo) for company-wide standards like security practices, licensing headers, and shared libraries. Use repo-level instructions for project-specific details like architecture and framework patterns.

8. Test your instructions

After writing or updating instructions, test them by asking Copilot to generate code that should follow the new rules. Try the Playground to iterate quickly. If Copilot doesn't follow an instruction, it may be too vague or buried under too many other rules.

Troubleshooting

Copilot ignores my instructions

• Verify the file is at .github/copilot-instructions.md (exact path and filename)
• Check that the file is committed to the branch you're working on
• Keep instructions concise -- if the file is too long, Copilot may truncate it
• Move your most critical instructions to the top of the file

Instructions conflict with each other

If organization-level and repo-level instructions conflict, repo-level instructions generally take precedence. Within a single file, later instructions may override earlier ones if they contradict. Be explicit and avoid ambiguity.

Instructions are too specific for some files

Unlike CLAUDE.md which supports directory-level files, copilot-instructions.md is repository-wide. If you need different instructions for different parts of your codebase, use conditional language: "In the frontend/ directory, use React conventions. In the api/ directory, follow Express patterns."

Getting Started

Creating your first copilot-instructions.md takes about 10 minutes. Here's a quick-start template:

# Copilot Instructions

## Project
[One-line description of what this project does and its tech stack]

## Architecture
[2-3 lines about how the codebase is organized]

## Conventions
- [Your most important coding convention]
- [Second most important]
- [Third most important]

## Testing
- [Test framework and how to run tests]
- [What to test and testing patterns]

## Avoid
- [Pattern or library to avoid]
- [Common mistake to prevent]

Create this file at .github/copilot-instructions.md, commit it, and start using Copilot. Iterate on the instructions over the following days as you notice areas where Copilot needs more guidance. For inspiration, explore the Skills library for pre-built instruction sets, or check the Claude Code vs Cursor comparison to see how different AI tools approach project customization.