How GitHub Copilot uses markdown and prompt folders within your repo

Learn how GitHub Copilot consumes prompt files, instructions, and agent definitions in VS Code and Visual Studio to enhance your development workflow
Author

Dario Airoldi

Published

December 26, 2025

How GitHub Copilot uses markdown and prompt folders within your repo

(For Visual Studio Code & Visual Studio)

GitHub Copilot’s generative AI is most effective when it has access to a structured context about your project.
Both Visual Studio Code (VS Code) and the latest versions of Visual Studio allow you to 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 explains how Copilot consumes these files in VS Code and Visual Studio, with clarifications based on updated official documentation and community practices.

Table of contents

📝 Prompt Files: What They Are and Where They Work

A prompt file is a reusable Markdown document (with a .prompt.md extension) that you can run as a slash- or hashtag-command in Copilot Chat.
It typically begins with an optional YAML header specifying metadata such as name, description, agent mode, preferred model and available tools.
The remainder is the prompt body, written in Markdown, containing the instructions or template you want Copilot to follow.
For example, a security audit prompt might instruct Copilot to review an API and output a list of vulnerabilities.

Prompt files were first introduced in VS Code and JetBrains IDEs.
and Visual Studio 2022 version 17.10 and later (including Visual Studio 2026).
In Visual Studio, you can reference these prompts by typing #prompt:<prompt-name> (or using the “+” icon) to attach the prompt to the chat.

Required Locations

  • .github/prompts/ (workspace prompts). This is the default folder for workspace-level prompt files and is recognized automatically by both VS Code and Visual Studio (17.10+). Any .prompt.md file here becomes available in Copilot Chat: in VS Code it appears as /promptName, and in Visual Studio it appears as #promptName or #prompt:<prompt-name>.
  • User prompt files (VS Code only). User-scope prompts are stored in a folder within your VS Code profile:
    • Windows: %APPDATA%\Code\User\prompts\ (stable) or %APPDATA%\Code - Insiders\User\prompts\ (Insiders)
    • macOS: ~/Library/Application Support/Code/User/prompts/
    • Linux: ~/.config/Code/User/prompts/
    These prompts are available across all your VS Code workspaces and appear as slash commands (e.g., /my-prompt). They do not synchronise to your team via Git, but you can enable VS Code’s Settings Sync to share them across your own machines. Visual Studio currently has no equivalent mechanism; it only consumes repository-level prompt files.

Prompt File Variables

Prompt files support variable substitution to make them dynamic and context-aware:

Variable Description
${selection} or ${selectedText} Currently selected text in the editor
${file} Full path of the current file
${fileBasename} Filename without path
${fileDirname} Directory containing the current file
${workspaceFolder} Root folder of the workspace
${workspaceFolderBasename} Name of the workspace folder
${input:variableName} Prompts user for input
${input:variableName:placeholder} User input with placeholder text

Example usage in a prompt file:

Analyze the following code from ${fileBasename}:
${selection}

Focus on: ${input:focus:What aspect should I focus on?}

Tool References in Prompts

Prompt files and instructions can reference specific tools using the #tool:<tool-name> syntax:

Use #tool:githubRepo to search for similar implementations.
Check #tool:terminalLastCommand for recent command output.

Common tool references:

  • #tool:githubRepo – Search GitHub repositories
  • #tool:terminalLastCommand – Access recent terminal output
  • #tool:problems – Get current workspace errors/warnings
  • #tool:codebase – Search the codebase semantically

Location not automatically supported

Some community blogs suggest grouping Copilot files under a .github/copilot/prompts/ folder. Officially, this location is not recognised by default. Both VS Code and Visual Studio expect prompt files in .github/prompts/ unless you change VS Code’s chat.promptFilesLocations setting to include the custom path. Visual Studio does not provide a configurable prompt-file location, so it cannot automatically read from .github/copilot/prompts/.

