do-presentation

name	do-presentation
description	Use when creating a presentation about a feature, concept, or system. Researches the topic, structures content for accessibility, generates diagrams, and exports polished Marp slides styled to the repo's design system. Triggered by 'make a presentation', 'create slides', 'do-presentation', or 'explain this as a deck'.
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, Agent
argument-hint	<topic or feature name>
context	fork

Make a Presentation

Creates polished, educational presentations about any feature, concept, or system in the current repo. Outputs Marp markdown with PDF and HTML exports, styled to match the repo's design system.

What this skill does

1. Researches the topic deeply across the codebase
2. Structures content using proven educational frameworks (high-school accessible)
3. Detects the repo's design system and builds a matching Marp theme
4. Generates diagrams (Mermaid/ASCII) for architecture and flows
5. Exports to PDF, HTML, and optionally PPTX

When to load sub-files

Sub-file	Load when...
CONTENT_GUIDE.md	Structuring slide content — educational best practices, slide types, pacing
THEME_DETECTION.md	Building the Marp CSS theme — how to find and adapt the repo's design system

Quick start

The topic comes from $ARGUMENTS. If empty, ask the user what to present on.

Step 1: Scope the topic

Determine what the presentation covers:

• A single feature? A system overview? A concept explanation?
• Who is the audience? Default: general technical audience, high-school reading level
• How long? Default: 10-15 slides (5-8 minute talk)

Ask the user only if the scope is genuinely ambiguous. Otherwise, make a reasonable call.

Step 2: Research

Spawn an Explore agent to deeply research the topic:

• Read relevant source files, docs, READMEs, and config
• Trace how the feature works end-to-end
• Identify the 3-5 key concepts someone must understand
• Find concrete examples, real data, or code snippets
• Note any diagrams that would clarify architecture or flow

Research output should answer:

1. What is this? (one sentence a teenager could understand)
2. Why does it exist? (the problem it solves)
3. How does it work? (the mechanism, simplified)
4. What are the key parts? (components, steps, or layers)
5. What's interesting about it? (the clever bit, the trade-off, the insight)

Step 3: Design the slide structure

Read CONTENT_GUIDE.md for educational best practices.

First, determine the presentation type — it changes the opening structure:

Type	Audience	Opening structure
Educational / internal	Technical teammates, general audience	What → How → Why it matters
Client-facing / working session	Client decision-makers, executives	Why (their problem) → How (the approach) → What (the specifics)

For client-facing decks, the first 3–4 slides must establish: (1) who the client is and what their operating reality looks like, (2) the problem they are experiencing in their own terms, (3) the governing principle or goal — before any solution, scope, or technical content appears. Opening with a solution before the client sees their problem reflected back is the single most common failure mode.

Default slide structure (educational):

1. Title slide (hook + subtitle)
2. The Problem (why this exists — relatable scenario)
3. The Big Idea (one-sentence thesis)
4. How It Works — Overview (diagram or visual)
5-8. Key Concepts (one per slide, with examples)
9. Architecture/Flow Diagram
10. Real Example (concrete, from the actual codebase)
11. Trade-offs / Design Decisions
12. Summary (3 bullet takeaway)
13. Questions / Further Reading

Client-facing / working session structure:

1. Title + session framing (not a pitch — a working session)
2. Why: Who is the client? (their context, their operating reality)
3. Why: The problem they are experiencing (in their terms)
4. How: The approach / governing principle
5. How: The mechanism (what the system does, simply)
6. What: The specific scope or decisions
7+. Decision / agenda items (one per slide)
N-1. Summary / next steps
N.  Appendix

Adjust count based on topic complexity. Aim for one idea per slide.

Step 4: Detect and build the theme

Read THEME_DETECTION.md for the full detection process. Quick version:

1. Search for CSS/design tokens in the repo:
   • **/*.css, **/tailwind.config.*, **/theme.*, **/variables.*, **/tokens.*
   • **/styles/**, **/design-system/**, **/ui/**
2. Extract: accent colors, fonts, border radius, spacing
3. If no design system found, use the clean light fallback theme
4. Build the Marp style: block from extracted tokens

IMPORTANT: All presentations use light backgrounds. Even if the repo's design system is dark, adapt it to light mode. Keep the accent colors and fonts, invert backgrounds to white/light gray, use dark text. See the "Light Mode Mandate" section in THEME_DETECTION.md for the full dark→light token mapping.

Step 5: Collect brand logos

When the presentation mentions companies, products, or branded technologies, pull in their logos for visual polish. Logos appear inline next to brand names or as small icons in tables/lists.

Source priority:

1. Simple Icons (GitHub raw) — 3000+ tech/business brands, monochrome SVGs, no auth

   # Download SVG (slug is lowercase brand name, no spaces)
   curl -s "https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/{slug}.svg" \
     -o diagrams/logo-{slug}.svg
   

   Common slugs: anthropic, stripe, github, slack, redis, python, docker, linear, sentry, notion, telegram, postgresql

   To find a slug, check: https://raw.githubusercontent.com/simple-icons/simple-icons/develop/slugs.md

2. Google Favicons — universal fallback, any domain, PNG

   curl -sL "https://www.google.com/s2/favicons?domain={domain}&sz=128" \
     -o diagrams/logo-{name}.png
   

Colorizing SVGs for dark backgrounds:

Simple Icons SVGs have no fill color (default black — invisible on dark slides). Inject a fill:

# White (safe default for dark themes)
sed -i '' 's/<path/<path fill="#e6edf3"/' diagrams/logo-{slug}.svg

# Or use the brand's official color (Simple Icons provides these)
sed -i '' 's/<path/<path fill="#FF6600"/' diagrams/logo-{slug}.svg

Converting SVG to PNG (if needed for Marp compatibility):

# macOS built-in, no dependencies, good quality at 512px
qlmanage -t -s 512 -o diagrams/ diagrams/logo-{slug}.svg 2>/dev/null
mv diagrams/logo-{slug}.svg.png diagrams/logo-{slug}.png

Using logos in Marp slides:

<!-- Inline next to text (small, 24-32px) -->
![w:28](diagrams/logo-anthropic.svg) Anthropic ships Managed Agents

<!-- In a table cell -->
| ![w:24](diagrams/logo-stripe.svg) Stripe | Payment processing |

<!-- Larger, standalone -->
![w:80](diagrams/logo-redis.svg)

Rules:

• Only fetch logos for brands that are central to the slide content, not every passing mention
• Keep logos small (24-32px inline, 64-80px standalone) — they accent, not dominate
• SVGs render directly in Marp with --allow-local-files — prefer SVG over PNG for sharpness
• If a brand isn't in Simple Icons, use Google Favicon as fallback
• Don't spend time on logos if the presentation is internal/informal — this is for polished decks

Step 6: Generate diagrams

For any architectural or flow concepts, create diagrams:

1. Prefer ASCII art in code blocks for simple flows (always renders correctly)
2. Use Mermaid for complex diagrams — check if mermaid-render skill is available:
   • Write .mmd file, render to PNG, embed as image
   • Fallback: include as fenced code block (renders in HTML export)
3. Use tables for comparisons, feature matrices, component lists

Diagram guidelines:

• Max 7 nodes/boxes per diagram (cognitive load limit)
• Label every arrow/connection
• Use the repo's accent color for emphasis nodes

Step 7: Write the Marp markdown

Create the presentation file. Location priority:

1. If user specifies a path, use that
2. If a docs/ directory exists, use docs/presentations/<slug>.md
3. Otherwise, use <repo-root>/presentations/<slug>.md

Marp file structure:

---
marp: true
theme: default
paginate: true
backgroundColor: <from-design-system>
color: <from-design-system>
style: |
  /* Theme CSS generated from repo design system */
  ...
---

<!-- _class: lead -->
# Title
subtitle

---

## Slide Title
content...

Writing rules:

• One idea per slide — if you need a scroll bar, split it
• Use <!-- _class: lead --> for section dividers
• Use tables over bullet lists when comparing things
• Use code blocks sparingly — only when the actual code IS the point
• Every 3rd-4th slide should be visual (diagram, table, or formatted example)
• Use > blockquotes for key takeaways or memorable quotes
• Bold key terms on first use
• Use analogies liberally — connect technical concepts to everyday things

Include these utility CSS classes in every theme — they get used on almost every deck:

/* Two-column grid */
.cols { display: grid; grid-template-columns: 1fr 1fr; gap: 24px; margin-top: 10px; }
.cols-3 { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 16px; margin-top: 10px; }

/* Callout — neutral/info (blue left accent) */
.stat {
  background: #eef2ff; border-left: 4px solid #2563a8;
  padding: 12px 20px; margin: 10px 0;
  font-size: 0.96em; font-weight: 600; color: #1a3a6b; line-height: 1.5;
}

/* Warning / risk callout (amber left accent) */
.warn {
  background: #fef3c7; border-left: 4px solid #f59e0b;
  padding: 10px 18px; margin: 10px 0;
  font-size: 0.88em; color: #92400e; line-height: 1.5;
}

/* Option/path cards — for A/B/C decision slides */
.path-card {
  border: 1px solid #e5e7eb; border-radius: 6px;
  padding: 14px 16px; font-size: 0.86em;
}
.path-card strong { display: block; margin-bottom: 4px; }

Use .cols / .cols-3 to break a slide that would otherwise be a dense list into scannable side-by-side sections. Use .stat for governing metrics and key facts. Use .warn for risks and blockers. Use .path-card inside .cols-3 for A/B/C decision options.

Step 8: Self-review pass (before export)

Before running Marp, spawn a subagent to critique the draft. This catches structural and density issues before the user sees a bad first version.

Spawn a plan-reviewer agent with this prompt template:

Review this Marp presentation draft for two things only — structure and density.
Do not evaluate content correctness.

STRUCTURE: Does it open with Why (the audience's problem / context), then How (the approach),
then What (the specifics)? For client-facing decks especially, flag if the first 3 slides do not
establish who the audience is and what problem they are experiencing before any solution content appears.

DENSITY: List every slide that exceeds 6 lines of body text, or has more than 2 dense paragraphs,
or has a table with more than 5 rows and verbose cell text. For each, suggest: split into 2 slides,
convert prose to a .cols layout, or trim to a single key sentence.

Return a short list — flagged slides with one-line diagnosis each. No other feedback.

Act on every flag before exporting. A split slide costs 2 minutes. Sending a dense deck to a client costs a revision cycle.

Step 9: Export

Run Marp CLI to generate outputs:

# PDF (primary deliverable)
npx --yes @marp-team/marp-cli "<source>.md" --pdf --allow-local-files -o "<source>.pdf"

# HTML (interactive, with slide navigation)
npx --yes @marp-team/marp-cli "<source>.md" --html --allow-local-files -o "<source>.html"

# PPTX (only if user requests editable format)
npx --yes @marp-team/marp-cli "<source>.md" --pptx --allow-local-files -o "<source>.pptx"

Step 10: Verify

After export, confirm:

• PDF generated without errors
• HTML generated without errors
• Slide count matches plan
• No slide flagged in the review pass was left unaddressed
• Report file locations to user

Output

Tell the user:

1. What files were created and where
2. Slide count and estimated talk time (~30 seconds per slide)
3. How to edit (it's just markdown) and re-export

Version history

• v1.2.0 (2026-05-07): Added client-facing Why→How→What structure guidance (Step 3), self-review critique pass via subagent (Step 8), utility CSS classes in theme defaults (Step 7), "Client-Facing Decks" section in CONTENT_GUIDE.md. Driven by real session: first-pass deck opened with V0.5 scope before establishing client context; dense slides caught only after user review — both preventable with the review pass.
• v1.1.0 (2026-04-13): Added Step 5 (brand logo collection via Simple Icons + Google Favicons), renumbered subsequent steps
• v1.0.0 (2026-04-10): Initial — research, structure, theme detection, Marp export