How to Name and Organize Prompt Files in Your GitHub Repository

A well-organized repository helps both developers and AI assistants like GitHub Copilot quickly locate the resources they need. Prompt files and their supporting documents benefit from predictable structures and conventions. This article synthesizes the latest GitHub Copilot, Visual Studio Code (VS Code) and Visual Studio documentation, along with community best practices, to provide clear guidance on naming and organizing Copilot-related files.

📁 Use the .github folder for team-shared prompts and instructions
💼 Organizing Local Context in .copilot (Optional)
� User Prompts in VS Code (Personal Prompt Library)
�💡 Additional Tips
📚 References

📁 Use the `.github` folder for team-shared prompts and instructions

GitHub Copilot looks in specific subfolders of .github/ to find prompt files, instructions and (in VS Code) custom agent definitions.

Path	Purpose
`.github/prompts/`	Workspace prompt files. Each `.prompt.md` file here becomes a slash-command (`/promptName` in VS Code) or a hashtag command (`#promptName` or `#prompt:<prompt-name>` in Visual Studio) when using Copilot Chat. This folder is recognized by VS Code and Visual Studio 2022 (version 17.10+). Older versions of Visual Studio (before 17.10) do not support prompt files. Note that prompt files must use the `.prompt.md` extension; there is no official support for a plain `.prompt` extension*. The `.prompt` extension (without `.md`) is not recognized by Copilot in VS Code or Visual Studio. Each file can start with YAML front matter specifying metadata (`name`, `description`, `agent`, `model`, `tools`, etc.) followed by the Markdown content of the prompt.
`.github/copilot-instructions.md`	Repository-level custom instructions. This file provides guidance on how Copilot should behave for your project (coding standards, tool preferences, naming conventions, etc.). It’s automatically applied to all chat requests when the “custom instructions” feature is enabled, and is supported by both VS Code and Visual Studio 17.10+.
`.github/instructions/`	Path- or language-specific instructions. Store one or more `.instructions.md` files here. Each file uses YAML front matter fields like `applyTo` to specify globs (e.g., `*/.cs`, `docs/*/.md`) that determine when the instructions should be applied. Supported in both VS Code and Visual Studio 17.10+.
`.github/agents/`	Custom agents for VS Code / Copilot CLI. In VS Code 1.106+ and Copilot CLI, `.agent.md` files here define specialized personas (e.g., “planning agent,” “test specialist”). Each file contains YAML frontmatter to declare allowed `tools`, a `description`, optional `handoffs` for workflow transitions, `model` selection, and a Markdown body describing the agent’s behavior. Legacy `.chatmode.md` files are still recognized but can be migrated using VS Code’s Quick Fix action. Note: This is different from `AGENTS.md` files (see below).
`AGENTS.md` (anywhere in repo)	Agent instructions for Copilot Coding Agent. You can create one or more `AGENTS.md` files stored anywhere in the repository. The nearest file in the directory tree takes precedence. Alternatively, you can use `CLAUDE.md` or `GEMINI.md` in the repository root. These files provide instructions for AI agents working on your codebase, supported in VS Code, Visual Studio, and GitHub.com. Note: `AGENTS.md` provides instructions to agents, while `.agent.md` files define custom agent personas.
`.github/copilot/`	Community convention for shared context. Some teams create a `.github/copilot/` folder to gather prompts and domain knowledge (e.g. `knowledge/`, `examples/`) in one place. Only a subfolder named `prompts/` under `.github` is recognized by default; other subfolders under `.github/copilot` serve as shared documentation and must be referenced manually in prompts or instructions.

Note about .prompt.yml files: GitHub also supports .prompt.yml or .prompt.yaml files for storing prompts intended for other GitHub AI tools (such as GitHub Models).
These YAML-based prompt files are not used by GitHub Copilot Chat in VS Code or Visual Studio.
For Copilot Chat, you must use the .prompt.md Markdown format.

