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.
As of Visual Studio 2022 version 17.10 and later (including Visual Studio 2026), Visual Studio also supports prompt files stored under .github/prompts with a .prompt.md extension.
In Visual Studio, you can reference these prompts by typing #prompt:<prompt-name> (or using the “+” icon) to attach the prompt to the chat.
For earlier Visual Studio versions (pre-17.10), prompt files are not recognized.

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} Currently selected text in the editor
${selectedText} Alias for ${selection}
${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/.

📚 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:

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.

🔧 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)
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.

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.

🔌 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

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.

📁 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

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+) 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) 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 Not applicable
Repo-level instructions (.github/copilot-instructions.md) Supported (requires enabling the “Use Instruction Files” setting) Supported (requires enabling custom instructions in options) Not supported prior to 17.10
Path-specific instructions (.github/instructions/*.instructions.md) Supported with applyTo patterns Supported (requires enabling custom instructions) 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). 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. Not available
MCP servers (mcp.json) Generally available (VS Code 1.102+). Connect to external data sources and tools via Model Context Protocol. Not currently supported. 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. 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 both VS Code and the latest Visual Studio versions.

🔗 References

Official GitHub Copilot Documentation

GitHub Copilot Documentation - Repository Instructions
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
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
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 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
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

GitHub Blog - How to use GitHub Copilot: Prompts, tips, and use cases
GitHub’s official blog post covering prompt engineering best practices, effective communication patterns with Copilot, and real-world use cases. Valuable for understanding how to write effective prompts and structure your instructions for optimal results.

How to write a great AGENTS.md: Lessons from over 2,500 repositories
Comprehensive analysis of over 2,500 agent.md files identifying 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
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
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 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.

Model Context Protocol and Tools

Model Context Protocol (MCP) Specification
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 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.

Prompt Engineering Fundamentals

Prompt engineering techniques - Microsoft Azure AI
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 and specifying output structures.

Prompt engineering - OpenAI
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
OpenAI’s guidance on best practices for reasoning models, covering chain-of-thought prompting, step-by-step breakdowns, and techniques for improving model accuracy.

Research

Lost in the Middle: How Language Models Use Long Contexts
Academic research on context window attention patterns, documenting the phenomenon where models under-weight middle content. Foundational research for understanding why commands should be placed early in prompts and why context placement matters.

📎 Appendix A: Legacy .chatmode.md Migration

Prior to VS Code 1.106, custom agents were called “chat modes” and used different file conventions:

Legacy Current
.chatmode.md extension .agent.md extension
.github/chatmodes/ folder .github/agents/ folder

Migration Steps

  1. VS Code automatically recognizes legacy .chatmode.md files
  2. A Quick Fix action appears to migrate files to the new format
  3. Rename files from *.chatmode.md to *.agent.md
  4. Move files from .github/chatmodes/ to .github/agents/

Recommendation: Migrate to the new format for consistency with current documentation and to ensure future compatibility.

📎 Appendix B: JetBrains IDE Support

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support GitHub Copilot with their own conventions:

Supported Files

File Type Location Notes
Workspace instructions .github/copilot-instructions.md Same as VS Code/Visual Studio
Global instructions OS-specific path (see below) Personal instructions across all projects
Prompt files .github/prompts/*.prompt.md Invoked via /promptName commands

Global Instructions Location

OS Path
Windows %APPDATA%\JetBrains\<product><version>\copilot\global-copilot-instructions.md
macOS ~/Library/Application Support/JetBrains/<product><version>/copilot/global-copilot-instructions.md
Linux ~/.config/JetBrains/<product><version>/copilot/global-copilot-instructions.md

Replace <product><version> with your IDE (e.g., IntelliJIdea2024.3, PyCharm2024.3).

Differences from VS Code

  • JetBrains does not support .agent.md files (custom agents)
  • JetBrains does not support MCP server configuration
  • Path-specific .instructions.md files work the same as VS Code
  • Prompt files use /promptName syntax (same as VS Code)

📎 Appendix C: Deprecated VS Code Settings

The following settings are deprecated as of VS Code 1.102. Use .instructions.md files instead:

Deprecated Setting Migration
github.copilot.chat.codeGeneration.instructions Use .github/instructions/*.instructions.md with applyTo patterns
github.copilot.chat.testGeneration.instructions Use .github/instructions/*.instructions.md with applyTo patterns

Recommendation: Remove these deprecated settings from your VS Code configuration and migrate to instruction files for better maintainability and version control.

Last updated: December 2025