/schema-author

name: schema-author
description: Design the Zod output schema of a Smithers <Task> as the contract between steps. Use when a step's output feeds a later step (or a branch/loop condition) and must be reliable — design the schema first, keep it minimal, and prefer typed fields over prose so downstream rendering can depend on it.

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>
  }),
});

• **Prefer enums and typed fields over prose.** `z.enum([...])`, `z.boolean()`,

`z.number()` give the next step something it can switch on. A free-string status is a bug waiting for a typo.

• **Make required things required.** Optional fields downstream assumes exist

are the classic silent failure: if `fix` always reads `analysis.issues`, don't make `issues` optional.

• **Constrain values, not just types.** `z.number().min(0).max(100)`,

`z.array(...).min(1)`: a validation failure feeds the error back and the agent self-corrects on retry, so tighter bounds are free reliability. Annotate non-obvious fields with `.describe("...")`; that text rides into the injected JSON-schema block and steers the agent.

Wire it: every `<Task>` gets `output={outputs.x}`

The schema is referenced by the typed `outputs.x` handle, which gives compile-time checks (a typo in the key is a type error):

<Task id="triage" output={outputs.triage} agent={analyst}>
  {`Triage: ${ctx.input.report}`}
</Task>

{/* downstream reads typed fields — no string parsing, no guessing */}
<Branch
  if={ctx.outputMaybe(outputs.triage, { nodeId: "triage" })?.severity === "high"}
  then={<Task id="escalate" .../>}
  else={<Task id="queue" .../>}
/>

The prompt body stays clean: end it with the task, let the runtime append the schema. Don't hand-write a "return JSON like {…}" block: it fights the injected one (see `skills/prompt-author/SKILL.md`).

When a task simply consumes an upstream output with no branching involved, prefer `<Task deps={{ triage: outputs.triage }}>` with a `(deps) => ...` callback: it makes the dependency explicit and needs no `ctx.outputMaybe` guard. `ctx.outputMaybe`/`<Branch>` stays right when downstream logic depends on the row's content, as above.

Rich or extensible outputs: `z.looseObject`

When you can't enumerate every field up front (a typed-extraction step, a payload that carries pass-through metadata, an evolving spec), use `z.looseObject({...})`: name and type the fields downstream *depends on*, and let the agent attach extra keys without tripping validation.

extract: z.looseObject({
  title: z.string(),
  amount: z.number(),          // downstream math reads this
  // agent may also return vendor, date, lineItems… — preserved, not rejected
}),

Use a strict `z.object` when the shape is a true contract a branch/loop keys off; use `z.looseObject` when richness and forward-compatibility matter more than locking the shape.

Verify the contract holds

Attach a `schemaAdherence` scorer to confirm the shape holds run to run, and read the persisted row:

bunx smthrs scores <run-id>          # did adherence hold?
bunx smthrs output <run-id> triage   # see the persisted row

See `skills/smithers/SKILL.md` for the runtime/CLI surface and `docs/llms-core.txt` ("The runtime injects a JSON-schema description … validates against Zod") for the exact validate-and-retry mechanics.