Imported from pysan3/dotfiles (config/claude/skills/marp-presentation/SKILL.md). Install upstream with npx skills add pysan3/dotfiles --skill marp-presentation. Copyright stays with the author (MIT).

MARP Presentation Skill

Purpose

Convert long-form markdown content into effective MARP slide decks. This skill helps Claude Code understand presentation design principles and MARP-specific syntax to produce slides that support speaking rather than replace it.

Core Principles

1. One Idea Per Slide

If a slide needs "and" in the title, it's two slides. Each slide should pass the "glance test"—the audience should grasp the point in 3 seconds.

2. Slides Are Prompts, Not Scripts

The slide reminds the speaker what to say. The speaker provides the depth, stories, and nuance. Never put on a slide what should come from the speaker's mouth.

3. Speaker Notes Carry the Payload

All the detail, stories, statistics, and elaboration go in speaker notes. The slide is the headline; the notes are the article.

4. Progressive Disclosure

Complex ideas build across multiple slides. Don't dump everything at once. Let the audience follow the logic step by step.

5. Visual Breathing Room

White space is a feature. Dense slides create cognitive overload. When in doubt, delete.

MARP Syntax Reference

Front Matter (Required)

---
marp: true
theme: default
paginate: true
header: "Header Text"
footer: "Footer Text"
---

Slide Separator

---

Three dashes create a new slide.

Speaker Notes

<!--
Speaker notes go here.
They don't appear on the slide.
Use for stories, details, transitions.
-->

Directives (Per-Slide Settings)

<!-- _class: lead -->      # Centered, large text
<!-- _paginate: false -->  # Hide page number
<!-- _header: '' -->       # Remove header for this slide
<!-- _footer: '' -->       # Remove footer for this slide
<!-- _backgroundColor: #123 -->
<!-- _color: white -->

Fitting Text

# <!-- fit --> This Title Scales to Fit

Images

Background (full slide):

![bg](image.jpg)

Background with opacity:

![bg opacity:0.5](image.jpg)

Background left/right split:

![bg left:40%](image.jpg)

# Content on right

Background tiled:

![bg vertical](image1.jpg)
![bg](image2.jpg)

Inline image:

![width:300px](image.jpg)

Columns (using HTML)

<div style="display: flex;">
<div style="flex: 1;">

Left column content

</div>
<div style="flex: 1;">

Right column content

</div>
</div>

Slide Patterns

Pattern: Title Slide

---
marp: true
theme: default
paginate: true
footer: "Author | Date"
---

# Presentation Title

## Subtitle or Tagline

**Author Name** | Event | Date

<!--
Welcome, introduce yourself, set context.
-->

---

Pattern: Section Divider

---

<!-- _class: lead -->
<!-- _paginate: false -->

# <!-- fit --> Section Title

<!--
Transition statement: "Now let's talk about..."
-->

---

Pattern: Key Point (Minimal)

---
# The Core Idea

One sentence that captures it.

<!--
Elaborate here. Tell the story. Give the example.
This is where the real content lives.
-->
---

Pattern: List Slide

---

# Three Things to Remember

- First point (brief)
- Second point (brief)
- Third point (brief)

<!--
Expand on each:
1. First point - full explanation
2. Second point - full explanation
3. Third point - full explanation
-->

---

Pattern: Quote

---

<!-- _class: lead -->

> "The quote goes here, kept reasonably short."

— Attribution

<!--
Context for the quote. Why it matters.
How it connects to your point.
-->

---

Pattern: Story Setup

---

# True Story

**The setup in one line.**

<!--
Tell the full story here:
- What happened
- Why it matters
- The lesson learned
-->

---

Pattern: Before/After or Problem/Solution

---

# The Problem

- Pain point one
- Pain point two

<!--
Describe the problem state fully.
-->

---

# The Solution

- Resolution one
- Resolution two

<!--
Describe how this solves it.
-->

---

Pattern: Resource Slide

---

# Resources

| Resource | Why |
|----------|-----|
| [Link](url) | One-line description |
| [Link](url) | One-line description |

<!--
Mention which ones you personally recommend and why.
-->

---

Pattern: Closing Slide

---

<!-- _class: lead -->

# Thank You

**Contact Info**
- Link 1
- Link 2

<!--
Closing thought, call to action, invitation to connect.
-->

---

Design Tips

Mermaid Diagrams

---
marp: true
header: '<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>'
---
<div class="mermaid">
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop HealthCheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
</div>

Draw.io Diagrams

Save the file to file-name.drawio.
Ask user to export as SVG and save as file-name.svg.
Reference the SVG in your markdown (see "Inline image" above).

Conversion Process

When converting long-form markdown to MARP slides:

Step 1: Identify Structure

Find the major sections (H2 headers typically)
Each major section becomes a section divider slide
Subsections become content slides

Step 2: Extract Headlines

Turn each paragraph's main point into a slide title
The first sentence often contains the headline
If a paragraph has multiple points, it's multiple slides

