The GitHub Copilot customization stack

tech
prompt-engineering
github-copilot
overview
A map of every customization mechanism in GitHub Copilot — prompt files, instructions, agents, skills, hooks, MCP, models, chat modes, and Copilot Spaces — with reading paths into the series.
Author

Dario Airoldi

Published

March 1, 2026

The GitHub Copilot customization stack

GitHub Copilot’s generative AI is most effective when it has access to structured context about your project. Both VS Code and Visual Studio let you embed that context directly in your repository using markdown-based prompt and instruction files. These files guide Copilot by encoding reusable prompts, coding standards, business rules, and project documentation.

This article is the series overview. It introduces every customization mechanism in the stack, explains how the pieces fit together, and points you to the concept articles, how-to guides, and reference tables where you’ll find the full details. If you’re new to Copilot customization, start here — then follow the reading paths at the end.

Table of contents

🏗️ How the stack fits together

Every message you type in Copilot Chat triggers a multi-layered construction process before the model sees a single token. The system prompt is built from layers of identity rules, instructions, and agent persona. The user prompt is assembled from your message, environment context, and any referenced files. The model processes both and generates a response — optionally calling tools (MCP, built-in, or extension-provided) along the way.

Each customization mechanism occupies a specific slot in this assembly:

Mechanism Assembly position Activation Persistence
Instructions (.instructions.md) System prompt Automatic (file-pattern match) Every request
Prompt files (.prompt.md) User prompt On demand (/command) Single invocation
Agents (.agent.md) System prompt (identity override) Agent picker Entire session
Skills (SKILL.md) System prompt (on match) Automatic (description match) Single request
Hooks (.github/hooks/*.json) Outside the prompt Lifecycle event trigger Deterministic
MCP servers (mcp.json) Tool schemas in system prompt Tool call at runtime Session

For the full architecture with diagrams and layer-by-layer breakdown, see How Copilot assembles and processes prompts.

📝 Prompt files

A prompt file is a reusable markdown document (.prompt.md extension) that you run as a slash command in Copilot Chat. It begins with an optional YAML header specifying metadata — name, description, agent mode, preferred model, available tools — followed by a markdown body containing the instructions or template you want Copilot to follow.

Where they live:

  • Workspace prompts: .github/prompts/*.prompt.md — recognized automatically by VS Code and Visual Studio (17.10+)
  • User prompts (VS Code only): Stored in your VS Code profile folder, available across all workspaces

Key features: Variable substitution (${selection}, ${file}, ${input:name}), tool references (#tool:githubRepo), and model routing via the model: header field.

📘 Concept: Understanding prompt files, instructions, and context layers 🔧 How-to: How to name and organize prompt files | How to structure content for Copilot prompt files

📚 Custom instructions

Custom instructions let you define persistent rules that Copilot follows on every request — coding standards, framework preferences, output formatting, business rules. They’re injected into the system prompt automatically without any manual invocation.

Two levels:

  • Repo-level: .github/copilot-instructions.md — applies to the entire repository. Supported by VS Code, Visual Studio (17.10+), and SDK apps.
  • Path-specific: .github/instructions/*.instructions.md — each file includes an applyTo glob pattern (e.g., **/*.cs) and activates only when the user works with matching files.

Key difference from prompt files: Instructions are always-on and land in the system prompt. Prompt files are on-demand and land in the user prompt. This distinction affects how strongly the model follows the content — system prompt rules carry more weight.

📘 Concept: Understanding prompt files, instructions, and context layers 🔧 How-to: How to structure content for Copilot instruction files

🤖 Custom agents

Custom agents (.agent.md files, VS Code 1.106+) let you define specialized AI personas with specific tools, instructions, and workflows. Each agent overrides Copilot’s identity layer in the system prompt, giving the model a focused role — security auditor, documentation reviewer, database migration specialist.

Key capabilities:

  • YAML frontmatter specifying tools, model preferences, and target environment (vscode or github-copilot)
  • Handoff workflows for multi-agent orchestration — one agent completes its task and offers a button to hand off to the next
  • Subagent delegation — agents can spawn other agents for isolated subtasks with fresh context windows
  • Visibility control — set user-invokable: false to create subagent-only agents

Important distinction: .agent.md files are interactive VS Code personas. AGENTS.md (and CLAUDE.md, GEMINI.md) files are used by the GitHub coding agent for asynchronous PR creation.

📘 Concept: Understanding agents, invocation, handoffs, and subagents 🔧 How-to: How to structure content for Copilot agent files | How to design subagent orchestrations

