What is copilot-instructions.md?
copilot-instructions.md is a Markdown file used to provide GitHub Copilot with repository-wide custom instructions.
The repository-wide file is stored at
.github/copilot-instructions.md.
What is it used for?
Repository custom instructions provide GitHub Copilot with additional context about how to understand, build, test and validate changes in a project.
They can describe things such as:
- Technology stack
- Project architecture
- Coding conventions
- Testing requirements
- Development workflows
- Repository-specific guidelines
copilot-instructions.md example
# GitHub Copilot Instructions ## Project This repository contains a TypeScript web application built with React and Node.js. ## Development Install dependencies: npm install Start development: npm run dev ## Coding Standards - Use TypeScript strict mode - Prefer functional React components - Follow existing project patterns - Keep functions focused - Avoid unnecessary dependencies ## Testing Before completing a change: - Run the relevant unit tests - Add tests for new functionality - Check linting and type errors ## Architecture Frontend code lives in /src Backend services live in /server Tests live in /tests ## Working Guidelines Before implementing a change: 1. Inspect the existing implementation 2. Reuse established patterns 3. Keep the change focused 4. Validate the result
Where does the file go?
my-project/ │ ├── .github/ │ └── copilot-instructions.md │ ├── PROJECT-GOALS.md ├── README.md └── src/
Repository-wide vs path-specific instructions
| File | Scope |
|---|---|
.github/copilot-instructions.md |
Repository-wide instructions |
.github/instructions/NAME.instructions.md |
Instructions associated with matching files or paths |
AGENTS.md |
Agent instructions |
Copilot instructions vs PROJECT-GOALS.md
| File | Purpose |
|---|---|
copilot-instructions.md |
How GitHub Copilot should work within the repository. |
PROJECT-GOALS.md |
What the project should achieve and its boundaries. |
A simple way to think about it:
- PROJECT-GOALS.md: What are we building?
- copilot-instructions.md: How should Copilot work on it?
Different AI coding instruction files
Modern coding agents use several Markdown conventions for project instructions and context.
my-project/ │ ├── README.md ├── PROJECT-GOALS.md ├── AGENTS.md ├── CLAUDE.md ├── GEMINI.md │ ├── .github/ │ └── copilot-instructions.md │ └── src/
Give your coding agent a clear destination.
PROJECT-GOALS.md can document your objectives, requirements and project boundaries separately from tool-specific instructions.
Generate PROJECT-GOALS.md