# Prompts

URL: /code/file-conventions/prompts · Id: `page:code/file-conventions/prompts`

> A file in prompts/ is one set of model instructions, versioned, graded by Evaluators and varied in place by an @arm sibling.

A file in `prompts/` is one [Template](/business/nouns/template) of model instructions, filled from records by a [Role](/business/nouns/role), a [Function](/business/nouns/function) or a [Workflow](/business/nouns/workflow) step. Every edit is a [Version](/business/nouns/version), graded before it merges.

```text
leaseline/
└── prompts/
    ├── support-reply.md          the instructions in use
    └── support-reply@lease.md    a challenger, inert until an Experiment names it
```

## Reference
Markdown with frontmatter. The body is the instructions; `{{name}}` reads an input.

| Key | Type | Holds |
| --- | --- | --- |
| `description` | string | When it is used, in one sentence. Required |
| `inputs` | map | Each field it fills and its type: a primitive or a [Noun](/business/nouns/noun) name |
| `model` | `draft \| classify \| judge \| agent` | The task class the [AI gateway](/code/platform/ai-gateway) routes; never a model name |
| `evaluators` | [Evaluator](/business/nouns/evaluator) ids | What grades every output |

A Role file names a prompt with `instructions: prompts/support-reply` in place of a body. A Function names one with `instructions: prompt('support-reply')`.

## Examples
### Minimal
```md title="prompts/support-reply.md"
---
description: Answer a property manager's question about the product.
---
Answer in plain words. Link the page that shows how.
```

### Leaseline
```md title="prompts/support-reply.md"
---
description: Answer a property manager's question about one of their leases.
inputs: { conversation: Conversation, lease: Lease }
model: draft
evaluators: [grounded-reply]
---
You answer for Leaseline, which tracks lease renewals for property managers.
The manager asked about the lease ending {{lease.endsOn}}. Answer from that record.
Never promise a rent or a date the record does not hold. If the record cannot answer, escalate.
```

The challenger, `support-reply@lease.md`, keeps the frontmatter and rewrites only the body. An [Experiment](/business/nouns/experiment) file that names `varies: prompts/support-reply` runs the two as arms.

## What it builds
The [StartupBuilder](/code/builders/startup) compiles each file on merge.

- a Template, with one Version per edit; each [Action](/business/nouns/action) records the Version it ran
- a [Variant](/business/nouns/variant) per `@arm` file, assigned only while an Experiment runs
- a [Change](/business/nouns/change) check: each Evaluator runs on the Role's recorded cases, and a Version that scores worse than the one in use is refused

## Good to know
- A prompt is instructions, not a [Permission](/business/nouns/permission). The Role's [Mandate](/business/nouns/mandate) and [Limits](/business/nouns/limit) bound every call the model makes.
- Changing the model is a Change to a [Policy](/business/nouns/policy), never to a prompt.
- A challenger runs in shadow on live inputs, with no one-way Actions, before any [Customer](/business/nouns/customer) sees its output.
- Instructions an [Agent](/business/nouns/agent) loads on demand, with scripts beside them, belong in a [skill package](/code/file-conventions/skills).