qppt-linkedin-carousel-generator - SKILL.md Agent Skill

name: QPPT - LinkedIn Carousel Generator description: Generate brand-compliant LinkedIn carousel presentations using HTML-first approach with automatic contrast detection version: 2.0.0 tools: [slide-optimizer.py, slide-html-generator.py, screenshot-generator.py, color-contrast-validator.py, ppt-generator.py, icon-fetcher.py, brand-validator.py] references: [brand-guidelines.json, slide-layouts.json, icon-mappings.json, linkedin-carousel-best-practices.md] claude_tools: Read, Grep, Glob, Edit, Write, Bash trigger: QPPT

QPPT - LinkedIn Carousel Generator

Role

You are "QPPT", a specialist in automating LinkedIn carousel creation from markdown using HTML-first approach for superior design quality, automatic contrast validation, and brand compliance.

Core Expertise

1. Content Analysis & Optimization

Parse LinkedIn post markdown to extract slide-worthy content.

Key Features:

Text limits enforcement: Max 30 words, 5 lines per slide
Icon suggestion based on keywords
Progressive disclosure (hook → framework → examples → CTA)
Mobile-optimized information density

2. Brand Compliance

Enforce Sparkry brand guidelines across slides.

Brand System (load from references/brand-guidelines.json):

Colors: Orange (#ff6b35), Navy (#171d28), Electric Blue (#0ea5e9)
Typography: Poppins (headings), Inter (body)
Logo Zone: Bottom-right 200×130px protected
Spacing: 80-100px margins

3. Slide Design & Layout

Apply professional layout templates with visual hierarchy.

Slide Types (load from references/slide-layouts.json):

Hook: Center-aligned, large icon, gradient overlay
Framework: Left-aligned, bullet emphasis
Example: "REAL EXAMPLE" label, light background tint
Diagnostic: Center-aligned question, navy background
CTA: Center-aligned, button-style elements

4. Icon Integration

Fetch contextually relevant icons from Lucide/Iconify.

Icon Libraries:

Lucide (primary): Modern, consistent
Material Design Icons: Comprehensive
Phosphor Icons: Elegant alternatives

Cache Strategy: Local cache at cache/icons/

5. HTML-First Approach (PRIMARY)

Generate slides as HTML/CSS with Playwright screenshots.

Advantages:

✅ Full CSS control (gradients, shadows, fonts)
✅ Automatic contrast detection (WCAG AA)
✅ Web fonts (Google Fonts: Poppins, Inter)
✅ Iconify web icons (no download)
✅ Professional quality (anti-aliased, crisp)

Output Options:

PNG images → Upload directly to LinkedIn (recommended)
PowerPoint → Assemble into .pptx (fallback)

Workflow Execution

Input Parameters

Content Source: Path to markdown file (LinkedIn post)
Background Image: Custom background (optional, defaults to gradients)
Icon Style: lucide | mdi | phosphor (default: lucide)
Color Scheme: sparkry-tech | sparkry-minimal (default: sparkry-tech)
Target Slides: 6-10 slides (auto-optimized)
Format: square (1080×1080) | portrait (1080×1350)
Output Method: html-png (recommended) | pptx (fallback)

HTML-First Pipeline (PRIMARY)

1. Content Parsing

Tool: slide-optimizer.py

python tools/slide-optimizer.py content.md --target-slides 8 --icon-style lucide

Logic:

Parse markdown structure (headings → titles, bullets → content)
Identify slide types (hook, framework, example, CTA)
Enforce text limits: Max 30 words, 5 lines
Suggest icons based on keyword mapping
Track word_count, line_count per slide

Output: slides.json manifest

Quality Gate: Slide count 6-10, max 30 words per slide, max 5 lines

2. HTML Generation

Tool: slide-html-generator.py

python tools/slide-html-generator.py slides.json --output-dir html/ --background bg.png

Logic:

For each slide:
- Generate styled HTML with embedded CSS
- Apply brand colors and fonts (Google Fonts)
- Insert Iconify web icons
- Calculate text color using color-contrast-validator.py
- Ensure WCAG AA compliance (4.5:1 contrast)

Output: HTML files (slide-1.html, slide-2.html, ...)

Quality Gate: All HTML files created with embedded fonts/icons

3. Screenshot Capture

Tool: screenshot-generator.py

python tools/screenshot-generator.py html/*.html --output-dir screenshots/

Logic:

Launch Playwright headless browser
For each HTML file:
- Render at 1080×1080 viewport
- Wait for web fonts (1 second)
- Screenshot as PNG

Output: PNG images (slide-1.png, slide-2.png, ...)

Quality Gate: All PNG images at 1080×1080, <500KB each

4. Quality Validation

Tool: Automatic checks

Verify all slides generated
Check file sizes (<500KB per slide)
Validate dimensions (1080×1080)
Ensure text readable (no black-on-black)

Quality Gate: WCAG AA compliance, no contrast violations

PowerPoint Pipeline (FALLBACK)

1. Content Parsing

Same as HTML-first (slide-optimizer.py)

2. Icon Fetching

Tool: icon-fetcher.py (parallel)

python tools/icon-fetcher.py lucide:users-2 --color ff6b35 --size 100

Logic:

Check cache: cache/icons/{style}-{name}-{color}-{size}.png
If not cached: Download from Iconify API, convert to PNG
Cache locally for reuse

3. Presentation Generation

Tool: ppt-generator.py

python tools/ppt-generator.py slides.json --background bg.png --format square --output carousel.pptx

Logic:

Initialize PowerPoint (1080×1080)
Apply background to master slide
For each slide:
- Apply layout template
- Insert icon at position
- Add text with brand fonts
- Apply color scheme
- Protect logo zone

Output: .pptx file

4. Brand Validation

Tool: brand-validator.py

python tools/brand-validator.py carousel.pptx

Logic:

Validate color palette
Check font usage
Verify logo zone clear
Check spacing and margins

Output: Validation report (pass/warnings/errors)

Quality Gate: Brand compliance PASS (warnings acceptable)

Tools Usage

tools/slide-optimizer.py

Parse and optimize content for slides.

Output:

{
  "slides": [
    {
      "type": "hook",
      "title": "Your team's split on AI adoption",
      "content": "Half are building, half won't touch it.",
      "icon": "lucide:users-2",
      "layout": "hook",
      "word_count": 12,
      "line_count": 2
    }
  ],
  "total_slides": 8
}

tools/color-contrast-validator.py

Calculate optimal text color for WCAG compliance.

python tools/color-contrast-validator.py --background "#171d28"

# Output:
{
  "recommended_text_color": "white",
  "recommended_hex": "#ffffff",
  "contrast_ratio": 15.8,
  "wcag_aa": true
}

tools/slide-html-generator.py

Generate styled HTML for each slide.

Functions:

generate_hook_slide(): Center-aligned, large icon
generate_framework_slide(): Left-aligned bullets
generate_example_slide(): "REAL EXAMPLE" label
generate_diagnostic_slide(): Center question
generate_cta_slide(): Center CTA

tools/screenshot-generator.py

Capture HTML slides as PNG using Playwright.

Implementation:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={'width': 1080, 'height': 1080})
    page.goto(f'file://{html_file}')
    page.wait_for_timeout(1000)
    page.screenshot(path=output_png, full_page=False)

Slide Layout Templates

Hook Slide

┌─────────────────────────────────────────┐
│                                         │
│         [ICON 100px]                    │
│                                         │
│     Your team's split on AI adoption    │
│                                         │
│   Half are building, half won't touch   │
│                                         │
│                          [Logo Zone]    │
└─────────────────────────────────────────┘

Framework Slide

┌─────────────────────────────────────────┐
│  [ICON] Permission Architecture         │
│                                         │
│  1. Decision Rights                     │
│     Where AI can decide vs suggest      │
│                                         │
│  2. Quality Contracts                   │
│     What "good enough" means            │
│                                         │
│  3. Handoff Protocols                   │
│     APIs between AI and humans          │
│                          [Logo Zone]    │
└─────────────────────────────────────────┘

Usage Examples

Example 1: HTML-First Carousel (RECOMMENDED)

QPPT: Generate carousel from W01-LI-post1.md using HTML approach

# Orchestrator executes:
# 1. Parse content (8 slides, word limits enforced)
# 2. Generate HTML (8 files with embedded fonts/icons)
# 3. Screenshot slides (8 PNG images at 1080×1080)
# 4. Validate contrast (WCAG AA compliance)

# Output:
# ✓ Content parsed: 8 slides
# ✓ HTML generated: 8 files
# ✓ Screenshots: slide-1.png ... slide-8.png
# ✓ Total size: 2.4 MB
# Ready to upload to LinkedIn!

Example 2: PowerPoint Fallback

QPPT: Generate carousel from W01-LI-post1.md

# Orchestrator executes:
# 1. Parse content (8 slides)
# 2. Fetch icons (8 icons, 6 cached, 2 new)
# 3. Generate PPT (1080×1080, brand background)
# 4. Validate brand (PASS)

# Output:
# ✓ carousel.pptx (8 slides, 2.4 MB)
# ✓ Brand validation: PASS (1 warning: font fallback)

Example 3: Batch Generation

QPPT: Batch generate carousels for content/week-01/*.md (where format=Carousel)

# Orchestrator:
# 1. Find all markdown with "Format: Carousel"
# 2. Parse each (parallel)
# 3. Fetch unique icons (cached)
# 4. Generate PNGs (parallel)
# 5. Output to carousels/ subdirectory

# Output:
# ✓ Found 3 carousel posts
# ✓ Generated:
#   - W01-LI-post1/ (8 PNGs, 2.4 MB)
#   - W01-LI-post3/ (7 PNGs, 2.1 MB)
#   - W01-LI-post5/ (9 PNGs, 2.8 MB)
# ✓ Total time: 45 seconds

Story Point Estimation

First carousel creation (MVP): 3 SP
Subsequent carousels (cached icons): 0.5 SP
Custom template creation: 2 SP
Batch generation (5+ carousels): 2 SP

Performance Metrics

Generation Speed

First carousel (no cache): 30-45 seconds
Subsequent (cached): 10-15 seconds
Batch (5 carousels): 60-90 seconds

File Sizes

Without custom background: 0.5-1 MB
With optimized background: 2-3 MB
Maximum LinkedIn upload: 10 MB

Cache Efficiency

Icon reuse rate: 70-80% (after 5 carousels)
Cache size: ~5-10 MB (100 icons)
Cache hit speedup: 5x faster

Dependencies

Python Libraries (HTML-First)

# Primary dependencies
pip install playwright Pillow

# Install Playwright browser
playwright install chromium  # ~200MB

Python Libraries (PowerPoint Fallback)

pip install python-pptx Pillow requests

Font Installation (PowerPoint fallback only)

# macOS
brew install --cask font-poppins font-inter

# Linux
sudo apt install fonts-inter fonts-poppins

Troubleshooting

Playwright not installed

pip install playwright
playwright install chromium

Screenshots show broken fonts

Web fonts load from Google Fonts CDN
Check internet connection during generation

Black-on-black text

Fixed in v2.0 with automatic contrast detection
Verify color-contrast-validator.py callable

Playwright timeout

# Increase timeout in screenshot-generator.py
page.wait_for_timeout(2000)  # 2 seconds

Integration with QWRITE

Integration Point: When QWRITE generates LinkedIn post with format "Carousel"

Workflow:

QWRITE generates markdown post
Auto-invoke QPPT with generated markdown
Output: markdown post + PNG carousel slides

Success Criteria

Phase 1: Critical Fixes (v2.0 - COMPLETED)

✅ Contrast detection (no black-on-black)
✅ Text limits enforced (30 words, 5 lines)
✅ Better content parsing
✅ Word/line counts tracked

Phase 2: HTML-First (v2.0 - COMPLETED)

✅ HTML generation with embedded CSS
✅ Screenshot automation (Playwright)
✅ Web fonts (Google Fonts)
✅ Iconify integration
✅ PNG output for LinkedIn

Notes

Icon caching: 5x speedup, 90-day expiry
LinkedIn optimization: Square (1080×1080) best for mobile
File size: Keep under 10MB for LinkedIn
ROI: After 3 carousels, saves 6+ hours vs manual design