How to Name and Organize Prompt Files in Your GitHub Repository
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.
Table of Contents
- π Use the
.githubfolder for team-shared prompts and instructions - πΌ Organizing Local Context in
.copilot(Optional) - π€ User Prompts in VS Code (Personal Prompt Library)
- π‘ Additional Tips
- π― Agent Skills (VS Code 1.107+ Preview)
- π¦ Supporting Assets: Snippets and Templates
- β οΈ Common Mistakes
- π References
- π Appendix A: Legacy .chatmode.md Migration
πΌ 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/andexamples/β 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.mdformat 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.mdfiles 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/promptNamein chat to invoke them. - Link to project docs within your prompts or instructions using Markdown links, or use
#fetchand#filereferences 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.
π― Agent Skills (VS Code 1.107+ Preview)
Agent Skills are a Preview feature introduced in VS Code 1.107 that enable portable, resource-rich workflows bundling instructions with templates, scripts, and examples. Unlike prompts (on-demand slash commands) or instructions (file-pattern rules), skills are discovered based on their description and can reference bundled resources following the open agentskills.io standard.
Skills vs. Other Resource Types
| Resource Type | Trigger | Scope | Bundled Resources |
|---|---|---|---|
Prompts (.prompt.md) |
Explicit /command or #command |
Single task | β None |
Instructions (.instructions.md) |
File pattern match (applyTo) |
Always-on rules | β None |
Agents (.agent.md) |
Explicit @agent mention |
Persona with tools | β None |
Skills (SKILL.md) |
Description-based discovery | Complex workflow | β Templates, scripts, examples |
Directory Structure
Each skill lives in its own subdirectory under .github/skills/:
.github/skills/
βββ article-review/
β βββ SKILL.md # Required: Instructions + metadata
β βββ templates/ # Optional: Reusable output templates
β β βββ review-summary.md
β βββ checklists/ # Optional: Structured checklists
β β βββ validation-checklist.md
β βββ examples/ # Optional: Real-world examples
β βββ sample-review.md
βββ webapp-testing/
β βββ SKILL.md
β βββ templates/
β β βββ test-scaffold.ts
β βββ scripts/ # Optional: Automation scripts
β βββ setup-test-env.sh
SKILL.md Frontmatter
The SKILL.md file requires YAML frontmatter with two essential fields:
---
name: article-review # Required: lowercase, hyphens, max 64 chars
description: > # Required: max 1024 chars
Comprehensive article review workflow for technical documentation.
Use when reviewing markdown articles, validating structure,
checking reference classifications, or preparing content for publication.
---Name Field Rules
| β Valid | β Invalid | Reason |
|---|---|---|
article-review |
Article Review |
No uppercase/spaces |
webapp-testing |
test |
Too generic |
k8s-deploy |
a-skill-name-that-exceeds-the-64-character-limit-check |
Too long |
Description Field Formula
Structure: [What it does] + [Technologies] + "Use when" + [Scenarios]
# β
Good - specific with use cases
description: >
Generate test suites for React components using Jest and RTL.
Use when writing unit tests, debugging failures, or setting up test infrastructure.
# β Bad - vague, no technologies, no scenarios
description: Helps with testingProgressive Loading System
Skills use a three-level loading system for efficient token usage:
| Level | What Loads | When | Token Impact |
|---|---|---|---|
| 1. Discovery | name + description from YAML |
Always indexed | ~50-100 tokens/skill |
| 2. Instructions | SKILL.md body content | Prompt matches description | ~500-1500 tokens |
| 3. Resources | Templates, examples, scripts | Copilot references them | Loaded on-demand |
This means your description field is criticalβit determines whether the skill gets activated and its full instructions loaded.
SKILL.md Body Content
After the YAML frontmatter, include structured instructions:
---
name: article-review
description: >
Comprehensive article review workflow for technical documentation.
Use when reviewing markdown articles or preparing content for publication.
---
# Article Review Skill
## Purpose
Perform comprehensive quality reviews of technical documentation articles.
## When to Use
Activate this skill when:
- **Reviewing articles**: "Review this article for publication readiness"
- **Checking structure**: "Validate the structure of this markdown file"
- **Quality assessment**: "Assess the quality of this technical documentation"
Do NOT use this skill for:
- Grammar checking (use grammar-review prompt instead)
- Code review (use code-review skill instead)
## Workflow
### Step 1: Structure Validation
Check that the article includes all required sections:
- [ ] Title (H1 heading at the start)
- [ ] Table of Contents (for articles > 500 words)
- [ ] References section with classified sources
### Step 2: Content Quality Checks
Review for:
- [ ] Active voice usage
- [ ] Proper markdown formatting
- [ ] Code examples with language identifiers
## Templates
- [Review Summary Template](./templates/review-summary.md)
- [Validation Checklist](./checklists/validation-checklist.md)Cross-Platform Compatibility
Skills work across multiple platforms:
| Platform | Discovery | Instructions | Scripts |
|---|---|---|---|
| VS Code Chat | β | β | β οΈ Requires approval |
| Copilot CLI | β | β | β οΈ Requires approval |
| GitHub Coding Agent | β | β | β οΈ Requires approval |
Portability checklist:
- Use relative paths only (no absolute paths)
- Include all resources in skill directory (no external URLs)
- Make scripts cross-platform when possible
- Test activation with various prompt phrasings
Storage Locations
Personal Skills (User-Level)
~/.copilot/skills/skill-name/SKILL.md # Recommended
~/.claude/skills/skill-name/SKILL.md # Legacy
When to Use Skills vs. Prompts
Use Skills when:
- β Workflow requires bundled resources (templates, scripts, examples)
- β Task is complex with multiple steps and validation phases
- β Same workflow needs to work across VS Code, CLI, and Coding Agent
- β Team needs portable, self-contained packages
Use Prompts when:
- β Task is simple and self-contained (single action)
- β No additional resources needed beyond the prompt text
- β
Explicit invocation via
/commandis preferred
π¦ Supporting Assets: Snippets and Templates
Beyond the core prompt, instruction, and agent files, GitHub Copilot ecosystems often include prompt snippets and templates to streamline development workflows. Understanding when to use each asset typeβand where to store themβhelps teams build reusable, discoverable resources.
Prompt Snippets
Prompt snippets are reusable text fragments designed to be inserted into chat conversations or combined with other prompts. Unlike full .prompt.md files, snippets are not standalone commands; they serve as building blocks for larger prompts or documentation.
When to Use Prompt Snippets
| Use Case | Example |
|---|---|
| Repeated context blocks | Standard project architecture descriptions, technology stack summaries |
| Common instructions | Code style reminders, testing requirements, security checklist items |
| Boilerplate questions | βExplain the error handling approachβ, βDocument the API contractβ |
| Domain vocabulary | Business-specific terminology, acronym definitions, concept explanations |
Where to Store Snippets
Recommended location: .github/prompt-snippets/ or .copilot/snippets/
.github/
βββ prompt-snippets/
β βββ architecture-context.md
β βββ security-checklist.md
β βββ testing-standards.md
β βββ domain-glossary.md
Snippet file characteristics:
- β No YAML frontmatter - Snippets are raw content, not executable commands
- β Not indexed as slash commands - Must be manually referenced
- β Composable - Multiple snippets can be combined in one conversation
- β Lightweight - Short, focused fragments (typically < 50 lines)
How to Reference Snippet Files
GitHub Copilot does not have automatic βincludeβ syntax. To use snippet files, reference them explicitly:
Method 1: File Reference in Chat (VS Code)
Please review this code for security issues.
#file:.github/prompt-snippets/security-checklist.mdβ
Best for: Interactive chat conversations, ad-hoc queries
β
Guarantees: Content is definitely included in context
Method 2: Markdown Link (Unreliable)
Please review this code following our [security checklist](.github/prompt-snippets/security-checklist.md).β οΈ Note: Copilot may or may not automatically read linked files
β Not recommended for critical content that must be included
Method 3: Copy-Paste When Executing
Please review this code for security issues.
## Security Checklist
[Manually paste security-checklist.md content here when running prompt]β
Best for: Ensuring snippet content is definitely included
β
Use when: #file reference isnβt working reliably
Snippets vs. Embedded Content
When to use snippet files (reusable across prompts):
- β Content is used by multiple prompts
- β Shared team knowledge (architecture, standards, checklists)
- β Content needs separate maintenance from prompts
- β Changes should propagate to all prompts using it
When to embed content directly (single prompt use):
- β Content is specific to one prompt only
- β Content is not reused elsewhere
- β Prompt should be self-contained
- β No need for separate file management
Example: Embedded content (NOT using snippets):
---
name: security-review-api-only
description: Security review focused specifically on REST API endpoints
---
Review this API code for security issues using this checklist:
## API-Specific Security Checklist
- [ ] Input validation on all parameters
- [ ] SQL injection prevention (parameterized queries)
- [ ] Authentication on protected routes
- [ ] Rate limiting configured
- [ ] CORS properly configured
[... content embedded directly, not shared with other prompts ...]Example: Using snippet file (reusable):
# In chat or prompt:
Review this code for security issues.
#file:.github/prompt-snippets/security-checklist.mdTemplates
Templates come in two flavors with different purposes:
1. Generated Templates (Output Templates)
Definition: Structures that prompts generate as output (e.g., code scaffolds, documentation skeletons, configuration files).
Examples:
- React component template (what a βgenerate componentβ prompt creates)
- API endpoint structure (what a βcreate REST endpointβ prompt produces)
- Test file layout (what a βscaffold testsβ prompt outputs)
Storage: Reference these in prompt instructions, but donβt store as separate files unless needed for consistency.
Example in prompt file:
---
name: create-react-component
description: Generate a React component with TypeScript
---
Create a functional React component following this structure:
```tsx
import React from 'react';
import styles from './${componentName}.module.css';
interface ${componentName}Props {
// Props here
}
export const ${componentName}: React.FC<${componentName}Props> = (props) => {
return (
<div className={styles.container}>
{/* Component implementation */}
</div>
);
};
```
Include PropTypes and a basic test file.2. Reusable Templates (Input Templates)
Definition: Starting points for creating new prompt files, agent files, or instruction filesβtemplates you copy and fill in.
Examples:
- Blank
.prompt.mdtemplate with standard YAML fields - Agent definition template with common tools and handoffs
- Instruction file template with
applyTopattern examples
Recommended location: .github/templates/ or .copilot/templates/
.github/
βββ templates/
β βββ prompt-template.md
β βββ agent-template.md
β βββ instruction-template.md
β βββ README.md # Explains when to use each template
Example: .github/templates/prompt-template.md
---
name: [prompt-name]
description: [Brief description of what this prompt does]
agent: [ask|edit|agent] # Optional: specify agent mode
model: [Model name] # Optional: Claude Sonnet 4, GPT-4, etc.
tools: [tool1, tool2] # Optional: limit available tools
argument-hint: [hint] # Optional: help text for arguments
---
# [Prompt Title]
[Clear description of the task this prompt performs]
## Context
[Any background information Copilot needs]
## Instructions
1. [Step-by-step instructions]
2. [Be specific and actionable]
## Output Format
[Describe the expected output structure]
## Example
[Optional: provide an example of the desired result]Decision Framework: Snippet vs. Template vs. Full Prompt vs. Skill
| Asset Type | Purpose | Reusability | Discoverability | Typical Size |
|---|---|---|---|---|
| Prompt Snippet | Context fragment for composition | High (included in multiple prompts) | Low (not indexed) | < 50 lines |
| Generated Template | Output structure definition | Medium (referenced in prompts) | Medium (via prompt docs) | Varies |
| Input Template | Starting point for new files | Low (copy-once) | Low (team documentation) | ~50 lines |
| Full Prompt | Standalone executable task | High (team-wide command) | High (slash/hashtag command) | 50-500 lines |
| Agent Skill | Complex workflow with resources | High (portable across platforms) | High (description-based discovery) | SKILL.md + bundled resources |
Organization Best Practices
1. Clear Separation
Donβt mix snippets, templates, skills, and prompts in the same folder:
β BAD: Everything mixed together
.github/prompts/
βββ create-component.prompt.md
βββ security-checklist.md # Is this a snippet or a prompt?
βββ template.md # What kind of template?
βββ SKILL.md # Wrong location for skills!
β
GOOD: Clear folder structure
.github/
βββ prompts/ # Executable prompt files
β βββ create-component.prompt.md
βββ prompt-snippets/ # Reusable fragments
β βββ security-checklist.md
βββ templates/ # Starting point files
β βββ prompt-template.md
βββ skills/ # Agent skills with resources
βββ article-review/
βββ SKILL.md
βββ templates/
2. Document Usage
Include a README.md in each folder explaining:
- What files are stored there
- How to use them (copy, include, reference)
- When to create new files vs. using existing ones
3. Version Control for Templates
When you update an input template, existing files created from that template are not automatically updated. Consider:
- Documenting template versions in the template file itself
- Creating migration guides when templates change significantly
- Using prompts to standardize existing files when templates evolve
Example:
---
# Template Version: 2.1
# Last Updated: 2025-12-25
# Changelog: Added 'tools' and 'model' fields, removed deprecated 'mode' field
---4. Snippet Composition Patterns
Pattern 1: Inline inclusion via #file (VS Code only)
Please analyze this code. #file:.github/prompt-snippets/security-checklist.md
Pattern 2: Manual copy-paste
Review the following for security issues:
[Content of security-checklist.md pasted here]Pattern 3: Reference in prompt YAML Pattern 4: Markdown link (may work, less reliable)
Follow the guidelines in [security-checklist.md](.github/prompt-snippets/security-checklist.md).Common Patterns
Snippets for Domain Context
.copilot/snippets/
βββ business-rules.md # Company-specific policies
βββ architecture-overview.md # System architecture summary
βββ tech-stack.md # Technology choices and versions
Use case: Include in multiple prompts requiring domain knowledge without duplicating content.
Templates for Consistency
.github/templates/
βββ feature-prompt.md # Template for feature implementation prompts
βββ review-prompt.md # Template for code review prompts
βββ refactor-prompt.md # Template for refactoring prompts
Use case: Ensure all team members create prompts with consistent structure.
Generated Templates in Prompts
---
name: scaffold-api-endpoint
---
Create a new API endpoint with this structure:
[Controller template code]
[Service template code]
[Test template code]
Replace placeholders with actual implementation.Use case: Standardize generated code structures without requiring separate template files.
Key Takeaways
- Snippets = Reusable context fragments included in other prompts
- Generated Templates = Structures that prompts output (code scaffolds, docs)
- Input Templates = Starting points for creating new prompt/agent/instruction/skill files
- Full Prompts = Standalone executable commands with YAML frontmatter
- Agent Skills = Portable workflows bundling SKILL.md with templates, scripts, and examples (VS Code 1.107+)
Store snippets and templates in dedicated folders, document their usage, and version them when they change. This organization ensures your team can easily find, reuse, and maintain supporting assets alongside core prompt files.
β οΈ Common Mistakes
Even with clear guidance on file organization, teams frequently make mistakes that reduce discoverability, create maintenance burdens, or cause confusion. Here are the most common organizational pitfalls and how to avoid them.
Mistake 1: Mixing File Types in the Same Folder
Problem: Storing prompts, snippets, templates, and documentation in the same folder makes it unclear which files are executable commands versus reference materials.
β Bad example:
.github/prompts/
βββ create-component.prompt.md # Executable prompt
βββ security-checklist.md # Is this a prompt or a snippet?
βββ template.md # What kind of template?
βββ architecture-notes.md # Documentation?
βββ README.md
β Solution: Separate by type with clear folder structure:
.github/
βββ prompts/ # Only executable .prompt.md files
β βββ create-component.prompt.md
βββ prompt-snippets/ # Reusable fragments
β βββ security-checklist.md
βββ templates/ # Starting point files
β βββ prompt-template.md
βββ docs/ # Team documentation
βββ architecture-notes.md
Mistake 2: Inconsistent Naming Conventions
Problem: Team members use different naming styles, making prompts hard to discover and remember.
β Bad examples:
.github/prompts/
βββ CreateReactComponent.prompt.md # PascalCase
βββ generate_unit_tests.prompt.md # snake_case
βββ ReviewAPI.prompt.md # Abbreviated, unclear
βββ refactor-code-for-performance.prompt.md # Too verbose
β Solution: Establish team convention (kebab-case recommended):
.github/prompts/
βββ create-react-component.prompt.md # Clear, concise, kebab-case
βββ generate-unit-tests.prompt.md # Consistent pattern
βββ review-api-security.prompt.md # Full words, not abbreviated
βββ refactor-performance.prompt.md # Descriptive but concise
Naming guidelines:
- Use kebab-case (lowercase with hyphens)
- Start with action verb (
create,generate,review,refactor) - Include domain/technology when relevant (
react,api,database) - Keep under 5 words for command brevity
Mistake 3: Wrong Extension or Location
Problem: Using incorrect file extensions or storing files in unrecognized locations prevents Copilot from discovering them.
β Bad examples:
.github/
βββ copilot/prompts/ # Wrong: Copilot doesn't scan here
β βββ my-prompt.prompt.md
βββ prompts/
β βββ another-prompt.prompt # Wrong: Missing .md extension
β βββ yet-another.md # Wrong: Missing .prompt part
βββ my-instructions.md # Wrong: Should be copilot-instructions.md
β Solution: Use official paths and extensions:
.github/
βββ prompts/ # Correct location
β βββ my-prompt.prompt.md # Correct: .prompt.md extension
βββ copilot-instructions.md # Correct: exact filename
βββ instructions/
βββ python-rules.instructions.md # Correct: .instructions.md extension
Critical rules:
- Prompt files:
.github/prompts/*.prompt.md(not.promptalone) - Repository instructions:
.github/copilot-instructions.md(exact name) - Path-specific instructions:
.github/instructions/*.instructions.md - Agents (VS Code):
.github/agents/*.agent.md
Mistake 4: No README or Documentation
Problem: New team members donβt know which prompts exist, what they do, or when to use them.
β Bad example:
.github/prompts/
βββ p1.prompt.md
βββ p2.prompt.md
βββ p3.prompt.md
βββ p4.prompt.md
No explanation of purpose, no usage examples, no maintenance notes.
β Solution: Add README.md in each folder:
<!-- .github/prompts/README.md -->
# Team Prompts
## Available Prompts
| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/create-react-component` | Generate functional React component | Creating new UI components |
| `/generate-unit-tests` | Create Jest tests for selected code | After writing new functions |
| `/review-api-security` | Security audit for API endpoints | Before deploying API changes |
## Usage
1. Open Copilot Chat
2. Type `/` to see available prompts
3. Select prompt or type `/promptName`
4. Provide required context (selection, arguments)
## Adding New Prompts
See `.github/templates/prompt-template.md` for the standard structure.Mistake 5: Orphaned or Outdated Files
Problem: Old prompts remain in the repository long after theyβre obsolete, creating confusion and clutter.
β Bad example:
.github/prompts/
βββ create-class-component.prompt.md # Obsolete: Team uses hooks now
βββ use-moment-js.prompt.md # Obsolete: Migrated to date-fns
βββ generate-flow-types.prompt.md # Obsolete: Migrated to TypeScript
βββ review-webpack-config.prompt.md # Obsolete: Using Vite now
β Solution: Regular maintenance with deprecation markers:
---
# create-class-component.prompt.md
name: create-class-component
description: "β οΈ DEPRECATED: Use /create-react-component instead (functional components)"
---
**This prompt is deprecated.**
Our team migrated to functional components with hooks.
Use `/create-react-component` instead.
This file will be removed on 2025-03-01.Maintenance checklist:
Mistake 6: User Prompts for Team-Wide Tasks
Problem: Creating prompts in user-scope folder when they should be shared with the entire team.
β Bad example:
# Developer creates prompt in:
%APPDATA%\Code\User\prompts\review-api-security.prompt.md
# Problem: Only available on that developer's machine
# Team can't use it, can't improve it, can't maintain it
β Solution: Workspace prompts for team tasks, user prompts for personal workflows:
# Team-shared prompts (version controlled):
.github/prompts/
βββ review-api-security.prompt.md # Everyone needs this
βββ generate-unit-tests.prompt.md # Team standard
# Personal prompts (developer's profile folder):
%APPDATA%\Code\User\prompts/
βββ my-notes-format.prompt.md # Personal note-taking style
βββ my-commit-message.prompt.md # Personal commit preferences
Decision framework:
- Workspace prompts (
.github/prompts/) β Team standards, project-specific tasks, shared workflows - User prompts (profile folder) β Personal preferences, individual workflows, cross-project utilities
Mistake 7: No Versioning Strategy for Templates
Problem: Teams update templates but donβt version them, breaking consistency for files created from older versions.
β Bad example:
---
# .github/templates/prompt-template.md
name: [prompt-name]
description: [description]
---
# [Prompt Title]
[Instructions...]No version number, no changelog, no way to know if existing prompts follow current template.
β Solution: Version templates and document changes:
---
# Template Version: 2.1.0
# Last Updated: 2025-12-25
# Changelog:
# v2.1.0 (2025-12-25): Added 'tools' field for tool restrictions
# v2.0.0 (2025-11-01): Added 'model' field, removed deprecated 'mode'
# v1.0.0 (2025-09-15): Initial template
#
# Instructions:
# 1. Copy this file to .github/prompts/
# 2. Rename to [your-prompt-name].prompt.md
# 3. Fill in all [bracketed] fields
# 4. Remove this header comment before committing
---
name: [prompt-name]
description: [Brief description of what this prompt does]
tools: [fetch, search, ...] # v2.1.0: Optional tool restrictions
model: [Model name] # v2.0.0: Optional model selection
---
# [Prompt Title]
[Clear description of the task]
## Instructions
1. [Step-by-step instructions]Key Takeaways
β DO:
- Separate file types into dedicated folders
- Use consistent naming conventions (kebab-case recommended)
- Follow official file locations and extensions
- Document prompts with README files
- Regularly review and deprecate outdated prompts
- Use workspace prompts for team tasks, user prompts for personal workflows
- Version templates and track changes
β DONβT:
- Mix prompts, snippets, templates, and docs in one folder
- Use inconsistent naming styles across team
- Store files in unrecognized locations or use wrong extensions
- Leave prompts undocumented
- Keep obsolete prompts indefinitely
- Put team-wide prompts in personal user folder
- Update templates without versioning
By avoiding these common mistakes, youβll create a well-organized, discoverable, and maintainable prompt library that serves your entire team effectively.
π References
Official GitHub Copilot Documentation
GitHub Copilot Custom Instructions
[π Official]
This reference explains how to create repository-level custom instructions using.github/copilot-instructions.mdto 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.mdfile format, YAML frontmatter options (includingtools,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.mdfiles 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 newexcludeAgentfrontmatter 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#fileand#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.mdfiles 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.
Agent Skills
- Agent Skills Open Standard (agentskills.io)
[π Verified Community]
The open standard for agent skills that enables portable, resource-rich workflows across platforms. Skills bundle instructions with templates, scripts, and examples in a discoverable format. Essential reference for understanding the skill structure and cross-platform compatibility requirements.
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, GitHub MCP Server (Preview), enhanced Language Models Editor with BYOK support, and Claude skills integration. Essential for understanding the latest agentic development capabilities and agent execution contexts.
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
.copilotContext 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@workspaceand#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.mdfiles as custom agents - Open any
.chatmode.mdfile and use the Quick Fix action (lightbulb) to migrate - The Quick Fix renames the file to
.agent.mdand 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.