version: "1.0.1" name: markdown-slides description: Create presentation slides in Markdown format (Deckset/Marp compatible). Use when user requests to create slides, presentations, or convert documents to slide format. Handles image positioning, speaker notes, and proper formatting. allowed-tools:

• Read
• Write
• Glob
• Bash

license: MIT

Markdown Slides Skill

Convert content to presentation slides in Markdown format compatible with Deckset and Marp presentation tools.

When to Use This Skill

Activate this skill when the user:

• Asks to create slides or a presentation
• Requests to convert a document to slide format
• Mentions Deckset or Marp
• Wants to generate speaker notes
• Needs to format images for presentations

Input Requirements

• Source content: Markdown file, outline, or structured content
• Images: Files in _files_/ directory or paths to be resolved
• Target platform: Deckset (default) or Marp
• Options:
• Speaker notes (enabled by default)
• Slide numbering (optional frontmatter)
• Emoji enhancement (enabled by default)

Output Specifications

• File location: Same folder as source
• File naming: Original name with - slides suffix
• Example: document.md → document - slides.md
• Format: Deckset-compatible markdown
• Structure: Proper slide dividers, image tags, speaker notes
• Enhancement: Emojis added for visual appeal

Main Process

Step 1: Slide Structure Setup

Objective: Create logical slide divisions with proper hierarchy

Actions:

1. Read and analyze source content structure
2. Insert slide dividers (---) at logical breaks:

• Between major sections
• Between distinct topics
• After section intro slides
• Before/after major diagrams

1. Maintain content hierarchy:

