What is copilot-instructions.md?

copilot-instructions.md is a configuration file that provides custom coding standards and rules to GitHub Copilot. It helps Copilot understand your project's conventions and generate more relevant code suggestions.

Where should I place copilot-instructions.md?

Place it at .github/copilot-instructions.md in your repository. Create the .github directory if it doesn't exist. This location ensures Copilot automatically reads your instructions.

Can I have path-specific instructions?

Yes. Create .instructions.md files with an applyTo field in YAML frontmatter to target specific files or directories. For example, applyTo: **/*.py for all Python files.

Do organization-level instructions override repository instructions?

No, personal instructions have highest priority, followed by repository instructions, then organization instructions. All relevant instructions are combined and provided to Copilot.

How do I verify my instructions are being used?

When repository instructions are used, the instructions file appears as a reference in Copilot Chat responses. Expand the references list at the top of a response to verify.

What format should I use for instructions?

Use Markdown format with clear, self-contained statements. Keep instructions short and focused on providing context or relevant information that supplements chat questions.

Can I exclude certain agents from reading my file?

Yes. Use the excludeAgent frontmatter property to prevent specific agents like Copilot code review or coding agent from reading your file.

How does copilot-instructions.md compare to .cursorrules?

Both serve similar purposes but for different tools. copilot-instructions.md is for GitHub Copilot, while .cursorrules is for Cursor IDE. Tools like ClaudeMDEditor can manage both.

GitHub Copilot Configuration

copilot-instructions.md Guide

Name: ClaudeMDEditor
Price: 13.00 USD
Availability: InStock
Author: ClaudeMDEditor

Configure GitHub Copilot with custom instructions. Learn how to set up repository-wide rules, path-specific instructions, and organization standards.

Understanding copilot-instructions.md

copilot-instructions.md is a Markdown file where you define custom coding standards, rules, and best practices that GitHub Copilot should follow across your repository. It helps Copilot generate code that matches your project's conventions and requirements.

With the largest market share among AI coding tools, GitHub Copilot's custom instructions feature gives you control over how Copilot understands your codebase and generates suggestions.

How to Set Up

Create a .github directory in your repository root if it doesn't exist
Create a file named copilot-instructions.md
Add natural language instructions in Markdown format
Commit and push to your repository

copilot-instructions.md Format

The instructions file uses Markdown format. Here's a recommended structure:

.github/copilot-instructions.md

# Project Coding Standards

## Language & Framework
- This is a TypeScript React project using Next.js 14
- Use App Router patterns, not Pages Router
- Target ES2022 JavaScript features

## Code Style
- Use functional components with hooks
- Prefer named exports over default exports
- Use TypeScript strict mode - no 'any' types
- Use arrow functions for component definitions

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with 'use' prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE

## State Management
- Use React Query for server state
- Use Zustand for client state
- Avoid prop drilling beyond 2 levels

## Testing
- Write unit tests for utility functions
- Use React Testing Library for components
- Mock external dependencies

## Documentation
- Add JSDoc comments to exported functions
- Include usage examples in complex utilities

Path-Specific Instructions

For language-specific or directory-specific rules, create .instructions.md files with YAML frontmatter:

.github/python.instructions.md

---
applyTo: "**/*.py"
---

# Python Code Standards

- Use Python 3.11+ features
- Follow PEP 8 style guidelines
- Use type hints for all function parameters and returns
- Use dataclasses or Pydantic for data models
- Prefer pathlib over os.path
- Use f-strings for string formatting
- Write docstrings in Google style format

.github/api.instructions.md

---
applyTo: "src/api/**/*"
---

# API Development Standards

- Use RESTful conventions
- Return proper HTTP status codes
- Validate all input data
- Handle errors gracefully with try/except
- Log all API errors
- Use async/await for database operations

Priority Order

Copilot combines instructions from multiple sources with this priority:

Personal instructions — Highest priority (your individual settings)
Repository instructions — Project-level rules in .github/
Organization instructions — Org-wide standards (enterprise)

All relevant instructions are combined and provided to Copilot. Avoid conflicting instructions across levels.

Best Practices

Keep instructions short and self-contained — Each statement should add context without depending on other statements
Use path-specific files for language rules — Don't mix Python and TypeScript rules in one file
Be specific about versions — Mention framework versions to prevent outdated suggestions
Verify with references — Check that your instructions appear in Copilot Chat references
Update regularly — Keep instructions in sync with project evolution

Frequently Asked Questions

Manage Your copilot-instructions.md Visually

ClaudeMDEditor lets you browse, edit, and organize copilot-instructions.md files across all your projects. Plus it handles CLAUDE.md, .cursorrules, and more.

Claude CodeCursorCopilotWindsurfGeminiCodexAider

Get ClaudeMDEditor — $13

One-time purchase for macOS Tahoe (26+)