Naming Guidelines for Prompt Files

Consistent naming: Use lowercase with hyphens or dots (e.g., create-react-form.prompt.md) to reflect the task or role. The filename or the YAML name becomes the slash/hashtag command.
Single purpose: Each prompt file should perform a distinct, cohesive task (e.g., “generate unit tests” or “review API security”). Avoid mixing unrelated tasks in one prompt.
Descriptive metadata: Include a description in the YAML header. VS Code and Visual Studio display this text when listing the prompt in the Chat UI. You can also set fields like agent (ask, edit, agent mode), model, tools, or argument-hint to refine prompt execution.

💼 Organizing Local Context in `.copilot` (Optional)

If you want Copilot to provide more project-aware suggestions, consider creating a .copilot/ directory at your repository root. While this is not an official requirement, it’s a community-recommended way to store detailed project documentation, domain concepts, architecture diagrams and other reference materials. Copilot’s semantic search will index the contents of .copilot/context/, making it more likely to find relevant documents when answering questions about your codebase.

A typical .copilot/context/ folder might include:

dataschemas/ – JSON or database schema docs.
apis/ – internal and external API contracts.
patterns/ – coding conventions (e.g., error handling, logging, testing guidelines).
workflows/ – business processes and flows.
guidelines/ – coding standards, architecture principles, security patterns.
images/ and examples/ – diagrams, charts and reference code.

These files do not create slash commands; instead, they enrich the context Copilot can draw upon.

👤 User Prompts in VS Code (Personal Prompt Library)

In addition to workspace prompts, VS Code supports user-scope prompt files that are available across all your projects. These personal prompts are stored in your VS Code profile directory:

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/

User prompt files:

Appear in Copilot Chat as slash commands (e.g., /my-personal-prompt) across all workspaces
Do not sync to your team via Git (they’re stored locally in your profile)
Can be shared across your own machines using VS Code’s Settings Sync feature
Follow the same .prompt.md format and YAML frontmatter as workspace prompts

Visual Studio does not currently support user-scope prompt files; it only recognizes workspace-level prompts in .github/prompts/.

💡 Additional Tips

Centralize general rules in .github/copilot-instructions.md, and use more granular .instructions.md files for narrower scopes (e.g. language-specific or directory-specific rules). Note that custom instructions must be enabled to be applied in Visual Studio or VS Code.
JetBrains IDE support: Prompt files are now supported in JetBrains IDEs (IntelliJ, PyCharm, etc.). You can create prompt files via the settings page under Tools > GitHub Copilot > Customizations, or manually in .github/prompts/. Use /promptName in chat to invoke them.
Link to project docs within your prompts or instructions using Markdown links, or use #fetch and #file references in VS Code to import remote or local content into Chat. (These tool references currently work in VS Code Chat; Visual Studio may not support every tool yet.)
Iterative improvement: Test prompts and update them based on feedback. Copilot’s responses are non-deterministic; small tweaks often change the quality of output. Encourage team members to contribute and refine prompts.

By following these naming and organization practices—and understanding where each file type is supported—you can ensure that GitHub Copilot operates consistently across your team’s tools and versions.

📚 References

Official GitHub Copilot Documentation

GitHub Copilot Custom Instructions [📘 Official]
This reference explains how to create repository-level custom instructions using .github/copilot-instructions.md to guide Copilot’s behavior across your project. It covers the syntax, best practices, and how these instructions are automatically applied to all chat requests when enabled. Essential for understanding how to standardize Copilot’s responses to match your team’s coding standards and conventions.
Using Prompt Files [📘 Official]
Learn how to create reusable prompt files in .github/prompts/ that become slash commands in VS Code or hashtag commands in Visual Studio. This guide covers the .prompt.md file format, YAML frontmatter options (including tools, agent, model, and variable references like ${selection}), and how to structure prompts for maximum reusability. Critical for teams wanting to create shared, discoverable prompts.
Path-Specific Instructions [📘 Official]
Documentation on using .github/instructions/ folder with .instructions.md files that apply to specific file patterns using glob syntax. This allows you to create granular rules that only apply to certain directories or file types, making your Copilot guidance more contextual and precise. Includes the new excludeAgent frontmatter option to control which agents use the instructions.

