md-slidesby Alireza Rezvani

MD Slides Skill.

Q: Which coding agents can run this skill?

The file lists claude-code, codex-cli, cursor, antigravity, opencode and gemini-cli as compatible tools, and it can also be triggered by the markdown-html-orchestrator classifying an input as SLIDES.

Q: What if my markdown has no clear slide boundaries?

The skill refuses instead of guessing and exits with code 6; the documented next step is to route that file to md-document, which handles one continuous document rather than discrete slides.

Q: How do I get a PDF out of the deck?

Use the print stylesheet: printing from the browser produces a PDF with one slide per page, so the export needs no separate tooling.

A Claude Code and Codex skill for PPT and slide decks: converts a Markdown deck into branded slides.

Presentations
HTML slides

Download OpenDesign View usage guide

alirezarezvani/claude-skills · markdown-html/skills/md-slides/SKILL.mdSKILL.md

--- name: md-slides description: Converts a markdown deck (slides separated by `---` HR boundaries or by `# ` H1 headings, with optional `` presenter notes blocks) into a single-file HTML presentation with arrow-key / space / PgDn / PgUp / Home / End / P / Esc keyboard navigation, presenter mode (split view with current slide + speaker notes + clock + next-slide preview), URL-hash deep linking, and `@media print` page-per-slide … --- ## When to invoke ## Pipeline ## What ships in the HTML ## Hard rules ## Forcing-question library (Matt Pocock grill discipline) ## Distinct from

Front matter and section headings read from the upstream file on 2026-09-14 · 6,506 characters in full

01 What it does

What the md-slides Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

md-slides converts a markdown deck into a single-file HTML presentation that runs in any browser. A deck is slides separated by --- HR boundaries or # H1 headings, with optional  presenter notes blocks. Three stdlib Python scripts pipeline: slide_splitter.py, presenter_notes_parser.py, deck_html_renderer.py.

The output ships keyboard navigation, URL-hash deep linking, a progress bar and slide counter, presenter mode with clock and next-slide preview, and a print stylesheet for one-slide-per-page PDF export. It reuses md-document's markdown parser and reads design-system tokens via config_loader.py. It refuses inputs with no clear slide boundaries, 1-slide decks, files under 100 lines, and decks failing --strict-notes 50% coverage.

What it produces

The rendered HTML deck, written as deck-{slug}.html in the resolved default output directory, with -2, -3 and so on appended on collisions.
Intermediate JSON files holding the split slides and then the slides with their attached notes.
A PDF with one slide per page, produced through the print stylesheet by printing from the browser.

See the example prompt ↗

How It Works

01
Split the Deck into Ordered Slides
slide_splitter.py reads the source markdown and splits it on --- HR lines or H1 headings, auto-detecting the boundary style by default, and writes an ordered slide list.
02
Attach Presenter Notes per Slide
presenter_notes_parser.py scans each slide for notes blocks and attaches them to that slide so presenter mode has something to show on the right-hand panel.
03
Render the single-file HTML Deck
deck_html_renderer.py combines slides with design-system tokens and emits the deck, taking a title and an output path on the command line.
04
Apply design-system Tokens
Twelve brand CSS custom properties come from the design system, and design_style changes how dense the slide layouts are.
05
Refuse Inputs That Are Not Decks
The skill exits rather than converting when the input has no clear slide boundaries, would yield a single slide, or fails the notes-coverage gate under --strict-notes.

02 Find your fit

When to Use the md-slides Skill

Use the md-slides skill in Claude Code or Codex when the job is PPT and slide decks of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

An orchestrator classified the input as SLIDES and routed it here.
Someone invokes the skill directly on a markdown file with the slash command.
The markdown already has 3 or more --- HR lines, or 5 or more H1 headings with short bodies.
The deck will be presented live, which is exactly when presenter notes matter and self-paced reading makes them optional.

Know the Boundaries

The input is a long-form spec rather than a deck; that should go to md-document.
The input is a code review, which belongs to md-review.
It is not a graphic-design tool: Keynote and PowerPoint own that space, while this handles markdown-authored decks projected from a browser.

What to Provide

The markdown deck fileIts path is passed to slide_splitter.py with --input, and the split result is written to a JSON file with --output.
Boundary styleSlides must be distinguishable, either by --- HR boundaries or by H1 headings, so the splitter has something to cut on.
Optional presenter notesNotes are supplied as HTML comment blocks inside slides and get parsed and attached per slide by the second pipeline step.

03 Inside the skill

