create-prompts

name	create-prompts
source	botcore
description	Provides expert guidance for creating VS Code Copilot prompt files (.prompt.md) used as reusable slash commands. Covers frontmatter schema, agent modes, tool scoping, variables, prompt patterns (review, generate, summarize, delegate, transform, multi-step, session init), naming conventions, and best practices. Use when creating new prompt files, reviewing prompt quality, designing prompt architecture, or improving existing prompts. Triggers: prompt file, .prompt.md, slash command, create prompt, prompt template, agent prompt, copilot prompt, reusable prompt, /command.
version	1.0.0
triggers	["prompt file",".prompt.md","slash command","create prompt","prompt template","agent prompt","copilot prompt","reusable prompt","/command","prompt patterns"]
portable	true

Creating VS Code Copilot Prompt Files

Expert guidance for creating effective VS Code prompt files (.prompt.md) -- reusable slash commands for GitHub Copilot chat.

Capabilities

1. Create prompts -- Generate new .prompt.md files with proper frontmatter and body structure
2. Review prompts -- Evaluate existing prompts for clarity, structure, tool scoping, and effectiveness
3. Pattern guidance -- Apply proven prompt patterns (review, generate, summarize, delegate, transform, multi-step, session init)
4. Improve prompts -- Refactor prompts to use variables, explicit output formats, tool restrictions, and better structure
5. Architecture advice -- Design prompt sets for teams, including naming conventions, file organization, and layering with instructions and agents

Routing Logic

Request type	Load reference
Frontmatter fields, schema, file format	references/format.md
Prompt patterns and examples	references/patterns.md
Tool scoping, MCP tools, built-in tools	references/tools.md
Variables, input, dynamic content	references/variables.md
Best practices, anti-patterns, naming	references/best-practices.md

Core Principles

1. One Purpose Per Prompt

Each prompt file should do one thing well. A prompt that reviews content should not also generate new content. If a task has sub-steps, decompose into multiple prompts or delegate to a skill/custom agent.

2. Description Is Discovery

The description field is the only UI-visible context in the / slash command menu. Make it specific and action-oriented so users know exactly when to invoke it. Prefix with a repo identifier (e.g., [my-repo]) when prompts from multiple repos may appear together.

3. Structure Drives Quality

Use Markdown headings to organize prompts into clear sections. Structured prompts consistently outperform wall-of-text instructions. Minimum viable structure: frontmatter with description, a title heading, a task section, and an output section.

4. Define Output Format Explicitly

The single biggest improvement to any prompt is specifying the exact output format. Use Markdown templates, tables, or code blocks to show the desired structure. Agents follow concrete output templates far more reliably than prose descriptions.

5. Scope Tools Explicitly

Use the tools frontmatter field to restrict which tools the prompt can use. This prevents unintended side effects and communicates intent. If a tool listed in tools is unavailable at runtime, it is silently ignored.

6. Agent Mode for Tool Use

Prompts that need to read files, run terminal commands, or call MCP tools must set agent: agent. Without it, the prompt produces text output only. Use agent: ask for read-only analysis and agent: plan for complex exploration.

7. Reference, Don't Duplicate

Use Markdown links to reference instructions, skills, and docs rather than copying content into each prompt. Links resolve relative to the prompt file's location (.github/prompts/), so workspace root references need ../../.

8. Prompts vs. Instructions

Type	Invocation	Purpose
Prompt files (.prompt.md)	Manual -- user types /name	Repeatable tasks
Instructions (.instructions.md, AGENTS.md)	Automatic -- always loaded	Coding standards, conventions

Do not put always-on rules in prompt files. Do not put task-specific workflows in instructions.

Quick Reference

File location

.github/prompts/my-prompt.prompt.md    # Workspace (shared via git)
~/prompts/my-prompt.prompt.md          # User profile (personal)

The file name (minus .prompt.md) becomes the /slash-command.

Minimal prompt

---
description: Review the current file for accessibility issues
---

Review ${file} for WCAG 2.2 AA compliance. Report issues in a table with
severity, location, WCAG criterion, and fix.

Full-featured prompt

---
description: Generate a new component
argument-hint: component name (e.g., data-grid)
agent: agent
model: claude-sonnet-4
tools:
  - create_file
  - read_file
  - list_dir
---

# Create component

Generate a new component named ${input:componentName}.

## Requirements

- Follow the pattern in src/components/sample-card/
- Create three files: component, template, styles
- Register in src/main.ts

## Output

Create the files directly. Do not ask for confirmation.

Frontmatter fields

Field	Required	Default	Description
description	Recommended	--	Shown in / menu. Include repo prefix for multi-repo setups.
agent	No	current	agent, ask, plan, or custom agent name.
tools	No	agent default	Array of tool/tool-set names. Scopes available tools.
model	No	current	Pin to a specific LLM model for consistent results.
name	No	filename	Override the slash command name (defaults to filename).
argument-hint	No	--	Placeholder text shown after the slash command in chat input.

Deprecated: mode has been renamed to agent. Migrate any mode: "agent" to agent: agent.

Workflow -- Creating a New Prompt

1. Identify the task -- What repeatable action do you perform via Copilot chat?
2. Choose a pattern -- Review, generate, summarize, delegate, transform, or multi-step (see references/patterns.md)
3. Write the prompt -- Start with description + task + output format
4. Scope tools -- Add tools array if the prompt should only use specific tools
5. Add variables -- Use ${file}, ${selection}, or ${input:name} for context-awareness
6. Test via play button -- Open the .prompt.md file, click the play button in the editor toolbar
7. Iterate -- Refine based on results, adjust tool restrictions or output format
8. Commit -- Place in .github/prompts/ for team use

Checklist -- Prompt Quality

• Description is concise and action-oriented (shown in slash command picker)
• Task section clearly states what the agent should do
• Output format is explicitly defined (template, table, or example)
• Uses variables (${file}, ${selection}, ${input:...}) instead of requiring manual context
• Tools are scoped to only what the prompt needs
• Agent mode is set appropriately (ask for read-only, agent for actions, plan for exploration)
• Filename is kebab-case and descriptive: review-content.prompt.md
• No always-on rules that belong in instructions files instead
• Important/guardrails section included for agent-mode prompts
• Prompt is under ~200 lines (extract to skill with references if longer)

When to Escalate

• Prompt requires persistent state across multiple invocations -- use a skill instead
• Prompt needs to modify agent behavior globally -- use instructions instead
• Prompt requires more than ~200 lines -- decompose into prompt + skill with references
• Prompt involves complex multi-role scenarios -- use custom agents (.agent.md)
• Prompt needs always-on rules -- use .instructions.md or AGENTS.md instead