marp-slide

name	marp-slide
description	Use when users request slide creation, presentations, or Marp documents. Creates professional Marp slides with 7 themes (default, minimal, colorful, dark, gradient, tech, business). Supports custom themes, image layouts, and "make it look good" requests.

Marp Slide Creator

Create professional, visually appealing Marp presentation slides with 7 pre-designed themes and built-in best practices.

When to Use This Skill

Use this skill when the user:

• Requests to create presentation slides or Marp documents
• Asks to "make slides look good" or "improve slide design"
• Provides vague instructions like "良い感じにして" (make it nice) or "かっこよく" (make it cool)
• Wants to create lecture or seminar materials
• Needs bullet-point focused slides with occasional images

Red Flags (Anti-Rationalization)

STOP and READ if you are thinking:

• "I know Marp syntax well enough, no need to read the references" → WRONG. Always read references/marp-syntax.md and the relevant template. Marp image syntax and directives have specific rules that differ from standard Markdown.
• "I'll just use the default theme, the user didn't specify" → WRONG. Infer the theme from content type using the Quick Start theme selection rules (technical → tech, business → business, creative → colorful/gradient, academic → minimal). Only fall back to default after inference fails.
• "I'll write the CSS from scratch instead of using the template" → WRONG. Templates contain tested, embedded CSS. Modifying CSS without reading references/theme-css-guide.md produces broken slides.

Rationalization Table

Agent Excuse	Reality
"The slide content is simple, I don't need a template"	Templates embed tested CSS. Without them, slides render with no styling in Marp.
"I'll combine all content onto fewer slides for efficiency"	Dense slides violate the 3-5 bullet points rule and destroy readability.
"The user will fix the image syntax later"	Broken Marp image directives (e.g., missing size or path) silently fail — the user sees nothing, not an error.
"I already checked best practices on a previous run"	Best practices are re-read per invocation. Memory does not persist between sessions.

Execution Mode

• Mode: prompt-first for content-creation; optional local-venv scripts/render for rendering.
• Rationale: Content-creation (picking templates, writing Marp-compatible markdown) is prompt-first and needs no runtime. Rendering to .pptx/.pdf/.html/.png/.jpeg is handled by an optional Python wrapper (scripts/render.py, invoked through a local venv) that pre-processes mermaid diagrams with a locally-installed mmdc before calling a locally-installed marp-cli. All rendering dependencies live under scripts/.venv/ and scripts/node_modules/ — nothing is installed globally.

Script Contract

• Input: a Marp-compatible .md file (positional arg to scripts/render.py).
• Flags: --format {pptx,pdf,html,png,jpeg} (default pptx), --output PATH, --no-mermaid, --strict-mermaid, --theme NAME.
• Output: single file in the requested format at --output (or <input_stem>.<format> next to the input).
• Side effects: per-deck cache directory <input_stem>_assets/ with diagram-<sha1>.mmd and .svg for each unique mermaid block. Re-runs reuse cached SVGs.
• Binary resolution: marp and mmdc are resolved from scripts/node_modules/.bin/ (local-venv install); falls back to PATH if absent. System-wide installs are not required.
• Exit codes: 0 success · 1 bad args / missing input · 2 marp CLI unavailable (run install.sh) · 3 marp rendering failed · 4 mermaid preprocessing failed AND --strict-mermaid was set.

Safety Boundaries

• Scope: Create or modify only the Marp .md file the user requested. Do not modify existing templates or CSS assets in the skill directory.
• Output Location: Save output to the user's working directory or the location they specify. Do not hardcode output paths.
• No External Fetching: Do not download images or external resources unless the user explicitly provides URLs and requests it.
• Template Integrity: Read templates from assets/ as references. Never overwrite them.
• Rendering Trust: scripts/render.py always invokes marp with --allow-local-files, so marp can embed any file the current user can read. Only render .md files you trust; do not run the renderer on decks from untrusted sources.

Validation Evidence

• Primary: The output .md file contains valid Marp frontmatter (marp: true, theme, paginate directives).
• Secondary: Every slide uses --- separators, title slide has <!-- _class: lead -->, and image directives use Marp syntax (not standard Markdown).
• Quality Gate: All items in the Quality Checklist (below) pass before delivering to the user.

Quick Start

Step 1: Select Theme

First, determine the appropriate theme based on the user's request and content.

Quick theme selection:

• Technical/Developer content → tech theme
• Business/Corporate → business theme
• Creative/Event → colorful or gradient theme
• Academic/Simple → minimal theme
• General/Unsure → default theme
• Dark background preferred → dark or tech theme

