layout	default
parent	Copilot Team Workflow
title	Part 01 - The .github Folder Explained
description	A tour of all 6 building blocks: copilot-instructions, instructions, agents, prompts, skills, and hooks.
nav_order	2

Learn: What's in the .github Folder?

← Part 00: Getting Started · 📚 Learn Series · Part 02: The 5-Phase Workflow →

The Big Idea

The .github/ folder is Copilot's brain for your project. Every file in it is a configuration that teaches Copilot something — how your project works, what your standards are, which specialist to call, what to do automatically.

You set it up once. After that, every developer on the team gets the same context automatically, every session.

The 6 Building Blocks

1. `copilot-instructions.md` — The Project Overview

Always loaded. Every session. Every file.

This is the one file that is loaded into Copilot's context no matter what. It should contain:

What the project does (one sentence)
The tech stack
Links to the key docs

# MyProject — GitHub Copilot Configuration

## What This Project Is
An order management API that integrates with Microsoft Dynamics 365 CRM.
Stack: Node.js + TypeScript + Express + PostgreSQL + Redis

## Key Documentation
- [Project Overview](https://github.com/SriSatyaLokesh/copilot-team-workflow/blob/main/docs/project.md)
- [API Architecture](../learn/03-api-architecture.md)
- [External APIs](https://github.com/SriSatyaLokesh/copilot-team-workflow/blob/main/docs/external-apis/)

Keep it short. It loads every session — if it's 500 lines, it wastes context.

2. `instructions/` — Rules Per File Type

Loaded automatically when you open a matching file.

Instructions are the most powerful feature. Write a rule once, it applies everywhere automatically.

.github/instructions/
├── developer-guide.instructions.md   ← applyTo: "**"  (always on)
├── api-architecture.instructions.md  ← applyTo: "src/api/**,src/wrappers/**"
├── backend.instructions.md           ← applyTo: "src/**/*.ts"
├── frontend.instructions.md          ← applyTo: "src/**/*.tsx"
└── testing.instructions.md           ← applyTo: "**/*.test.*"

The applyTo field in the frontmatter tells Copilot which files trigger this instruction:

---
applyTo: "src/wrappers/**,src/services/**"
---
# API Architecture Standards
...rules about the Controller→Service→Wrapper→Transformer pattern...

When a developer opens src/wrappers/dynamics-wrapper.ts, Copilot automatically loads the API architecture rules. Without the developer doing anything.

Real example: The VS Code team has typescript.instructions.md that applies to all .ts files — every TypeScript suggestion automatically follows their internal standards.

3. `agents/` — Specialist Assistants

Selected by the developer or triggered by handoff.

Agents are like hiring a specialist for each phase of work. Each agent file defines:

What this agent is good at
Which tools it can use
What it does step by step
Which agent it hands off to next

.github/agents/
├── discuss.agent.md          ← Phase 1: clarifies requirements
├── research.agent.md         ← Phase 2: reads codebase before planning
├── plan.agent.md             ← Phase 3: creates task list
├── tdd.agent.md              ← Phase 4: writes tests first, then code
├── review.agent.md           ← Reviews code before PR
├── verify.agent.md           ← Phase 5: checks Issue is done
├── api-builder.agent.md      ← Specialist for external API integrations
└── parallel-builder.agent.md ← Orchestrator: dispatches 3+ independent tasks simultaneously

Example agent frontmatter:

---
description: 'Use when starting any new feature, fix, or task — when developer says "I want to build X" or "work on a new issue".'
name: Discuss
argument-hint: 'Briefly describe what you want to build (e.g. "add rate limiting to login endpoint")'
tools: ['search', 'codebase', 'editFiles']
model: 'gpt-4o'
handoffs:
  - label: Start Research →
    agent: Research
    send: true        ← auto-triggers Research without asking
---

The argument-hint field shows placeholder text in the chat input after selecting an agent — so developers know exactly what to type.

The handoffs field creates a button in Copilot chat. send: true means it fires automatically.

4. `prompts/` — Slash Commands

Triggered by the developer with /command.

Prompts are reusable, parameterized instructions your team runs as slash commands. They're how you trigger a workflow with one command instead of typing a long prompt each time.

.github/prompts/
├── start-issue.prompt.md      ← /start-issue (always start here)
├── discuss.prompt.md          ← /discuss
├── research.prompt.md         ← /research
├── plan.prompt.md             ← /plan
├── execute.prompt.md          ← /execute
├── verify.prompt.md           ← /verify
├── debug.prompt.md            ← /debug
├── add-new-api.prompt.md      ← /add-new-api
├── receive-review.prompt.md   ← /receive-review
├── finish-branch.prompt.md    ← /finish-branch
├── generate-api-doc.prompt.md ← /generate-api-doc
├── update-api-doc.prompt.md   ← /update-api-doc
├── status.prompt.md           ← /status (check progress)
├── summarize.prompt.md        ← /summarize (save session context)
└── sync-docs.prompt.md        ← /sync-docs (bulk doc updates)

Example prompt file:

---
description: 'Add a new external API call — walks through the full architecture'
agent: 'ApiBuilder'
tools: ['editFiles', 'terminal', 'search']
---
You are adding a new external API call.

First, read: #docs/external-apis/${input:api-name}/README.md
Then implement: Transformer → Wrapper → Service → Controller → Tests

The ${input:api-name} syntax creates an input field in the chat — Copilot asks the developer to fill it in before starting.

5. `skills/` — Bundled Knowledge Packs

Referenced by agents. Loaded when the agent decides it needs them.

A skill is a folder containing a SKILL.md — a detailed reference document that an agent can read when it needs deep context on a specific area.

.github/skills/
├── acquire-codebase-knowledge/SKILL.md  ← Factual codebase mapping (Arch, Stack, etc.)
├── agent-activity-logger/SKILL.md        ← Log format for session audit trail
├── doc-reviewer/SKILL.md                 ← Brutal doc review (Critical/Major/Minor + score)
├── documentation-writer/SKILL.md         ← Diátaxis-guided doc creation (4 types)
├── github-cli-workflow/SKILL.md          ← gh CLI: issues, PRs, branches, merge patterns
├── gitlab-cli-workflow/SKILL.md          ← glab CLI: issues, MRs, branches, merge patterns
├── playwright-automation-fill-in-form/SKILL.md ← Automate form fill via Playwright MCP
├── playwright-explore-website/SKILL.md   ← Explore URL, find 3-5 flows, propose tests
├── playwright-generate-test/SKILL.md     ← Generate TypeScript Playwright spec
├── receiving-code-review/SKILL.md        ← Evaluate-before-implement pattern
├── requesting-code-review/SKILL.md       ← Dispatch code-reviewer subagent
├── subagent-driven-development/SKILL.md  ← Per-task subagent + 2-stage review
└── test-driven-development/SKILL.md      ← Iron Law TDD, Red-Green-Refactor, rebuttal table

Skills are different from instructions:

Instructions → auto-loaded per file type, always active
Skills → auto-loaded by Copilot when your prompt matches the skill's description (or invoked manually with /skill-name). Rich descriptions help Copilot decide when to load them automatically.

VS Code team has 11 skills including one for writing vscode extension tests, one for localization strings, one for accessibility checks.

6. `hooks/` — Scripts That Run Automatically

Triggered by Copilot agent lifecycle events.

Hooks let you run shell scripts at specific moments — session start, session end, every prompt submitted.

.github/hooks/
├── session-auto-commit/
│   ├── hooks.json         ← { "sessionEnd": [run auto-commit.sh] }
│   └── auto-commit.sh     ← git add -A && git commit && git push
└── session-logger/
    ├── hooks.json         ← { "sessionStart": ..., "sessionEnd": ..., "userPromptSubmitted": ... }
    ├── log-session-start.sh
    ├── log-session-end.sh
    └── log-prompt.sh

The hooks.json defines when each script runs. VS Code uses PascalCase event names:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": ".github/hooks/session-auto-commit/auto-commit.sh",
        "windows": "powershell -ExecutionPolicy Bypass -File .github/hooks/session-auto-commit/auto-commit.ps1",
        "timeout": 30
      }
    ]
  }
}