Step 3: Compress to Bullets

Full sentences become bullet fragments
Remove articles, helping verbs, filler
"You should always make sure to test your code" → "Test your code"

Step 4: Move Depth to Speaker Notes

Full paragraphs → speaker notes
Examples and stories → speaker notes
Statistics and details → speaker notes
The slide gets the takeaway; notes get the support

Step 5: Add Transitions

Section dividers between major themes
Speaker notes should include transition phrases
"Now that we've covered X, let's look at Y..."

Step 6: Balance the Deck

Check for runs of text-heavy slides (break them up)
Check for back-to-back lists (add variety)
Insert breathing room slides (quotes, images, dividers)

Quality Checklist

Run this check on completed slide decks:

Per-Slide Checks

Title is under 8 words
No more than 5 bullets
Each bullet under 10 words
No full sentences on slide (bullets are fragments)
Speaker notes exist and are substantive
Only one level of bullet nesting

Deck-Level Checks

Title slide has name, date, event
Section dividers between major themes
No more than 3 text slides in a row without variety
Closing slide with contact info
Total slide count reasonable for time (roughly 1-2 min/slide)

Speaker Notes Checks

Every content slide has notes
Notes include stories/examples where relevant
Transition phrases included
Timing notes for long sections

Common Mistakes to Fix

Mistake: Wall of Text

Before:

# Career Ownership

You need to take ownership of your career because no one else will do it for you. Your employer provides opportunities but you must drive your own development. This means investing time in learning, building your portfolio, and creating options for yourself. Don't wait for permission to grow.

After:

# Own Your Career

- Your employer provides opportunities
- You drive development
- Build your portfolio
- Create your options

<!--
Full explanation: No one else will do this for you...
[rest of paragraph goes here as notes]
-->

Mistake: Too Many Ideas

Before:

# Key Lessons

- Be the CEO of your career
- Learn out loud by building and sharing
- Get out of your own way—fear and ego block growth
- Find your community
- Use sandboxes to learn safely
- Bridge technologies intentionally

After: Split into 6 slides, one per point, with section dividers grouping related concepts.

Mistake: Missing Speaker Notes

Problem: Slide has bullets but no context for the speaker. Fix: Add notes with the full explanation, a story, or an example for each bullet.

Mistake: Nested Complexity

Before:

- Main point
  - Sub point A
    - Detail 1
    - Detail 2
  - Sub point B

After: Flatten to one level or split across slides.

MARP CLI Commands

# Preview with live reload
npx @marp-team/marp-cli -p slides/presentation.marp.md

# Export to PDF
npx @marp-team/marp-cli slides/presentation.marp.md -o exports/presentation.pdf

# Export to PowerPoint
npx @marp-team/marp-cli slides/presentation.marp.md -o exports/presentation.pptx

# Export to HTML
npx @marp-team/marp-cli slides/presentation.marp.md -o exports/presentation.html

# Watch mode (auto-rebuild on save)
npx @marp-team/marp-cli -w slides/presentation.marp.md

Theme Customization

Basic custom styling in front matter:

---
theme: gaia
pagination: true
lang: ja
style: |
  h1, h2, h3, h4, h5, h6, p {
    word-break: auto-phrase;
  }
  h1, h2, h3, h4, h5, h6 {
    text-wrap: balance;
  }
  p {
    text-wrap: pretty;
  }
  section {
    justify-content: start;
    font-size: 22px;
  }
  .columns {
    display: grid;
    grid-template-columns: repeat(2, minmax(0, 1fr));
    gap: 1rem;
  }
---

For full custom themes, create a CSS file and reference it:

---
marp: true
theme: ./themes/custom.css
---

About

MARP Presentation Skill

Purpose

Core Principles

1. One Idea Per Slide

2. Slides Are Prompts, Not Scripts

3. Speaker Notes Carry the Payload

4. Progressive Disclosure

5. Visual Breathing Room

MARP Syntax Reference

Front Matter (Required)

Slide Separator

Speaker Notes

Directives (Per-Slide Settings)

Fitting Text

Images

Columns (using HTML)

Slide Patterns

Pattern: Title Slide

Pattern: Section Divider

Pattern: Key Point (Minimal)

Pattern: List Slide

Pattern: Quote

Pattern: Story Setup

Pattern: Before/After or Problem/Solution

Pattern: Resource Slide

Pattern: Closing Slide

Design Tips

Mermaid Diagrams

Draw.io Diagrams

Conversion Process

Step 1: Identify Structure

Step 2: Extract Headlines

Step 3: Compress to Bullets

Step 4: Move Depth to Speaker Notes

Step 5: Add Transitions

Step 6: Balance the Deck

Quality Checklist

Per-Slide Checks

Deck-Level Checks

Speaker Notes Checks

Common Mistakes to Fix

Mistake: Wall of Text

Mistake: Too Many Ideas

Mistake: Missing Speaker Notes

Mistake: Nested Complexity

MARP CLI Commands

Theme Customization

Use it

Manifest

Reviews