Schema Author

Schema Author

This skill is about one thing: the output schema, the Zod shape a <Task> produces and the next step consumes: Smithers's contract between steps. The runtime injects a JSON-schema description into the prompt, parses the response, validates against Zod, retries on mismatch, and persists the row; everything downstream (ctx.outputMaybe(...), <Branch>, <Loop until={...}>) reads that row. A loose or prose-heavy schema makes every later step unreliable; a tight, typed one makes the graph deterministic.

This is the BAML insight: the prompt is a schema. Don't beg the model for JSON in prose: declare the type and let the runtime enforce it, before you write the prompt or the workflow.

When to reach for it

• A step's output feeds a later step, a branch condition, or a loop's until, where a wrong shape would silently break the run.
• An agent keeps returning the right idea in the wrong shape (free text where you need an enum, missing a field downstream code indexes into).
• You're about to add a reviewer/retry to compensate for output you could just type instead.

Skip it when the output is terminal (nothing downstream reads it): a summary string is fine.

Design the contract first, keep it minimal

Author the schema in createSmithers({...}) before the prompt or the graph. Include only what downstream actually reads: a one-line summary plus the few fields the next step indexes into. Every extra field is another thing the agent can get wrong and another retry.

const { Workflow, smithers, outputs } = createSmithers({
  triage: z.object({
    summary: z.string(),                                  // human-readable, terminal
    severity: z.enum(["low", "medium", "high"]),          // a <Branch> reads this
    category: z.enum(["bug", "feature", "question"]),     // routes to a specialist
    needsHuman: z.boolean(),                              // gates an <Approval>