Rules the md-slides Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Boundary Requirement
Auto mode needs at least 3 HR lines or at least 5 H1 headings in the source; if neither is present the skill refuses and the input should go to md-document instead.
No single-slide Output
A deck that renders to one slide is rejected as a poster, not a deck, with exit code 5.
Minimum 100 Source Lines
Inputs shorter than 100 lines are refused, using the same Shihipar threshold applied across all the converters.
Onboarding Gate
The skill refuses to run without onboarding, the same gate every converter uses.
Strict Notes Coverage
With --strict-notes the skill refuses a deck where fewer than 50% of slides carry notes, because it is not set up for presenter mode; that refusal exits 7.
Warn on Overlong Slides
Slides over 40 source lines produce a soft warning about signal-to-noise; the deck still renders but the count is surfaced.
Keep the Output single-file
All CSS and JS are inlined; the only external resource is the Google Fonts CSS, and Prism.js is opt-in through --syntax rather than bundled by default.
No Framework Runtime
The deck uses vanilla JS and keyboard event handlers only, with no React, Vue or Svelte runtime involved.

04 Put it to work

Install md-slides in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add md-slides to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/alirezarezvani/claude-skills --skill md-slides

Generic skills CLI form for markdown-html/skills/md-slides/SKILL.md; the repository may document its own path.

Give the Skill a First PPT and Slide Decks Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Convert [deck.md] into a presentation. It uses --- HR boundaries for slides and each slide has a <!-- notes: ... --> block. Title it "[Talk title]" and run it with --strict-notes, since it will be presented live rather than read on its own. Write the result to [output/deck.html].

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Open the deck in a browser and walk the keys: arrows, Space and PgDn advance, PgUp goes back, Home and End jump, P toggles presenter mode, Esc leaves it.
Test deep linking: #3 should jump to slide 3, browser back and forward should walk the slides, and a shared deck.html#5 should open directly on slide 5.
Check the slide counter in the bottom-right corner, which reads like "3 / 12", against the deck length.
Confirm the reduced-motion media query is honored, so animation is dropped for viewers who request less motion.

In OpenDesign import md-slides from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Alireza Rezvani
Repository: github.com/alirezarezvani/claude-skills Branch main
Skill file: markdown-html/skills/md-slides/SKILL.md Content checksum recorded at verification; commit 19392f7
License: MIT From LICENSE.
Repository stars: 25,934 GitHub snapshot taken 2026-09-14 for the whole alirezarezvani/claude-skills repository, which contains 5 skills in this catalog. Not a rating or usage count for md-slides.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

When to invokeRouting symptoms, plus which inputs should be refused or sent elsewhere.
PipelineThree commands that split, parse notes, and render the deck.
What ships in the HTMLNavigation, deep linking, presenter mode, print stylesheet, tokens, parser reuse.
Hard rulesRefusal thresholds, soft warnings, and single-file output constraints.
Forcing-question library (Matt Pocock grill discipline)Five questions to settle before converting a source file.
Distinct fromHow it differs from md-document, md-review, landing pages, Keynote.
Output artifactOutput path resolution and the collision suffix convention.
ReferencesSources and canon behind the deck conventions.

The Skill's Own Description

“Converts a markdown deck (slides separated by `---` HR boundaries or by `# ` H1 headings, with optional `` presenter notes blocks) into a single-file HTML presentation with arrow-key / space / PgDn / PgUp / Home / End / P / Esc keyboard navigation, presenter mode (split view with current slide + speaker notes + clock + next-slide preview), URL-hash deep linking, and `@media print` page-per-slide for PDF export. Triggers when the markdown-html-orchestrator classifies an input as SLIDES, or when invoked directly via /cs:md-slides. Reuses md-document's markdown parser for slide-body rendering and reads design-system tokens via config_loader.py. Refuses if input has no clear slide boundaries, produces a 1-slide deck, or `--strict-notes` is on with < 50% notes coverage. Use after orchestrator routing.”

Front-matter description from SKILL.md. The full file is about 6,506 characters. Read the full file on GitHub.

06 Before you install

Questions About the md-slides Skill

Answers come from the SKILL.md as read on 2026-09-14, not from a recorded run.

Which coding agents can run this skill?

The file lists claude-code, codex-cli, cursor, antigravity, opencode and gemini-cli as compatible tools, and it can also be triggered by the markdown-html-orchestrator classifying an input as SLIDES.

What if my markdown has no clear slide boundaries?

The skill refuses instead of guessing and exits with code 6; the documented next step is to route that file to md-document, which handles one continuous document rather than discrete slides.

How do I get a PDF out of the deck?

Use the print stylesheet: printing from the browser produces a PDF with one slide per page, so the export needs no separate tooling.

MD Slides

Run md-slides on a Real PPT and Slide Decks Task.

Download OpenDesign, import md-slides from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills