Appendix: Prompt file YAML field reference

tech
github-copilot
prompt-engineering
Complete field-by-field reference for all YAML frontmatter fields supported in .prompt.md files ? type, support status, purpose, code examples, and best practices
Author

Dario Airoldi

Published

December 26, 2025

Appendix: Prompt file YAML field reference

This file contains the YAML frontmatter reference appendix extracted from the How to structure content for GitHub Copilot prompt files article. It provides comprehensive documentation of all metadata fields supported in .prompt.md YAML frontmatter across GitHub Copilot implementations and related tools.

Contents

  • Core Metadata Fields - Complete specifications for the 6 essential YAML fields:

    • name - Command identifier for invoking prompts
    • description - UI display text shown in prompt picker
    • agent - Execution mode (ask, edit, agent, or custom)
    • model - LLM selection for specific capabilities
    • tools - Capability restrictions for security/focus
    • argument-hint - Usage guidance displayed to users

  • Extended Metadata Fields - Experimental and custom fields for advanced use cases:

    • version, author, tags, category for organization and tracking

  • Custom Agent Metadata - Additional fields for .agent.md files defining specialized personas

  • Platform-Specific Differences - Distinctions between VS Code and Visual Studio implementations

  • Complete Examples - Full YAML headers showing all fields working together

  • Validation & Best Practices - Essential guidance including:

    • Required vs optional fields checklist
    • Common mistakes and how to avoid them
    • Recommended configurations for different scenarios

  • Future Proposed Fields - Community-requested capabilities planned for future releases

Each field entry includes: type, support status, purpose, code examples, and best practices. Use this appendix as your go-to reference when authoring or troubleshooting prompt files.

Core Metadata Fields

name

  • Type: String
  • Required: No (defaults to filename without extension)
  • Purpose: Defines the command name used to invoke the prompt
  • VS Code: Invoked as /name (slash command)
  • Visual Studio: Invoked as #name (hashtag command)
  • Example: name: react-form ? Use /react-form in VS Code
  • Best Practice: Use lowercase with hyphens for multi-word names
name: code-review

description

  • Type: String
  • Required: No (but highly recommended)
  • Purpose: Human-readable explanation shown in prompt picker/autocomplete
  • Visibility: Appears in UI when selecting prompts
  • Character Limit: Keep under 100 characters for best display
  • Best Practice: Write clear, action-oriented descriptions
description: "Review code for security vulnerabilities and best practices"

agent

  • Type: String (enum)
  • Required: No (defaults to user’s current chat mode)
  • Purpose: Specifies the execution mode for the prompt
  • Supported Values:
    • ask - Research/analysis mode (no file edits)
    • edit - Direct file modification mode
    • agent - Autonomous multi-step agent mode
    • Custom agent names (if .agent.md files defined)
  • VS Code: Fully supported (1.106+)
  • Visual Studio: Limited support (check version docs)
agent: agent  # Use autonomous agent mode

Agent Mode Comparison:

Mode File Edits Multi-step Tool Access Best For
ask No Limited Yes Analysis, Q&A, research
edit Yes No Limited Direct code modifications
agent Yes Yes Full Complex workflows, automation

model

  • Type: String
  • Required: No (uses user’s default model)
  • Purpose: Specifies which LLM to use for this prompt
  • Common Values:
    • gpt-4 or GPT-4
    • gpt-4-turbo
    • gpt-3.5-turbo
    • claude-sonnet-4.5
    • o1-preview
    • o3
  • Availability: Depends on user’s Copilot subscription and enabled models
  • Best Practice: Only specify when prompt requires specific model capabilities
model: claude-sonnet-4.5  # Use Claude for this prompt

tools

  • Type: Array of strings
  • Required: No (all tools available by default)
  • Purpose: Restricts which tools/capabilities the prompt can use
  • Supported Values:
    • codebase - Semantic search across repository
    • editor - File read/write operations
    • filesystem - Directory listing, file operations
    • fetch - Web content retrieval
    • web_search - Internet search capabilities
    • MCP server names (e.g., github, azure)
  • Use Case: Security, performance, or focus constraints
  • VS Code: Full support
  • Visual Studio: Limited support
tools: ['codebase', 'editor', 'filesystem']  # Restrict to local operations only