Important: Files stored in .github/copilot/prompts/ will not automatically show up in Copilot Chat unless you explicitly configure VS Code settings or manually attach them. The official, out-of-the-box location is .github/prompts/.

🏗️ Prompt Assembly Architecture

Before diving into each customization type, it’s worth understanding how VS Code assembles the final prompt that gets sent to the model. Every message you send in Copilot Chat triggers a multi-layered construction process—and knowing where each component lands helps you make better decisions about which customization mechanism to use.

System prompt (model context)

The system prompt is assembled first and sets the model’s identity, rules, and capabilities. It’s built in layers, from most general to most specific:

┌─────────────────────────────────────────────────────────────┐
│                    SYSTEM PROMPT                            │
├─────────────────────────────────────────────────────────────┤
│  1. Core identity and global rules                          │
│     "You are an expert AI programming assistant..."         │
│                                                             │
│  2. General instructions                                    │
│     Model-specific behavioral rules and quirks              │
│                                                             │
│  3. Tool use instructions                                   │
│     How to call tools, format parameters, handle results    │
│                                                             │
│  4. Output format instructions                              │
│     Markdown formatting, code block rules, link styles      │
│                                                             │
│  5. Custom instructions (.instructions.md files)            │
│     Your project-specific guidance (auto-injected)          │
│     ⚠️ copilot-instructions.md is always injected LAST      │
│                                                             │
│  6. Custom agent definition (.agent.md body)                │
│     Agent persona, workflow, and constraints                │
│     Only present when a custom agent is active              │
└─────────────────────────────────────────────────────────────┘

Key details:

  • Layers 1–4 are built-in—you don’t control them. VS Code generates them automatically.
  • Layer 5 is where your custom instructions go. If you have multiple .instructions.md files, they’re injected based on their applyTo patterns. The repository-wide copilot-instructions.md file is always appended last, giving it the final word on project conventions.
  • Layer 6 is where custom agents inject their persona and workflow. This only happens when a custom agent is active (selected in the agent picker). The agent body acts as a full identity override—it doesn’t just provide information, it tells the model who it is.

User prompt (your message + context)

The user prompt is assembled separately and contains everything specific to the current request:

┌─────────────────────────────────────────────────────────────┐
│                     USER PROMPT                             │
├─────────────────────────────────────────────────────────────┤
│  1. Prompt file contents (.prompt.md body)                  │
│     Only present when you invoke a prompt via /command      │
│                                                             │
│  2. Environment info                                        │
│     OS, IDE version, available extensions                   │
│                                                             │
│  3. Workspace info                                          │
│     Project structure, folder layout (text format)          │
│                                                             │
│  4. Context info                                            │
│     Current date/time, open terminals, attached files       │
│                                                             │
│  5. Your message                                            │
│     The actual text you type in the chat input              │
└─────────────────────────────────────────────────────────────┘

