ppt-skill

name

ppt-skill

description

AI-powered PPT generation skill — extracts design specs from existing PPTX files and generates natively editable .pptx files with agent-loop style verification. Use /ppt-spec to analyze a reference PPTX and extract design spec, or /ppt to generate a presentation. Also use when the user asks to create slides, make a presentation, generate pptx, analyze pptx style, or convert content to slides. Supports cover/toc/content/end_page recognition, multi-layout content, VL model analysis, and 90%+ style fidelity.

PPT Skill

Spec-driven PPT generation: extract design DNA from reference PPTX → gather content → generate natively editable slides with agent-loop style verification.

Slash Commands

Command	Purpose
/ppt-spec <file.pptx>	Extract design spec from reference PPTX (cover/toc/content/end_page recognition + layout analysis)
/ppt-spec-vl <file.pptx>	Extract VL-driven spec with element role analysis, layout dedup, JSON output (no text content)
/ppt-outline <content>	Generate content outline using WPS model from prompt-ppt-content.md (titles + body only)
/ppt-diagram <type> <content>	Generate diagram (architecture/flowchart/sequence) from description
/ppt <content or file>	Generate PPT: gather content → confirm outline → generate PPTX → apply layout design

Quick Start

# Extract design spec from a reference PPTX
python scripts/ppt_cli.py extract-spec reference.pptx

# Generate PPT from content (with agent-loop style verification)
python scripts/ppt_cli.py generate-pptx --spec specs/my_spec/ --outline outline.yaml -o output.pptx --workers 4

# Direct SVG to PPTX conversion
python scripts/ppt_cli.py convert slide1.svg slide2.svg -o output.pptx

Commands

Command	Description
extract-spec <pptx>	Extract design spec → specs/<name>/ directory (pages by type, assets, logic.yaml)
extract-vl-spec <pptx>	Extract VL-driven spec → specs/<name>/ JSON + slide images (no text, layout dedup)
generate-pptx	Generate PPTX from spec + outline with agent-loop eval (--spec --outline -o --workers)
convert <svg>... -o <pptx>	Direct SVG→native-shape PPTX conversion
list-specs	List available design specs
select-spec <name>	Set active design spec
gather-content <text|file>	Content gathering → slide-by-slide outline (adaptive questioning, 8-question cap)
list-outlines	List saved content outlines

All scripts run from the skill root directory.

Workflow

/ppt-outline — Generate Content Outline

This command has two modes depending on input richness:

Mode A — Topic-only (input <= 30 words, no structure markers) The user only provided a topic name (e.g. "AI in Healthcare 2024"). Do NOT proceed with outline generation directly. Instead:

1. Detect sufficiency: The skill outputs a structured JSON delegation signal:

   {
     "type": "delegate",
     "skill": "deerflow-skill",
     "query": "<topic>",
     "context": "Research this presentation topic comprehensively. Gather key sections, trends, data points, examples, case studies, and supporting evidence needed for a professional slide deck."
   }
   

2. Call deerflow-skill: The outer agent reads this signal and invokes deerflow-skill with the query to research the topic thoroughly.
3. Return enriched content: After deerflow-skill returns comprehensive research, call ppt-skill again with the enriched content.
4. Apply prompt-ppt-content.md: When the content is received (now rich), apply prompt-ppt-content.md WPS rules to optimize the content into a structured outline:
   • Each slide gets W (What): Navigation label
   • P (Point): Core conclusion (bold, prominent)
   • S (Support): Evidence (data, cases, quotes)
5. Output: Markdown outline ready for /ppt generation

Mode B — Rich content (detailed input with structure) The user provided sufficient detail (bullets, sections, or extensive text).

1. Apply WPS model: Use prompt-ppt-content.md principles directly
   • Analyze input → extract sections and key points
   • Structure each slide with W (What) / P (Point) / S (Support)
   • Validate outline completeness
2. Output: Markdown outline ready for /ppt generation

/ppt-diagram — Generate Diagram

1. Classify diagram type: architecture, data-flow, flowchart, sequence, class, er-diagram, network-topology
2. Extract structure: identify nodes, edges, containers from description
3. Apply layout rules:
   • Architecture: horizontal layers (Client → Gateway → Services → Data)
   • Flowchart: top-to-bottom, diamond for decisions
   • Sequence: vertical lifelines with horizontal messages
4. Generate SVG using 7 visual styles:
   • Style 1: Flat Icon (default, white bg)
   • Style 2: Dark Terminal (monospace, dark bg)
   • Style 3: Blueprint (cyan on navy)
   • Style 4: Notion Clean (minimal)
   • Style 5: Glassmorphism (translucent)
   • Style 6: Claude Official (warm cream)
   • Style 7: OpenAI (green accent)
5. Export: SVG + PNG via rsvg-convert

/ppt-spec — Extract Design Spec

Two extraction modes:

Mode A — Standard (extract-spec) — preserves text content

1. Read the reference PPTX with python-pptx + lxml
2. Extract color palette (12 HEX values from theme1.xml), fonts, backgrounds
3. Classify each page: cover / toc / transition / content / end_page
4. For content pages, identify layout sub-type: left_right, top_bottom, etc.
5. If VL_ENABLED=true in config.txt, use VL model for enhanced layout description
6. Extract reusable assets (backgrounds, images)
7. Analyze presentation logic (narrative, density rhythm, sections)
8. Save as directory: specs/<name>/ with spec.yaml, pages/, assets/, logic.yaml

Mode B — VL-driven (extract-vl-spec) — no text content, layout dedup

