Arguments, agent, and tools

A prompt file works with nothing but a description and a body. The frontmatter can make it flexible: accept a parameter, pin the role it runs in, and scope which tools it may use. (Reminder from the chapter opening: this machinery works where prompt files load at all - the Local harness; other harnesses do not load them, and the VS Code prompt files documentation (verified October 2026) points to agent skills and a conversion path. The field names below are per that page.)

The frontmatter fields

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

• description - a one-line summary of what the prompt does; shown 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 the name derives from the filename. Naming it explicitly keeps the command predictable for a team.
• argument-hint - text describing the input the prompt expects, shown as a hint when invoking. This is how a prompt takes a parameter: instead of hard-coding “an endpoint,” the prompt accepts which endpoint as an argument, so one file scaffolds any of them.
• agent - which role the prompt runs in. Accepts ask, agent, plan, or the name of a custom agent (the next chapter builds those). A scaffold-an-endpoint prompt that creates files and writes a test wants agent, because it is doing multi-step work, not answering a question.
• model - which model the prompt runs against, by the same per-request picker you would 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 may use when it runs. It is a list of the same tool names a custom agent declares, including MCP servers by "<server-name>/*" entries - so a prompt pinned to a narrow list cannot reach tools you left off it. Like everything else in a .prompt.md, the field applies where prompt files load (the Local harness, per the chapter opening).

A wired-up version of the endpoint prompt, written for orders-service, the course’s illustrative order-management API your squad owns, which imports the internal shared-lib library:

---
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:purpose}.

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, for whatever endpoint you name. The argument flows in through the documented variable form ${input:variableName} (a placeholder suffix also exists: ${input:variableName:placeholder}), and the always-on rules still shape the output underneath.

The precedence rule worth remembering

tools is the one field with a gotcha, worth committing to memory because the next chapter builds 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 (documented precedence, verified September 2026). The mental model: the agent defines a persona’s default capabilities, but a prompt is a specific job you hand it, and the job’s tool requirements take priority. Know this now: it explains an agent that seems to have access it should not, or lacks access it should.

Prompt tools override agent tools

If an agent seems to have access it shouldn’t - or lacks access it should - check whether a prompt file is overriding its tools list. The prompt wins, silently, for that invocation.

Where this chapter leaves you

A repeated multi-step request is now codified once: a named, parameterized, role-pinned slash command a whole team runs the same way, layered on top of always-on rules. For harnesses other than the Local harness, the same procedure belongs in an Agent Skill - the Skills chapter covers that format - but the placement judgment (always-on context versus invoked procedure) is identical.

There is a thread left dangling on purpose: the agent field and the tools-precedence rule both point at custom agents - something you can pin a prompt to but have not built yet. That is the next chapter. Next chapter: Custom agents & subagents.