MDX Workflow Authoring

create-workflow writes a .tsx orchestration skeleton and its prompts, then verifies and documents the result with a companion agent skill. For most workflows you describe the behavior instead of hand-editing the generated .tsx file.

The two-file model

File	What it is	Who edits it
`.smithers/workflows/WORKFLOW_ID.tsx`	Durable run, agent wiring, output schema	Rarely - only when you need branching, schemas, or loops
`.smithers/prompts/WORKFLOW_ID.mdx`	The agent’s instruction - what you actually change	You, always

The .tsx file imports and renders the .mdx file at runtime. Editing the prompt changes agent behavior on the next run - no build step, no TypeScript.

Your first edit

After create-workflow has generated a workflow, open its companion .smithers/prompts/WORKFLOW_ID.mdx:

Write a short, friendly one-sentence greeting for {props.name}.

This is your workflow prompt. Edit this file to change what the agent does -
it is plain Markdown, no TypeScript required. Anything in {curly braces} is a
value passed in from the workflow (here, props.name).

Change the instruction - for example, ask for a haiku:

Write a haiku about {props.name}.

Run it again:

bunx smithers-orchestrator workflow run WORKFLOW_ID --input '{...}'

The agent now writes haiku. The .tsx file didn’t change.

Template syntax

Props come from the workflow input and are interpolated with {props.key}:

Summarize this pull request for a non-technical stakeholder:

> {props.title}

Keep it under two sentences. Plain language only.

Any input field the workflow declares is available as props.<field> in the prompt.

Create a new MDX-backed workflow

Use the built-in create-workflow workflow:

bunx smithers-orchestrator workflow run create-workflow

Or scaffold by hand:

Create .smithers/prompts/my-task.mdx - write the instruction.
Copy examples/init-pack/hello.tsx, rename the workflow name and prompt import.
Run bunx smithers-orchestrator workflow run my-task.

When to graduate to TypeScript

Stay in MDX as long as possible. Add TypeScript only when you need:

Multi-step branching - different tasks depending on a prior output
Parallel fan-out - multiple tasks running simultaneously
Validated structured output - Zod schemas on task results
Loops - retry until a score threshold passes

See the TypeScript SDK for all of that. Start with MDX, graduate only when the task demands it.

Common Footguns

JSX API

Start

Articles

Learn

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

MDX Workflow Authoring

The two-file model

Your first edit

Template syntax

Create a new MDX-backed workflow

When to graduate to TypeScript

​The two-file model

​Your first edit

​Template syntax

​Create a new MDX-backed workflow

​When to graduate to TypeScript

The two-file model

Your first edit

Template syntax

Create a new MDX-backed workflow

When to graduate to TypeScript