Create a prompt file

Say the request you keep re-typing is “scaffold an audited endpoint” - the five-step procedure from this course’s running example. This page turns it into a prompt file. The mechanics work in Local harness sessions; as the chapter opening explains, other harnesses do not load prompt files - the slash command never appears there - so what you build here runs where the Local harness is selected, and doubles as the migration source for an Agent Skill, the route for other harnesses. The reliable check for which you are on is empirical: create the file, type / plus its name, and see whether the command appears.

Where prompt files live

A prompt file is a Markdown file with a .prompt.md extension. By default Copilot looks for them in .github/prompts/ at the root of your workspace (default location, the /create-prompt generator, and the invocation routes below are per the VS Code prompt files documentation, verified September 2026), so the prompt ships in the repo, version-controlled, and everyone on the team gets it the moment they pull. That is the point: the team task lives where the team can see it, not in one person’s chat history. If you are on a current VS Code build, the Agent Customizations editor (a preview feature) is the graphical way to browse and manage these customizations; the older prompt-file location setting no longer appears in the current prompt files documentation.

Let Copilot draft it for you

You can write a .prompt.md by hand, but you do not have to start from a blank file. Copilot has a generator: run /create-prompt in the chat, describe the reusable task in plain language, and it scaffolds the file - frontmatter and body - for you to refine. Like everything prompt-file, the generator appears where the Local harness loads prompt files; if /create-prompt does not appear in your chat, hand-write the file - the shape below is the whole format.

Describe the task the way you would describe it to a teammate. In this course’s illustrative scenario the endpoints live in orders-service, the course’s illustrative order-management API your squad owns, and the helpers come from shared-lib, the internal library it imports:

A prompt that scaffolds a new audited endpoint the way our team does it: add the route, run inputs through the validation helper, enforce the configurable approval threshold, record an audit event via shared-lib, and stub a test.

Copilot writes the file. Now read it, because a prompt you will run dozens of times deserves the same scrutiny as code.

What the prompt file holds

Open the generated file under .github/prompts/. The body is the prompt itself - the instruction Copilot follows when you invoke it. Make it concrete and ordered, the way you actually want the work done:

---
description: Scaffold a new audited endpoint following our team's conventions.
---

Scaffold a new audited endpoint for orders-service. Steps:

1. Add the route handler in the conventional location for this service.
2. Run incoming inputs through the shared-lib validation helper.
3. Enforce the configurable approval threshold: orders at or above it
   require a second approver before the action proceeds.
4. Record an audit event via the shared-lib audit helper, matching how
   the existing endpoints emit their events.
5. Stub a test covering the below-threshold and at-or-above-threshold paths.

Follow the repository's custom instructions for style and structure.

Two things to notice. First, that last line leans on your repo’s rules file: the prompt file says what procedure to run, and the always-on instructions handle how the code should look. They compose. Second, “an audited endpoint” is this team’s shorthand for exactly this shape, and now the shorthand is executable.

The frontmatter so far is just a description - enough to run. The lesson on arguments, role, and tools adds the rest. A prompt file does its job with nothing but a body and a one-line description.

Invoke it

Three ways to run a prompt file, all equivalent:

• Type / and its name in the Chat view. Copilot lists your prompt files as slash commands; pick one and it runs. This is the everyday path - why people call them slash commands. (If typing / lists no prompt files, you are not in a Local harness session; see the chapter opening.)
• Run the “Chat: Run Prompt” command from the Command Palette and choose the file.
• Open the .prompt.md file and click the play button in the editor - handy while tuning it.

Run it once against your repo (orders-service is the course’s example service; shared-lib the library it imports). Copilot works through the five steps and returns the scaffolded endpoint as a reviewable change - the same proposes-you-decide loop from your first change, except one slash command triggered five steps instead of you typing them out.

Try it

Create a .prompt.md for a task you repeat often - “write tests for the file I name” is a good first one. Invoke it with / in the chat, then type the same instruction freehand in a new conversation and compare. The prompt file should give you the same shape every time; the freehand version probably will not.

You have a working prompt file, and a fair question: conventions went into a rules file last chapter, and now a task has gone into a prompt file. When does a thing belong in which? Next: Prompt vs rule - invoked vs always-on.