Presentation Generation Skill¶

Generate professional architecture presentations from Markdown using Marp CLI.

AI Agent Instructions¶

CRITICAL: When asked to create a presentation, you MUST deliver the final exported file (PPTX/PDF), not just the markdown source.

End-to-End Workflow¶

Install dependencies (if needed): npm install -g @marp-team/marp-cli
Create markdown presentation with Marp front matter
Export to PPTX (default) or PDF/HTML if requested
Report file path to user

# Always run after creating markdown
marp {slides.md} --pptx -o {slides.pptx}

Default format: PPTX (most portable for sharing)

Overview¶

This skill enables generation of slide decks (PPTX, PDF, HTML) from Markdown source files. It follows a docs-as-code approach where presentations are version-controlled, reviewable, and automatically exportable.

Why Markdown Presentations?¶

Benefit	Description
Version Control	Track changes with git, enable PR reviews
Consistency	Themes ensure uniform styling across decks
Automation	CI/CD can auto-generate exports
Focus on Content	Markdown syntax keeps focus on message, not formatting
Reusability	Templates and snippets can be shared across presentations

Tool: Marp CLI¶

Package: @marp-team/marp-cli Install: npm install -g @marp-team/marp-cli

Core Commands¶

# Markdown to HTML slides
marp slides.md -o slides.html

# Markdown to PDF
marp slides.md --pdf -o slides.pdf

# Markdown to PowerPoint
marp slides.md --pptx -o slides.pptx

# Watch mode with live preview
marp -w -p slides.md

# Server mode (directory)
marp -s ./presentations/

# With custom theme
marp slides.md --theme ./themes/architecture.css -o slides.pptx

Output Formats¶

Format	Extension	Use Case
HTML	`.html`	Web viewing, self-contained
PDF	`.pdf`	Printing, distribution
PPTX	`.pptx`	Editing, corporate templates
PNG/JPEG	`.png`/`.jpg`	Individual slide images

Marp Markdown Syntax¶

Slide Separation¶

Slides are separated by --- (horizontal rule):

---
marp: true
theme: default
paginate: true
---

# First Slide

Content here

---

# Second Slide

More content

Front Matter¶

---
marp: true                    # Required: enable Marp
theme: default                # Theme: default, gaia, uncover, or custom
paginate: true                # Show page numbers
header: "Company Name"        # Header on all slides
footer: "Confidential"        # Footer on all slides
backgroundColor: white        # Background color
backgroundImage: url(bg.png)  # Background image
class: lead                   # Default class for slides
---

Directives¶

Global Directives (Front Matter)¶

Apply to all slides:

---
marp: true
theme: gaia
class: lead
paginate: true
---

Local Directives (Per Slide)¶

Apply to current slide only:

---

<!-- _class: lead -->
<!-- _backgroundColor: #234 -->
<!-- _color: white -->

# Dark Slide

This slide has custom styling

Built-in Themes¶

Theme	Description
`default`	Clean, minimal design
`gaia`	Bold, colorful slides
`uncover`	Modern, gradient backgrounds

Special Classes¶

<!-- _class: lead -->      <!-- Centered, large text -->
<!-- _class: invert -->    <!-- Dark background, light text -->

Images¶

# Standard image
![](image.png)

# Sized image
![width:500px](image.png)
![height:300px](image.png)
![w:500 h:300](image.png)

# Positioned image
![bg](background.png)           <!-- Full background -->
![bg left](sidebar.png)         <!-- Left 50% -->
![bg right:30%](sidebar.png)    <!-- Right 30% -->
![bg fit](diagram.png)          <!-- Fit to slide -->
![bg contain](logo.png)         <!-- Contain within slide -->

Multiple Background Images¶

![bg left:33%](image1.png)
![bg](image2.png)
![bg](image3.png)

Speaker Notes¶

# Slide Title

Visible content

<!--
Speaker notes go here.
Not visible in presentation.
Visible in presenter view.
-->

Code Blocks¶

# Code Example

```python
def hello():
    print("Hello, World!")
```

Syntax highlighting is automatic based on language.

Math Equations (KaTeX)¶

# Math Support

Inline: $E = mc^2$

Block:
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

Architecture Presentation Patterns¶

The Architecture Decision Deck¶

