Prompt Files in Depth: Build Reusable Slash Commands That Actually Scale

Dhanoop Bhaskar June 28, 2026 copilot

Why prompt files are a force multiplier

Prompt files let you turn ad-hoc prompting into reusable team workflows. Instead of rewriting the same long instruction every day, you package it once and run it as a slash command.

They are ideal for high-frequency, bounded tasks such as:

  • README generation
  • code review reports
  • API documentation generation
  • test generation
  • onboarding plans

Prompt files are supported in VS Code, Visual Studio, and JetBrains IDEs. Verify support for your IDE version and Copilot plan in the official documentation before standardizing team workflows.

Use cases

  • Developers who repeat the same chat workflows every day
  • Leads creating reusable slash-command workflows for teams
  • Developers who want consistent, structured output from Copilot Chat

Step 1: Understand where prompt files live

Common locations:

  • Workspace scope: .github/prompts
  • User scope: profile-level prompt storage (IDE-managed)

In VS Code, workspace discovery can be extended with configuration settings and monorepo parent discovery options.

Step 2: Learn the file format

Prompt files are Markdown files with .prompt.md extension and optional YAML frontmatter.

Frequently used frontmatter fields:

  • description — shown in the slash-command picker and tooltips
  • name — controls the slash-command name (e.g., name: review-code → invoked as /review-code)
  • argument-hint — text shown in the chat input as a usage hint, e.g., focus=security|performance
  • agent — set to agent to use the default Copilot agent, or a custom agent name for specialist routing
  • model — override the model for this prompt (optional)
  • tools — restrict tools available during this prompt's execution

Minimal file

---
description: Explain selected code with clear language
agent: agent
---

Explain the selected code:
${selection}

Include:
- What it does
- Step-by-step flow
- One usage example

Step 3: Understand tool resolution priority

If tools are declared in multiple places, the effective tool set follows priority:

  1. Tools in the prompt file
  2. Tools from the custom agent referenced by that prompt
  3. Default tools from selected/current agent

This is one of the most important controls for reducing tool misuse in sensitive workflows.

Diagram: Tool resolution

+-----------------------------+
| Prompt file declares tools? |
+-----------------------------+
        | yes           | no
        v               v
+------------------+   +------------------------------+
| Use prompt tools |   | Agent declares tools?        |
+------------------+   +------------------------------+
                              | yes               | no
                              v                   v
                      +------------------+   +----------------+
                      | Use agent tools  |   | Use defaults   |
                      +------------------+   +----------------+

Step 4: Use input variables for flexibility

Prompt files become much more useful when you parameterize them.

Common variable patterns:

  • ${selection} for selected editor text
  • ${input:name} for user-supplied values
  • ${input:name:placeholder text} for guided input

Example with variables

---
name: review-code
description: Perform a structured code review report
agent: agent
---

Review this code with focus on ${input:focus:security, performance, maintainability}.

Code:
${selection}

Return:
- Critical issues
- Improvement suggestions
- Positive patterns

Step 5: Create prompt files with and without AI assistance

In VS Code, practical creation paths include:

  1. Manual authoring — Create the .prompt.md file directly in .github/prompts/. Add frontmatter fields and write the instruction body.
  2. Convert a successful chat session — When you find a prompt that produced a reliably good output, save that exact prompt as a prompt file. This is the fastest way to build a library from real usage patterns.
  3. Generate a template with Copilot — Ask Copilot Chat to draft a prompt file for a specific task. For example: "Create a prompt file that generates an OpenAPI spec summary for a selected API file. Include input variables for API version and output format."

Treat any AI-generated prompt file as a draft. Before sharing it with a team, test it on at least two real inputs and verify the output structure matches what you actually want. The frontmatter is straightforward; the instruction body requires human judgment about scope and output constraints.

Step 6: Map the six library examples to real-world use

The customization library includes six prompt file examples. Here is how to use them strategically.

Example Task shape Suggested usage
Your first prompt file General explanation workflow Internal knowledge sharing
Create README Documentation synthesis New repository initialization
Onboarding plan Personalized phased guidance New hire onboarding
Document API OpenAPI-oriented documentation API governance and docs automation
Review code Structured report format Manual quality gates before PR
Generate unit tests Behavior-focused test generation Fast regression coverage

Step 7: Design for deterministic outputs

To improve repeatability:

  • Define exact output structure
  • Constrain scope explicitly
  • Provide success criteria
  • Include concrete examples of expected output

Weak instruction:

  • Review this code.

Strong instruction:

  • Review this file and output three sections: Critical issues, Suggested fixes with code snippets, and Positive practices. Prioritize security first.

Step 8: Adopt a publish-and-test lifecycle

A practical team lifecycle:

  1. Draft prompt file
  2. Test against 3 real examples
  3. Collect feedback from 2 or more users
  4. Revise for clarity and edge cases
  5. Version in repository and document intended use

Keep a lightweight changelog in prompt comments or adjacent docs for traceability.

Step 9: Avoid prompt file anti-patterns

Common anti-patterns:

  • Repeating global conventions already covered by custom instructions
  • Leaving outputs unconstrained, causing variable response formats
  • Making prompts too broad, effectively replacing custom agents
  • Not specifying focus areas when review rigor is required

A reliable pattern is narrow prompts with explicit outputs and just enough inputs.

Step 10: Hands-on lab

Follow this exact lab to create, run, and verify one useful prompt file.

Goal

Create a reusable review prompt that always returns a structured report.

Create the file

Path: .github/prompts/review-selected-code.prompt.md

---
name: review-selected-code
description: Structured review for selected code
argument-hint: focus=security|performance|maintainability
agent: agent
tools: ["read", "search"]
---

Review the selected code with focus on ${input:focus:maintainability}.

Code:
${selection}

Return exactly these sections:
1. Findings (ordered by severity)
2. Suggested patch
3. Tests to add
4. Residual risks

Run it

In VS Code:

  1. Open any source file and select a function with your cursor.
  2. Open the Copilot Chat panel (Ctrl+Alt+I / Cmd+Alt+I).
  3. Type /review-selected-code — the argument-hint value appears as placeholder text in the input field.
  4. Type focus=security after the slash command and press Enter.
  5. Copilot resolves ${selection} automatically from your editor selection and ${input:focus} from your typed argument.

The response will always contain the four sections defined in the prompt file: Findings, Suggested patch, Tests to add, and Residual risks. That structure is guaranteed by the prompt — you do not need to remember to ask for each section manually.

Validate quality

  • Run the prompt on two different files and compare consistency.
  • Ensure recommendations are specific to the selected code, not generic.
  • Update the prompt if you see repeated ambiguity.

This lab covers the full prompt lifecycle — author, execute, evaluate, refine — in a single session.

Key takeaways

  • Prompt files convert repeat work into reusable slash commands.
  • Input variables dramatically improve reuse without sacrificing control.
  • Tool priority rules are essential for safe execution boundaries.
  • Library examples are best used as design patterns, not fixed templates.
  • Test and iterate prompt files like production assets.


References

Post a Comment

0 Comments