VSCode Copilot Custom Instructions & Prompt Files

Expert guidance for creating and managing VSCode Copilot customization files including custom instructions, prompt files, and agent configurations.

When to Use This Skill

Activate this skill when:

• Creating

  .github/copilot-instructions.md

  files
• Building

  .instructions.md

  files with applyTo patterns
• Setting up

  AGENTS.md

  configurations
• Creating

  .prompt.md

  reusable prompts
• Configuring YAML frontmatter for any of these file types
• Understanding variable syntax (

  ${variable}

  )
• Referencing tools (

  #tool:toolName

  ) or files in instructions
• Troubleshooting instruction file activation issues
• Sharing custom instructions across teams or repositories

Quick Overview: File Types

1.

.github/copilot-instructions.md

Always-on workspace instructions — Applied automatically to all chat requests in the workspace.

When to use: General coding guidelines, team conventions, project-specific rules that apply throughout the project.

Location:

.github/copilot-instructions.md

at workspace root

Example:

# Project Guidelines

- Use TypeScript for all new code
- Follow functional programming patterns
- Write tests using Jest
- API responses must use our standard error format

📄 Complete Guide: references/copilot-instructions-guide.md

---

2.

.instructions.md

Files

Conditional, targeted instructions — Apply to specific file types, locations, or tasks using

applyTo

glob patterns.

When to use: Language-specific guidelines, framework-specific patterns, file-type-specific rules.

Location:

.github/instructions/

folder or user profile

Example:

---
name: python-coding-standards
description: Python coding standards and best practices
applyTo: "**/*.py"
---

# Python Standards

- Follow PEP 8 style guide
- Use type hints for all functions
- Write docstrings using Google style

📄 Complete Guide: references/instructions-files-guide.md

---

3.

AGENTS.md

File

Multi-agent workspace instructions — Useful when working with multiple AI agents, applied automatically like copilot-instructions.md.

When to use: When you work with multiple AI coding assistants and want unified instructions.

Location: Workspace root, or subfolders (experimental)

Example:

# Agent Guidelines

All agents working in this codebase must:

- Never modify files in the `legacy/` directory
- Always run tests before committing
- Use the project's error handling utilities

📄 Complete Guide: references/agents-md-guide.md

---

4.

.prompt.md

Files

Reusable, on-demand prompts — Triggered via

/command

in chat for specific development tasks.

When to use: Standardized workflows, code generation templates, review checklists, common development tasks.

Location:

.github/prompts/

folder or user profile

Example:

---
name: create-react-component
description: Generate a React component with TypeScript and tests
argument-hint: component-name
agent: edit
---

# Create React Component

Create a new React component named ${input:componentName} with:

1. TypeScript interface for props
2. Function component implementation
3. Jest test file with basic tests
4. Storybook story file

Follow our component patterns in [docs/component-guidelines.md](docs/component-guidelines.md).

📄 Complete Guide: references/prompt-files-guide.md

---

Decision Tree: Which File Type?

Do you want instructions that apply automatically?
├─ YES → Always-on for entire workspace?
│   ├─ YES → Use .github/copilot-instructions.md
│   └─ NO → Apply to specific files/patterns?
│       └─ Use .instructions.md with applyTo pattern
│
└─ NO → Want to trigger on-demand?
    └─ Use .prompt.md file (invoked via /command)

Also consider: Use

AGENTS.md

if working with multiple AI agents simultaneously.

---

Common Elements Across All File Types

YAML Frontmatter (Optional but Recommended)

All file types support YAML frontmatter for metadata:

---
name: file-name-slug
description: What this file does
applyTo: "**/*.py"           # .instructions.md only
agent: edit                  # .prompt.md only
tools: [githubRepo, files]   # .prompt.md only
---

Variable Syntax

Reference dynamic values in file bodies:

- `${workspaceFolder}` — Workspace root path
- `${file}` — Currently open file path
- `${selection}` — Selected text
- `${input:variableName}` — User input from chat
- `${input:variableName:placeholder}` — With placeholder hint

