> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MDX Workflow Authoring

> Author workflows by editing plain Markdown prompt files. No TypeScript required - change the instruction, run again, see it change.

`create-workflow` writes a `.tsx` orchestration skeleton and its prompts, then verifies and documents it with a companion agent skill.

## The two-file model

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

The `.tsx` imports and renders the `.mdx` at runtime: editing the prompt changes behavior on the next run, no build step, no TypeScript.

## Your first edit

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

```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
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, e.g. ask for a haiku:

```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
Write a haiku about {props.name}.
```

Run it again:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}`:

```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
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>`.

## Create a new MDX-backed workflow

Use the built-in `create-workflow` workflow:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator workflow run create-workflow
```

Or scaffold by hand:

1. Create `.smithers/prompts/my-task.mdx` and write the instruction.
2. Copy `examples/init-pack/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 until you need:

* **Multi-step branching** - different tasks depending on a prior output
* **Parallel fan-out** - 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.