| name | create-custom-prompt |
| description | Use when asked to create, update, or review a VS Code prompt file (.prompt.md). Provides the correct file format, frontmatter fields, and guidelines for writing effective, reusable slash-command prompts.
|
| argument-hint | <prompt-name> [task description] |
Create a Custom Prompt File
Prompt files (.prompt.md) are slash commands — reusable, manually-invoked
prompts for common repetitive tasks. They carry structured instructions, context,
and optionally restrict which tools or agent are used.
When to Use a Prompt (vs other customizations)
| Need | Use |
|---|
Repeatable task invoked manually (/my-prompt) | Prompt file (.prompt.md) |
| Persistent AI persona with tool restrictions | Custom Agent (.agent.md) |
| Domain knowledge loaded automatically | Skill (SKILL.md) |
| Coding standards always applied | Instructions (.instructions.md) |
File Location
| Scope | Location |
|---|
| Workspace (shared with team) | .github/prompts/<prompt-name>.prompt.md |
| User profile (personal, all workspaces) | ~/.copilot/prompts/<prompt-name>.prompt.md |
File Format
---
name: <prompt-name>
description: <Short description of what this prompt does>
argument-hint: <hint shown after /prompt-name in chat input>
agent: ask | agent | plan | <custom-agent-name> # optional
model: <model-name> # optional
tools:
- <tool-name>
---
# Prompt Body
Detailed instructions for the task. Use Markdown formatting.
Reference workspace files with relative Markdown links.
Reference tools with `#tool:<tool-name>` syntax.
Use `${input:variableName}` or `${input:variableName:placeholder}` for user inputs.
Use `${selection}` to capture the current editor selection.
Frontmatter Fields
| Field | Required | Description |
|---|
name | No | Name used after / in chat. Defaults to file name. |
description | No | Short description shown in the / command menu. |
argument-hint | No | Hint text shown after the slash command in chat input. |
agent | No | Agent to use: ask, agent, plan, or a custom agent name. Defaults to current. |
model | No | Specific model. Defaults to user-selected model in picker. |
tools | No | Restricts available tools for this prompt. Prompt tools take highest priority. |
Tool List Priority
When running a prompt:
- Tools from the prompt file (highest priority)
- Tools from the referenced agent (if
agent: is set)
- Default tools for the selected agent
Built-in Variables
| Variable | Description |
|---|
${selection} | Currently selected text in the editor |
${input:name} | Prompts user for input with label name |
${input:name:placeholder} | Input with placeholder text |
#tool:<tool-name> | Reference a tool in the body text |
Step-by-Step Workflow
Step 1: Define the task
What exactly does this prompt do? It should be a single, well-scoped task (e.g.,
"scaffold a new Android ViewModel", "run and fix unit tests", "prepare PR description").
Step 2: Choose the right agent
ask → best for research, explanations, no file changesagent → best for tasks that need file editing or terminalplan → best for planning tasks- Custom agent name → when the task requires a specialized persona
Step 3: Create the file
.github/prompts/<prompt-name>.prompt.md
Step 4: Write the body
- Be specific about expected input and output format.
- Use
${input:variableName} for required inputs.
- Reference related instruction files instead of duplicating rules.
- Include examples of expected output where helpful.
Step 5: Verify
Examples
Scaffold Android ViewModel
---
name: new-android-viewmodel
description: Scaffold a new Android ViewModel with Hilt injection and StateFlow
argument-hint: <ViewModelName>
agent: agent
tools:
- create_file
- read_file
---
Create a new Android ViewModel named `${input:viewModelName:e.g. LoginViewModel}`.
Follow these conventions:
- Use Hilt `@HiltViewModel` + `@Inject constructor`
- Expose UI state via `StateFlow<UiState>`
- Use `viewModelScope` for coroutines
[See project conventions](.github/instructions/android/viewmodel.instructions.md)
Generate Commit Message
---
name: commit-msg
description: Generate a Conventional Commits message for the current changes
agent: ask
---
Review the following diff and generate a commit message following Conventional Commits format:
${selection}
Format:
():
[optional body]
[optional footer: TICKET-ID]
Types: feat, fix, test, static, refactor, docs, format, chore, perf
Security Review
---
name: security-review
description: Review selected code for OWASP Top 10 and memory safety issues
argument-hint: [scope description]
agent: reviewer-security
---
Perform a security review of the code below.
${selection}
Check for:
1. Input validation / injection vulnerabilities
2. Memory safety (buffer overflows, use-after-free)
3. Authentication and authorization issues
4. Hardcoded secrets or credentials
5. OWASP Top 10 violations
End with `[PASS]` or `[FAIL: <findings>]`.
Tips for Effective Prompts
- One task per prompt — if it needs multiple agents, use handoffs instead.
- Reference don't duplicate — link to instructions files rather than copying rules.
- Name clearly —
/new-android-viewmodel is better than /create-vm.
- Use
argument-hint so users know what to type after /name.
- Test with the play button — open the
.prompt.md file and press ▶ to iterate fast.
Prerequisites
- VS Code 1.87+ with the GitHub Copilot extension installed.
- A workspace with a
.github/prompts/ directory (create it if absent).
- Understanding of the task you want to automate as a reusable prompt.
Troubleshooting
- AI never auto-loads the skill / agent / instruction — verify
disable-model-invocation is not true and description contains a clear "Use when ..." trigger phrase.
- Skill / prompt not shown in the
/ command menu — check that user-invocable is not false and the file is saved to the correct .github/ subdirectory.
name validator error (FM_NAME_DIR_MISMATCH) — the name frontmatter field must exactly match the directory/file name (case-sensitive, lowercase, hyphens only).- Companion file not found by the AI — reference files with paths relative to the skill/instruction/prompt file (e.g.,
./examples/good.cpp).
References