🎯 Agent Skills (preview)

Agent Skills (VS Code 1.107+, preview) are portable, resource-rich capabilities that work across VS Code, CLI, and the GitHub coding agent. Unlike instructions (file-pattern rules) or agents (VS Code personas), skills bundle templates, scripts, and examples alongside instructions.

Key differences from other mechanisms:

Feature Skills Instructions Prompts Agents
Activation Auto (description match) Auto (file pattern) On demand (/name) Agent picker
Resources Templates, scripts, examples None None None
Cross-platform VS Code, CLI, coding agent VS Code + GitHub.com VS Code only VS Code only
Tool control Limited None Full Full

Skills use three-level loading — name and description first (~50-100 tokens), then the SKILL.md body on match (~500-1500 tokens), then resource files only when referenced. This progressive disclosure keeps the context window lean until the skill is actually needed.

📘 Concept: Understanding skills, hooks, and lifecycle automation 🔧 How-to: How to structure content for Copilot skills

🪝 Agent hooks (preview)

Agent hooks (VS Code 1.109.3+, preview) let you execute custom shell commands at key lifecycle points during agent sessions. Unlike instructions or prompts that guide behavior, hooks provide deterministic, code-driven automation with guaranteed outcomes.

Eight lifecycle events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStart, SubagentStop, Stop.

Why hooks matter: They’re the enforcement layer. Instructions can suggest that the model runs tests after editing a file — hooks guarantee it. Common patterns include blocking dangerous commands in PreToolUse, running formatters in PostToolUse, and generating audit logs on Stop.

VS Code uses the same hook format as Claude Code and Copilot CLI for cross-platform compatibility.

📘 Concept: Understanding skills, hooks, and lifecycle automation 🔧 How-to: How to use agent hooks for lifecycle automation

🔌 Model Context Protocol (MCP)

The Model Context Protocol (MCP) is generally available in VS Code (1.102+). MCP provides a standardized way to connect Copilot to external data sources and tools — databases, APIs, cloud services, browser automation — using typed, narrowly-scoped tool definitions.

MCP 1.0 features (December 2024): Tasks (durable, resumable operations), Sampling (server-initiated LLM completions), Elicitation (server-prompted user input), and Custom Icons.

Discovery: Search @mcp in the Extensions view for the curated MCP Registry. One-click installation adds servers to your mcp.json. A built-in GitHub MCP Server (preview) provides repository operations without additional setup.

📘 Concept: Understanding MCP and the tool ecosystem 🔧 How-to: How to create MCP servers for Copilot | How to leverage tools in prompt orchestrations

🧠 Models and BYOK

GitHub Copilot supports multiple model families — GPT (explicit instruction followers), Claude (clarity and context), Gemini (structured reasoning), and reasoning models (o-series, minimal prompting). Each model interprets the same prompt differently, like “different compilers” for the same source code.

VS Code 1.107 introduced the Language Models Editor and bring-your-own-key (BYOK) support. You can add models from Cerebras, OpenRouter, Ollama, Azure OpenAI, Anthropic, and HuggingFace — all accessible through the Copilot model picker without consuming your subscription quota.

📘 Concept: Understanding LLM models and model selection 🔧 How-to: How to optimize prompts for specific models 📋 Reference: Copilot settings, IDE support, and compatibility reference (BYOK tables, filter syntax, provider details)

💬 Chat modes and Agent HQ

GitHub Copilot Chat provides four built-in chat modes:

Mode Description Use case
Agent Autonomous mode that applies changes directly to your workspace Complex multi-file refactoring, feature implementation
Plan Creates detailed implementation plans without modifying files Architecture planning, understanding approach before execution
Ask Q&A mode for questions without file modifications Learning, code explanations, debugging assistance
Edit Direct code editing mode for targeted changes Quick fixes, single-file modifications

VS Code 1.107 introduced Agent HQ, a unified interface for managing agent sessions across three execution contexts — local (interactive), background (work tree isolation), and cloud (GitHub PR). Plan mode integrates with agent delegation: after generating a plan, you can use the “Start Implementation” button to hand off to any execution context.

📘 Concept: Chat modes, Agent HQ, and execution contexts

🌐 Copilot Spaces (preview)

Copilot Spaces (preview) let you assemble a collection of instructions, files, repositories, and web links into a shareable, persistent context that Copilot can reference across conversations. Unlike repo-level files (.github/, .copilot/), Spaces aren’t tied to a single repository — they can pull sources from multiple repos, uploaded documents, and external URLs.

