Presentation Skill

Build professional Marp presentations from a structured sketch file.

Invocation

/presentation <filename>

• No filename provided → ask for one
• File does not exist → create a skeleton sketch at that path (use references/skeleton.md as the template), then stop — user fills it in and re-runs
• File exists → build the presentation from the sketch

Sketch Format

Standard markdown plus custom tags:

Component	Syntax
Title	# Title — first # heading; becomes presentation title and slug
Slide	## Slide Title — each ## is one slide
Bullets	- text
Numbered list	1. text
Viz embed	[viz: name] — fuzzy-match against .viz/*.png (no extension needed)
Image	[image: path] — any local image path, referenced in-place
Callout box	[callout: text] — highlighted box for key stats or quotes
Two-column	[two-col] ... [---] ... [/two-col]
Mermaid diagram	[mermaid] ... [/mermaid] — fenced mermaid code, pre-rendered to PNG
Table	standard markdown pipe table
Block quote	> text
Speaker notes	[notes: text] — hidden from audience

See references/component-map.md for exactly how each component renders in Marp.

Building the Presentation

You MUST follow these steps exactly. Do NOT skip the parallel agent approach. Do NOT write slides directly into a single file yourself. Every slide MUST be generated by its own dedicated Task agent.

Step 1: Parse slides

Split the sketch on ## headings. Each slide spec = heading + all content until the next ## or EOF.

Step 2: Resolve images

• Resolve [viz: name] — fuzzy-match against .viz/*.png; if ambiguous, list matches and ask before proceeding
• Copy all resolved images to presentations/<slug>/assets/

Step 3: Generate all slides in parallel

Spawn a Task agent for every slide (subagent_type general-purpose, model sonnet). CRITICAL: Launch ALL slide agents in a single message containing multiple Task tool calls — this is what makes them run concurrently. Do NOT spawn them one at a time across separate messages.

To keep prompts small enough to fit all slides in one message, do NOT inline reference file contents. Each agent receives only:

• The slide spec from the sketch (the ## heading + its content)
• The presentation slug and assets path (presentations/<slug>/assets/)
• File paths to read: {SKILL_DIR}/references/marp-syntax.md, {SKILL_DIR}/references/component-map.md, {SKILL_DIR}/references/template.md
• The compile script path: {SKILL_DIR}/scripts/compile_marp.sh
• Instruction: "Read the reference files first, then follow the workflow below."

Each agent's workflow:

1. Generate — Translate the slide spec into Marp markdown using the component mappings
2. Render mermaid — If the slide contains [mermaid]...[/mermaid] blocks, render each to PNG via mmdc -i temp.mmd -o presentations/<slug>/assets/mermaid-<slide>-<n>.png -t neutral -b white -s 2 and replace with ![w:800](./assets/mermaid-<slide>-<n>.png)
3. Preview — Build a temporary single-slide Marp file (template frontmatter + --- + this slide's markdown), compile to PNG via marp --images png --no-stdin --allow-local-files --html <tmpfile>, and visually inspect the rendered image
4. Refine — If the preview shows overflow, clipping, or layout problems, adjust the markdown and re-preview (up to 2 refinement passes)
5. Return — Return the final slide markdown only (no frontmatter, no --- separators)

Collect all results in slide order.

Step 4: Stitch

Concatenate: frontmatter (from references/template.md) + title slide + all slide outputs, separated by ---.

Step 5: Write and compile

1. Write presentations/<slug>/slides.md
2. Compile: {SKILL_DIR}/scripts/compile_marp.sh <slug> pdf
3. Show the user the PDF path and ask: "Also export as PowerPoint (.pptx)?"
4. If yes: {SKILL_DIR}/scripts/compile_marp.sh <slug> pptx

Output: presentations/<slug>/slides.pdf (and optionally slides.pptx)

Marp Rendering Notes

• Inline styles: The compile script uses --html so inline style="" attributes work. But prefer CSS classes defined in the template (callout, cols, col) for reliability.
• Diagrams: Use Mermaid for flowcharts, sequence diagrams, gantt charts, state diagrams, ER diagrams. For visualizations Mermaid can't express (timelines, custom bar charts, etc.), fall back to matplotlib — write a Python script and run it via uv run --project {SKILL_DIR}/scripts python <script> to save a PNG to presentations/<slug>/assets/, then embed it.
• Slide sizing: Usable content area is roughly 1000x500px after heading and padding. Content that exceeds this will be clipped in PDF output — there is no scrolling.

References

• references/skeleton.md — Template used when creating a new sketch file
• references/component-map.md — Sketch component → Marp markdown mappings
• references/template.md — Standard CSS template for slides.md
• references/marp-syntax.md — Full Marp syntax reference
• references/chart-styling.md — Matplotlib graph styling for viz outputs