Module 11 — Customizing Copilot: Instructions & Prompt Files

Goal: Make Copilot follow your rules automatically. Master the file-based customization layers — copilot-instructions.md, path-specific .instructions.md, prompt files, and AGENTS.md — and understand exactly how they merge and which wins.

This is the first lever from Module 10. Get it right and you stop repeating yourself in every prompt.

---

11.1 The problem custom instructions solve

Without customization, every conversation starts from zero. You find yourself typing “use TypeScript, not JavaScript,” “we indent with tabs,” “always include tests,” “follow our naming conventions” over and over. Custom instructions are persistent text files that Copilot reads automatically and folds into every relevant request — so the rules are applied without you restating them.

Think of them as a standing brief you hand a new teammate on day one, except Copilot re-reads it on every task.

---

11.2 The customization files (the toolbox)

There are four file-based mechanisms. They live mostly in the special .github/ folder (the same one GitHub uses for Actions, Module 7).

1. Repository-wide instructions — .github/copilot-instructions.md

A single Markdown file at .github/copilot-instructions.md, committed to the repo. It applies to everyone on the team automatically — no per-user setup, no opt-in. It’s read by VS Code Chat, JetBrains, github.com chat, the Copilot CLI, and the cloud agent. This is your most important customization file.

# Project: Acme Web App

## Tech stack
- TypeScript + React, Node.js backend.
- Use functional components and hooks; never class components.

## Conventions
- Indent with 2 spaces. Prefer named exports.
- Every new function needs a unit test in the same folder.
- Use our logger (`src/lib/log.ts`), never `console.log`.

## Don'ts
- Don't add new dependencies without noting why.
- Don't touch files in `/legacy`.

Keep it concise and concrete. It’s prepended to requests, so every word competes for context-window space (Module 13). Bullet points of clear rules beat long prose.

2. Path-specific instructions — *.instructions.md

Sometimes a rule should apply only to certain files. Put one or more NAME.instructions.md files in .github/instructions/. Each has YAML frontmatter with an applyTo glob pattern that scopes it:

---
applyTo: "**/*.test.ts"
---
- Use Vitest, not Jest.
- Name tests with "should ..." phrasing.
- Mock network calls with `msw`.

Now those rules activate only when Copilot is working on files matching **/*.test.ts. You can have many of these — one for tests, one for src/api/**, one for styles, etc. This keeps each rule set focused and avoids dumping every rule into one giant file.

3. Prompt files — *.prompt.md

Where instructions are passive (always-on rules), prompt files are reusable commands you invoke on demand. Store team-shared ones in .github/prompts/ (or personal ones in your editor profile). Each captures a whole task you do repeatedly:

---
mode: agent
description: Scaffold a new REST endpoint with tests
---
Create a new Express route for the resource the user names.
Include input validation, error handling, and a full test file.
Follow the conventions in copilot-instructions.md.

You then run it like a slash command (e.g. typing / and the prompt’s name) instead of retyping the instructions. Prompt files turn your best prompts into shareable, version-controlled tools.

4. AGENTS.md

AGENTS.md is an emerging cross-tool standard (not GitHub-specific) for giving AI agents project guidance — build commands, conventions, how to run tests. Copilot reads it as one of the instruction layers. If your project already has an AGENTS.md for other AI tools, Copilot will honor it too, which is handy for staying tool-neutral. You can place an AGENTS.md at the repo root (and nested ones in subfolders for area-specific guidance).

Bonus: personal & organization instructions

• Personal instructions set in your GitHub.com settings apply to you across all repos (e.g. “always explain your reasoning briefly”).
• Organization instructions (Enterprise) let admins set rules across all repos in the org.

---

11.3 How the layers merge and which wins

All applicable layers are combined and sent with each request — they’re additive, not exclusive. When guidance overlaps or conflicts, there’s a priority order. From highest to lowest priority:

1. Personal instructions        (your GitHub.com settings)        ← highest
2. Path-scoped *.instructions.md (matching applyTo)
3. Repo-wide copilot-instructions.md
4. AGENTS.md
5. Organization-level instructions                                 ← lowest

So a personal preference can override a repo rule, and a focused path-specific rule outranks the broad repo-wide file. In practice, conflicts are rare if you keep each layer’s job distinct: org sets baseline policy, repo sets project conventions, path files set area specifics, prompt files capture tasks, personal tweaks your own style.

Practical takeaway: put broad, always-true project rules in copilot-instructions.md; put narrow, file-type-specific rules in *.instructions.md with applyTo; put repeatable tasks in *.prompt.md. Don’t cram everything into one file — focused, scoped instructions are both clearer and cheaper on context.

---

11.4 Writing instructions that actually work

A few field-tested tips:

• Be specific and imperative. “Use 2-space indentation” beats “format nicely.”
• Show, don’t just tell. A tiny code example of your preferred pattern is worth a paragraph.
• Keep it short. Every instruction consumes context budget (Module 13). Trim anything Copilot already does well by default.
• State the don’ts. “Never use any in TypeScript” prevents a whole class of bad output.
• Scope aggressively. If a rule only matters for tests, put it in a test-scoped .instructions.md, not the global file.
• Treat it like code. Commit it, review changes to it in PRs, and refine it when Copilot gets something wrong — the fix is often “add a line to the instructions.”

---

11.5 How this connects to the rest of Part C

Instructions are the passive, always-on layer of guidance. They differ from skills (Module 12), which are on-demand expertise loaded only when relevant, and from memory (Module 13), which is learned automatically across sessions. A well-tuned project uses all three: instructions for standing rules, skills for specialized procedures, memory for accumulated project facts.

---

Try it yourself

1. Create .github/copilot-instructions.md in a repo with 5–8 concrete rules about your stack and conventions. Commit it.
2. Ask Copilot to write a new function and observe it following your rules without being told.
3. Add a .github/instructions/tests.instructions.md with applyTo: "**/*.test.*" and a rule (e.g. your test framework). Generate a test and confirm the rule applies only there.
4. Create a .github/prompts/ prompt file for a task you do often, and invoke it.

Key takeaways

• Custom instructions are persistent files Copilot folds into every request so you stop repeating yourself.
• Four mechanisms: repo-wide copilot-instructions.md, path-scoped *.instructions.md (with applyTo), reusable *.prompt.md commands, and the cross-tool AGENTS.md.
• All applicable layers merge; priority runs personal → path-scoped → repo-wide → AGENTS.md → org.
• Keep instructions specific, short, and scoped — every line spends context budget.

---

Sources

• Adding repository custom instructions for GitHub Copilot — GitHub Docs
• Use custom instructions in VS Code — VS Code Docs
• 5 tips for writing better custom instructions for Copilot — The GitHub Blog
• How Copilot’s customization layer actually works — Nived Velayudhan (Medium, 2026)

Next: Module 12 — Copilot Skills: How They Work