Instructions Files

What Is an Instructions File?

Skills are loaded on demand — when Copilot decides they're relevant, or when you explicitly call them. Instructions files are different: they're loaded every single time you send Copilot a message.

Open

Think of it as a persistent briefing. Every request you send is automatically paired with the contents of this file. If you want Copilot to always know something — your tech stack, your folder structure, your conventions — put it in the instructions file and it will never forget.

For GitHub Copilot, this file can live in two places:

• CLAUDE.md at the project root (shared with Claude Code)

• .github/copilot-instructions.md (Copilot-specific)

Copilot is designed to find and read both automatically.

✏️ A Simple Demo

Before building the real file, here's a quick demo to make the concept concrete.

Open CLAUDE.md and add this line:

Now reload the VS Code window with Cmd+Shift+P → Reload Window.

Say "hi" to Copilot. It should respond with 👋 every time — because that instruction is now attached to every message you send.

Open

Open

Delete that line when you're done. It was just a demo.

What Goes in an Instructions File?

The instructions file defines the universe Copilot operates in. When you're building it, think about what Copilot would need to know to help you effectively on any request — without you having to explain your project every time.

Good candidates for the instructions file:

• Tech stack and key packages — what language, framework, and libraries the project uses

• Folder structure — where things live so Copilot can navigate confidently

• Common commands — how to run, test, and build the project

• Coding conventions — naming patterns, formatting rules, architecture preferences

• Data model overview — key entities, how the database is structured

• Common pitfalls — things Copilot might get wrong without a heads-up

Size guideline: Keep it under 5–10 KB, around 1,500 words or fewer. The more concise and focused, the better. This file gets loaded with every message, so bloating it will eat into your context window.

✏️ Exercise: Auto-Generate the Instructions File

Copilot can generate this file for you. It'll scan the codebase, identify what's relevant, and write a concise instructions file based on what it finds.

Step 1: Enable auto-accept so Copilot can write files without stopping to ask permission each time.

At the bottom of the Copilot chat panel, click Default Approvals and switch to Bypass Approvals.

Open

Step 2: Run this prompt:

Copilot will explore the project — reading files, checking folder structure, identifying patterns — and write the file. This can take 5–10 minutes. Let it run.

Step 3: Review what was generated.

Open CLAUDE.md and read through it. You should see things like:

• Package and dependency info

• Key commands (npm run dev, npm test, etc.)

• Architecture notes

• Data model summary

• Common pitfalls

Open

This is now the core context document for your project. Every message you send to Copilot will include this file automatically.

Going forward: As your project evolves, keep this file up to date. Add new conventions as they emerge. Remove things that are no longer true. Treat it like living documentation that the agent reads every day.

Next: Context Engineering Theory