---
name: markdownto-slides
description: Author, repair, validate, and review portable slides documents and their rendered results.
---
# Working with slides

Use this skill when the user wants the slides workflow. Read [SPEC.md](SPEC.md), then [shared conventions](../conventions.md). Published equivalents live at https://markdownto.ai/specs/slides.md and https://markdownto.ai/specs/conventions.md. The spec and fixtures govern conformance; this editorial guidance is non-normative and adapts to the user's brief.

## Author and repair

Confirm the purpose from the request, inspect any supplied references, and preserve supplied content and constraints. Start from a relevant valid fixture, not a remembered grammar. Write the envelope and meaningful `##` sections, then sparse direction. Avoid invented IDs. Run `mdto validate file.md` after edits. Repair diagnostics at their reported location using the spec's rationale; preserve unrelated source. Prefer the spec-owned verbs for state changes and preview their diff when useful. If the CLI is unavailable, perform a clearly labeled manual check against the spec and do not claim tool validation.

## Editorial judgment

Establish audience, purpose, speaking duration, and the decision the deck should make possible. Give every slide one claim. Write a narrative outline before choosing layouts. Alternate quiet title/statement slides with evidence slides; do not fill every slide with bullets. Use split only for a real comparison and quote only for attributable quoted words. Label illustrative numbers. Use image layout when a picture carries the point; source images honestly and provide useful alt text. Speaker notes carry nuance, transitions, citations and rehearsal cues without making the audience read the script. Keep titles short, avoid tiny text, and split an overloaded slide instead of shrinking it. Rehearse with keyboard navigation, check overview, verify notes stay out of PDF, and examine every exported page at actual size. A technically valid deck can still be visually weak: revise composition, rhythm, evidence and ending independently of parser validation.

## Review and delivery

Use `mdto render file.md` and the spec's build or review verbs. Inspect the actual resulting interface or artifact, including mobile/narrow views, keyboard controls and content extremes. Verify state-changing UI actions against the same CLI operations. Deliver the Markdown and usable output, explain any real limitation, and never equate a valid file with a successful artifact review. If artifact inspection is unavailable, say which checks remain undone.

## Rich but dependable decks

Choose among the ten layouts in SPEC §2.2. The website example and `fixtures/valid/showcase.md` demonstrate every one with bullets, an original pull quote, comparisons, pictures, video, and speaker notes. Use three-column for three parallel ideas, image-left/right when the picture needs explanation, and section for a real change of topic. Keep individual slides sparse even when the whole deck is rich.

Author palette/font defaults in frontmatter and override them sparingly per slide. Hex colors in YAML must be quoted. Prefer a coherent palette, a readable body size, and the two system type families over arbitrary custom fonts. Validation enforces contrast and bounded body size; the browser fit check enforces geometry, not good taste.

Use local PNG/JPEG/GIF files beside the manuscript for portable CLI builds. Give photographs honest provenance and alt text; do not describe generated imagery as documentary evidence. The bundled lake is AI-generated illustrative photography. The source image and prompt are recorded in `skills/markdownto/SLIDE-ASSETS.md` in the checkout.

YouTube is a live presentation enhancement with a permanent link fallback. Verify the chosen video's availability and permission to embed; loading the iframe is not proof that a restricted video plays. Do not promise video playback offline or inside PDF. Open the hosted deck to rehearse, test navigation stops playback, and confirm the PDF retains the readable URL. Local `file:` previews intentionally use the external link.

## Agent visual-review loop

Run `mdto slides images --file deck.slides.md --out /tmp/deck-review --json`. Open each PNG path in the response, review composition and visible markers, and check every slide's `issues` array. The manifest records titles, numbers, dimensions and source hash so findings map back to the manuscript. Fix the source and re-export to a new directory; use `--slide 3` to inspect just the third slide during iteration. Capture success means images were produced, not that the layout passed: resolve fit findings before delivery. PNGs are fixed-size slide canvases without controls or speaker notes; YouTube remains a static fallback. Chrome/Chromium is required, with `--browser` or `MDTO_CHROME` available for agent environments.