Use .github/ and .copilot/ for project-specific rules. Use Spaces for cross-project knowledge, team onboarding guides, or organizational standards.

📘 Deep dive: Copilot Spaces — setup instructions, IDE integration, collaboration roles, and a decision guide

🧰 GitHub Copilot SDK

The GitHub Copilot SDK (announced January 2026, technical preview) enables any application to embed Copilot’s agentic loop outside the editor. Available for Node.js, Python, Go, and .NET, the SDK connects to the Copilot CLI running in server mode via JSON-RPC.

SDK-based applications consume the same prompt files, agent definitions, instruction files, and MCP servers documented in this series. The authoring best practices in the how-to guides apply directly — you don’t need to learn a separate prompt format.

Capability SDK support
Workspace prompt files (.prompt.md) ✅ via workspace scanning
Instruction files (.instructions.md) ✅ via workspace scanning
Agent definitions (.agent.md) ✅ via agent definitions
Agent Skills (SKILL.md) ✅ via agent skills
MCP servers ✅ full support
#file references ❌ no editor UI
Custom slash commands ❌ no editor UI

🔧 How-to: How to use prompts with the GitHub Copilot SDK

📁 Optional .copilot/ folder

Although not part of the official specification, a .copilot/ directory can hold rich project documentation and reference materials to help Copilot understand your codebase. Common subfolders include context/ (data schemas, API contracts, code patterns), architecture/, troubleshooting/, and examples/.

None of these files automatically generate chat commands — they improve the semantic search that Copilot uses when answering questions about your project. Both VS Code and Visual Studio index files in .copilot/.

🔑 Feature compatibility matrix

The table below summarizes which customization features are supported across VS Code, Visual Studio, SDK apps, and earlier Visual Studio versions. For each capability, the table shows the support level and any version requirements.

