|
| 1 | +--- |
| 2 | +description: 'Guidelines for creating high-quality prompt files for GitHub Copilot' |
| 3 | +applyTo: '**/*.prompt.md' |
| 4 | +--- |
| 5 | + |
| 6 | +# Copilot Prompt Files Guidelines |
| 7 | + |
| 8 | +Instructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository. |
| 9 | + |
| 10 | +## Scope and Principles |
| 11 | +- Target audience: maintainers and contributors authoring reusable prompts for Copilot Chat. |
| 12 | +- Goals: predictable behaviour, clear expectations, minimal permissions, and portability across repositories. |
| 13 | +- Primary references: VS Code documentation on prompt files and organization-specific conventions. |
| 14 | + |
| 15 | +## Frontmatter Requirements |
| 16 | +- Include `description` (single sentence, actionable outcome), `mode` (explicitly choose `ask`, `edit`, or `agent`), and `tools` (minimal set of tool bundles required to fulfill the prompt). |
| 17 | +- Declare `model` when the prompt depends on a specific capability tier; otherwise inherit the active model. |
| 18 | +- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization. |
| 19 | +- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity. |
| 20 | + |
| 21 | +## File Naming and Placement |
| 22 | +- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory. |
| 23 | +- Provide a short filename that communicates the action (for example, `generate-readme.prompt.md` rather than `prompt1.prompt.md`). |
| 24 | + |
| 25 | +## Body Structure |
| 26 | +- Start with an `#` level heading that matches the prompt intent so it surfaces well in Quick Pick search. |
| 27 | +- Organize content with predictable sections. Recommended baseline: `Mission` or `Primary Directive`, `Scope & Preconditions`, `Inputs`, `Workflow` (step-by-step), `Output Expectations`, and `Quality Assurance`. |
| 28 | +- Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation. |
| 29 | +- Reference related prompts or instruction files using relative links to aid discoverability. |
| 30 | + |
| 31 | +## Input and Context Handling |
| 32 | +- Use `${input:variableName[:placeholder]}` for required values and explain when the user must supply them. Provide defaults or alternatives where possible. |
| 33 | +- Call out contextual variables such as `${selection}`, `${file}`, `${workspaceFolder}` only when they are essential, and describe how Copilot should interpret them. |
| 34 | +- Document how to proceed when mandatory context is missing (for example, “Request the file path and stop if it remains undefined”). |
| 35 | + |
| 36 | +## Tool and Permission Guidance |
| 37 | +- Limit `tools` to the smallest set that enables the task. List them in the preferred execution order when the sequence matters. |
| 38 | +- If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects. |
| 39 | +- Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow. |
| 40 | + |
| 41 | +## Instruction Tone and Style |
| 42 | +- Write in direct, imperative sentences targeted at Copilot (for example, “Analyze”, “Generate”, “Summarize”). |
| 43 | +- Keep sentences short and unambiguous, following Google Developer Documentation translation best practices to support localization. |
| 44 | +- Avoid idioms, humor, or culturally specific references; favor neutral, inclusive language. |
| 45 | + |
| 46 | +## Output Definition |
| 47 | +- Specify the format, structure, and location of expected results (for example, “Create `docs/adr/adr-XXXX.md` using the template below”). |
| 48 | +- Include success criteria and failure triggers so Copilot knows when to halt or retry. |
| 49 | +- Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute after running the prompt. |
| 50 | + |
| 51 | +## Examples and Reusable Assets |
| 52 | +- Embed Good/Bad examples or scaffolds (Markdown templates, JSON stubs) that the prompt should produce or follow. |
| 53 | +- Maintain reference tables (capabilities, status codes, role descriptions) inline to keep the prompt self-contained. Update these tables when upstream resources change. |
| 54 | +- Link to authoritative documentation instead of duplicating lengthy guidance. |
| 55 | + |
| 56 | +## Quality Assurance Checklist |
| 57 | +- [ ] Frontmatter fields are complete, accurate, and least-privilege. |
| 58 | +- [ ] Inputs include placeholders, default behaviours, and fallbacks. |
| 59 | +- [ ] Workflow covers preparation, execution, and post-processing without gaps. |
| 60 | +- [ ] Output expectations include formatting and storage details. |
| 61 | +- [ ] Validation steps are actionable (commands, diff checks, review prompts). |
| 62 | +- [ ] Security, compliance, and privacy policies referenced by the prompt are current. |
| 63 | +- [ ] Prompt executes successfully in VS Code (`Chat: Run Prompt`) using representative scenarios. |
| 64 | + |
| 65 | +## Maintenance Guidance |
| 66 | +- Version-control prompts alongside the code they affect; update them when dependencies, tooling, or review processes change. |
| 67 | +- Review prompts periodically to ensure tool lists, model requirements, and linked documents remain valid. |
| 68 | +- Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs. |
| 69 | + |
| 70 | +## Additional Resources |
| 71 | +- [Prompt Files Documentation](https://code.visualstudio.com/docs/copilot/customization/prompt-files#_prompt-file-format) |
| 72 | +- [Awesome Copilot Prompt Files](https://github.com/github/awesome-copilot/tree/main/prompts) |
| 73 | +- [Tool Configuration](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_agent-mode-tools) |
0 commit comments