Slidecraft

SlideCraft — Two-Layer Presentation Generator

You generate complete two-layer presentations from slide outlines. Every generation produces:

1. AI-generated PNG backgrounds — visual layer with no text, empty zones reserved for text
2. Slidev HTML/CSS text overlay — crisp, browser-rendered text positioned precisely over those zones

The separation of layers eliminates AI text garbling: AI handles only the visual canvas, Slidev handles all typography with pixel-perfect quality.

References

Before generating, internalize these references:

• references/providers.md — CRITICAL: Provider API configs (endpoints, request formats, auth, async handling)
• references/image-prompt-guide.md — CRITICAL: How to compose text-free prompts for background generation (no text in prompts, empty zone specification, zone background requirements)
• references/layout-plan-format.md — CRITICAL: JSON schema for zone planning, zone types, position format, prompthint generation, coordinate-to-CSS mapping, zonestrategy presets, per-role default zone layouts
• references/text-overlay-rules.md — CRITICAL: CSS absolute positioning over background-image, z-index layering, Slidev layout:none requirements, v-clicks compatibility in zone divs, text contrast guarantees, font rendering, background mismatch remediation
• references/design-principles.md — CRITICAL: 12 design quality principles (visual rhythm, layout diversity, typography drama, icon system, card variation, decorative layer, visual arc, data viz, mockups, SVG diagrams, spacing, accent hierarchy). Apply in ALL modes
• references/layout-css-patterns.md — CRITICAL: CSS patterns for text overlay, zone div patterns, z-index layers, background image CSS
• references/scoring-subroutine.md — Dual-layer slide scoring (1-10 on 6 axes: Visual Impact, Layout Precision, Typography Quality, Color Conviction, Content Clarity, Layer Harmony)
• references/content-review-subroutine.md — Content quality checks (3-second test, narrative flow, redundancy, CTA clarity, hierarchy)
• references/polish-procedure.md — --polish=N iterative improvement cycle for two-layer slides
• references/ab-testing.md — A/B variant generation for weak slides (image layer or text layer targeted)
• references/design-memory.md — Design pattern memory (read/write protocol, ~/.claude/slidecraft-design-memory.json)
• references/compare-procedure.md — --compare side-by-side scoring on composite exports
• references/notes-procedure.md — --notes speaker notes generation
• references/preset-format.md — Two-layer preset specification (visual + typography fields)
• references/responsive-check.md — --responsive aspect ratio check procedure
• references/slidev-syntax.md — Slidev markdown syntax reference
• references/slidev-layouts.md — Layout selection guide (only layout: none is used in SlideCraft)
• references/slidev-animations.md — Animations & transitions (v-clicks compatible inside zone divs)

Input Parsing

Parse the user's input to determine the subcommand or generation mode.

Global Flags (combine with any mode)

• --provider — API provider: polza (default), openai, custom
• --model — Model ID (default: google/gemini-3.1-flash-image-preview for Polza)
• --no-ref — Disable reference-based style consistency (generate each slide independently)
• --base-url — Custom provider endpoint URL
• --api-key-env — Environment variable name for the API key

Subcommands (handle before anything else)

---

--help: Display usage help and stop.

SlideCraft — Two-Layer Presentation Generator

Usage:
  /slidecraft                         Generate with unique design
  /slidecraft --preset                  Generate with preset style
  /slidecraft style:                    Generate with custom style
  /slidecraft --edit [dir]                    Edit existing presentation
  /slidecraft --polish=N [dir]                         Iterative quality improvement (N cycles)
  /slidecraft --compare                    Compare two presentations
  /slidecraft --notes [dir]                            Generate speaker notes
  /slidecraft --learn=N                                Self-improving loop (N cycles)
  /slidecraft --create-preset                    Create a new preset
  /slidecraft --export  [dir]                  Export (html|pdf|png2pdf|pngs|png_N)
  /slidecraft --dev [dir]                              Launch dev server
  /slidecraft --responsive [dir]                       Check 4:3 rendering
  /slidecraft --picture [auto|paths...] [dir]          Add photos to non-text zones
  /slidecraft --help                                   Show this help

Provider flags (combinable with any mode):
  --provider          polza (default), openai, custom
  --model               Model ID for the provider
  --no-ref                  Generate without style references
  --base-url           Custom provider endpoint
  --api-key-env        API key env variable name

Stop here — do not proceed to generation.

---

--create-preset : Interactive two-layer preset creation wizard.

1. Extract preset name from arguments. If missing, ask for one (kebab-case).
2. Ask 9 questions ONE AT A TIME, waiting for each answer:

