Using *instructions.md to encourage GitHub Copilot to behave

Ever wished GitHub Copilot could read your mind (or at least your repository's README)? You're not alone - it's time to turn your AI assistant into a well-behaved coding partner, who actually does what you want.

Say "NO!" to more random changes and weird side paths. Let's learn how to customize Copilot's behavior so it aligns with your project's quirks and keeps the code fresh.

By the end, you'll wonder how you ever coded without these instruction files making Copilot act better (and less like Jar Jar Binks - OR 2 raccoons in a trench coat on meth).

Background

GitHub Copilot has evolved significantly since its initial release. One of the (slightly) more recent additions to its feature set is the ability to use special instruction files to guide Copilot's behavior in your repositories.

And when I say "files", I really do mean a number of files. Many files, even.

More on that in a bit - but let's take a look at the history of trying to guide Copilot first!

History: The evolution of Copilot instructions

The first thing we got was a single file called copilot-instructions.md, which provided global instructions for Copilot in that repository.

Then, we got the ability to create multiple .instructions.md files, which can provide more granular, context-specific guidance to Copilot.

And more recently, support for AGENTS.md file was added, which largely overlaps with the functionality of copilot-instructions.md files, but is targeted specifically at the Copilot coding agent.

How to use these files?

Let's get the basics out of the way first.

What are copilot-instructions.md and *.instructions.md files?

Both of the files are located under the hidden ".github" folder in the root of your repository.

• .github/copilot-instructions.md
  • a single, repository‑level Markdown file intended to provide global custom instructions for Copilot chat and the Copilot coding agent.
• .github/instructions/*.instructions.md
  • modular instruction files you place under .github/instructions
  • you can have many and use YAML frontmatter to limit which files or directories each file applies to, giving per-area guidance to Copilot.

Samples below!

Sample copilot-instructions.md

There are no strict rules on what to put in these files, but here's an example of a copilot-instructions.md file with some general guidance and exact commands for the project.

Especially the exact commands on how to run the project and install dependencies can be very helpful for Copilot to understand the project structure and tooling - by default, it tends to downgrade the project before installing new things like .NET SDK versions - and possibly even happily commit changes without even being able to build the project as the build fails due to missing dependencies.

And of course it'll happily deflect blame by changing the unit tests instead of fixing the issue - and blaming someone else (its earlier commits) for breaking other tests :)

Anyway - here we go with a mildly helpful copilot-instructions.md file:

# Basic project information
- .NET 9 web application using Blazor WebAssembly and ASP.NET Core.
- Uses Entity Framework Core 9 for data access
- Hosted on Azure App Service with Azure SQL Database

# Behavior expectations
- Do not modify the Dockerfiles unless explicitly asked to
- Do not remove Unit Tests unless explicitly asked to

# Exact project commands
- restore: dotnet restore
- build: dotnet build --configuration Release --no-restore
- test: dotnet test --no-build --configuration Release
- format-check: dotnet format --verify-no-changes
- vuln-scan: dotnet list package --vulnerable

# Available scripts
- Use the following command to install .NET 9 SDK: $ curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0

Sample "general" .instructions.md (applies to entire repository)

---
applyTo: '**/backend/**'
---

# Agent behavior (must be followed exactly)

- Before proposing a PR, run the full verification sequence for restore, build, test, format, vulnerability scan, and analyzers. Summarize results in the PR.

- Include a `Verification commands` fenced code block in the PR showing the exact steps you executed (copy‑pasteable), without editing or paraphrasing them.

- If formatting verification fails, either provide exact fix commands and a separate format-only commit, or create a format-only automated commit and reference it in the PR body.

- Add tests for new behavior or regression fixes. Tests must be deterministic and runnable in CI without manual steps.

- Never create, rotate, or commit credentials, keys, or certificates in the repo. 

- For database schema changes:
  - include migration scripts, a backward-compatibility strategy, and an integration test plan;  
  - if changes are not backward-compatible, include a rollout plan and feature-flag instructions.

- Summarize what you ran and why in 3–5 bullets at the top of the PR body and populate the blocking checklist per the repo PR template.

What other instruction files are there?

Admittedly, I have no experience with these ones yet - but I think it's still worth it to document them:

• **/AGENTS.md
  • a single, repository‑level Markdown file intended to provide global custom instructions specifically for the Copilot coding agent.
• /CLAUDE.md
  • a single, repository‑level Markdown file intended to provide instructions only when using the Claude model in GitHub Copilot.
• /GEMINI.md
  • a single, repository‑level Markdown file intended to provide instructions only when using the Gemini model in GitHub Copilot.

Where are these files applied?

Notes

• 1: According to the documentation - but I have no experience with these
• For copilot-instructions.md, you can enable or disable its usage in Copilot Chat settings in the UI (both web and IDE extensions)
• I'll need to continue testing the different markdown files - and update them in the process. I'll report back :)

General guidance

• Order of precedence:
  • Scoped .instructions.md files should contain explicit scope in the YAML frontmatter
  • Use priority to indicate stricter guidance for overlapping scopes
• Keep global rules minimal:
  • Use .github/copilot-instructions.md for broad conventions and guilt-tripping the Coding Agent to try and discourage it from making mistakes
• Keep scoped files focused:
  • Put implementation details, toolchain commands, and package‑specific policies into .github/instructions/*.instructions.md
• Keep all files concise:
  • Avoid overwhelming Copilot with too much information - too much context will likely lead to worse results.
• Don't use GitHub Copilot to generate these files!
  • My experience is that Copilot is not very good at writing these instruction files, or at the very least, it's difficult to have it hit the balance between specificity and conciseness.
  • Consider writing them yourself - or at least reviewing and editing any AI-generated content carefully.

References

• GitHub Blog Changelog: Copilot coding agent now supports AGENTS.md custom instructions (2025-08-28)
• GitHub Docs: Get the best results — Copilot coding agent (Enterprise Cloud)
• 5 tips for writing better custom instructions for Copilot