Copilot Prompt Files Guidelines

Copilot Prompt Files Guidelines

Instructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository.

Scope and Principles

• Target audience: maintainers and contributors authoring reusable prompts.
• Goals: predictable behaviour, clear expectations, minimal permissions, portability.
• Primary references: VS Code documentation on prompt files and organization conventions.

Frontmatter Requirements

Every prompt file should include YAML frontmatter with the following fields:

Required/Recommended Fields

Guidelines

• Use consistent quoting (single quotes recommended)
• Keep one field per line for readability and version control clarity
• If tools are specified and the current agent is ask or edit, the default agent becomes agent
• Preserve any additional metadata (language, tags, visibility, etc.) required by your organization

File Naming and Placement

• Use kebab-case filenames ending with .prompt.md
• Store them under .github/prompts/ unless your workspace specifies otherwise
• Provide a short filename that communicates the action (e.g., generate-readme.prompt.md rather than prompt1.prompt.md)

Body Structure

• Start with an # heading that matches the prompt intent for Quick Pick search
• Organize with predictable sections: Mission, Scope & Preconditions, Inputs, Workflow (step-by-step), Output Expectations, and Quality Assurance
• Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation
• Reference related prompts or instruction files using relative links

Input and Context Handling

• Use ${input:variableName[:placeholder]} for required values
• Explain when the user must supply them; provide defaults where possible
• Call out contextual variables (${selection}, ${file}, ${workspaceFolder}) only when essential, describing how Copilot should interpret them
• Document how to proceed when mandatory context is missing (e.g., "Request the file path and stop if undefined")

Tool and Permission Guidance

• Limit tools to the smallest set that enables the task
• List them in preferred execution order when sequence matters
• If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects
• Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow

Instruction Tone and Style

• Write in direct, imperative sentences targeted at Copilot ("Analyze", "Generate")
• Keep sentences short and unambiguous
• Follow Google Developer Documentation translation best practices
• Avoid idioms, humor, or culturally specific references

Output Definition

• Specify the format, structure, and location of expected results (e.g., "Create docs/adr/adr-XXXX.md using the template below")
• Include success criteria and failure triggers
• Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute

Examples and Reusable Assets

• Embed Good/Bad examples or scaffolds (Markdown templates, JSON stubs)
• Maintain reference tables inline to keep the prompt self-contained
• Update these tables when upstream resources change
• Link to authoritative documentation instead of duplicating lengthy guidance

Quality Assurance Checklist

• Frontmatter fields are complete, accurate, and least-privilege
• Inputs include placeholders, default behaviours, and fallbacks
• Workflow covers preparation, execution, and post-processing without gaps
• Output expectations include formatting and storage details
• Validation steps are actionable (commands, diff checks, review prompts)
• Security, compliance, and privacy policies are current
• Prompt executes successfully in VS Code using representative scenarios

Maintenance Guidance

• Version-control prompts alongside the code they affect
• Update them when dependencies, tooling, or review processes change
• Review prompts periodically to ensure tool lists and linked documents remain valid
• Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs

Additional Resources

• Prompt Files Documentation
• Awesome Copilot Prompt Files
• Tool Configuration