GitHub Copilot Custom Instructions: Generate copilot-instructions.md From Your Stack

What GitHub Copilot Custom Instructions Do

GitHub Copilot custom instructions are coding standards you write into .github/copilot-instructions.md so Copilot follows your project's rules across chat, completions, and code review. It's a markdown file at the repo root, version-controlled, and read as standing context on every request. Get it right and Copilot stops suggesting requests when your codebase standardized on httpx.

GitHub's own 5 tips for writing better custom instructions and the repository custom instructions docs tell you what to include: a project overview, the tech stack, coding guidelines, structure. Solid advice. None of it produces the filled file for you. You read the tips, then go type two pages from scratch.

Why Hand-Written Copilot Instructions Underperform

Most instruction files fail in one of two directions. They're too thin: a project name and "write clean code," which tells Copilot nothing it didn't already assume. Or they're a wall of prose, paragraph after paragraph the model half-absorbs.

GitHub's guidance is specific about format: short imperative directives, distinct headings, bullets for scanning. The reason is mechanical. Copilot weights structured, scannable instructions more reliably than narrative. "Use async/await, never .then() chains" lands. "We generally prefer modern asynchronous patterns where appropriate" doesn't. And size matters. Keep a single file to roughly two pages, because past about 1,000 lines response quality drops off.

The Section Contract a Generator Fills

A generator prompt that reads your stack can produce the file GitHub's tips describe, against a fixed skeleton:

• Project overview. Two lines: what the app is, who it's for. Enough to anchor Copilot's assumptions.
• Tech stack. Backend, frontend, APIs, testing framework, named, with versions where behavior depends on them.
• Coding guidelines. The rules reviewers enforce, as imperatives. Type hints, error handling, import order.
• Project structure. Where handlers live, where shared code lives, what's generated.
• Resources. The scripts and MCP servers Copilot can lean on.
• Path-scoped plan. A list of .instructions.md files to add, each with its applyTo glob, so the repo-wide file stays short.

That last item is what separates a generated plan from a single dumped file. It tells you what to split out.

What Copilot Actually Does With Your Instructions

It helps to know how Copilot reads the file, because it changes what you write. The instructions don't replace Copilot's training; they bias it. A line like "use zod for runtime validation" doesn't force the choice, but it tips the model toward zod over the half-dozen alternatives it knows equally well. The more specific the line, the stronger the tip.

That's why vague instructions underperform measurably. "Write secure code" matches nothing concrete in the model's behavior, so it changes little. "Never interpolate user input into SQL strings; use parameterized queries" maps to a pattern the model recognizes and can apply. The first reads like a value statement. The second reads like a rule with a checkable shape.

Versions matter for the same reason. "Use React" is weaker than "React 19, function components, the use hook for promises," because the model's behavior for React 18 and React 19 differs, and naming the version steers it to the right one. When a convention depends on a major version, say the version. Copilot can't infer it from a dependency file it isn't always shown, and guessing wrong is exactly the failure custom instructions exist to prevent.

How to Generate Your Copilot Instructions, Step by Step

1. Gather stack facts

Pull the real dependencies from your manifest, the test command, the folder layout, and the three conventions reviewers reject most.

2. Fill the variables

The prompt takes {{stack_facts}} (the raw dump) and {{conventions}} (the rules you actually enforce). It maps them into the section contract above.

3. Run it and review

You get a scannable repo-wide file plus a suggested set of path-scoped rules. Read both. Cut anything Copilot would infer anyway.

4. Commit and iterate

Treat it as a living document. When a review keeps catching the same thing, that's a new line, usually a path-scoped one.

One Opinion: Path-Scoped Rules Beat a Bigger Root File

Here's a stance most teams learn the slow way. When Copilot misses a language-specific convention, the reflex is to add another bullet to copilot-instructions.md. Resist it. A repo-wide file that's grown frontend rules, backend rules, and test rules is a file where every request pays for context it doesn't need, and where the relevant rule is buried among twenty that don't apply.

Push specifics into path-scoped .instructions.md files instead. Your TypeScript rules load on .tsx, your Python rules on .py, and the root file stays at the two-page sweet spot. It's the same principle that governs a good CLAUDE.md memory file: lean always-on context, detail loaded on demand.

Variables You'll Set

Getting Started

1. List your stack from the dependency manifest.
2. Write down the conventions reviewers actually catch.
3. Feed {{stack_facts}} and {{conventions}} to a generator prompt with a fixed section contract.
4. Take the repo-wide file plus the path-scoped plan it proposes.
5. Commit both, and add to the path-scoped files as reviews surface new rules.

Because Copilot, Cursor, and Claude all read variations of the same instruction format, the AGENTS.md Generator for Polyglot Monorepos produces the source-of-truth file once and you adapt it per tool. For the review rules specifically, the Code Review Policy System Prompt gives Copilot's code-review instructions a severity-rated contract.

Why the contract matters for code review

Copilot can use custom instructions during code review, not just completions. A vague instructions file produces vague reviews. A contract-locked one (the kind that says "flag every unhandled promise rejection as high severity, every missing type annotation as low") produces reviews you can triage. The specificity that helps completions helps reviews more, because review output is something a human acts on line by line. A reviewer who gets a severity-tagged list can jump to the high items first; a reviewer who gets "looks mostly fine, a few nits" has to re-read the diff anyway, which defeats the point of asking Copilot to review it.

Custom instructions are the cheapest way to make Copilot fit your codebase instead of the average one it trained on. Generate the file, scope the specifics, keep the root lean. For the equivalent move in Cursor, read how to write .cursorrules that actually work, and for the canonical cross-tool config, how to write an AGENTS.md file with AI.