Skip to main content

2 posts tagged with "copilot"

View All Tags

Copilot Configuration Files: What They Are, Where They Live, and When to Use Them

· 18 min read
dfberry

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.

Layers of governance showing instructions, agents, and skills as concentric circles

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​

FileLives atPurposeWhen to use
Copilot instructions.github/copilot-instructions.mdRepository-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.mdReusable workflow package with instructions, resources, and optional scripts"This is a repeatable procedure Copilot should know how to do"
Prompt files / prompt docsOfficial prompt files: .github/prompts/*.prompt.md; repo-local docs often live in .github/prompts/*.mdReusable 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"

Configuration files structure across the five .github families

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.

Stylized .github home showing where instructions, agents, skills, prompts, and workflows live

The folder-house metaphor emphasizes that these files live together, but each room has a different job.

The Instructions vs Skills Distinction: Governance vs Execution

· 20 min read
dfberry

When I look at repos that manage agents and skills, I keep noticing the same pattern: governance rules do not stay in the instruction layer. They get pushed down into skills. A repo starts with a clean distinction in theory, then practical pressure takes over. It feels easier to tuck a rule into the skill that already handles PRs, releases, reviews, or docs updates than to keep the governance layer separate and durable.

That leak creates a mess fast. Policy gets buried inside execution, contributors have to hunt through step-by-step workflow files to figure out what is actually required, CI can only enforce the rules that escaped into the right place, and every workflow tweak risks rewriting what should have been a stable repo expectation. The instructions-versus-skills distinction only matters if you keep the layers separate. Once rules get pushed into skills, you lose both layers.

So I kept pulling on one simple question: when does guidance belong in repo instructions, and when does it belong in a skill?