Available events:

Event	When it fires
`SessionStart`	runs when agent session opens
`Stop`	runs when agent session closes
`UserPromptSubmit`	runs on every prompt
`PreToolUse`	runs before any tool is invoked
`PostToolUse`	runs after any tool completes

Windows note: Use the windows property for PowerShell overrides. Use command for bash/default.

How It All Connects

Developer opens src/wrappers/dynamics-wrapper.ts
        ↓
Copilot auto-loads:
  - copilot-instructions.md (project overview)
  - developer-guide.instructions.md (always on)
  - api-architecture.instructions.md (matches src/wrappers/**)

Developer types: /add-new-api
        ↓
add-new-api.prompt.md activates → ApiBuilder agent launches
        ↓
ApiBuilder reads:
  - docs/external-apis/dynamics/ (field maps for Dynamics CRM)
  - .github/instructions/api-architecture.instructions.md (standards)
        ↓
Agent writes code → session ends

hooks/session-auto-commit/auto-commit.sh runs automatically
hooks/session-logger/log-session-end.sh logs the session

Summary

File/Folder	Loaded When	Purpose
`copilot-instructions.md`	Every session	Project overview
`instructions/*.instructions.md`	File matches `applyTo`	Standards per file type
`agents/*.agent.md`	Developer selects or handoff	Specialist assistant
`prompts/*.prompt.md`	Developer types `/command`	Reusable workflow
`skills/*/SKILL.md`	Agent reads it	Deep knowledge reference
`hooks/*/hooks.json`	Session event fires	Automation

Next: The 5-Phase Issue Workflow → 02-five-phase-workflow.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Learn: What's in the .github Folder?

The Big Idea

The 6 Building Blocks

1. `copilot-instructions.md` — The Project Overview

2. `instructions/` — Rules Per File Type

3. `agents/` — Specialist Assistants

4. `prompts/` — Slash Commands

5. `skills/` — Bundled Knowledge Packs

6. `hooks/` — Scripts That Run Automatically

How It All Connects

Summary

Further Reading

FilesExpand file tree

01-github-folder-explained.md

Latest commit

History

01-github-folder-explained.md

File metadata and controls

Learn: What's in the .github Folder?

The Big Idea

The 6 Building Blocks

1. copilot-instructions.md — The Project Overview

2. instructions/ — Rules Per File Type

3. agents/ — Specialist Assistants

4. prompts/ — Slash Commands

5. skills/ — Bundled Knowledge Packs

6. hooks/ — Scripts That Run Automatically

How It All Connects

Summary

Further Reading

1. `copilot-instructions.md` — The Project Overview

2. `instructions/` — Rules Per File Type

3. `agents/` — Specialist Assistants

4. `prompts/` — Slash Commands

5. `skills/` — Bundled Knowledge Packs

6. `hooks/` — Scripts That Run Automatically