---
title: MDX Workflow Authoring
description: Author workflows by editing plain Markdown prompt files. No TypeScript required - change the instruction, run again, see it change.
---

`init` seeds two things side-by-side: a `.tsx` orchestration skeleton that handles execution, and an `.mdx` prompt file you edit to change what the agent does. For most workflows you never touch the `.tsx` file.

## The two-file model

| File | What it is | Who edits it |
|---|---|---|
| `.smithers/workflows/hello.tsx` | Durable run, agent wiring, output schema | Rarely - only when you need branching, schemas, or loops |
| `.smithers/prompts/hello.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 `bunx smithers-orchestrator init`, open `.smithers/prompts/hello.mdx`:

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

This is your hello-world workflow. 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:

```markdown
Write a haiku about {props.name}.
```

Run it again:

```bash
bunx smithers-orchestrator workflow run hello --name Ada
```

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}`:

```markdown
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:

```bash
bunx smithers-orchestrator workflow run create-workflow
```

Or scaffold by hand:

1. Create `.smithers/prompts/my-task.mdx` - write the instruction.
2. Copy `.smithers/workflows/hello.tsx`, rename the workflow name and prompt import.
3. 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](/jsx/overview) for all of that. Start with MDX, graduate only when the task demands it.
