---
name: markdownto-narrate
description: Write or revise Markdown To narration manuscripts for clear, engaging spoken delivery.
---
# Markdown To narrate
## Contract and workflow
Read `mdto spec narrate` (or the adjacent `SPEC.md` in a checkout) and the
[shared conventions](https://markdownto.ai/specs/conventions.md) before authoring or
repairing content. Outside a checkout, use the [published spec](https://markdownto.ai/specs/narrate.md).
This skill accompanies `[email protected]`. The spec and its fixtures govern conformance;
editorial advice below is non-normative and should adapt to the user's brief.
If the source declares another version, obtain its matching contract before changing it.
Use `markdownto: [email protected]`. Level-2 headings divide chapters; prose before them forms
an implicit chapter. Read the block, pause, voice, and pronunciation rules before adding
production direction: rendered content and spoken content are not interchangeable.
Use podcast for native two-speaker dialogue. Inspect `mdto narrate --help` for the
estimate, preview, produce, and voices commands.
## Content quality
Write for a listener who cannot scan backward: introduce terms before relying on them,
keep referents clear, and speak numbers in a way the audience can follow. Give a chapter
one through-line, use concrete scenes or examples, and make transitions audible because
headings alone cannot orient the listener. Vary sentence length without filling every
pause. Read a passage aloud and remove phrases that work only on the page. Preserve
source claims and uncertainty when adapting research; do not invent quotes for texture.
## Check and deliver
Validate the file with `mdto validate <path>` before editing existing content and again
after changes. Read diagnostics against the spec's rationale; preserve meaning when
repairing syntax. Prefer spec-owned verbs for edits they support, checking their current
`--help`; otherwise make a focused source edit, preserving unrelated content and IDs.
Render with `mdto render <path>` and inspect the result when available. Validation checks
structure, not editorial quality: review the content against the user's purpose as well.
Without the CLI, use the contract and examples and report that validation was not run.
Deliver the Markdown source and any requested artifacts, stating what was actually checked.
Before paid generation or audition, inspect the command's help and estimate the requested
scope. Use existing authorization when it covers the cost; otherwise show the estimate
and obtain approval before spending. Supply `--yes` only within that authorization.
A text draft does not require audio generation. Mock output checks the pipeline, not
spoken quality; never present it as a completed listening review.
Give this guide to your agent, or read it as an author. It covers workflow and editorial judgment; the specification defines conformance.
Contract and workflow
Read mdto spec narrate (or the adjacent SPEC.md in a checkout) and the shared conventions before authoring or repairing content. Outside a checkout, use the published spec. This skill accompanies [email protected]. The spec and its fixtures govern conformance; editorial advice below is non-normative and should adapt to the user's brief. If the source declares another version, obtain its matching contract before changing it.
Use markdownto: [email protected]. Level-2 headings divide chapters; prose before them forms an implicit chapter. Read the block, pause, voice, and pronunciation rules before adding production direction: rendered content and spoken content are not interchangeable. Use podcast for native two-speaker dialogue. Inspect mdto narrate --help for the estimate, preview, produce, and voices commands.
Content quality
Write for a listener who cannot scan backward: introduce terms before relying on them, keep referents clear, and speak numbers in a way the audience can follow. Give a chapter one through-line, use concrete scenes or examples, and make transitions audible because headings alone cannot orient the listener. Vary sentence length without filling every pause. Read a passage aloud and remove phrases that work only on the page. Preserve source claims and uncertainty when adapting research; do not invent quotes for texture.
Check and deliver
Validate the file with mdto validate <path> before editing existing content and again after changes. Read diagnostics against the spec's rationale; preserve meaning when repairing syntax. Prefer spec-owned verbs for edits they support, checking their current --help; otherwise make a focused source edit, preserving unrelated content and IDs. Render with mdto render <path> and inspect the result when available. Validation checks structure, not editorial quality: review the content against the user's purpose as well. Without the CLI, use the contract and examples and report that validation was not run. Deliver the Markdown source and any requested artifacts, stating what was actually checked.
Before paid generation or audition, inspect the command's help and estimate the requested scope. Use existing authorization when it covers the cost; otherwise show the estimate and obtain approval before spending. Supply --yes only within that authorization. A text draft does not require audio generation. Mock output checks the pipeline, not spoken quality; never present it as a completed listening review.