VS Code Copilot Features

VS Code Copilot Chat Documentation [📘 Official]
Comprehensive guide to using Copilot Chat in VS Code, including chat participants, slash commands, and context variables like #file and #fetch. Essential for understanding how to reference files and external resources within your prompts and how to leverage VS Code’s chat interface effectively.
Custom Agents in VS Code [📘 Official]
Documentation for creating custom agents using .agent.md files in .github/agents/. Explains how to define specialized AI personas with specific tools, behaviors, handoff capabilities for workflow transitions, and model selection. Custom agents (formerly “chat modes”) became stable in VS Code 1.106. Important for teams building advanced workflow automation with multiple specialized agents.

Visual Studio Copilot Features

GitHub Copilot in Visual Studio [📘 Official]
Microsoft’s official documentation for using GitHub Copilot in Visual Studio 2022 (version 17.10+). Covers hashtag commands, prompt files support, and custom instructions. Essential for teams using Visual Studio to understand platform-specific features and compatibility.
Prompt Files in Visual Studio [📘 Official]
Details on how Visual Studio implements prompt files with the hashtag command syntax and the differences from VS Code’s slash command approach. Important for cross-platform teams to understand how prompt files work consistently across different IDEs.

Community Best Practices

Awesome GitHub Copilot - Prompt Engineering [📒 Community]
Community-curated collection of resources, tips, and examples for working with GitHub Copilot. Includes practical prompt engineering techniques, repository organization patterns, and real-world examples from various teams. Valuable for discovering innovative approaches to prompt organization and learning from community experiences.
The .copilot Context Pattern [📒 Community]
GitHub code search results showing real-world implementations of the .copilot/context/ pattern. Explore how different teams organize domain knowledge, schemas, and reference materials to enhance Copilot’s contextual awareness. Useful for seeing practical examples of context organization strategies.

Semantic Search and Context

How GitHub Copilot Uses Context [📘 Official]
Explains how Copilot’s semantic search indexes your repository to find relevant context. Understanding this mechanism helps you organize documentation and reference materials in ways that maximize Copilot’s ability to find and use them effectively.
Workspace Context Best Practices [📘 Official]
VS Code documentation on how to structure your workspace to provide optimal context to Copilot. Covers file organization, documentation placement, workspace indexing (local and remote via GitHub/Azure DevOps), and the difference between @workspace and #codebase (the latter is now recommended for flexibility).

These references provide comprehensive coverage of GitHub Copilot’s file organization features, from official documentation to community best practices, ensuring you have authoritative sources for all recommendations in this article.

📎 Appendix A: Legacy .chatmode.md Migration

Deprecated as of: VS Code 1.106
Replaced by: .agent.md files in .github/agents/

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
Limited frontmatter fields	Extended frontmatter with `handoffs`, `target`, `mcp-servers`

Migration Steps

VS Code automatically recognizes legacy .chatmode.md files as custom agents
Open any .chatmode.md file and use the Quick Fix action (lightbulb) to migrate
The Quick Fix renames the file to .agent.md and moves it to .github/agents/
Update any team documentation referencing the old paths

New Frontmatter Fields

Custom agents now support additional configuration options:

---
description: Generate an implementation plan
name: Planner
tools: ['fetch', 'githubRepo', 'search']
model: Claude Sonnet 4
target: vscode  # or 'github-copilot' for remote agents
handoffs:
  - label: Start Implementation
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
mcp-servers:  # For github-copilot target only
  - name: my-server
    url: https://...
---

For detailed guidance on creating and structuring custom agent files, including persona design, tool configuration, and handoff workflows, see How to Structure Content for Copilot Agent Files.