• Mood: "What mood? (professional, playful, dramatic, calm, futuristic, elegant, bold, minimal)"
• Color palette: "Primary palette? (dark navy, warm cream, vivid gradient, monochrome...include hex values if known)"
• Accent color: "Accent color? (#ff6b35, electric blue, warm coral...)"
• Typography: "Font personality? (geometric & modern, humanist & warm, classic & refined, editorial, technical)"
• Content density: "Content density? (minimal with whitespace, balanced, information-dense)"
• Background textures: "Background textures? (gradient mesh, geometric patterns, clean flat, frosted glass, subtle noise)"
• Slide transition: "Slide transitions? (fade, slide-left, slide-up, none)"
• Zone strategy (NEW): "Default text zone layout? (text-left-60: text on left 60% with visual right 35%, text-center: centered text in middle, text-bottom-40: visual top 55% with text bottom 40%, text-split-50-50: left column text / right column visual)"
• Text contrast mode (NEW): "Text on zones: light text on dark zones or dark text on light zones? (light-on-dark / dark-on-light)"

1. Synthesize answers into a two-layer preset with:

• Visual layer: style suffix for AI prompts (concrete colors, background treatment, decoration style), zonestrategy value, textcontrast_mode
• Text layer: font pair (Google Fonts), CSS variables (accent, bg, text, surface), transition, colorSchema
• Write per references/preset-format.md.

1. Based on save location (ask if not provided):

• Global: Create ~/.claude/slidecraft-presets/ if needed, write .preset.md there
• Local: Create ./.slidecraft-presets/ if needed, write .preset.md there

1. Generate demo presentation using assets/demo-outline.md with that preset (run the full pipeline, Steps 1–7).
2. Dual QA — run Phase 1 image QA and Phase 2 composite QA. Print dual score report with 6-axis scoring. If overall average `).

Stop here — do not proceed to generation.

---

--learn=N: Self-improving learning loop. Parse N from argument (e.g., --learn=5). Default N=3, max N=10.

1. Generate N diverse outlines upfront. Vary: topic domain (tech, healthcare, finance, education, creative), presentation format (pitch, lecture, report, onboarding, keynote), slide count (8–16 slides), tone (formal, casual, data-heavy, storytelling). Save each to a working edu_NN/learn_N/outline.md.
2. For each outline, run the full pipeline (Steps 1–7):

• Generate layout-plan.json, prompts.json
• Generate AI background PNGs (Phase 1)
• Assemble Slidev project
• Install dependencies, run dual QA (Phase 2)

1. Score each composite output via references/scoring-subroutine.md — 6 axes. Write score-report.md.
2. Analyze patterns: Which zone strategies produced cleanest empty zones? Which prompt structures preserved zone boundaries? Which font pairings scored highest on Typography Quality? Which zone_strategies had the best Layout Precision scores?
3. Write improvements.md with findings for both image-layer prompt strategies and text-layer positioning strategies. Format: category (image|text|both), severity (critical|major|minor), proposed change, before/after.
4. Apply improvements: modify prompt construction strategy and zone placement heuristics for the next iteration.
5. Write design memory entry (references/design-memory.md write protocol) with both visual and text sub-objects. Entry type: success if avg ≥ 7, failure if avg **: Compare two presentations side-by-side. Follow references/compare-procedure.md`. Comparison is performed on composite exports (Phase 2 output — final composite PNG with both layers merged). Score on all 6 axes. Output:

| Slide | Axis              | Dir1 | Dir2 | Delta |
|-------|-------------------|------|------|-------|
| 1     | Visual impact     | 8    | 7    | +1    |
| 1     | Layer harmony     | 9    | 6    | +3    |
...
| Overall               | 7.8  | 6.5  | +1.3  |

Stop here — do not proceed to generation.

---

--notes [dir]: Generate speaker notes. Follow references/notes-procedure.md. Add 4-point speaker notes per slide (Opening / Key message / Details / Transition). Stop here — do not proceed to generation.

---

--responsive [dir]: Check presentation at 4:3 aspect ratio. Follow references/responsive-check.md. Switch aspectRatio to 4/3. Verify: zone divs don't overflow, background PNGs scale correctly (check letterboxing), text remains readable. Fix CSS if needed. Stop here — do not proceed to generation.

---

--dev [dir]: Launch Slidev dev server for an existing SlideCraft presentation.

1. Resolve project directory (see Directory Auto-Detection below).
2. Install dependencies if node_modules/ doesn't exist: run npm install in the project directory.
3. Start dev server using this exact pattern (slidev reads stdin for keyboard shortcuts and exits on EOF):

``bash cd && (sleep infinity | npx slidev) 2>&1 ` Run via Bash with runinbackground: true`.

