GitHub Copilot Instructions: The Complete Guide

What Copilot custom instructions are

Custom instructions are persistent natural-language rules Copilot reads before it answers, so you don’t have to restate your project’s conventions in every prompt. “We use Vitest, not Jest.” “Never edit files under generated/.” “Use our internal logger, not console.log.” You write these once; Copilot applies them automatically to chat, agent mode, and code review.

There are four distinct scopes, and keeping them straight is the whole game:

The two repo-committed scopes — repository-wide and path-specific — are the ones worth most of your attention, because they ship with the code and apply to the whole team. The rest of this guide focuses there.

Repository-wide: .github/copilot-instructions.md

The foundational file is .github/copilot-instructions.md. The path is exact and unforgiving: it’s inside the .githubdirectory (not the repo root), and the filename must match character-for-character. Get the path right and Copilot picks it up automatically — there’s nothing to register.

It’s a plain Markdown file with no required frontmatter. Keep it focused on durable, project-wide facts and rules:

# Copilot instructions for Acme API

## Stack
- TypeScript (strict). Node 22, Next.js App Router.
- Vitest for unit tests, Playwright for E2E.

## Conventions
- Never use `any`. No unguarded `as` casts.
- Use the internal `logger` module, never `console.log`.
- Functions under 50 lines; files under 800.

## Don't
- Don't edit anything under `src/generated/`.
- Don't run `pnpm install` without asking first.

This file is enabled by default. The behavior is gated by the VS Code setting github.copilot.chat.codeGeneration.useInstructionFiles, which is on out of the box — so you only ever touch it to disable instruction files, never to turn them on. It applies across VS Code, Visual Studio, and Copilot on GitHub.com.

Path-specific: .instructions.md with applyTo

A single repo-wide file gets unwieldy the moment your conventions differ by area — your React rules aren’t your SQL migration rules. That’s what .instructions.md files solve. They live in .github/instructions/, end in .instructions.md, and carry a YAML frontmatter block whose key field is applyTo — a comma-separated set of globs that decides which files the instructions attach to.

---
applyTo: "**/*.ts,**/*.tsx"
description: TypeScript and React conventions
---

- Prefer function components and hooks; no class components.
- Co-locate tests as `*.test.tsx` next to the component.
- Use `zod` for runtime validation at every boundary.
- Type props explicitly; never rely on inference for public APIs.

When Copilot works on a file that matches the glob, these instructions are layered in on top of the repo-wide ones. The frontmatter supports a few fields:

• applyTo — the glob(s) that scope the file. Use applyTo: "**" to apply to everything (a second way to write a repo-wide rule).
• description — optional human-readable summary shown in the UI.
• excludeAgent — optional; keep the file from applying to specific agents.

Prompt files (.prompt.md)

Prompt files are frequently confused with instructions, but they solve a different problem. An instruction file answers “how should you alwaysbehave when working here?” A prompt file answers “run this specific tasknow.” They’re reusable, self-contained chunks of prompt you invoke explicitly.

Prompt files live in .github/prompts/, end in .prompt.md, and you trigger one by typing /name in chat (a file named generate-test.prompt.md is invoked as /generate-test). Their frontmatter supports description, agent, model, and tools:

---
description: Scaffold a Vitest suite for the selected module
agent: agent
model: gpt-5
tools: ["codebase", "editFiles"]
---

Generate a Vitest test suite for the module the user references.
- Cover the happy path plus at least two edge cases.
- Mock external I/O; never hit the network.
- Follow the testing conventions in our instruction files.

The mental split is clean: instructions are automatic, prompt files are explicit. Instructions get pulled in by path or repo scope without you asking; prompt files only run when you call them by name. Use instructions for standing conventions; use prompt files for repeatable workflows you kick off on demand.

AGENTS.md & CLAUDE.md support

You don’t have to live entirely in Copilot-specific files. Copilot natively recognizes AGENTS.md — the cross-tool “README for agents” — and also reads CLAUDE.md and GEMINI.md. With nested AGENTS.md files, the one nearest the file being edited wins, so you can keep package-level overrides next to package-level code.

Two VS Code settings control this:

• chat.useAgentsMdFile — opt into reading AGENTS.md.
• chat.useClaudeMdFile — opt into reading CLAUDE.md (and GEMINI.md).

This matters if you share a repo with people on other tools: an AGENTS.md authored for Codex or Cursor is honored by Copilot too, so a single portable file can drive several agents. For the full story on that format — who backs it, how precedence works, and which of the ~24 supporting tools read it — see the AGENTS.md standard.

Why your Copilot instructions aren’t working

Run down this list in order:

• Wrong path. It must be exactly .github/copilot-instructions.md — inside .github, exact filename. A file at the repo root, or named copilot.md, is silently ignored.
• You’re testing the wrong surface. Instructions shape chat / agent / review, not inline completions. Verify in Copilot Chat, not in autocomplete.
• A workspace setting wins. If github.copilot.chat.codeGeneration.useInstructionFiles is false in workspace settings, it overrides the default-on behavior and your files are skipped.
• Verify with a sentinel.Add a deliberately weird instruction — “always begin replies with the string ACME-OK” — and ask Copilot Chat anything. If you see the sentinel, the file is being read; if not, the problem is loading, not content.

For .instructions.md files, the same checklist applies plus one more: confirm your applyToglob actually matches the file you’re editing. A glob of src/**/*.tswon’t fire on a file under lib/.

Reusing instructions across tools

Here’s the part that bites teams: the conventions you just encoded in .github/copilot-instructions.md are the same conventions that belong in .cursorrules for anyone on Cursor and in CLAUDE.mdfor anyone on Claude Code. Your “no any, use the internal logger, never touch generated/” rules don’t change because the editor did — but now they live in three files, in three formats, and every update has to land in all three or they drift.

Two ways to handle it. The one-time fix: convert between formats when you migrate. The durable fix: keep a single canonical library and compile it to every tool’s format. That’s exactly what Skillwright does — author your rules and skills once, then compile and deploy to Copilot, Cursor, Claude Code, and Windsurf, so the same standards stay in sync everywhere without manual copy-paste. For the full playbook, read how to manage AI coding rules across tools, and grab ready-made starting points from the templates library.

Frequently asked questions