What Is copilot-instructions.md?
GitHub Copilot's project rules file, and how to write one

What copilot-instructions.md actually is

• In one line: a "project briefing" you write ahead of time for GitHub Copilot. It reads this before it works and tries to follow your project's rules.
• Format: plain text plus Markdown syntax, with the .md extension — written the same way as a README.
• Location: by convention it goes in the .github/ folder in your repo root, and the filename is literally copilot-instructions.md.
• How it differs from typing in chat: what you type in chat applies that one time; rules written into this file are "standing notes" it reads every time, so you don't have to repeat yourself.

Where it goes, and how it takes effect

Putting it in the right place is the prerequisite. The convention is .github/copilot-instructions.md in your repo root. In supported Copilot environments (like VS Code's Copilot Chat), it's read automatically as project-level instructions.

Whether you need to enable it in your editor's settings, and the exact read behavior, depend on GitHub's and your editor's official docs — this area changes fast, so don't place it on a hunch. Wrong folder or wrong filename, and it's just for show.

What usually goes inside

No need for an essay — cover the project across a few areas and that's plenty:

The trick: write specific conventions that are easy to get wrong, like "state via Zustand, don't introduce Redux" or "comments in English" — far more useful than a vague "keep the code clean."

How to write it: a good-enough example

A first version that clearly covers "what the project is, what to follow, and what not to touch" is plenty. Here's what good-enough looks like:

# Copilot project instructions

## What this project is
A React + TypeScript front-end, built with Vite.

## Coding conventions
- Function components + Hooks, no class components
- State via Zustand, don't introduce Redux
- Styles in CSS Modules, named xxx.module.css

## What not to do
- Don't change config under src/config/
- Don't hard-code API URLs in components, go through src/api/

## Output preferences
- Comments in English
- One line per change explaining what changed

A few key points:

• Use plain language, don't pile on jargon.
• Keep it short — ideally readable within a screen or two; too long and both Copilot and you will skip it.
• Write conventions you can verify, so it's easy to check afterward whether it followed them.
• To get symbols like #, -, and code blocks right, see How to Write Markdown.

How it differs from CLAUDE.md and AGENTS.md

They do similar jobs — project rules written for AI coding tools — differing mainly in filename and where they go. Always defer to the official docs of the tool you're actually using, since this area changes fast.

Write the one that matches the tool you use. For managing a whole pile of them, see How to Manage Your AI Coding Rule Files.

Open this local copilot-instructions.md with NoteLoom

Whether this file was generated by an AI or written by you, once it lands on your disk it's just a local .md. NoteLoom is an editor that reads and writes local md files right in the browser, which makes it a good fit for opening, reading, and editing it.

Let's be clear about the boundaries up front: NoteLoom has no AI whatsoever, and it doesn't integrate with GitHub Copilot, Claude Code, Cursor, or git. It won't write rules for you, won't generate or summarize, and can't make Copilot "listen to you better." All it does is let you open this file, read it clearly, edit it, and save it back to your disk.

It gives you three views for reading the same file:

Here's roughly how you use it:

1. Open app.noteloom.cc in Chrome, Edge, or Arc.
2. Select your repo's .github folder (NoteLoom has to mount a folder before it can read or write, and it skips dot-folders when you mount a parent, so point it straight at .github).
3. Open copilot-instructions.md from the file tree.
4. Use the reading view to see the formatting first; switch to live or source to edit.
5. When you're done, it writes straight back to the original local file — no account involved, nothing goes to the cloud.

Common pitfalls

• Wrong folder or filename: not in .github/, or the wrong name, and Copilot simply can't read it. Place it per the official docs.
• Writing it too long and exhaustive: a rules file of hundreds of lines is one neither Copilot nor you will bother reading. Keep the few most important, most error-prone points.
• Assuming it forces Copilot to obey: it's a strong suggestion, not a hard lock — review the important changes yourself.
• Opening it in Notepad shows a pile of # and -: that's just unrendered text, not a broken file. Switch to an editor that displays Markdown formatting.
• Expecting NoteLoom to understand or execute it: it won't. NoteLoom only opens, reads, edits, and saves this local file — it doesn't connect to any AI tool and doesn't run the rules inside.