• H1 (#) for section titles
• H2 (##) for main slide titles
• H3 (###) for sub-topics

1. Preserve original organization and flow
2. Add optional frontmatter: slidenumbers: true

Example:

slidenumbers: true
# 1. Section Title 🎯
 
![](section-background.png)
 
^ Introduction to this section.
 
---
 
## Main Topic 📊
 
Content here...
 
---
 
### Detailed Subtopic
 
More details...

Step 2: Image Format Conversion

Objective: Convert images to Deckset format with proper positioning

Critical Requirements: ⚠️ MUST resolve relative paths per-image basis ⚠️ MUST URL-encode spaces and escape special characters ⚠️ MUST verify image files exist

Image Position Formats:

Actions:

1. Identify all image references in source
2. For each image:

`` a. Determine appropriate position format b. Resolve relative path from slide file location c. URL-encode spaces: " " → "%20" d. Escape parentheses: "(" → "%28", ")" → "%29" e. Verify file exists at resolved path f. Use original images when available g. Copy missing images to _files_/ directory ``

1. Apply positioning based on context:

• Section intros: Use ![]() for full background
• Diagrams in text: Use ![inline]()
• Default for content slides: Use ![right fit]() ⭐
• Custom sizing: Use ![right XX%]() when needed
• Full-width inline: Use ![inline fill]() for wide images

Examples:

# Section Title
![](background-image.png)
 
---
 
## Content Slide
Key points here:
-Point 1
-Point 2
 
![right fit](diagram.png)
 
---
 
## Inline Diagram
Text before diagram.
 
![inline](process-flow.svg)
 
Text after diagram.

Step 3: Speaker Notes Conversion

Objective: Convert appropriate content to speaker notes

Format: Lines starting with ^ (caret + space)

Placement: At the end of each slide

Convert to speaker notes: ✅ Multi-sentence paragraphs ✅ Explanatory text ✅ Additional context ✅ Talking points

DO NOT convert: ❌ Single-sentence paragraphs ❌ Lists (bullet or numbered) ❌ Block quotes ❌ Sentences ending with colon (:) ❌ Headers (H1, H2, H3) ❌ Table content

For Marp platform: Use HTML comments instead

<!-- This is a speaker note for Marp -->

Examples:

## Slide Title
 
Main content visible to audience.
 
^ This paragraph becomes a speaker note because it's multi-sentence explanatory text. It provides context that the speaker needs but the audience doesn't need to read on the slide.
 
---
 
## Another Slide
 
-Bullet points stay visible
-Not converted to notes
 
^ Additional speaking points go here.

Step 4: Content Enhancement

Objective: Polish the presentation for maximum impact

Actions:

1. Add emojis to section and slide titles:

• Use relevant emojis that enhance meaning
• Don't overuse - keep it professional
• Examples: 🎯📊🤖💡🚀📚🔧⚡

1. Clean up comments:

• Remove markdown comments not meant for slides
• Remove TODO items
• Remove internal notes

1. Ensure clean format:

• Consistent spacing
• Proper header hierarchy
• Clear slide breaks

1. Add frontmatter (if requested):

``markdown slidenumbers: true ``

1. Final review:

• Each slide has clear focus
• Images positioned correctly
• Speaker notes placed at end
• No orphaned content

Critical Guidelines

Image Handling

⚠️ CRITICAL RULES:

1. NEVER invent images - Only reference images that exist in the source document or _files_/ folder. Do NOT create placeholder references like background-xxx.png for images that don't exist.
2. Use original images from source when available
3. Copy missing images to _files_/ directory rather than substituting
4. Resolve paths per-image - don't assume same directory
5. URL-encode spaces: my file.png → my%20file.png
6. Escape special characters:

• Parentheses: ( → %28, ) → %29
• Other special chars as needed

1. Verify existence before referencing - run ls or glob to confirm file exists
2. Maintain semantic relevance - image should match slide content
3. Section intros without images are OK - If no background image exists for a section intro slide, just use the title and speaker notes without an image reference

Image Position Standards

Decision tree for image positioning:

Is it a section intro slide with just title?
  → Does a background image exist?
    → YES: Use ![]() for full background
    → NO: Skip image, use title + speaker notes only
 
Is it a diagram embedded in flowing text?
  → YES: Use ![inline]() or ![inline fill]()
 
Is it the main visual for the slide with bullet points?
  → YES: Use ![right fit]() ⭐ PRIMARY FORMAT
 
Does it need specific sizing?
  → YES: Use ![right 80%]() or other percentage

Speaker Notes Rules

When to convert to speaker notes:

• Multi-sentence explanatory paragraphs
• Contextual information not needed on slide
• Talking points for the speaker
• Additional details for verbal explanation

When NOT to convert:

• Single-sentence paragraphs (might be slide content)
• Bullet or numbered lists (usually slide content)
• Block quotes (usually featured content)
• Sentences ending with : (usually introducing lists)
• Any header level
• Table content

Format:

Slide content here.
 
^ Speaker note paragraph one. Can be multiple sentences providing context.
 
^ Speaker note paragraph two. Each note paragraph gets its own ^ prefix.

Content Standards

1. File Naming:

• Always use - slides suffix
• Preserve original filename otherwise
• Example: AI for PKM.md → AI for PKM - slides.md

1. Emoji Usage:

• Add to H1 and H2 headers
• Choose relevant, professional emojis
• Don't overuse - quality over quantity
• Examples:
• 🎯 Goals/Objectives
• 📊 Data/Charts
• 🤖 AI/Technology
• 💡 Ideas/Insights
• 🚀 Future/Launch
• 📚 Learning/Knowledge

1. Hierarchy:

• H1 for major sections (usually numbered)
• H2 for main slide titles
• H3 for subtopics within slides
• Consistent numbering scheme

1. Slide Breaks:

• Use --- (three dashes) on its own line
• Blank line before and after recommended
• Logical breaks between topics

Platform-Specific Notes

Deckset (Default)

Format:

• Speaker notes: ^ prefix on each line
• Image positioning: All formats fully supported
• Frontmatter: Simple key-value pairs

Features:

• Automatic slide numbering with slidenumbers: true
• Full control over image positioning
• Rich presenter notes support

Example Frontmatter:

slidenumbers: true
autoscale: true
theme: Plain Jane, 3

Marp (Optional)

Format:

• Speaker notes: HTML comments <!-- speaker note -->
• Image positioning: May use different syntax
• Frontmatter: YAML with marp: true

Conversion for Marp:

---
marp: true
paginate: true
---
 
<!-- This is a speaker note in Marp -->

Differences:

• HTML comments instead of ^ prefix
• Different frontmatter structure
• May need ![bg]() for backgrounds instead of ![]()

Quality Checklist

Before marking task complete, verify:

• [ ] No invented images - every image reference points to a real file
• [ ] All images have valid, URL-encoded paths
• [ ] Image files exist at specified locations (run ls to confirm)
• [ ] Spaces in paths converted to %20
• [ ] Special characters properly escaped
• [ ] Speaker notes use ^ prefix (or HTML for Marp)
• [ ] Speaker notes placed at END of each slide
• [ ] Slide dividers (---) at logical breaks
• [ ] Consistent header hierarchy (H1 → H2 → H3)
• [ ] Emojis added appropriately to titles
• [ ] File saved with '- slides' suffix
• [ ] Content hierarchy maintained from source
• [ ] No orphaned content or broken sections
• [ ] Internal comments removed
• [ ] Frontmatter added if requested

Error Handling

Missing Images

Problem: Source references image that doesn't exist

Solution:

1. Check source _files_/ directory
2. Check parent directory _files_/
3. Search for image by name in project
4. If found: Copy to presentation _files_/ directory
5. If not found: Note in speaker notes and skip image

Broken Relative Paths

Problem: Path doesn't resolve correctly

Solution:

1. Determine slide file location
2. Calculate relative path from slide to image
3. Test path resolution
4. URL-encode the working path

Invalid Characters in Paths

Problem: Special characters break image links

Solution:

• Spaces: Convert to %20
• Parentheses: ( → %28, ) → %29
• Brackets: [ → %5B, ] → %5D
• Other special chars: Use URL encoding

Tips for Best Results

1. Start with outline: Create clear section and slide structure first
2. One idea per slide: Each slide should have single clear message
3. Visual hierarchy: Use H1 for sections, H2 for slides, H3 for sub-points
4. Image positioning: Default to ![right fit]() for content slides
5. Speaker notes: Add context that helps speaker but clutters slide
6. Emoji consistency: Use similar emojis for similar concepts
7. Test in Deckset: Preview the slides to verify formatting
8. Iterate: First pass for structure, second for polish