Capability VS Code Visual Studio 2022 (17.10+) SDK apps Earlier VS versions
Workspace prompt files (.github/prompts/*.prompt.md) Supported; slash commands /promptName appear in chat Supported; use hashtag commands #promptName (since 17.10) ✅ via workspace scanning Not supported prior to 17.10
User prompt files (.prompt.md in VS Code profile) Available as personal slash commands across all projects Not supported ❌ editor-only Not applicable
Repo-level instructions (.github/copilot-instructions.md) Supported (requires enabling the “Use Instruction Files” setting) Supported (requires enabling custom instructions in options) ✅ via workspace scanning Not supported prior to 17.10
Path-specific instructions (.github/instructions/*.instructions.md) Supported with applyTo patterns Supported (requires enabling custom instructions) ✅ via workspace scanning Not supported prior to 17.10
Custom agents (.github/agents/*.agent.md) Supported from VS Code 1.106+. Supports handoffs for multi-agent orchestration. Not supported for chat; Visual Studio uses AGENTS.md, CLAUDE.md, or GEMINI.md for its async coding agent (creates PRs). ✅ via agent definitions Not available
Agent Skills (.github/skills/*/SKILL.md) Preview (v1.107+): Portable, resource-rich workflows. Cross-platform (VS Code, CLI, coding agent). Enable via chat.useAgentSkills. Not currently supported. ✅ via agent skills Not available
Chat modes (Agent, Plan, Ask, Edit) Built-in modes available via agent picker. Agent mode enables autonomous file editing; Plan mode creates implementation plans. Not applicable; Visual Studio has different interaction patterns. ❌ no editor UI Not available
Unified Agent Architecture (v1.107+) Agent HQ provides unified interface for local, background (work tree), and cloud agent sessions with seamless delegation. Cloud agents via Copilot coding agent (creates PRs). ⚠️ depends on app architecture Not available
Agent hooks (.github/hooks/*.json) Preview (v1.109.3+): Eight lifecycle events. Cross-compatible with Claude Code and Copilot CLI format. Not currently supported. ⚠️ depends on runtime Not available
MCP servers (mcp.json) MCP 1.0 GA (VS Code 1.102+). Features: Tasks, Sampling, Elicitation, Custom Icons. MCP Registry via @mcp search. GitHub MCP Server (Preview) built-in. Not currently supported. ✅ full support Not available
Copilot Spaces (GitHub.com) Preview: Persistent, shareable context collections (instructions, files, repos, links). Not tied to a single repo. Not currently supported. ❌ GitHub-hosted only Not available
BYOK / Model Management (v1.107+) Language Models Editor with BYOK support (Cerebras, OpenRouter, Ollama, etc.). HuggingFace extension for open-weights models. Not currently supported. ⚠️ via Copilot subscription models Not available
.github/copilot/ directory Optional; improves semantic search context. These files don’t create commands. Optional; improves local semantic search in Visual Studio. ✅ via workspace scanning Optional but not part of official features.

🗺️ Reading paths

New to Copilot customization?

  1. Start here — you’ve read this overview
  2. How to name and organize prompt files — set up your first .github/prompts/ folder
  3. How to structure content for Copilot prompt files — write your first prompt file
  4. How to structure content for Copilot instruction files — add project-wide rules

Want to understand how it all works?

Read the concept articles in order — each one builds on the previous:

  1. How Copilot assembles and processes prompts — the assembly architecture
  2. Understanding prompt files, instructions, and context layers — the three written customization types
  3. Understanding agents, invocation, handoffs, and subagents — agent identity and orchestration
  4. Understanding skills, hooks, and lifecycle automation — portable capabilities and deterministic enforcement
  5. Understanding MCP and the tool ecosystem — extending Copilot with external tools
  6. Understanding LLM models and model selection — model families and selection strategies
  7. Chat modes, Agent HQ, and execution contexts — how and where agents execute

Looking up specific settings?

Applied patterns and case studies

🎯 Conclusion

Key takeaways

  • The customization stack has seven layers — prompt files, instructions, agents, skills, hooks, MCP, and chat modes — each occupying a specific slot in the prompt assembly
  • Where your content lands determines how the model treats it — system prompt content is treated as rules, user prompt content as context
  • Progressive complexity works: start with instructions and prompt files, then add agents and skills as your workflows grow
  • Cross-platform support varies — VS Code has the richest feature set; Visual Studio supports prompts and instructions; SDK apps consume workspace files programmatically

Series navigation

This is the first article in the Prompt Engineering for GitHub Copilot series. Start with the reading paths above, or browse the full series ROADMAP.

📚 References

Official GitHub Copilot documentation

GitHub Copilot Documentation — Repository Instructions [📘 Official] Official GitHub documentation for customizing Copilot with repository-level instructions. Covers prompt files, instruction files, and AGENTS.md configuration. The authoritative source for understanding the specification behind the customization stack.

VS Code Copilot Customization Overview [📘 Official] Microsoft’s comprehensive guide to customizing GitHub Copilot in VS Code. Covers custom agents, instructions, prompt files, and MCP configuration. The authoritative source for VS Code-specific features and settings.

VS Code — GitHub Copilot Chat [📘 Official] VS Code’s official documentation for GitHub Copilot Chat features, including slash commands, context variables, and prompt file integration.

Visual Studio support

Visual Studio 2022 Release Notes — GitHub Copilot Features [📘 Official] Official release notes documenting when Copilot features were added to Visual Studio 2022. Version 17.10 introduced prompt files and custom instructions.

Visual Studio GitHub Copilot Documentation [📘 Official] Microsoft’s guide to using GitHub Copilot in Visual Studio, including configuration and how to enable custom instructions.

Community best practices

How to write a great AGENTS.md: Lessons from over 2,500 repositories [📗 Verified Community] Official GitHub blog post analyzing agent files to identify patterns that separate successful custom agents from failures.

How to use GitHub Copilot: Prompts, tips, and use cases [📘 Official] Official GitHub documentation covering prompt engineering best practices and effective communication patterns with Copilot.

Architecture and extensibility

Model Context Protocol (MCP) Specification [📘 Official] The protocol specification for connecting AI assistants to external data sources and tools. Foundation for the MCP sections in this series.

VS Code Agent Hooks Documentation [📘 Official] Official documentation for agent hooks — all eight lifecycle events, JSON configuration format, input/output schemas, and cross-platform compatibility.

VS Code release notes

VS Code v1.107 Release Notes [📘 Official] December 2024 release introducing Agent HQ, background agents, MCP 1.0, Language Models Editor with BYOK support, and Claude skills.

VS Code v1.106 Release Notes [📘 Official] November 2024 release that stabilized custom agents (.agent.md), introduced handoff workflows, and added the target field.

Research

Lost in the Middle: How Language Models Use Long Contexts [📗 Verified Community] Academic research (Liu et al., 2023, TACL) documenting the U-shaped attention pattern in transformer models. Foundational for understanding why instruction placement matters in the assembly architecture.