Copilot Configuration Files: What They Are, Where They Live, and When to Use Them
When I work with repos that use Copilot, I keep running into the same confusion: people have these files scattered across .github/, but they don't know what each one does, why they exist separately, or how they're supposed to work together.
I'll see .github/copilot-instructions.md and .github/agents/ in the same repo, then a prompts/ folder, then maybe a workflow file that looks half like YAML and half like agent instructions. The files exist, but the mental model doesn't.
This guide is my attempt to make that mental model boring and usable. I want to show what each file is for, where real repos keep them, and which claims I can actually defend with links.
The governance metaphor works like nested rings: instructions shape the space, agents interpret it, and skills do the work at the center.
Quick Reference: The Five File Families
| File | Lives at | Purpose | When to use |
|---|---|---|---|
| Copilot instructions | .github/copilot-instructions.md | Repository-wide governance (always-on context) | "All Copilot work in this repo should follow these rules" |
| Agent definitions | .github/agents/ | Specialist persona with its own scope, tools, and constraints | "This task needs a reviewer or specialist with tighter boundaries" |
| Skills | .github/skills/{name}/SKILL.md | Reusable workflow package with instructions, resources, and optional scripts | "This is a repeatable procedure Copilot should know how to do" |
| Prompt files / prompt docs | Official prompt files: .github/prompts/*.prompt.md; repo-local docs often live in .github/prompts/*.md | Reusable prompt template or task-specific reference context | "I need either a reusable prompt in the IDE or a deeper reference doc for a specific task" |
| Workflows | .github/workflows/ | GitHub Actions automation and remote triggers | "I need this to run on a label, schedule, dispatch, or PR event" |
This structure diagram turns the five file families into one navigable map so you can see which pieces are baseline, specialized, reusable, or event-driven.
The folder-house metaphor emphasizes that these files live together, but each room has a different job.