1. Read the reference PPTX with python-pptx, extract every element's properties:
   • Position, size (normalized 0-1)
   • Font family, size, weight, color, alignment
   • Fill color, stroke color/width, corner radius
   • Image dimensions
   • Z-order, shape name
2. Render each slide to PNG via macOS QuickLook
3. Send slide image + structured element properties to VL model:
   • VL compares the visual image with extracted element attributes
   • VL describes each element's ROLE: "Element 1 is the title bar", "Elements 3-6 form a flowchart in the content area"
   • VL identifies composite groups and design patterns
4. Layout dedup: group similar pages by element structure signature
   • Cover/end_page → one JSON file each
   • Content pages with same layout → merged into one JSON file
5. Output specs/<name>/ with:
   • spec.json — master spec (palette, fonts, canvas, layout index)
   • cover.json, end_page.json, content_*.json — per-layout blueprints
   • slides/ — slide PNG screenshots
   • Source PPTX copy for reference

See references/spec-format.md.

/ppt — Generate Presentation

1. Assess sufficiency: evaluate if user input has enough detail
2. If insufficient (topic-only): call deerflow-skill to research the topic, gather comprehensive content, then apply prompt-ppt-content.md for outlined>
3. If sufficient: proceed directly with prompt-ppt-content.md WPS optimization
4. User confirms the outline before generation
5. Phase 1: Spec Matching (agent-loop, per slide, in parallel, using VL model):
   • Match slide to correct spec page type (cover→cover spec, content→matching layout spec, etc.)
   • Generate SVG with strict style constraints from spec
   • Evaluate: color match, font match, layout IoU, background, density
   • If score < 90% → add fix instructions, regenerate (max 5 iterations)
   • All slides generated in parallel via ThreadPoolExecutor
6. Phase 2: Layout Design (agent-loop, using prompt-ppt-layout.md):
   • Apply WPS hierarchy: W (navigation) small, P (point) large/bold, S (support) regular
   • Typography: sans-serif fonts, 1.5x line spacing, justified text
   • Color rules: single primary color, dark text (#333-#444)
   • Whitespace: 8-12% margins, breathing room
   • Visuals: Bootstrap Icons from assets/bootstrap-icons-1.13.1/
   • Validate layout checklist (max 3 iterations)
7. Convert: all SVGs → native-shape PPTX via SVG→DrawingML pipeline
8. Output: editable .pptx with real PowerPoint shapes

Content Gathering Mode

When the user just wants to prepare content without generating PPTX:

1. Assess content sufficiency (word count, structure markers)
2. If sufficient → directly apply prompt-ppt-content.md WPS optimization
3. If insufficient (topic-only) → call deerflow-skill to research, then apply WPS optimization
4. Output: outlines/<name>.yaml — ready for /ppt generation

Configuration

Copy config.example.txt to config.txt for VL model analysis in spec extraction:

VL_ENABLED=true
VL_PROVIDER=openai        # openai | anthropic | gemini | ollama
VL_MODEL=gpt-4o
VL_API_KEY=sk-...

Resources

Directory/File	Contents
scripts/ppt_cli.py	CLI entry point
scripts/ppt_skill/	Python package (converter, spec, content, layout, diagram, finalize, evaluator)
references/spec-format.md	Design spec schema
references/prompt-ppt-content.md	Content generation principles (WPS model)
references/prompt-ppt-layout.md	Layout design principles
references/diagram-styles/	Diagram style references (7 styles + icons)
templates/diagram/	Diagram SVG templates
assets/Illustration/	400 vector illustrations (unDraw, MIT License)
assets/bootstrap-icons-1.13.1/	2000+ SVG icons for slides
assets/templates/icons/	11,600+ SVG icons (5 libraries)
assets/templates/charts/	70+ chart/infographic SVGs
config.example.txt	Model configuration template

Illustration Library

assets/Illustration/ contains 283 open-source vector illustrations from unDraw:

Categories

Category	Count	Examples
AI & Technology	10+	ai-chat, ai-code-assistant, coding-assistant
Data Analytics	15+	analyze, data-table, analytics-setup
Team & Collaboration	10+	collaboration, followers, eating-together
Success & Achievement	10+	accomplishments, completed, goals
Business & Marketing	15+	business-decisions, customer-survey, contract
Learning & Education	10+	continuous-learning, exam-prep, five-year-plan
Documents & Files	10+	document-ready, file-analysis, add-files

Search Illustrations

# Search for AI-related illustrations
python3 scripts/ppt_skill/illustration_finder.py search "ai"

# Search by category
python3 scripts/ppt_skill/illustration_finder.py list --category data

# Get random illustrations
python3 scripts/ppt_skill/illustration_finder.py random --count 5

# List all categories
python3 scripts/ppt_skill/illustration_finder.py list --categories

Use in PPT

from pptx import Presentation
from pptx.util import Inches

# Add illustration to slide
prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[6])
slide.shapes.add_picture(
    "assets/Illustration/undraw_ai-chat_ljb9.svg",
    Inches(1), Inches(1), Inches(4)
)

Customize Colors

Edit SVG fill attributes to match your brand:

<!-- Original orange -->
<path fill="#f9a826" d="..." />

<!-- Change to brand blue -->
<path fill="#0070C0" d="..." />

Requirements

Python 3.10+ with:

python-pptx>=0.6.21
Pillow>=9.0.0
PyYAML>=6.0

Optional for VL analysis: openai, anthropic, or google-generativeai.