For detailed theme selection guidance, read references/theme-selection.md.

Step 2: Create Slides

1. Read relevant references first:

   • Always start by reading references/marp-syntax.md for basic syntax
   • For images: references/image-patterns.md (official Marpit image syntax)
   • For advanced features (math, emoji): references/advanced-features.md
   • For custom themes: references/theme-css-guide.md

2. Copy content from the appropriate template file:

   • assets/template-basic.md - Default theme (most common)
   • assets/template-minimal.md - Minimal theme
   • assets/template-colorful.md - Colorful theme
   • assets/template-dark.md - Dark mode theme
   • assets/template-gradient.md - Gradient theme
   • assets/template-tech.md - Tech/code theme
   • assets/template-business.md - Business theme

3. Read references/best-practices.md for quality guidelines

4. Structure content following best practices:

   • Title slide with <!-- _class: lead -->
   • Concise h2 titles (5-7 characters in Japanese; 2-5 words in English)
   • 3-5 bullet points per slide
   • Adequate whitespace

5. Add images if needed using patterns from references/image-patterns.md

6. Save to the user's working directory (or their specified output path) with .md extension

Step 3: Render (optional)

If the caller wants .pptx, .pdf, .html, or image output — not just the .md — use the skill's own renderer:

bash scripts/install.sh            # one-time: creates scripts/.venv + scripts/node_modules
scripts/render INPUT.md            # default: .pptx with mermaid pre-rendered
scripts/render INPUT.md --format pdf

The renderer:

• runs entirely from a local Python venv (scripts/.venv/) and local node_modules/ (scripts/node_modules/) — nothing installed globally;
• handles mermaid diagrams (pre-rendered to SVG via mmdc before marp sees them) — closes the marp-core gap that leaves mermaid as raw code blocks;
• supports formats pptx, pdf, html, png, jpeg;
• caches SVG diagrams in <input>_assets/ by SHA1 of the mermaid source (re-runs skip mmdc);
• degrades gracefully when mmdc is absent (prints a WARN, leaves mermaid as code).

See scripts/README.md for CLI flags, CI integration, and troubleshooting. See ## Dependencies below for what install.sh sets up.

Available Themes

1. Default Theme

Colors: Beige background, navy text, blue headings Style: Clean, sophisticated with decorative lines Use for: General seminars, lectures, presentations Template: template-basic.md

2. Minimal Theme

Colors: White background, gray text, black headings Style: Minimal decoration, wide margins, light fonts Use for: Content-focused presentations, academic talks Template: template-minimal.md

3. Colorful & Pop Theme

Colors: Pink gradient background, multi-color accents Style: Vibrant gradients, bold fonts, rainbow accents Use for: Youth-oriented events, creative projects Template: template-colorful.md

4. Dark Mode Theme

Colors: Black background, cyan/purple accents Style: Dark theme with glow effects, eye-friendly Use for: Tech presentations, evening talks, modern look Template: template-dark.md

5. Gradient Background Theme

Colors: Purple/pink/blue/green gradients (varies per slide) Style: Different gradient per slide, white text, shadows Use for: Visual-focused, creative presentations Template: template-gradient.md

6. Tech/Code Theme

Colors: GitHub-style dark background, blue/green accents Style: Code fonts, Markdown-style headers with # symbols Use for: Programming tutorials, tech meetups, developer content Template: template-tech.md

7. Business Theme

Colors: White background, navy headings, blue accents Style: Corporate presentation style, top border, table support Use for: Business presentations, proposals, reports Template: template-business.md

Handling "Make It Look Good" Requests

When users give vague instructions like "良い感じにして", "かっこよく", or "make it cool":

1. Infer theme from content:

   • Business content → business theme
   • Technical content → tech or dark theme
   • Creative content → gradient or colorful theme
   • General → default theme

2. Apply best practices automatically:

   • Shorten titles to 5-7 characters (Japanese) or 2-5 words (English)
   • Limit bullet points to 3-5 items
   • Add adequate whitespace
   • Use consistent structure

3. Enhance visual hierarchy:

   • Use h3 for sub-sections when appropriate
   • Break up dense text into multiple slides
   • Ensure logical flow (intro → body → conclusion)

4. Maintain professional tone:

   • Match formality to content
   • Use parallel structure in lists
   • Keep technical terms consistent

Image Integration

For slides with images, consult references/image-patterns.md for detailed syntax.

Common patterns:

• Side image: ![bg right:40%](image.png) - Image on right, text on left
• Centered: ![w:600px](image.png) - Centered with specific width
• Full background: ![bg](image.png) - Full-screen background
• Multiple images: Multiple ![bg] declarations