Key details:

  • Prompt files inject into the user prompt, NOT the system prompt. This is a critical distinction. Prompt files are treated as user-provided context, not as system-level rules. The model sees them as “the user is asking me to follow these instructions” rather than “these are my built-in rules.”
  • Environment and workspace info are auto-generated by VS Code so the model understands your development context.
  • Attached files (via #file:, drag-and-drop, or @workspace references) appear in the context info section.

Assistant response and the growing context window

Once the model responds, its output becomes part of the context window—the running conversation history. Each subsequent exchange appends more content:

┌─────────────────────────────────────────────────────────────┐
│                   CONTEXT WINDOW                            │
├─────────────────────────────────────────────────────────────┤
│  System prompt (persists across the session)                │
│  User message #1                                            │
│  Assistant response #1 (+ tool call results)                │
│  User message #2                                            │
│  Assistant response #2 (+ tool call results)                │
│  ...                                                        │
│  ⚠️ As this grows, earlier content loses influence          │
└─────────────────────────────────────────────────────────────┘

This growth is why starting new chat sessions frequently matters. As the context window fills, the model’s accuracy on earlier instructions degrades—a phenomenon called context rot. For a deeper treatment of this effect and strategies to manage it, see How to Manage Information Flow During Prompt Orchestrations and How to Optimize Token Consumption.

Why this matters for your customization choices

Understanding the assembly architecture helps you choose the right mechanism:

If you want to… Use Why
Set persistent project rules Custom instructions Injected into every request via the system prompt
Run a reusable workflow Prompt file Injected into the user prompt on demand
Give the model a new identity Custom agent Overrides the system prompt’s behavior layer
Route to a cheaper model Prompt file (model: field) Model routing without changing the active agent

The sections below cover each customization type in detail. As you read them, keep this assembly diagram in mind—it explains why custom instructions persist across requests (they’re in the system prompt) while prompt files don’t (they’re in the user prompt), and why custom agents feel like a different personality (they override the identity layer).

📚 Custom Instructions: Cross-IDE Context

To ensure Copilot respects project-specific rules and guidelines—such as your naming conventions, security requirements or testing standards—you can add custom instructions. These instructions are stored in Markdown files that Copilot automatically injects into every chat request.

  • .github/copilot-instructions.md is the repository-wide instructions file. Both VS Code and Visual Studio support this file, provided that the “Use Instruction Files” feature is enabled. The file should contain concise, self-contained statements about your project’s coding guidelines or tooling requirements. In Visual Studio, you must enable custom instructions in the Copilot settings (Tools > Options > GitHub > Copilot > Copilot Chat). Once enabled, instructions are injected into every chat request but remain hidden from view.

  • .github/instructions/ holds one or more .instructions.md files for path- or language-specific guidance. Each file can specify front-matter fields like applyTo to control which files or folders the instructions apply to (e.g., only **/*.cs for C# files). This feature is supported by both VS Code and Visual Studio 17.10+ (though Visual Studio requires the custom instructions feature to be enabled). Visual Studio 2022 versions prior to 17.10 do not support custom instructions.

Instructions File Frontmatter

---
applyTo: "**/*.ts"           # Glob pattern for matching files
excludeAgent: "code-review"   # Exclude from specific agents
---

The excludeAgent property controls which agents should NOT use these instructions:

  • "code-review" – Excludes instructions from Copilot code review
  • "coding-agent" – Excludes instructions from the GitHub Copilot coding agent

🤖 Chat Modes in VS Code

GitHub Copilot Chat provides four built-in chat modes accessible via the agent picker in the chat input:

alt text
Mode Description Use Case
Agent Autonomous mode that determines necessary changes and applies them directly to your workspace Complex multi-file refactoring, feature implementation
Plan Creates detailed implementation plans without modifying files (read-only) 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

These built-in modes supersede many custom multi-phase agent patterns that were previously required. For example, a three-phase “analyze → plan → implement” workflow can now be achieved by using Plan mode first, then switching to Agent mode for execution.

Unified Agent Architecture (v1.107+)

VS Code 1.107 introduced Agent HQ, a unified interface for managing agent sessions across three execution contexts:

Context Execution Isolation Best For
Local Interactive, in current workspace None—shares your workspace Quick tasks, interactive debugging
Background Runs autonomously using Git work trees Full—uses isolated work tree Long-running tasks without blocking workflow
Cloud Runs on GitHub, creates PRs Full—separate branch Async work, team collaboration, overnight tasks

alt text

Planning mode now integrates with agent delegation: After Plan mode generates an implementation plan, you can use the “Start Implementation” button to delegate execution to a local, background, or cloud agent.

For comprehensive coverage of Agent HQ, session management, work tree isolation workflows, and visual walkthroughs, see 📎 Appendix A: Unified Agent Architecture.

🔧 Custom Agents

Custom agents (previously called “chat modes”) allow you to define specialized AI personas with specific tools, instructions, and workflows. These are stored as .agent.md files and are available from VS Code 1.106+.

For comprehensive guidance on structuring agent files, defining personas, configuring tools, and creating handoff workflows, see How to Structure Content for Copilot Agent Files.

Agent File Locations

  • .github/agents/ – Workspace-level agents shared via Git with your team
  • User profile folder (VS Code only) – Personal agents available across all workspaces

Agent File Structure

Each .agent.md file includes:

  • YAML frontmatter specifying tools, model preferences, and target environment
  • Markdown body containing the agent’s persona, instructions, and workflow
  • Handoffs (optional) for orchestrating multi-step workflows between agents
---
name: security-auditor
description: Reviews code for security vulnerabilities
tools:
  - read_file
  - semantic_search
  - grep_search
model: claude-sonnet-4
target: vscode
---
You are a security expert. Analyze the provided code for:
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication bypasses
...

Supported frontmatter fields:

Field Description
name Agent identifier
description Brief description shown in agent picker
argument-hint Placeholder text in chat input
tools List of tools/tool sets the agent can use
model Preferred AI model (e.g., claude-sonnet-4, gpt-4o)
target Environment: vscode or github-copilot
mcp-servers MCP server configs (for github-copilot target)
user-invokable Boolean. Set to false to hide from agent picker (subagent-only). Default: true
disable-model-invocation Boolean. Set to true to prevent automatic subagent invocation. Default: false
agents Array of agent names available as subagents. Use * for all, [] for none
handoffs Workflow transitions to other agents

Handoffs: Multi-Agent Workflows

Handoffs enable orchestrating multi-step workflows between agents:

---
name: architect
description: Plans implementation approach
handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: Now implement the plan outlined above.
    send: false  # false = user reviews before sending
---

When the architect agent completes its task, the user sees a “Start Implementation” button to hand off to the implementer agent.

Practical Example: Creating a Documentation Agent

Here’s a complete example of creating a documentation review agent:

.github/agents/doc-reviewer.agent.md:

---
name: doc-reviewer
description: Reviews documentation for clarity and completeness
argument-hint: Path to documentation file
tools:
  - read_file
  - grep_search
  - semantic_search
model: claude-sonnet-4
target: vscode
---
You are a technical documentation expert. When reviewing documentation:

1. **Structure Check**: Verify proper heading hierarchy (H1 → H2 → H3)
2. **Completeness**: Ensure all code examples are tested and include output
3. **Clarity**: Flag jargon without definitions, identify unclear explanations
4. **References**: Verify all links are accessible and properly formatted

Provide specific line numbers and actionable recommendations.

Usage workflow:

  1. Save the file to .github/agents/doc-reviewer.agent.md
  2. Reload VS Code window (Cmd/Ctrl+Shift+P → “Developer: Reload Window”)
  3. Open the file you want to review
  4. In Copilot Chat, select @doc-reviewer from the agent picker
  5. Type: “Review this documentation file”

The agent will analyze structure, completeness, and clarity based on its instructions.

AGENTS.md vs .agent.md

Important distinction:

File Used By Execution Location
AGENTS.md GitHub Copilot coding agent Asynchronous (runs on GitHub, creates PRs) Repo root (or subfolders*)
CLAUDE.md Alternative to AGENTS.md Same as AGENTS.md Repo root
GEMINI.md Alternative to AGENTS.md Same as AGENTS.md Repo root
.agent.md VS Code chat agents Interactive (runs locally in IDE) .github/agents/

*Nested AGENTS.md files in subfolders are supported experimentally via the chat.useNestedAgentsMdFiles setting. The nearest file in the directory tree takes precedence.

Visual Studio uses AGENTS.md (or alternatives) for its coding agent integration but does not currently support .agent.md files for chat.

🎯 Agent Skills (Preview)

⚠️ Preview Feature: Agent Skills were introduced in VS Code 1.107 (December 2024) and are currently in Preview.

Agent Skills are a new way to extend Copilot with 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 Customizations

Feature Skills Instructions Prompts Agents
File SKILL.md in directory .instructions.md .prompt.md .agent.md
Activation Auto (description match) Auto (file pattern) On-demand (/name) Agent picker
Resources ✅ Templates, scripts ❌ 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
Handoffs ❌ Not supported ❌ Not supported ❌ Not supported ✅ Full

Skill Structure

.github/skills/skill-name/
├── SKILL.md                    # Required: Instructions + metadata
├── templates/                  # Optional: Reusable templates
├── examples/                   # Optional: Real-world examples
└── scripts/                    # Optional: Automation scripts

SKILL.md Format

---
name: webapp-testing                    # Required: lowercase, hyphens, max 64 chars
description: >                          # Required: max 1024 chars
  Generate test suites for React components using Jest.
  Use when writing tests, debugging failures, or setting up infrastructure.
---

# Web Application Testing Skill

## Purpose
[What this skill accomplishes]

## When to Use
[Scenarios that trigger this skill]

## Workflow
[Step-by-step procedure]

## Templates
Use [test template](./templates/component.test.js) as starting point.

Progressive Disclosure

Skills use three-level loading to optimize context consumption:

  1. Level 1 (Always): name + description (~50-100 tokens per skill)
  2. Level 2 (On match): SKILL.md body (~500-1500 tokens)
  3. Level 3 (On reference): Resource files (loaded only when needed)

Enabling Skills

// settings.json
{
  "chat.useAgentSkills": true
}

When to Use Skills vs Agents

Use Case Recommendation
Cross-platform workflow with templates Skill
Complex multi-agent orchestration Agent (handoffs)
VS Code-specific tool configuration Agent
Shareable community capabilities Skill (open standard)

For comprehensive guidance on creating skills, see How to Structure Content for Copilot Skills.

🪝 Agent Hooks (Preview)

⚠️ Preview Feature: Agent hooks were introduced in VS Code 1.109.3 and are currently in Preview.

Agent hooks 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.

Why hooks matter

Hooks are the enforcement layer for policies that instructions can only suggest:

  • Security enforcement — Block dangerous commands (rm -rf, DROP TABLE) before they execute
  • Code quality automation — Run formatters, linters, or tests after file modifications
  • Audit trails — Log every tool invocation for compliance and debugging
  • Context injection — Add project-specific information at session start
  • Approval control — Auto-approve safe operations, require confirmation for sensitive ones

Hook lifecycle events

VS Code supports eight hook events:

Event When it fires Common use cases
SessionStart First prompt of a new session Initialize resources, inject project context
UserPromptSubmit User submits a prompt Audit requests, inject system context
PreToolUse Before agent invokes any tool Block dangerous operations, modify tool input
PostToolUse After tool completes successfully Run formatters, log results
PreCompact Before context compaction Export important context, save state
SubagentStart Subagent is spawned Track nested agent usage
SubagentStop Subagent completes Aggregate results, cleanup
Stop Agent session ends Generate reports, send notifications

Configuration

Hooks are configured in JSON files stored in .github/hooks/*.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeout": 15
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

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

📘 Deep dive: See How to Use Agent Hooks for Lifecycle Automation for complete coverage of all eight events, input/output schemas, permission decisions, and practical patterns.

🔌 Model Context Protocol (MCP)

The Model Context Protocol (MCP) is now generally available in VS Code (1.102+). MCP provides a standardized way to connect Copilot to external data sources and tools.

What MCP Enables

  • Structured tool access – Connect to databases, APIs, cloud services
  • Typed data retrieval – Get data in formats Copilot can reason about
  • Reduced tool clash – Narrowly-scoped tool definitions prevent conflicts

MCP 1.0 Features (December 2024)

The MCP 1.0 anniversary release introduced production-ready features:

Feature Description
Tasks Durable, resumable operations that persist across sessions
Sampling MCP servers can request LLM completions from the client
Elicitation Servers can prompt users for input (URL mode, traditional dialogs)
Custom Icons Servers can provide icons for tools and resources

MCP Registry and Discovery

Discover MCP servers via @mcp search in the Extensions view. The curated registry includes servers for:

  • Playwright – Browser automation and testing
  • GitHub – Repository operations and issue management
  • Wikipedia – Knowledge base queries
  • Microsoft Learn – Azure and Microsoft documentation

One-click installation adds servers directly to your mcp.json configuration.

GitHub MCP Server (Preview)

VS Code 1.107 includes a built-in GitHub MCP server for remote agent operations:

Setting Description Default
github.copilot.chat.githubMcpServer.enabled Enable GitHub MCP server false
github.copilot.chat.githubMcpServer.toolsets Enable tool categories (issues, prs, repos, etc.) All enabled
github.copilot.chat.githubMcpServer.readonly Restrict to read-only operations false
github.copilot.chat.githubMcpServer.lockdown Limit to current repository only false

Configuration

MCP servers are configured via mcp.json files in your workspace or user settings. The GitHub MCP registry at github.com/mcp provides pre-built servers for common integrations.

{
  "servers": {
    "azure-devops": {
      "command": "npx",
      "args": ["@azure/mcp-server-ado"]
    }
  }
}

MCP is particularly valuable for building specialized agents that need access to external systems—such as an Azure DevOps agent that can query work items, or a database agent that can inspect schemas.

📘 Building your own MCP server? See How to Create MCP Servers for GitHub Copilot for implementation guides in TypeScript, C#, and Python.

🌐 Copilot Spaces — persistent context beyond the repo

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.

Spaces complement the repo-level mechanisms covered above: use .github/ and .copilot/ for project-specific rules, and Spaces for cross-project knowledge, team onboarding guides, or organizational standards.

📘 Deep dive: See Appendix G: Copilot Spaces for setup instructions, IDE integration, collaboration roles, and a decision guide on when to use Spaces vs. repo-level files.

🧰 GitHub Copilot SDK — Prompts Beyond the Editor

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 (@github/copilot-sdk), Python (github-copilot-sdk), Go, and .NET (GitHub.Copilot.SDK), the SDK connects to the Copilot CLI running in server mode via JSON-RPC.

Why this matters for prompt engineering

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

Key capabilities

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

For a deep dive into the SDK’s architecture and setup, see GitHub Copilot SDK — Building agents for any application. For a practical walkthrough of using prompts with the SDK, see How to Use Prompts with the GitHub Copilot SDK.

📁 Optional .copilot/ Folder: Enhancing Local Context

Although not part of the official specification, a practical .copilot/ directory can hold rich project documentation and reference materials to help Copilot understand your codebase. It may include subfolders such as:

  • context/ (e.g. data schemas, API contracts, code patterns, workflows, guidelines, examples) – Copilot will index files here and use them to inform its responses.
  • architecture/, troubleshooting/, examples/, images/, data/, reference/ – these are suggested subfolders used in some community guides. None of these files automatically generate chat commands; they simply improve the semantic search used by Copilot in both VS Code and Visual Studio.

⚙️ VS Code Settings Reference

The following settings control how VS Code handles Copilot customization files:

Prompt Files Settings

Setting Description Default
chat.promptFiles Enable/disable prompt file support true
chat.promptFilesLocations Additional folders to search for .prompt.md files []
chat.promptFilesRecommendations Show prompts as recommended actions when starting new chat true

Instructions Settings

Setting Description Default
chat.instructionsFilesLocations Additional folders to search for .instructions.md files []
github.copilot.chat.reviewSelection.instructions Custom instructions for code review []
github.copilot.chat.commitMessageGeneration.instructions Instructions for commit message generation []
github.copilot.chat.pullRequestDescriptionGeneration.instructions Instructions for PR description generation []

Agent Settings

Setting Description Default
chat.useNestedAgentsMdFiles Experimental: Enable AGENTS.md files in subfolders false
chat.useAgentSkills Preview: Enable Agent Skills from .github/skills/ false

MCP Settings

Setting Description Default
chat.mcp.discovery.enabled Auto-discover MCP servers from mcp.json files true
chat.mcp.gallery.enabled Enable the MCP server gallery in Extensions view true

Settings Sync

You can synchronize prompt files and instructions across devices using VS Code’s Settings Sync. Enable via: Settings Sync: Configure → Check Prompts and Instructions

🔑 Key Takeaways

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+. Each .agent.md defines a specialized persona, tools, and workflow. 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 with templates, checklists, and scripts. Cross-platform (VS Code, CLI, coding agent). Enable via chat.useAgentSkills. See article 06. 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. See Appendix A. 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 (PreToolUse, PostToolUse, SessionStart, Stop, SubagentStart, SubagentStop, PreCompact, UserPromptSubmit). Cross-compatible with Claude Code and Copilot CLI format. See article 09. 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—pulls from multiple sources. See Appendix G. 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. See Appendix D: BYOK. Not currently supported. ⚠️ via Copilot subscription models Not available
.github/copilot/ directory Optional; backed by community best practices for storing shared context, knowledge, patterns and examples. These files improve context but don’t create commands. Optional; improves local semantic search in Visual Studio. ✅ via workspace scanning Optional (if user chooses), but not part of official features.

By following these updated guidelines—placing prompt files in .github/prompts/ with a .prompt.md suffix, activating instruction files appropriately, and using a .copilot/ folder for extended context—you can leverage GitHub Copilot effectively across VS Code, the latest Visual Studio versions, and SDK-based applications.

📚 References

Official GitHub Copilot Documentation

GitHub Copilot Documentation - Repository Instructions [📘 Official]
The official GitHub documentation for customizing Copilot with repository-level instructions. Covers prompt files (.prompt.md), instruction files (.github/copilot-instructions.md and .github/instructions/), and AGENTS.md configuration. Essential reading for understanding the official specification and best practices.

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

Visual Studio Code - GitHub Copilot Chat [📘 Official]
VS Code’s official documentation for GitHub Copilot Chat features, including slash commands, context variables, and prompt file integration. Provides practical examples of using Copilot within the VS Code environment and configuring chat settings.

Visual Studio Support

Visual Studio 2022 Release Notes - GitHub Copilot Features [📘 Official]
Official Microsoft release notes documenting when GitHub Copilot features were added to Visual Studio 2022. Version 17.10 introduced support for prompt files and custom instructions. Essential for understanding feature compatibility across different Visual Studio versions.

Visual Studio GitHub Copilot Documentation [📘 Official]
Microsoft’s comprehensive guide to using GitHub Copilot in Visual Studio, including configuration, chat features, and how to enable custom instructions through Tools > Options > GitHub > Copilot settings. Relevant for Visual Studio users who need to configure Copilot properly.

Community Best Practices and Patterns

How to use GitHub Copilot: Prompts, tips, and use cases [📘 Official]
Official GitHub documentation covering prompt engineering best practices, effective communication patterns with Copilot, and real-world use cases. Includes examples of clear instructions, providing context, and breaking down complex tasks for optimal results.

How to write a great AGENTS.md: Lessons from over 2,500 repositories [📗 Verified Community]
Official GitHub blog post analyzing over 2,500 agent.md files to identify patterns that separate successful custom agents from failures. Covers the six core areas (commands, testing, project structure, code style, git workflow, and boundaries) with practical templates and real-world examples.

VS Code Agent Mode Documentation [📘 Official]
Documentation for the Agent mode in VS Code that enables autonomous file editing and code generation. Explains how Agent mode, combined with Plan mode, provides powerful multi-step workflows.

Additional Context and Architecture

VS Code API - Chat Extension Guide [📘 Official]
For developers building VS Code extensions that integrate with Copilot Chat. Explains the chat API, participant patterns, and how extensions can contribute custom slash commands. Relevant for understanding the extensibility model and how prompt files fit into the broader VS Code chat architecture.

GitHub Copilot Trust Center [📘 Official]
Official resource covering security, privacy, and data handling in GitHub Copilot. Important for understanding how your prompts, instructions, and code context are processed, what data is sent to GitHub, and compliance considerations for enterprise use.

Agent Hooks and Lifecycle

VS Code Agent Hooks Documentation [📘 Official]
Official VS Code documentation for agent hooks. Covers all eight lifecycle events, JSON configuration format, input/output schemas, permission decisions in PreToolUse, cross-platform compatibility with Claude Code and Copilot CLI, and security considerations.

Model Context Protocol and Tools

Model Context Protocol (MCP) Specification [📘 Official]
The protocol specification for connecting AI assistants to external data sources and tools. MCP provides structured, typed access to external systems, enabling narrowly-scoped tool definitions that reduce tool clash and improve reliability.

VS Code MCP Servers Documentation [📘 Official]
Official VS Code documentation for configuring MCP servers. Explains how to set up mcp.json files and connect Copilot to external data sources like databases, cloud services, and APIs.

VS Code Release Notes

VS Code v1.107 Release Notes [📘 Official]
December 2024 release introducing Agent HQ unified interface, background agents with work tree isolation, MCP 1.0 features (Tasks, Sampling, Elicitation), GitHub MCP Server (Preview), enhanced Language Models Editor with BYOK support, and Claude skills integration. Essential reading for understanding the latest agentic development capabilities.

VS Code v1.106 Release Notes [📘 Official]
November 2024 release that made custom agents (.agent.md files) stable, introduced handoff workflows between agents, and added the target field for distinguishing VS Code vs GitHub Copilot execution contexts.

HuggingFace for VS Code Extension [📘 Official]
Official extension for using HuggingFace models in VS Code Copilot Chat. Provides access to open-weights models (Llama, Mistral, DeepSeek, Qwen) via multiple inference providers with automatic cost/speed optimization.

Prompt Engineering Fundamentals

Prompt engineering techniques - Microsoft Azure AI [📘 Official]
Microsoft’s comprehensive guide to prompt engineering techniques covering instruction design, primary content structuring, few-shot learning, and output specification. Includes detailed examples of breaking down tasks, specifying output structures, temperature settings, and grounding context. Note: These techniques apply to GPT models; reasoning models (gpt-5, o-series) require different approaches.

Prompt engineering - OpenAI [📘 Official]
OpenAI’s official prompt engineering guide providing foundational strategies for working with GPT models. Covers core techniques including instruction clarity, systematic approaches to prompt construction, and best practices for reducing hallucination.

Reasoning best practices - OpenAI [📘 Official]
OpenAI’s guidance on best practices for reasoning models (o-series). Explains when to use reasoning models vs GPT models, covering seven use case categories including needle-in-haystack retrieval, visual reasoning, code review, and multistep planning. Emphasizes keeping prompts simple and avoiding chain-of-thought instructions.

Research

Lost in the Middle: How Language Models Use Long Contexts [📗 Verified Community]
Academic research (Liu et al., 2023, TACL) on context window attention patterns, documenting the phenomenon where models under-weight middle content in long contexts. Performance is significantly better when relevant information appears at beginning or end of prompts. Foundational research for understanding why commands should be placed early in prompts and why context placement matters for agent instructions.

📎 Appendices

Detailed reference appendices have been extracted to a dedicated file for better maintainability:

📎 Appendices A–F: Getting started reference material

  • Appendix A — Unified Agent Architecture (v1.107+): Agent HQ, session contexts, work tree isolation, plan-to-delegate workflows
  • Appendix B — Deprecated VS Code Settings: migration from codeGeneration.instructions / testGeneration.instructions
  • Appendix C — Feature Compatibility Matrix: JetBrains file support and global instructions paths
  • Appendix D — Bring-Your-Own-Key Model Management: Language Models Editor, BYOK providers, HuggingFace integration
  • Appendix E — Legacy .chatmode.md Migration: renaming and folder changes
  • Appendix F — JetBrains IDE Support: file locations and differences from VS Code

📎 Appendix G: Copilot Spaces (separate file)