MDX Workflow Authoring

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:

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:

Write a haiku about {props.name}.

Run it again:

bunx smthrs 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>.

Create a new MDX-backed workflow

Use the built-in create-workflow workflow:

bunx smthrs workflow run create-workflow

Or scaffold by hand:

Create .smithers/prompts/my-task.mdx and write the instruction.
Copy examples/init-pack/hello.tsx, rename the workflow name and prompt import.
Run bunx smthrs 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 for all of that.

Start

Articles

Learn

Capabilities

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