Marp Slide

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 . next to the input).
• Side effects: per-deck cache directory _assets/ with diagram-.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 ``, 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

1. 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

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

1. Structure content following best practices:

• Title slide with ``
• Concise h2 titles (5-7 characters in Japanese; 2-5 words in English)
• 3-5 bullet points per slide
• Adequate whitespace

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

1. 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 _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

1. 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

1. Enhance visual hierarchy:

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

1. 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: `` - Image on right, text on left
• Centered: `` - Centered with specific width
• Full background: `` - Full-screen background
• Multiple images: Multiple ![bg] declarations

Example lecture pattern:

## Slide Title

- 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 ``
• [ ] 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 PUPPETEERSKIPDOWNLOAD=true export PUPPETEEREXECUTABLEPATH=/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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MatrixFounder
• Source: MatrixFounder/Universal-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.