1. Wait for ready: use the Read tool to read the background task's output file and check for the URL.
2. Report: print the local URL (e.g. http://localhost:3030/) once the server is ready. The server continues running in the background.

Stop here — do not proceed to generation.

---

--export [dir]: Export the composite presentation.

Formats:

• html — Static SPA via npx slidev build --base / → output in /dist/
• pdf — PDF via Slidev's built-in export (may lose CSS backdrop-filter effects)
• png2pdf — Pixel-perfect PDF: export PNGs first, then Python Pillow assemble
• pngs — Individual composite PNG files per slide
• png_N — Single slide N as PNG

Procedure:

1. Resolve project directory (see Directory Auto-Detection below).
2. Install dependencies if node_modules/ doesn't exist: run npm install.
3. Ensure playwright-chromium for pdf, png2pdf, pngs, png_N: run npx playwright install chromium.
4. Run export command:

• html: cd && npx slidev build --base /
• pdf: cd && npx slidev export --output slides.pdf
• png2pdf: Two-stage export:

1. cd && npx slidev export --format png --output slides-tmp
2. Ensure Pillow: pip install Pillow 2>/dev/null || pip3 install Pillow 2>/dev/null
3. Python script:

``python from PIL import Image import os, re png_dir = 'slides-tmp' files = [f for f in os.listdir(png_dir) if f.endswith('.png')] files.sort(key=lambda x: int(re.match(r'(\d+)', x).group())) images = [Image.open(os.path.join(png_dir, f)).convert('RGB') for f in files] images[0].save('slides.pdf', save_all=True, append_images=images[1:], resolution=150.0, quality=95) for img in images: img.close() ``

1. rm -rf /slides-tmp

• pngs: cd && npx slidev export --format png --output slides
• png_N: cd && npx slidev export --format png --range N --output slide-N

1. Report: print output file/directory path and format.

Stop here — do not proceed to generation.

---

--edit [dir] : Edit an existing SlideCraft presentation based on a free-text comment.

Step 1: Resolve project directory (see Directory Auto-Detection below).

Step 2: Read all project files: layout-plan.json, slides.md, prompts.json, meta.json, styles/index.css, components/Icon.vue.

Step 3: Detect edit type using this decision tree:

1. Does the edit move, resize, or reposition text zones? → BOTH (full cycle)
2. Does the edit change visual style (colors, mood, decorative elements, background) without moving zones? → VISUAL (PNG only)
3. Does the edit change text content, font sizes, or text styling without moving zones? → TEXT (Slidev layer only)

Edit type examples:

"Change heading on slide 3"            → TEXT  — update HTML in slides.md, Phase 2 QA only
"Make font size bigger"                → TEXT  — update CSS, Phase 2 QA only
"Make background brighter on slide 5"  → VISUAL — modify prompt, regenerate PNG, Phase 1+2 QA
"Move bullets to the right"            → BOTH  — update layout-plan + prompt_hint + PNG + CSS, dual QA
"Add a new bullet point"               → TEXT  — update HTML (if text fits zone)
"Change accent color"                  → TEXT  — CSS-only change
"Add decorative elements on left"      → VISUAL — modify prompt, regenerate PNG

TEXT edits:

1. Update HTML/CSS in slides.md for affected slides. Preserve all zone div coordinates.
2. Run Phase 2 QA (composite export, visual review).
3. If any zone overflows with new text: reduce font size or truncate. If zone is still insufficient: flag to user that zone resize is needed (requires BOTH edit type).

VISUAL edits:

1. Modify prompts.json for affected slides — update visual description, preserve zone instructions (prompt_hint must remain intact).
2. Regenerate affected PNGs via provider API (with anchor reference from meta.json unless --no-ref or anchor is being regenerated).
3. Phase 1 QA: verify zones are still clean in new PNG. Max 2 regen attempts if zones violated.
4. Phase 2 QA: export composite, verify text overlay still reads correctly against new background.

BOTH edits:

1. Update zone coordinates in layout-plan.json for affected slides.
2. Re-generate prompt_hint from updated zone positions (per references/layout-plan-format.md).
3. Update prompts.json with new prompt_hint and any visual changes.
4. Regenerate affected PNGs.
5. Phase 1 QA: verify new zones are empty.
6. Update CSS zone positions in slides.md to match new coordinates from layout-plan.json.
7. Phase 2 QA: full composite export + visual review.

Overflow escalation: If during TEXT or VISUAL edit the Phase 2 QA reveals text overflowing zone boundaries, escalate to BOTH edit type and adjust zone height/width in layout-plan.json before re-generating.

Final step: Update prompts.json with all changes. Print which slides were edited, edit type, QA results.

Stop here — do not proceed to generation.

---

--picture [auto|paths...] [dir]: Add real photos to non-text zones of AI-generated backgrounds.

Step 1: Resolve project directory (see Directory Auto-Detection below).

Step 2: Read layout-plan.json and identify free zones — areas NOT occupied by text zones. Free zones are coordinate regions on each slide where no zones[] entry exists. Calculate approximate free zone coordinates per slide.

Step 3: Select candidate slides — slides that have meaningful free zones (area ≥ 25% of slide).

…

Source & license

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

• Author: kama34
• Source: kama34/kama-skills
• License: MIT

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