# Marp Slides

> Convert content-only markdown documents into Marp slide decks with smart, content-shape-aware layout selection. Use when the user wants to turn a doc/report/article into slides, build a Marp presentation, or extend an existing deck — especially when they say "make slides from X", "convert to slides", "presentation from this markdown", or ask about slide layout choices. Provides a 13-layout taxono…

- **Type:** Skill
- **Install:** `agentstack add skill-ranacm-marpsmith-marp-slides`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [RanaCM](https://agentstack.voostack.com/s/ranacm)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [RanaCM](https://github.com/RanaCM)
- **Source:** https://github.com/RanaCM/marpsmith/tree/main/skills/marp-slides

## Install

```sh
agentstack add skill-ranacm-marpsmith-marp-slides
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Marp slide builder with auto-layout

Convert content-only markdown into a Marp deck where each slide's layout matches its content shape. Don't bullet-ify everything — that's the failure mode this skill exists to prevent.

## Related skills

Part of the **marpsmith** bundle — composes with:
- **theme-generator** — generate a new theme CSS from brand colors, then set it as the deck's `theme:`.
- **deck-a11y-audit** — check a finished deck or theme for WCAG contrast and colorblind safety.

> Script paths below use `` — the skills directory configured by the active agent harness; the marpsmith skills live there together.

## Workflow

1. **Read the source document fully** before writing any slides. Layout decisions need the whole document's structure, not just one section at a time.
2. **Read the active theme** — check `.marprc.yml` (or the deck frontmatter) for the theme name, then skim the theme CSS. Note: (a) **heading prefix style** — does it emit `## ` / `# ` before headings? If yes, those ~3 chars count against per-line length budget and increase overflow risk for long headings; (b) **list marker style** — numbered lists with the theme's marker color and spacing; (c) **any custom layout classes** beyond the standard 12; (d) **light vs. dark background** — affects legibility of code blocks and image-heavy slides. These observations should inform phrasing choices and layout selection throughout the conversion.
3. **Set up the project** (only if not already configured). 5 supported starter themes live under `themes/` — single CSS files with palette + layout structure merged in. All share the var-based theming contract: layouts and structure live in a common block driven by CSS custom properties; each theme's palette section sets those vars. A deck written for one theme renders correctly under any other — only the frontmatter `theme:` line changes. Some themes also append a small **layout variant** override (uppercase section dividers, neon glow on hero stats, bordered big-stat, etc.) — the variant changes how a layout renders but never breaks the markdown contract. See `themes/README.md` for the full catalog (dark, light, high-contrast, newspaper, synthwave). Copy what you need to `.marp/` and register them in `.marprc.yml` (see "File setup" below). **Don't replace the user's existing theme.** To create a new color variant, copy `dark.css` (for dark-bg) or `light.css` (for light-bg) and adapt the palette section, including the CSS-var declarations.
4. **Segment the source** into "content blocks" — typically each heading with its body. Split further if a block is too dense for one slide, but do not over-split short adjacent prose blocks; merge related short blocks when they would produce sparse standalone slides.
5. **For each block, run the decision rubric** (below) to pick a layout. First match wins.
6. **Emit the slides** with appropriate `` directives and the markdown patterns documented per-layout below. **Do not** add heading scale modifiers (`h-XX`) — headings are never scaled down (see "Heading size rule" below). **Do not** add body scale modifiers (`b-XX`) by hand — `auto-fit.mjs` assigns them. **Preserve the original heading level** — if the source has `### Subsection`, render the slide heading as `###`, not `##`. The hierarchy carries meaning (part > section > subsection) that flattening destroys.
7. **Pre-flight lint** — run `node /marp-slides/scripts/lint-deck.mjs ` (see "Pre-flight linter" section). Fast, render-free markdown analysis that mechanizes the cheap checks: layout repetition, sparse prose, asymmetric comparisons, missing pull-quote attribution, heading wrap risk, process-flow verb cues, over-dense bullet lists, over-long tables, frontmatter sanity, duplicate `_class` directives. Fix HIGH and MED findings in source before moving on; LOW findings are advisory.
8. **Auto-fit pass** — run `node /marp-slides/scripts/auto-fit.mjs  --apply --theme ` (see "Auto-fit" section). When `--theme` points to a CSS file, the script registers it with Marp's `themeSet` so the deck frontmatter remains authoritative. The script measures each slide's rendered geometry, picks the smallest discrete body scale that fits, and writes `b-XX` classes back to the markdown. Headings are never scaled. Slides that can't fit at the body floor (`b-90`) are flagged for splitting via stderr.
9. **Apply split recommendations.** For each `split-*` action surfaced by auto-fit, read the slide content and split it:
   - `split-list-midpoint` — pure list slide; split items at midpoint, reuse heading on both halves.
   - `split-paragraph-midpoint` — multi-paragraph prose; split at paragraph midpoint.
   - `split-table-midpoint` — single-table slide; split rows at midpoint, refine sub-headings to label each half (e.g., "Topic — Clinical" / "Topic — Community"). Keep the header row on both halves.
   - `split-comparison-detail` — comparison slide that overflows; condense the original to a concise side-by-side overview, then add two detail slides (`compare-detail-a` for the left column's expansion, `compare-detail-b` for the right). The cyan/pink left-edge + tint preserves the visual association.
   - `split-restructure` — mixed content (TL;DR + bullets, etc.); judgment required. Often the right call is to **shorten** the content or restructure it rather than split mechanically.
   - See "Splitting strategy" below for content-aware guidance.
10. **Re-run auto-fit + sanity backstop.** Run auto-fit again; should be idempotent. Then run `check-slides.mjs` as a backstop — it should report zero `vertical-overflow` HIGH issues. Repeat up to 3 iterations if splits introduced new overflow.
11. **Quality checklist pass** (existing checklist at the end of this file).
12. **Escalation** — if HIGH-severity issues remain after 3 iterations, surface a summary to the user with specific slide indices and ask for guidance. Don't silently ship broken slides.

## Heading hierarchy

Keep the source document's heading tiers intact across the slide deck. A document structured as `#` → `##` → `###` should produce slides where:
- `#` headings appear on title-cover or `section-divider` slides as `#`
- `##` headings on most content slides remain `##`
- `###` subsection headings stay `###`
- `####` and deeper render at their natural level

The theme's CSS styles each level differently (h1 has the largest tag background, h2 medium, h3 smaller, etc.), so preserving the level visually communicates depth without extra effort. Don't promote/demote headings just because you wrapped a slide in a layout class — the layout class controls *positioning and decoration*, the heading level controls *hierarchical meaning*.

Exception: if a layout class explicitly normalizes headings (e.g., `big-stat-hero` styles its label uniformly regardless of level), that's intentional. Otherwise, faithfully reflect the source.

## Pre-flight linter

`scripts/lint-deck.mjs` is a fast, render-free markdown linter that runs **before** auto-fit. It catches deck-quality issues that don't require a Chrome render — usually in under 100 ms on a 50-slide deck.

```bash
# Default: print colorized summary, exit 1 on any finding
node /marp-slides/scripts/lint-deck.mjs path/to/deck.md

# Machine-readable JSON
node /marp-slides/scripts/lint-deck.mjs path/to/deck.md --json

# CI gate: only HIGH findings affect exit code
node /marp-slides/scripts/lint-deck.mjs path/to/deck.md --severity high
```

Exit codes: `0` = clean at the chosen severity threshold; `1` = at least one finding; `2` = script error.

### Checks

| Rule | Severity | What it flags |
|---|---|---|
| `frontmatter-missing` / `-no-marp` / `-no-theme` | HIGH | YAML frontmatter missing, no `marp: true`, or no `theme:` |
| `duplicate-class-directive` | HIGH | Two or more `` comments on a single slide (Marp uses the last — usually a bug) |
| `layout-repetition` | MED | Same `_class:` directive on 4+ consecutive slides (Cross-deck variety rule) |
| `asymmetric-comparison` | MED | `comparison` columns with word-count ratio > 3:1 |
| `heading-wrap-risk` | MED | Heading > 60 chars on content layout, or > 40 chars on cover-like layout (`title-cover`, `section-divider`, `big-stat-hero`, `pull-quote`) |
| `bullet-list-too-many` | MED | Default bullet slide with > 6 items (should be `two-col-list`) |
| `two-col-list-too-many` | MED | `two-col-list` with > 10 items (should split) |
| `table-too-many-rows` | MED | Table with > 6 data rows |
| `sparse-prose` | LOW | `prose` slide with /marp-slides/scripts
npm install
```

**Invoke:**

```bash
# Dry run: emit JSON report, no writes.
node /marp-slides/scripts/auto-fit.mjs path/to/deck.md --theme path/to/theme.css

# Apply: rewrite markdown with recommended classes; surface splits to stderr.
node /marp-slides/scripts/auto-fit.mjs path/to/deck.md --theme path/to/theme.css --apply
```

When `--theme` is an existing CSS path, the helper registers it as a theme file (`themeSet`) and still lets the deck's frontmatter `theme:` choose by `@theme` name. When `--theme` is a non-path name, it uses Marp's theme override semantics.

The script is **idempotent**: it strips any existing `h-XX` / `b-XX` from the class list before computing fresh ones. Re-running after content edits yields fresh decisions.

**Output (per slide that needs a class or a split):**

```json
{
  "index": 60,
  "action": "rescale",
  "h_scale": 1.0,
  "b_scale": 0.9,
  "recommended": ["b-90"],
  "evidence": { "overflow_at_1": 12 }
}
```

```json
{
  "index": 75,
  "action": "split-restructure",
  "h_scale": 1.0,
  "b_scale": null,
  "recommended": [],
  "evidence": { "overflow_at_0_90": 18 }
}
```

`split-list-midpoint` and `split-paragraph-midpoint` are mechanical and obvious; `split-restructure` requires content judgment (see "Splitting strategy").

Exit code `1` if any split recommendations remain; `0` if everything fit by rescaling alone.

## Heading size rule

Applies to **all themes** (dark, dark-derived color variants, monokai-glow variants, and any custom theme).

**Headings on content slides always stay at the theme's default font size.** Do not apply `h-XX` modifier classes. The `auto-fit.mjs` script skips heading scale entirely — the table in the Auto-fit section above has no `h-XX` column deliberately.

Covered layouts (headings must not be scaled): `prose`, `prose-with-tldr`, `comparison`, `compare-detail-a / b`, `bullet list` (default), `two-col-list`, `process-flow`, `matrix-2x2`, `table / wide-table`, `code-showcase`, `image-led`.

Excluded (intentionally oversized centered text — skip this rule): `title-cover`, `section-divider`, `big-stat-hero`, `pull-quote`.

**What to do when a heading overflows one line:**

1. **Shorten the heading text first.** Cut filler ("The", "Overview of"), tighten phrasing, drop subordinate clauses. Most headings can shed 20–40% of characters without losing meaning.
2. **Two-line wrap is acceptable as a last resort.** If the heading genuinely cannot be shortened without losing its argument, let it wrap to a second line. When it wraps, check that the break is semantically and visually natural: prefer phrase boundaries, subtitle separators, clause boundaries, or other meaningful units. Avoid breaks that orphan a key noun, split a named concept, or leave a qualifier disconnected from the phrase it modifies. If browser wrapping chooses a poor break, insert an explicit `` in the markdown at the better semantic break, for example `## ADHD, Anger, and Racial Misperception— The Systemic Pattern`.
3. **Never shrink the heading font.** A heading at 0.8em or 0.65em looks like body text and breaks the visual hierarchy. That outcome is worse than a two-line heading.

## Splitting strategy

When auto-fit recommends a split, read the slide content before applying it. Mechanical density application loses information that thoughtful splitting preserves; mechanical splitting loses rhythm that thoughtful condensation preserves.

**For `split-list-midpoint`:** straightforward. Split items at (or near) the midpoint, reuse the heading on both halves OR refine each into a sub-heading (`## Topic — Foundations` / `## Topic — Advanced`).

**For `split-paragraph-midpoint`:** straightforward. Split at the paragraph break.

**For `split-table-midpoint`:** straightforward. Cut data rows at the midpoint, keep the header row on both halves, and refine the heading on each half to label what set of rows it contains (semantic grouping beats `(1/2)` / `(2/2)` whenever the rows fall into natural categories).

**For `split-comparison-detail`:** turn one overflowing comparison into three slides:
1. **The original `comparison` slide** stays as the side-by-side overview, but condense each column's bullets to short labels (1–3 words). The audience sees the contrast frame.
2. **A `compare-detail-a` slide** expands the left column. Use whatever inner layout fits the content shape — `prose compare-detail-a` for short prose, `prose-with-tldr compare-detail-a` for denser prose, or just `compare-detail-a` for a regular bullet list. The cyan left edge + side-fade tint signals "this is the left column from the previous slide."
3. **A `compare-detail-b` slide** does the same for the right column with the pink accent.

The detail slides aren't side-by-side — they get the full slide width, with one column's worth of content expanded. The visual continuity comes entirely from the color cue. Don't add `(detail)` or `— Expanded` suffixes; the color does that work.

**For `split-restructure`:** judgment required. Common patterns:
- `prose` or `prose-with-tldr` with 2+ paragraphs covering distinct sub-themes → split into two prose slides, each with one paragraph. Keep a TL;DR only where it adds orientation; drop it when the heading carries the claim.
- `comparison` where one column has 8 bullets and the other has 3 → rebalance content rather than split (auto-fit can't help with column imbalance, but the recommendation flags it).
- Severe overflow (>30% over) on dense single-unit content → consider whether the slide is trying to do too much; often the right move is to shorten, not split.

**Avoid splitting:**
- `pull-quote`, `big-stat-hero`, `title-cover`, `section-divider` — these are standalone layouts. If they overflow, restructure or shorten.
- Slides where the rhythm relies on staying together (quote + immediate context, stat + explanation, list with a summary line).

**Format for split slides:**
- Reuse the same heading, OR refine into sub-headings (`## Topic — Mechanism` / `## Topic — Treatment Implications`).
- Don't add `(1/2)` / `(2/2)` suffixes by default — they read as scaffolding. Use them only when explicit pagination helps the audience.
- After splitting, **re-run auto-fit** — the halves may now fit at 1.00, or fall to 0.95 / 0.90.

**When the heading itself is the problem:** the heading is too long. Don't shrink it — **shorten the heading text**. A 60+ character heading on a content slide is almost always over-detailed.

## Backstop: check-slides.mjs

`scripts/check-slides.mjs` is a sanity check that runs after auto-fit. It emits a JSON report of remaining geometric issues — overflow, header collision, asymmetric columns, etc. After auto-fit + splits have been applied, this should report zero `vertical-overflow` HIGH issues. Use it for CI / automated quality gates.

```bash
node /marp-slides/scripts/check-slides.mjs path/to/deck.md --theme path/to/theme.css
```

As with `auto-fit.mjs`, a CSS path is registered with `themeSet`; it does not override the deck's frontmatter theme name.

Exit code `1` if any HIGH-severity issue remains; `0` otherwise.

## File setup

Five supported starter themes under `themes/`. Each is a **single CSS file** — palette + layout structure merged in. No external CSS dependencies beyond an optional Google Font import (Newspaper). The full catalog with variants is in `themes/README.md`.

All themes share the var-based theming contract: a common layout block driven by CSS custom properties. Themes that

…

## Source & license

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

- **Author:** [RanaCM](https://github.com/RanaCM)
- **Source:** [RanaCM/marpsmith](https://github.com/RanaCM/marpsmith)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ranacm-marpsmith-marp-slides
- Seller: https://agentstack.voostack.com/s/ranacm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.