Tool Access Patterns:

## Minimal tools (fast, focused)
tools: ['editor']

## Code-focused (no external access)
tools: ['codebase', 'editor', 'filesystem']

## Research-enabled (includes external data)
tools: ['codebase', 'fetch', 'web_search']

## Full access (all available tools)
tools: []  # or omit the field entirely

argument-hint

  • Type: String
  • Required: No
  • Purpose: Shows usage hint in chat input field
  • Visibility: Displayed as placeholder text when invoking prompt
  • Best Practice: Use concise syntax examples
  • Format: Suggest argument patterns users should provide
argument-hint: 'fields=name:string,age:number,email:string'

Effective Argument Hints:

## File path argument
argument-hint: 'path/to/file.ts'

## Key-value pairs
argument-hint: 'component=Button props=variant,size'

## Optional parameters
argument-hint: '[language] [framework]'

## Multiple files
argument-hint: 'file1.ts file2.ts ...'

Extended Metadata Fields

version

  • Type: String (semantic version)
  • Status: Not officially documented but supported by some tools
  • Purpose: Track prompt file versions for compatibility
  • Format: Follow semantic versioning (major.minor.patch)
version: "1.2.0"

author

  • Type: String or array
  • Status: Not officially documented
  • Purpose: Document prompt creator(s)
  • Use Case: Team attribution, maintenance responsibility
author: "Development Team"
## or
author: ["Alice Smith", "Bob Jones"]

tags

  • Type: Array of strings
  • Status: Experimental/custom
  • Purpose: Categorize prompts for searching/filtering
  • Use Case: Large prompt libraries with organizational needs
tags: ['security', 'code-review', 'python']

category

  • Type: String
  • Status: Custom/organizational
  • Purpose: High-level prompt classification
  • Use Case: Aligns with prompt organization structure
category: "quality-assurance"

Custom Agent Metadata (.agent.md files)

When defining custom agents in .github/agents/*.agent.md, additional fields are available:

instructions

  • Type: Markdown content (in body, not YAML)
  • Purpose: Define agent’s system instructions and behavior
  • Location: Main content after YAML frontmatter

functions (Proposed)

  • Type: Array of function definitions
  • Status: Experimental
  • Purpose: Define custom capabilities for specialized agents

Platform-Specific Metadata

VS Code Specific

## VS Code Preview features (1.106+)
name: my-prompt
agent: custom-agent-name  # Reference .agent.md file
tools: ['codebase', '@mcp-server-name']  # MCP server integration

Visual Studio Specific

## Visual Studio 17.10+
name: my-prompt  # Invoked as #my-prompt (not /my-prompt)
## Note: Limited tool/agent support compared to VS Code

Complete Example with All Common Fields

---
name: comprehensive-code-review
description: "Perform security audit and best practices review with detailed report"
agent: agent
model: claude-sonnet-4.5
tools: ['codebase', 'editor', 'fetch']
argument-hint: '[focus=security|performance|style]'
version: "2.1.0"
author: "Security Team"
tags: ['security', 'code-review', 'audit']
category: "quality-assurance"
---

## Comprehensive Code Review Prompt

[Prompt content here...]

Validation and Best Practices

Required Fields Checklist:

  • ? name (or rely on filename)
  • ? description (strongly recommended)

Optional but Recommended:

  • agent - Specify if prompt needs specific mode
  • model - Specify if prompt requires specific capabilities
  • tools - Restrict for security/performance
  • argument-hint - Guide users on usage

Common Mistakes:

  • ? Using spaces in name (use hyphens: code-review not code review)
  • ? Overly long description (keep under 100 chars)
  • ? Specifying unavailable models (check user’s subscription)
  • ? Over-restricting tools (limits functionality unnecessarily)
  • ? Vague argument hints (be specific about expected format)

Future Metadata Fields (Proposed)

Based on community requests and tool evolution:

## Proposed future fields
requires: ['extension-id']  # Extension dependencies
min-version: "1.95.0"       # Minimum VS Code version
max-tokens: 8000            # Token limit for responses
temperature: 0.7            # Model temperature override
context-files: ['docs/**']   # Auto-include file patterns

These fields are not currently supported but represent potential future capabilities.