Standard structure for presenting architecture decisions:

Title - Decision name, date, audience
Context - Business driver, current state
Problem - What needs solving
Options - Alternatives considered (2-4)
Comparison - Decision matrix
Recommendation - Selected option with rationale
Impact - What changes, who's affected
Next Steps - Actions, timeline
Q&A - Discussion

The Architecture Vision Deck¶

For presenting high-level architecture:

Title - System/initiative name
Business Context - Why we're doing this
Current State - Baseline architecture (C4 Context)
Pain Points - Problems with current state
Target State - Future architecture (C4 Context)
Key Changes - What's different
Benefits - Expected outcomes
Risks - What could go wrong
Roadmap - High-level timeline
Ask - What you need from audience

The Technical Deep Dive Deck¶

For technical audiences:

Title - Component/system name
Context - Where this fits (C4 Context)
Containers - C4 Container diagram
Key Components - C4 Component diagram
Data Flow - How data moves
Sequence - Key interactions
Code - Representative examples
Performance - Metrics, benchmarks
Trade-offs - Design decisions
Questions - Discussion

The Migration Briefing Deck¶

For migration planning communication:

Title - Migration name, phase
Recap - Current state, why migrating
Scope - What's included/excluded
Approach - Strategy (big bang, phased, strangler)
Timeline - Gantt or milestone view
Risks - Mitigation strategies
Dependencies - Critical blockers
Support Model - During migration
Rollback - If things go wrong
Success Criteria - How we'll know we're done

Embedding Diagrams¶

From Mermaid¶

Export diagram to PNG/SVG:
```
mmdc -i diagram.mmd -o diagram.png
```

Include in Marp:

# Architecture Overview

![bg right:60% contain](./diagrams/context.png)

Key components:
- Service A
- Service B
- Database

From Excalidraw¶

Export from Excalidraw to PNG/SVG
Include in Marp same as above

From Structurizr¶

Export diagrams from Structurizr
Include in Marp same as above

File Organization¶

presentations/
├── architecture-vision/
│   ├── slides.md              # Main presentation
│   ├── diagrams/              # Exported diagrams
│   │   ├── context.png
│   │   └── container.png
│   └── exports/               # Generated files
│       ├── slides.pptx
│       └── slides.pdf
├── adr-001-api-gateway/
│   ├── slides.md
│   └── exports/
├── themes/                    # Shared themes
│   └── architecture.css
└── templates/                 # Slide templates
    ├── vision-deck.md
    └── adr-deck.md

Integration with Toolkit¶

After Architecture Analysis¶

Generate presentations from analysis outputs:

# Use cases
- Present architecture vision to stakeholders
- Brief teams on migration plan
- Document ADR decisions
- Technical deep dives for new team members

Workflow¶

Analyze - Run architecture analysis
Export diagrams - Generate PNG/SVG from Mermaid/Structurizr
Write slides - Create Markdown presentation
Review - Preview with marp -p
Export - Generate PPTX/PDF
Present - Deliver to stakeholders

Requirements¶

Installation¶

# Required
npm install -g @marp-team/marp-cli

# For PDF/PPTX export (uses Chromium)
# Puppeteer is bundled with marp-cli

# Optional: For diagram export
npm install -g @mermaid-js/mermaid-cli

VS Code Integration¶

Install Marp for VS Code (marp-team.marp-vscode) for: - Live preview - Export from editor - Syntax highlighting

Key Principles¶

Content First - Write content before worrying about styling
One Message Per Slide - Don't overload slides
Visual Hierarchy - Use headings, bullets, images consistently
Diagrams Over Text - Show architecture visually
Version Control - Track presentations in git
Reuse Templates - Don't start from scratch each time
Export Early - Test PPTX export early to catch issues

Common Pitfalls¶

Pitfall	Solution
Too much text per slide	Limit to 6 bullets max
Small diagrams	Use `bg` directive for full-slide images
Inconsistent styling	Use themes, not inline styles
Missing speaker notes	Add notes for complex slides
Large file size	Compress images before embedding
PPTX edit issues	Accept that PPTX is for delivery, not editing

Structurizr - C4 diagram generation
Architecture Synthesis - Parsing visual diagrams
TOGAF Vision - Architecture vision content