marp

Skill for all Marp slide tasks: creation, editing, theme design, conversion, and reading.

Quick Reference

Design Ideas

Don't create boring slides. Every slide must be visually engaging.

Pick colors for YOUR topic

Don't default to blue. Choose colors that match your topic using the Topic → Color mapping in theme-guide. Cooking → warm tones, technology → cobalt blue, environment → olive green.

Every slide needs a visual element

Include an image, chart, icon, or background image. Text-only slides are forbidden. Code blocks count as visual elements — syntax-highlighted code, grid-2col Before/After comparisons, and vs-card code comparisons serve as visual elements in code-heavy presentations.

Vary your layouts

Switch layout patterns every 2-3 slides. Repeating the same structure (heading + bullets) creates visual boredom. Combine multiple patterns from layout-patterns.

Text alignment

• Body text: left-aligned (center-aligned body text is hard to read)
• Center alignment is only for h1 on title slides (lead class)

NEVER

• NEVER create text-only slides without any visual element
• NEVER repeat the same layout for 3+ consecutive slides
• NEVER center-align body text or bullet lists
• NEVER use default blue palette without considering the topic's emotional tone
• NEVER put a decorative accent line directly under the slide title
• NEVER mention a library/package/API/tool without a link — all external references must include links by default
• NEVER use vague terms instead of precise terminology — use exact names + <small> annotations for explanation
• NEVER leave bg images without brightness specification (text becomes unreadable)
• NEVER use ![bg] with SVG diagrams without contain — default cover crops text/data SVGs

Mode A: Create (New Slides)

Triggered by "create slides", "prepare presentation", "write a script". If structure planning (story arc, audience analysis, outline) is not done, recommend running a presentation-planning skill first.

Workflow

1. Confirm requirements: Topic, audience, duration, slides/script/both
2. Design planning: Reference slide-design-principles and layout-patterns to determine layout composition
3. Generate: Create slide files
4. Quality check: Verify per qa-checklist
5. Visual verification: Generate PNGs and visually inspect. If SVGs are included, run SVG quality validation
6. PDF/PPTX export: Generate PDF and/or PPTX output

File Structure

slides/<project-name>/
├── README.md           # Presentation overview
├── 01_opening.md       # Split by section
├── 02_<topic>.md
├── 0N_closing.md
├── themes/             # Custom theme (optional)
│   └── <theme-name>.css
└── pdfs/               # PDF output

Frontmatter Template

---
marp: true
theme: default          # or custom theme name
paginate: true
---

Slide Separation

Use *** (horizontal rule) to separate slides. Per-slide directives:

<!-- _class: lead -->
<!-- _backgroundColor: #1a0f05 -->

Scripts

See script-format for detailed conventions.

Mode B: Edit (Partial Editing)

Triggered by "fix slide 3", "change the layout", "update the text".

Workflow

1. Identify target: Confirm file path and slide number
2. Read current state: Read the target file, understand frontmatter, theme, and structure
3. Edit: Apply changes with the Edit tool. Be careful not to break existing styles/theme/structure
4. Diff verification: Follow "Mode B: Edit diff check" in qa-checklist to verify changes and surrounding impact
5. Visual verification: Generate PNGs and verify
6. Regenerate PDF/PPTX: Regenerate output files after editing

Guidelines

• Only change the specified slides — do not affect others
• If changing frontmatter or theme, warn the user about whole-deck impact first
• Reference layout-patterns when changing layouts

Mode C: Theme (Create/Edit Themes)

Triggered by "create a theme", "change the colors", "make it dark".

Workflow

1. Confirm requirements: Purpose, color preferences, dark/light preference
2. Palette design: Reference theme-guide, design palette using 60-30-10 rule
3. Generate CSS: Create theme file following the theme file structure
4. Contrast verification: Follow "Mode C: Theme contrast verification" in qa-checklist to check WCAG AA compliance
5. Preview: Preview with Marp CLI server mode

Theme File Location

slides/<project-name>/themes/<theme-name>.css

Mode D: Convert (Outline → Marp)

Triggered by "convert this outline to slides", "turn this memo into a deck".

Workflow

1. Parse input: Analyze source file structure (headings, bullets, paragraphs)
2. Determine slide boundaries: Split by heading level or content breaks
3. Generate Marp: Add frontmatter, split with ***, apply directives
4. Apply design: Reference layout-patterns and slide-design-principles for appropriate layouts
5. Verify: Run qa-checklist quality checks

Conversion Guidelines

• h1 → New slide title
• h2 → In-slide heading, or new slide boundary (depending on volume)
• Bullet lists → Keep as bullets (split if over 5-6 items)
• Long paragraphs → Extract key messages into bullets

Handling Repetitive Structures

When converting N similar items (library introductions, feature comparisons), the same layout tends to repeat. Use these 4 strategies to add variety:

1. Grouping: Combine related items into a single slide (e.g., compare 2 of 5 plugins side by side)
2. Layout rotation: Apply different layout patterns to each item
3. Restructuring: Reorganize from per-item to per-aspect (e.g., "challenges → solutions → config" instead of "Plugin A → B → C")
4. Detail gradient: Cover 1-2 representative items in detail, summarize the rest in a table

Mode E: Read (Summarize)

Triggered by "what is this slide about?", "summarize this deck".

Workflow

1. Read file: Load the target Marp file(s)
2. Analyze structure: Count slides, identify sections, theme, layouts used
3. Generate summary: Output in the following format

Output Format

## Overview
[1-2 sentence summary of the entire presentation]

## Structure
- Slide count: N slides
- Theme: [theme name]
- Sections:
  1. [Section name] (slides N-M)
  2. ...

## Key Messages
- [Key message 1]
- [Key message 2]
- ...

Commands

# Preview with server mode
npx @marp-team/marp-cli -s slides/ --theme ./path/to/theme.css

# Watch single file
npx @marp-team/marp-cli -w <file>.