Arguments, agent, and tools

Your prompt file works with nothing but a description and a body. Now you’ll make it flexible — accept a parameter so it scaffolds any endpoint, pin the mode it runs in, and control which tools it can touch. All of that lives in the frontmatter.

The frontmatter fields

The block at the top of a .prompt.md accepts a handful of keys, each one tuning how the prompt behaves when invoked:

• description — a one-line summary of what the prompt does. You already have this; it’s what shows up next to the slash command in the chat.
• name — the /-invoke name. Set it and you call the prompt with /that-name. Leave it off and Copilot derives a name from the filename. Naming it explicitly makes the command predictable for the whole squad.
• argument-hint — text describing the input the prompt expects, shown as a hint when you invoke it. This is how a prompt takes a parameter: instead of hard-coding “an endpoint,” your prompt accepts which endpoint as an argument, so the same file scaffolds any of them.
• agent — which mode the prompt runs in. Accepts ask, agent, plan, or the name of a custom agent (you’ll build one next chapter). This is where the modes from chapter two reconnect: a scaffold-an-endpoint prompt that creates files and writes a test wants agent, because it’s doing multi-step work, not answering a question.
• model — which model the prompt runs against, by the same per-request picker you’d use in the chat. Pin it only when a task genuinely needs different reasoning than your default; otherwise leave it and let your normal selection stand.
• tools — the set of tools the prompt is allowed to use when it runs.

A wired-up version of your endpoint prompt:

---
description: Scaffold a new audited endpoint following our team's conventions.
name: scaffold-audited-endpoint
argument-hint: the endpoint's purpose, e.g. "cancel an order"
agent: agent
---

Scaffold a new audited endpoint for orders-service: ${input}.

1. Add the route handler in the conventional location for this service.
2. Run inputs through the shared-lib validation helper.
3. Enforce the configurable approval threshold.
4. Record an audit event via the shared-lib audit helper.
5. Stub a test for the below- and at-or-above-threshold paths.

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

Now /scaffold-audited-endpoint cancel an order runs the same five steps, in agent mode, for whatever endpoint you name — the argument flows into the body, and the always-on rules still shape the output underneath.

The precedence rule worth remembering

tools is the one field with a gotcha, and it’s worth committing to memory because next chapter you’ll build custom agents that also declare a tools list.

When a prompt file is pinned to a custom agent, and both the prompt file and that agent declare a tools set, the prompt file’s tools win. The prompt overrides the agent’s tool list for that invocation. The mental model: the agent defines a persona’s default capabilities, but a prompt is a specific job you’re handing it, and the job’s tool requirements take priority. Know this now so that when an agent seems to have access it shouldn’t — or lacks access it should — your first check is whether a prompt file is overriding it.

Where this chapter leaves you

You came into this chapter re-typing a multi-step request and leave it with that request codified once — a named, parameterized, mode-pinned slash command your whole squad runs the same way. Combined with the always-on rules from last chapter, Copilot now knows both who it is in your repos and which procedures you hand it on demand.

There’s a thread left dangling on purpose. Twice now — the agent field, the tools-precedence rule — we’ve pointed at custom agents as something you can pin a prompt to but haven’t built yet. That’s the next chapter, and it’s where the careful work begins: Act 1 opens on shared-lib, the library a dozen services depend on, and you’ll build a custom agent designed to make changes there safely. Next chapter: Custom agents & subagents.