{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"prompt","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Guidelines for creating high-quality prompt files for GitHub Copilot'\napplyTo: '**/*.prompt.md'\n---\n\n# Copilot Prompt Files Guidelines\n\nInstructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository.\n\n## Scope and Principles\n- Target audience: maintainers and contributors authoring reusable prompts for Copilot Chat.\n- Goals: predictable behaviour, clear expectations, minimal permissions, and portability across repositories.\n- Primary references: VS Code documentation on prompt files and organization-specific conventions.\n\n## Frontmatter Requirements\n\nEvery prompt file should include YAML frontmatter with the following fields:\n\n### Required/Recommended Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `description` | Recommended | A short description of the prompt (single sentence, actionable outcome) |\n| `name` | Optional | The name shown after typing `/` in chat. Defaults to filename if not specified |\n| `agent` | Recommended | The agent to use: `ask`, `edit`, `agent`, or a custom agent name. Defaults to current agent |\n| `model` | Optional | The language model to use. Defaults to the currently selected model |\n| `tools` | Optional | List of tool/tool set names available for this prompt |\n| `argument-hint` | Optional | Hint text shown in chat input to guide user interaction |\n\n### Guidelines\n\n- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity\n- If `tools` are specified and the current agent is `ask` or `edit`, the default agent becomes `agent`\n- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization\n\n## File Naming and Placement\n- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.\n- Provide a short filename that communicates the action (for example, `generate-readme.prompt.md` rather than `prompt1.prompt.md`).\n\n## Body Structure\n- Start with an `#` level heading that matches the prompt intent so it surfaces well in Quick Pick search.\n- Organize content with predictable sections. Recommended baseline: `Mission` or `Primary Directive`, `Scope \u0026 Preconditions`, `Inputs`, `Workflow` (step-by-step), `Output Expectations`, and `Quality Assurance`.\n- Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation.\n- Reference related prompts or instruction files using relative links to aid discoverability.\n\n## Input and Context Handling\n- Use `${input:variableName[:placeholder]}` for required values and explain when the user must supply them. Provide defaults or alternatives where possible.\n- Call out contextual variables such as `${selection}`, `${file}`, `${workspaceFolder}` only when they are essential, and describe how Copilot should interpret them.\n- Document how to proceed when mandatory context is missing (for example, “Request the file path and stop if it remains undefined”).\n\n## Tool and Permission Guidance\n- Limit `tools` to the smallest set that enables the task. List them in the preferred execution order when the sequence matters.\n- If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects.\n- Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow.\n\n## Instruction Tone and Style\n- Write in direct, imperative sentences targeted at Copilot (for example, “Analyze”, “Generate”, “Summarize”).\n- Keep sentences short and unambiguous, following Google Developer Documentation translation best practices to support localization.\n- Avoid idioms, humor, or culturally specific references; favor neutral, inclusive language.\n\n## Output Definition\n- Specify the format, structure, and location of expected results (for example, “Create `docs/adr/adr-XXXX.md` using the template below”).\n- Include success criteria and failure triggers so Copilot knows when to halt or retry.\n- Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute after running the prompt.\n\n## Examples and Reusable Assets\n- Embed Good/Bad examples or scaffolds (Markdown templates, JSON stubs) that the prompt should produce or follow.\n- Maintain reference tables (capabilities, status codes, role descriptions) inline to keep the prompt self-contained. Update these tables when upstream resources change.\n- Link to authoritative documentation instead of duplicating lengthy guidance.\n\n## Quality Assurance Checklist\n- [ ] Frontmatter fields are complete, accurate, and least-privilege.\n- [ ] Inputs include placeholders, default behaviours, and fallbacks.\n- [ ] Workflow covers preparation, execution, and post-processing without gaps.\n- [ ] Output expectations include formatting and storage details.\n- [ ] Validation steps are actionable (commands, diff checks, review prompts).\n- [ ] Security, compliance, and privacy policies referenced by the prompt are current.\n- [ ] Prompt executes successfully in VS Code (`Chat: Run Prompt`) using representative scenarios.\n\n## Maintenance Guidance\n- Version-control prompts alongside the code they affect; update them when dependencies, tooling, or review processes change.\n- Review prompts periodically to ensure tool lists, model requirements, and linked documents remain valid.\n- Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs.\n\n## Additional Resources\n- [Prompt Files Documentation](https://code.visualstudio.com/docs/copilot/customization/prompt-files#_prompt-file-format)\n- [Awesome Copilot Prompt Files](https://github.com/github/awesome-copilot/tree/main/prompts)\n- [Tool Configuration](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_agent-mode-tools)\n","description":"Guidelines for creating high-quality prompt files for GitHub Copilot","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/prompt.instructions.md"},"manifest":{}},"content_hash":[86,14,135,152,145,209,139,184,222,253,247,88,122,234,88,109,237,122,156,57,204,136,191,65,154,121,142,225,250,155,132,118],"trust_level":"unsigned","yanked":false}