One File So You Stop Repeating Yourself To Copilot

If you've ever pasted the same "use tabs, not spaces" or "always add error handling" reminder into GitHub Copilot Chat for the third time this week, you already know the problem. Copilot has no memory between chat sessions — every new conversation starts from zero context about how your team actually writes code. The fix isn't a better prompt. It's a file Copilot reads automatically, before it answers anything.

The problem: context that evaporates

Copilot Chat is stateless across sessions. Whatever conventions you typed into yesterday's conversation — your naming scheme, your preferred error handling pattern, "never use any in TypeScript" — are gone the moment you open a new chat. Multiply that by every teammate who uses Copilot on the same repo, and you get a team silently drifting: each person re-explains a slightly different version of "how we do things here," and Copilot's suggestions vary depending on who happened to type what into chat that day.

The fix: repository custom instructions

GitHub Copilot supports a repository-wide instructions file that it loads automatically, in every chat, for every contributor. Create it at:

.github/copilot-instructions.md

The filename and path are exact — Copilot looks for this specific file, in this specific location, in Markdown format. Anything you put there — architectural conventions, testing requirements, preferred libraries, style rules — gets folded into Copilot's context before it generates a response. No copy-paste, no re-explaining, no drift between teammates: everyone inheriting the same repo inherits the same rules.

Per GitHub's docs, the instructions "must not be task specific" and should stay under roughly two pages — this is a place for durable conventions ("we use dependency injection for all services"), not one-off task instructions ("fix the bug in checkout.js").

How to create it

You have two paths:

1. Write it by hand. Create .github/copilot-instructions.md in your repo root and list your conventions as plain Markdown bullets or sections — no special syntax required for the repo-wide file.
2. Let Copilot draft it for you. In Copilot Chat, click the gear icon and choose "Generate agent instructions." Copilot scans your repository and drafts a starting file, and it's smart enough to check for instructions you may have already written for other tools — it looks for an existing AGENTS.md, CLAUDE.md, GEMINI.md, or a Windsurf rules file and folds relevant content in rather than starting from nothing. Review and edit what it generates; treat it as a first draft, not a final answer.

Scoping rules to specific files

Not every convention applies everywhere. Your PowerShell scripts need different formatting rules than your test files, and neither should pollute the other's context. For that, Copilot supports path-specific instructions files, stored under .github/instructions/ and named NAME.instructions.md. Each one opens with YAML frontmatter declaring which files it applies to:

---
applyTo: "**/*.ps1"
---

The applyTo value is a glob pattern — **/*.ps1 matches PowerShell files anywhere in the repo, src/**/*.py scopes to Python files under src/. You can also target multiple patterns in one file with a comma-separated list, e.g. "**/*.ts,**/*.tsx". GitHub's docs also document an optional excludeAgent key to keep a given instructions file out of specific tools (for example a code-review agent or a cloud agent), if you need instructions that shouldn't apply universally.

Precedence when rules conflict

When a path-specific file and the repo-wide file both apply to the same file — say you're editing a .ps1 script and both copilot-instructions.md and powershell.instructions.md are in scope — Copilot uses both, and the more specific instructions win on conflicts. GitHub documents the broader priority order as: personal instructions (your own, if configured) first, then repository instructions, then organization-level instructions last. Practically, that means your scoped .instructions.md files are a safe place to carve out exceptions to a global rule without having to rewrite the global file.

Pitfalls to avoid

• Don't dump your entire style guide in. Every line in copilot-instructions.md consumes context on every single chat interaction. A bloated file drowns out the specific question you're actually asking. Keep it to the conventions that actually change Copilot's output, not general engineering wisdom.
• Don't make it task-specific. GitHub explicitly discourages instructions like "when I ask X, do Y" in the repo-wide file — that belongs in a prompt, not in standing instructions.
• Remember it's markdown, not magic. Copilot follows these instructions as strong guidance, not a hard constraint — you'll still want to spot-check suggestions, especially early on while you're tuning the file.
• Keep path-specific files narrow. A glob pattern that's too broad (**/*) defeats the purpose of scoping — you end up back at one global file, just split across multiple locations.

Takeaway

One markdown file, one location, read automatically by every chat: that's the entire mechanism. Write .github/copilot-instructions.md by hand or generate a draft with the gear menu, then layer .github/instructions/*.instructions.md files with applyTo globs for anything that shouldn't apply repo-wide. Do it once, and every future Copilot conversation on that repo starts already knowing how your team works.

Resources

• GitHub Docs — Add repository custom instructions for GitHub Copilot