# Prompt YAML Schema


The definitive reference for `prompt.yaml` configuration fields.

## Why This Matters

| Problem | Solution | Result |
|---------|----------|--------|
| **Guesswork** | Strict Schema | Errors caught at load time |
| **Silent Failures** | Type Validation | Bad inputs fail fast |
| **Hidden Features** | Explicit Config | Full control over MCP behavior |

---

## Root Fields

Top-level properties for `prompt.yaml`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | **Yes** | Unique identifier (e.g., `code_review`). Used in `>>id`. |
| `name` | `string` | **Yes** | Human-readable name for MCP clients. |
| `description` | `string` | No | Tooltip description shown in clients. |
| `userMessageTemplate` | `string` | No* | Inline content. *One of `...Template` or `...File` required.* |
| `userMessageTemplateFile` | `string` | No* | Path to external `.md` file. |
| `systemMessageFile` | `string` | No | Path to system prompt file. |
| `registerWithMcp` | `boolean` | No | Show in client lists? Default `true`. |
| `tools` | `string[]` | No | Script tools to attach (auto-trigger). |
| `gateConfiguration` | `object` | No | Quality gate settings. |
| `subagentModel` | `enum` | No | Model tier hint for delegation: `heavy`, `standard`, `fast`. |
| `chainSteps` | `object[]` | No | Multi-step chain definition. See [Chain Schema](chain-schema.md). |

### Example

```yaml
id: analyze_data
name: Data Analysis
description: Analyzes CSV data using Python
userMessageTemplateFile: user-message.md
registerWithMcp: true
tools: [csv_validator]
subagentModel: fast  # delegated steps use a lightweight model
```

---

## Arguments Schema

Defines inputs passed to the prompt (`>>prompt arg='value'`).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | `string` | — | Argument name (used in template `{{name}}`). |
| `type` | `string` | `string` | `string`, `number`, `boolean`, `array`, `object`. |
| `required` | `boolean` | `false` | If true, execution fails if missing. |
| `defaultValue` | `any` | — | Used if argument is missing. |
| `description` | `string` | — | shown in MCP client UI. |
| `validation` | `object` | — | Validation rules. |

### Validation Rules

| Rule | Type | Description |
|------|------|-------------|
| `minLength` | `number` | Minimum string length. |
| `maxLength` | `number` | Maximum string length. |
| `pattern` | `string` | Regex pattern to match (e.g., `^https://`). |

### Example

```yaml
arguments:
  - name: url
    type: string
    required: true
    validation:
      pattern: "^https://"
  - name: retries
    type: number
    defaultValue: 3
```

---

## Gate Configuration

Control which quality gates apply to this prompt.

| Field | Type | Description |
|-------|------|-------------|
| `include` | `string[]` | Canonical gate IDs to enforce. |
| `exclude` | `string[]` | Auto-assigned gates to ignore. |
| `framework_gates` | `boolean` | Enable methodology gates? Default `true`. |
| `inline_gate_definitions` | `object[]` | Custom gate rules for this prompt. |

### Example

```yaml
gateConfiguration:
  include: ["technical-accuracy"]
  exclude: ["creative-writing"]
  framework_gates: false
```