Example lecture pattern:

## Slide Title

![bg right:40%](diagram.png)

- Explanation point 1
- Explanation point 2
- Explanation point 3

File Output

Save the final Marp file with .md extension to the user's working directory or a path they specify:

• presentation.md
• seminar-slides.md
• lecture-materials.md

Quality Checklist

Before delivering slides, verify:

• Theme selected appropriately for content
• CSS theme is embedded in the file
• Title slide uses <!-- _class: lead -->
• All h2 titles are concise (5-7 chars Japanese / 2-5 words English)
• Bullet points are 3-5 items per slide
• Images use proper Marp syntax
• File saved to user's working directory or specified path
• Content follows best practices

Dependencies

The content-creation portion of this skill (picking templates, writing Marp-compatible markdown) has no runtime dependencies — it's prompt-first, produces a .md file, and is portable across any environment.

The rendering portion (optional; see Step 3 above) is fully local — no global installs. bash scripts/install.sh sets up everything under scripts/.venv/ and scripts/node_modules/:

Dependency	Where installed	How
Python 3.10+	host	system package manager
Node.js 18+	host	https://nodejs.org/
Python venv	scripts/.venv/	install.sh → python3 -m venv (stdlib only, no pip packages)
@marp-team/marp-cli	scripts/node_modules/	install.sh → npm install (local, not -g)
@mermaid-js/mermaid-cli	scripts/node_modules/	install.sh → npm install (local, not -g). Optional: without it mermaid degrades to code.
Headless Chromium	Puppeteer cache	auto-downloaded by marp/mmdc on first npm install (~200 MB)

Run bash scripts/install.sh once to install and verify all of the above. The script is idempotent — safe to re-run. To fully uninstall, just delete scripts/.venv/ and scripts/node_modules/.

CI / sandboxed environments

Set these env vars before running install.sh on networks that block the Puppeteer Chromium download:

export PUPPETEER_SKIP_DOWNLOAD=true
export PUPPETEER_EXECUTABLE_PATH=/path/to/chromium

Cyrillic / CJK / RTL text in mermaid diagrams

mmdc's default font does not contain all Unicode ranges — non-Latin text in a mermaid diagram may render as boxes. Fix via a mermaid config JSON, applied one of two ways:

Auto-load: drop a mermaid-config.json into scripts/; render.py picks it up on every run.

Per-run: pass --mermaid-config PATH to scripts/render.

# Example config
cat > scripts/mermaid-config.json <<'EOF'
{ "theme": "default", "themeVariables": { "fontFamily": "Arial, sans-serif" } }
EOF

The config content + mmdc --version are folded into the SHA1 cache key, so cached SVGs invalidate automatically when either changes. See scripts/README.md for details.

References

Core Documentation

• Marp syntax: references/marp-syntax.md - Basic Marp/Marpit syntax (directives, frontmatter, pagination, etc.)
• Image patterns: references/image-patterns.md - Official image syntax (bg, filters, split backgrounds)
• Theme CSS guide: references/theme-css-guide.md - How to create custom themes based on Marpit specification
• Advanced features: references/advanced-features.md - Math, emoji, fragmented lists, Marp CLI, VS Code
• Official themes: references/official-themes.md - default, gaia, uncover themes documentation

Quality & Selection Guides

• Theme selection: references/theme-selection.md - How to choose the right theme for content
• Best practices: references/best-practices.md - Quality guidelines for "cool" slides

Templates & Assets

• Templates: assets/template-*.md - Starting points with embedded CSS for each theme (7 themes)
• Standalone CSS: assets/theme-*.css - CSS files for reference (already embedded in templates)

Renderer & Fixtures

• Renderer operator notes: scripts/README.md — CLI flags, install, CI, troubleshooting
• Fixtures:
  • examples/fixture-mermaid-minimal.md — minimal smoke (one mermaid mindmap)
  • examples/fixture-mermaid-full-deck.md — realistic 10-slide deck with Cyrillic mermaid content
  • examples/fixture-mermaid-multi.md — 3 mermaid blocks (2 unique + 1 duplicate), guards regex and SHA1 dedup

Official External Links

• Marp Official Site: https://marp.app/
• Marpit Directives: https://marpit.marp.app/directives
• Marpit Image Syntax: https://marpit.marp.app/image-syntax
• Marpit Theme CSS: https://marpit.marp.app/theme-css
• Marp Core GitHub: https://github.com/marp-team/marp-core
• Marp CLI GitHub: https://github.com/marp-team/marp-cli