📄 Complete Reference: references/variables-and-references.md

Tool References

Reference agent tools using special syntax:

Use #tool:githubRepo to search the repository.
Use #tool:files to read workspace files.

File References

Link to other workspace files using relative Markdown links:

Follow the patterns in [docs/api-guide.md](docs/api-guide.md).
See [scripts/validate.py](scripts/validate.py) for examples.

---

Reference Documentation

All detailed guides are in the

references/

folder:

• Copilot Instructions Guide —

  .github/copilot-instructions.md

  complete reference
• Instructions Files Guide —

  .instructions.md

  with applyTo patterns
• AGENTS.md Guide — Multi-agent workspace configuration
• Prompt Files Guide —

  .prompt.md

  reusable prompts
• Variables & References — All variable syntax and file referencing
• Best Practices — Writing effective instructions
• Troubleshooting — Common issues and solutions

---

Template Files

Ready-to-use templates in

assets/templates/

:

• copilot-instructions.template.md
• instructions-file.template.md
• agents.template.md
• prompt-file.template.md

---

Quick Start Workflows

Creating Always-On Instructions

# 1. Create .github directory if needed
mkdir -p .github

# 2. Create copilot-instructions.md
code .github/copilot-instructions.md

# 3. Add your guidelines
# 4. Enable in settings: github.copilot.chat.codeGeneration.useInstructionFiles

Creating Conditional Instructions

# 1. Create instructions directory
mkdir -p .github/instructions

# 2. Create instruction file
code .github/instructions/my-rules.instructions.md

# 3. Add YAML frontmatter with applyTo pattern
# 4. Enable: chat.includeApplyingInstructions

Creating Reusable Prompts

# 1. Create prompts directory
mkdir -p .github/prompts

# 2. Create prompt file
code .github/prompts/my-task.prompt.md

# 3. Use in chat: /my-task

---

Settings to Enable

Ensure these VS Code settings are enabled:

{
  // Enable copilot-instructions.md
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,
  
  // Enable .instructions.md with applyTo patterns
  "chat.includeApplyingInstructions": true,
  
  // Enable AGENTS.md
  "chat.useAgentsMdFile": true,
  
  // Enable nested AGENTS.md in subfolders (experimental)
  "chat.useNestedAgentsMdFiles": false,
  
  // Show prompts as recommendations
  "chat.promptFilesRecommendations": true
}

---

Key Best Practices

✅ Keep Instructions Concise: Each instruction should be a single, clear statement
✅ Use Specific Examples: Show code examples of what you want
✅ Reference, Don't Duplicate: Use Markdown links to existing docs
✅ Test Activation: Verify instructions trigger correctly
✅ Layer Appropriately: Use the right file type for the right scope

❌ Avoid Vague Guidance: "Write good code" → Instead: "Use functional components with TypeScript interfaces"
❌ Don't Overload: Too many instructions reduce effectiveness
❌ Don't Forget Settings: Instructions won't work without proper VS Code settings

📄 Full Best Practices: references/best-practices.md

---

Troubleshooting

Instructions not applying?

1. Check the file is in the correct location
2. Verify the relevant setting is enabled
3. Check YAML frontmatter syntax
4. For

   .instructions.md

   : verify

   applyTo

   glob pattern matches
5. View diagnostics: Right-click in Chat → Diagnostics

📄 Full Troubleshooting Guide: references/troubleshooting.md

---

Example Use Cases

Use Case 1: Team Coding Standards

Solution:

.github/copilot-instructions.md

with always-on guidelines

Use Case 2: Python-Specific Rules

Solution:

.instructions.md

with

applyTo: "**/*.py"

Use Case 3: Generate API Endpoint

Solution:

.prompt.md

with

/create-endpoint

command

Use Case 4: Multiple AI Assistants

Solution:

AGENTS.md

at workspace root

---

Community Resources

• Official VSCode Docs
• Prompt Files Docs
• Awesome Copilot Repository — Community examples

---

Remember: Instruction files are most effective when they're specific, actionable, and well-organized. Start simple and iterate based on what works for your team.