How to Write Custom Instructions for GitHub Copilot

The short version

Custom instructions are a file in your repository that tells GitHub Copilot how your project works, so you stop repeating yourself in every chat. Write down what a new developer would need on day one: what the project is, how to build and test it, and the rules you care about.

Step by step

1. Create .github/copilot-instructions.md in the root of your repository. Create the .github folder if it doesn’t exist.
2. Write in plain Markdown. GitHub says blank lines and line breaks are ignored, so format for humans.
3. Cover the basics: a short summary of the project, languages and frameworks, the build, test and lint commands (with tool versions), the folder layout, and the checks to run before committing.
4. Use “always” language for required steps, such as “Always run npm install before building.”
5. Keep it short: GitHub’s guidance is no longer than two pages, and not about one specific task.
6. Add path-specific rules if needed. Create NAME.instructions.md files in .github/instructions, with an applyTo glob in the front matter, such as applyTo: "app/models/**/*.rb".
7. Save and test. Instructions take effect as soon as you save. Ask Copilot Chat a question and check the references list for your file.

Prompts to copy

Draft the file with Copilot:

Read this repository and draft a .github/copilot-instructions.md file.
Include: a two-sentence project summary, the exact build, test and lint commands from package.json,
the folder layout, and the rules you can infer from existing code. Under one page.

Find gaps:

Based on the last 10 pull requests, what conventions do we follow that aren't in our instructions file?

A starter file:

# Project
Recipe-sharing website. React 19 + TypeScript front end, Node API in /api.

# Commands
- Install: npm install
- Test: npm test (must pass before any commit)
- Type-check: npx tsc --noEmit

# Rules
- Always add a test for new functions.
- Never commit secrets or .env files.
- Use existing components in src/components before creating new ones.

Example

Before: every chat starts with “We use pnpm, not npm” and Copilot still suggests npm.

After: one line in .github/copilot-instructions.md (“Always use pnpm. Never use npm or yarn.”) and the suggestions follow it. The references list in chat shows the file was used.

Mistakes to avoid

• Writing a novel. Long files bury the rules that matter.
• Conflicting instructions. GitHub says personal instructions come first, then repository, then organization, and all are sent to Copilot, so avoid contradictions.
• Vague rules. “Write clean code” changes nothing. “Functions under 40 lines” does.
• Never updating it. When commands change, update the file.

Good to know

If you use several AI coding tools, one AGENTS.md can serve them all; GitHub Copilot reads the nearest one. Our free AGENTS.md generator builds a starting file, and our guide to writing project rules for AI coding assistants explains what to put in it. Custom instructions are also used for Copilot code review by default; you can change that in the repository’s Settings > Copilot > Code review.

Related: use GitHub Copilot in VS Code.