Zap.md Recipe Format: Fields, Inputs, and Validation Rules

Zap.md is the single source of truth for a one-shot content recipe. It lives inside an Eve skill directory and combines YAML frontmatter — which the Zap runtime parses and validates — with Markdown prose that gives the agent authoring context about intent, creative direction, and usage notes. Everything the CLI, web runtime, and provider adapters need to plan and execute a pipeline is derived from this one file.

Directory Layout

Every Zap recipe lives inside a skill folder with a predictable structure:

agent/skills/zap-<slug>/
  SKILL.md          # Eve skill descriptor — describes the recipe to the agent
  Zap.md            # Recipe definition (frontmatter + prose context)
  prompts/*.md      # Prompt templates referenced by step fields

The prompts/ directory holds Markdown prompt templates. Each template can reference {INPUT_NAME} variables that must be declared in the inputs map of the frontmatter.

Minimum Valid Frontmatter

The smallest Zap.md that passes validation looks like this:

---
zap: launch-trailer
version: 1
description: A short creator video.
budget:
  estimate_usd: 0
  cap_usd: 5
defaults:
  provider: mock
  aspect: "9:16"
inputs:
  PROMPT:
    type: textarea
    label: Prompt
    required: true
steps:
  - id: initial_frame
    kind: image.gen
    provider: mock
    model: mock-image
    prompt: prompts/initial-frame.md
  - id: initial_gen
    kind: video.gen
    provider: mock
    model: mock-video
    inputs: [initial_frame]
    duration_s: 15
    prompt: prompts/initial-gen.md
  - id: stitch
    kind: stitch
    inputs: [initial_gen]
output: Zap.mp4
---

Top-Level Fields

string

required

Unique recipe slug — used as the run identifier in CLI commands and the web dashboard. Must be at least one character. Example: world-cup-entrance.

integer

required

Schema version. Currently 1. Zap will reject recipes with an unrecognised version number before validation begins.

string

required

Human-readable description of what the recipe produces. Shown in the web UI and surfaced to the Eve agent as task context.

object

required

Hard cost constraints for the recipe. Contains two sub-fields:

estimate_usd (number, ≥ 0) — the planner’s pre-run cost estimate. Must not exceed cap_usd.
cap_usd (number, > 0) — the hard spending ceiling. Live runs are rejected before provider submission if the quote exceeds this value.

budget:
  estimate_usd: 1.25
  cap_usd: 5

object

Fallback values applied to any step that does not declare its own provider or aspect.

provider (string, default: "gmi") — the provider adapter used when a step omits provider.
aspect (string, optional) — default aspect ratio forwarded to image and video models (e.g. "9:16", "16:9", "1:1").

object

Map of uppercased variable names to input specs. These are the values a creator supplies when running the recipe — either via --input KEY=value on the CLI or through the web form. Each key becomes a {VARIABLE} available in prompt templates.See Input Schema Fields below for the shape of each value.

array

required

Ordered list of pipeline steps. Must contain at least one step. Steps are executed in declaration order; use the inputs field on each step to express dependencies on earlier steps’ outputs. See the Steps reference for all supported kind values and step-level fields.

string

default:"Zap.mp4"

The filename of the final artifact produced by the stitch step. Defaults to Zap.mp4. Override when producing WebM or a custom output name.

Input Schema Fields

Each entry in the inputs map is an object with the following fields:

string

required

The UI widget and value type for this input. One of:

Value	Description
`string`	Single-line text field
`textarea`	Multi-line text area
`image`	Image file upload
`video`	Video file upload
`select`	Dropdown — requires `options`
`number`	Numeric input

string

Human-readable label shown above the input in the web form. If omitted, the variable name is used.

string

Short helper text shown beneath the input field.

boolean

default:"false"

When true, the Zap runtime will throw a Missing required input error before the pipeline starts if this value is not supplied.

array

Required when type is select. An array of string values the creator can choose from. Example: ["cinematic", "anime", "documentary"].

Validation Rules

The Zap runtime enforces three rules every time a recipe is parsed or run:

Unique step IDs — every steps[].id must be unique within the recipe. Duplicate IDs cause a Duplicate step id error at parse time.
Declared variables — every {VARIABLE} placeholder referenced in a prompt file must have a matching key in the inputs map. The validator checks all prompt paths listed in step.prompt fields.
Budget check — budget.estimate_usd must not exceed budget.cap_usd. This is enforced both at parse time and again at plan time before any provider call is made.

Every {VARIABLE} in a prompt file must be declared in inputs. If a prompt template references {SELFIE} or {STYLE} and those keys are absent from the inputs map, validation will throw Step <id> references undeclared input {VARIABLE} and the run will be blocked.

Validate and Lint Commands

Run these commands after every recipe edit to catch errors before a live run:

# Validate schema, step IDs, and declared variables
npx @wzrdtech/zap@0.1.0 validate

# Run the linter (style, completeness, and budget checks)
npx @wzrdtech/zap@0.1.0 lint

Both commands exit with a non-zero code on failure and print a structured error report to stdout, making them safe to run in CI.

Legacy 0.3.1 Recipes

Core Concepts

Web App

Providers

Agent Framework

Deployment

Reference

Browser Use

Zap.md Recipe Format: Fields, Inputs, and Validation Rules

Directory Layout

Minimum Valid Frontmatter

Top-Level Fields

Input Schema Fields

Validation Rules

Validate and Lint Commands

​Directory Layout

​Minimum Valid Frontmatter

​Top-Level Fields

​Input Schema Fields

​Validation Rules

​Validate and Lint Commands

Directory Layout

Minimum Valid Frontmatter

Top-Level Fields

Input Schema Fields

Validation Rules

Validate and Lint Commands