| 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
-
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
-
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
-
Read references/best-practices.md for quality guidelines
-
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
-
Add images if needed using patterns from references/image-patterns.md
-
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":
-
Infer theme from content:
- Business content → business theme
- Technical content → tech or dark theme
- Creative content → gradient or colorful theme
- General → default theme
-
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
-
Enhance visual hierarchy:
- Use h3 for sub-sections when appropriate
- Break up dense text into multiple slides
- Ensure logical flow (intro → body → conclusion)
-
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:
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