beamer-ppt

name	beamer-ppt
description	A conversational assistant skill for creating professional LaTeX Beamer presentations through natural dialogue. Users create slides page-by-page with flexible layouts and instant PDF preview. Supports both Chinese (ctex) and English typesetting with multi-project management and undo/redo capabilities.

Beamer PPT Typesetting Assistant

Create professional LaTeX Beamer presentations through conversational interaction.

When to Use This Skill

Use this skill when users want to:

• Create academic presentations (thesis defense, conference talks, lab group meetings)
• Build business presentations (product demos, project reports, pitch decks)
• Design lecture slides for teaching or tutorials
• Generate LaTeX Beamer code without deep LaTeX expertise
• Convert content ideas into professionally typeset slides

Core Capabilities

Conversational Slide Creation

Guide users through creating slides one-by-one via natural dialogue. Collect content incrementally, suggest improvements, and confirm before proceeding.

Flexible Layouts

Offer preset layouts from @scripts/layouts/ or interpret custom layout descriptions in natural language. Support single-column, multi-column, image-text combinations, and special arrangements.

Instant PDF Preview

Compile LaTeX after each slide and display the resulting PDF. Enable immediate visual feedback and iteration.

Multi-Project Support

Maintain multiple presentation projects simultaneously. Track project state, enable switching between projects, and resume interrupted sessions.

Language Independence

Separate conversation language from presentation language. Support Chinese (via ctex package) and English typesetting regardless of the dialogue language.

Undo/Redo and History

Maintain complete session history with automatic snapshots. Enable rollback to any previous state and recovery from crashes.

Visual Mode Configuration

Model Capability Detection

At project initialization, determine the AI model's visual capabilities:

[Skill] Please confirm your AI model's capabilities:
A) My model supports image understanding (GPT-4V, Claude 3, etc.)
B) My model does NOT support images (text-only model)

This determines how we preview and refine slides.

Store this choice in beamer-skill.json:

{
  "settings": {
    "visual_mode": "enabled" | "disabled"
  }
}

Allow mode switching mid-session:

[User] /mode visual
[Skill] Switched to visual mode. PDF previews will be converted to images.

[User] /mode text
[Skill] Switched to text mode. Please describe issues you see in the PDF.

PDF-to-Image Tool Detection

When visual mode is enabled, check for required tools at project initialization:

[Skill] Checking PDF-to-image tools...

✓ pdftoppm found (optimal)
⚠ ImageMagick found (fallback)
✗ pdf2image not found

Visual preview: Available
Resolution: 150 DPI (optimal for speed/quality balance)

Tool Priority:

1. pdftoppm (poppler-utils) - Fastest, best quality

   • macOS: brew install poppler
   • Ubuntu: sudo apt-get install poppler-utils
   • Windows: Download Xpdf tools

2. ImageMagick (convert) - Fallback option

   • Available on most systems
   • Slower but reliable

3. pdf2image (Python) - Alternative

   • Requires: pip install pdf2image poppler

Automatic Degradation: If no tools available:

[Skill] ⚠ No PDF-to-image tools detected.

Automatically switching to text-only mode.
You can still create presentations, but I'll rely on
your descriptions to make adjustments.

To enable visual preview later, install:
- macOS: brew install poppler
- Ubuntu: sudo apt-get install poppler-utils
- Windows: https://www.xpdfreader.com/download.html

Or switch anytime with: /mode text

Visual Mode Workflow

When Visual Mode is Enabled:

After compilation:

[Skill] Compiling... ✓ Success!
        Converting to image... ✓ Done!

[Preview Image: page-3.png]

Visual inspection:
✓ Text fits within margins
✓ Image proportions correct
⚠ Title is quite long (3 lines), consider shortening
✓ Good contrast and readability

Options:
A) Accept and continue
B) Fix the long title
C) Other adjustments

When Visual Mode is Disabled:

After compilation:

[Skill] Compiling... ✓ Success!

PDF saved to: ./my-presentation/.beamer-skill/preview/page-3.pdf

Since I cannot view images, please describe what you see:
A) Looks good, continue
B) Text is too small/large
C) Image looks stretched/squashed
D) Text overflows the slide
E) Other issue (please describe)

For detailed visual checks, refer to @references/visual-checklist.md

Visual Inspection Checklist

When visual mode is enabled, systematically check each slide for:

Critical Issues (must fix):

• Text overflow beyond slide boundaries
• Image aspect ratio distortion (stretched/squashed)
• Severe compression artifacts
• Poor contrast making text illegible

Important Issues (should fix):

• Font too small/large for content
• Image quality problems (blurry/pixelated)
• Alignment problems
• Title wrapping to too many lines

Enhancement Opportunities:

• Color harmony
• Whitespace balance
• Font hierarchy clarity
• Consistency across slides

Reference detailed checklist at @references/visual-checklist.md

Getting Started

Starting a New Project

Recognize project initiation requests such as:

• "帮我做一个关于机器学习的PPT" (Create a presentation about machine learning)
• "Create a presentation for my thesis defense"
• "I need slides for a conference talk"

Guide the user through:

1. Selecting presentation language (Chinese/English)
2. Choosing a template from available options
3. Creating slides page-by-page with preview
4. Refining content based on feedback

Working with Existing Projects

Support project management commands:

• "打开项目毕业论文答辩" - Open existing project by name
• "切换到项目组会汇报" - Switch between active projects
• "继续上次的编辑" - Resume from last saved state
• "列出所有项目" - Show available projects

Workflow

1. Project Initialization

When starting a new project, present language options:

[Skill] Welcome! I'll help you create a professional Beamer presentation.

Choose presentation language:
A) 中文（简体）- Chinese with ctex package
B) English - Standard English typesetting
C) Other

Note: This determines the PPT content language, independent of our conversation.

Store the language choice in the project configuration and apply appropriate LaTeX packages.

2. Template Selection

After language selection, present template categories:

Academic Templates:

1. Thesis Defense - Formal academic style for degree presentations
2. Group Meeting Report - Lab meeting format with progress focus
3. Conference Talk - Compact format for time-limited talks

Business Templates: 4. Product Demo - Modern style for product introductions 5. Project Report - Professional format for status updates

Teaching Templates: 6. Lecture Slides - Classroom format with clear sections 7. Tutorial - Step-by-step guide format

Load template configuration from @assets/templates/*/template.json files.

3. Page-by-Page Creation

Guide through each slide systematically:

[Skill] ─────────────────────────────────────
        Page 1: Title Slide
        ─────────────────────────────────────
        
        Enter presentation title:

[User] Deep Learning for Medical Image Analysis

[Skill] Enter author name:

[User] John Smith

[Skill] Generating code... Compiling preview...
        
        [Preview Image]
        
        Satisfied?
        A) Yes, continue to next page
        B) Modify layout
        C) Modify content
        D) Delete and redo

Continue this pattern for each slide type defined in the template.

4. Compilation and Preview Process

Step-by-Step Compilation:

After content collection for each slide:

[Skill] Step 1: Generating LaTeX code
        ✓ Frame code written to main.tex
        
        Step 2: Compiling with xelatex
        ✓ Compilation successful
        
        Step 3: Converting to preview format

Compilation Command:

# Standard compilation
xelatex -interaction=nonstopmode -file-line-error main.tex

# With bibliography (if citations present)
xelatex -interaction=nonstopmode main.tex
bibtex main
xelatex -interaction=nonstopmode main.tex
xelatex -interaction=nonstopmode main.tex

Preview Generation:

For visual mode (with tools available):

# Extract current page as PNG (150 DPI)
pdftoppm -f <page_num> -l <page_num> -png -r 150 \
         main.pdf \
         .beamer-skill/preview/page-<page_num>

# Alternative with ImageMagick
convert -density 150 main.pdf[<page_num-1>] \
        .beamer-skill/preview/page-<page_num>.png

Preview File Locations:

• PDF: .beamer-skill/preview/page-XX.pdf
• PNG (visual mode): .beamer-skill/preview/page-XX.png
• Resolution: 150 DPI (optimal balance)

Visual Mode Preview:

[Skill] ✓ Compilation successful
        ✓ Converted to image

[Display: .beamer-skill/preview/page-3.png]

Visual analysis:
✓ Text within boundaries
✓ Image proportions correct  
⚠ Title wraps to 3 lines
✓ Good contrast

Options:
A) Accept and continue
B) Adjust title length
C) Modify layout

Text-Only Mode Preview:

[Skill] ✓ Compilation successful

PDF saved: .beamer-skill/preview/page-3.pdf

Since visual mode is disabled, please review manually
and describe any issues you notice.

Common issues to check:
- Text overflowing slide boundaries
- Images stretched or squashed
- Font too small/large
- Poor alignment

Options:
A) Looks good, continue
B) Describe issues for me to fix

Automatic Error Recovery:

If compilation fails:

[Skill] ⚠ Compilation failed

Error: File `results.png' not found
Location: Slide 3, line 15

Options:
A) Check figures/ folder and retry
B) Skip this image temporarily
C) Use placeholder text instead

If PDF-to-image conversion fails in visual mode:

[Skill] ⚠ PDF conversion failed (tool not available)

Automatically switching to text-only mode for this session.

PDF is still available at: .beamer-skill/preview/page-3.pdf
Please review manually and describe any issues.

To re-enable visual mode, install:
- macOS: brew install poppler
- Ubuntu: sudo apt-get install poppler-utils

5. Layout Options

Standard Layouts (reference @scripts/layouts/):

From single-column/:

• text-only.tex - Pure text paragraphs
• bullet-list.tex - Bulleted or numbered lists

From two-column/:

• image-left.tex - Image on left, text on right
• image-right.tex - Text on left, image on right

Custom Layouts:

Interpret natural language descriptions:

[User] I want a title at top, then left side big image taking 2/3 width,
       right side three small images stacked vertically

[Skill] Understood! Adjusting to:
        
        ┌─────────────────────┐
        │      Title          │
        ├──────────┬──────────┤
        │          │  Small 1 │
        │   Big    ├──────────┤
        │  (66%)   │  Small 2 │
        │          ├──────────┤
        │          │  Small 3 │
        └──────────┴──────────┘

Generate appropriate LaTeX code using columns, minipages, or custom arrangements.

6. Quick Commands

Support power-user commands for efficiency:

Command	Action
/next	Proceed to next slide
/list	Display all slides with indices
/goto <n>	Jump to slide n for editing
/preview	Recompile and preview current slide
/delete	Remove current slide
/copy	Duplicate current slide
/undo	Revert last action
/redo	Reapply undone action
/theme	Change Beamer theme
`/mode [visual	text]`
/help	Display command reference

Mode Switching:

[User] /mode visual
[Skill] Switched to visual mode.
        PDF previews will be converted to images.
        Requirements: pdftoppm or ImageMagick

[User] /mode text
[Skill] Switched to text-only mode.
        Please describe issues you see in the PDF.
        Useful for text-only AI models.

File Organization

Project Structure

Each presentation project creates a dedicated directory:

my-presentation/
├── main.tex              # Main LaTeX file (always compilable)
├── beamer-skill.json     # Project configuration
├── figures/              # Image resources directory
└── .beamer-skill/        # Skill working directory
    ├── snapshots/        # Undo/redo history
    └── preview/          # Generated preview images

Maintain main.tex in a compilable state at all times. Store project metadata in beamer-skill.json.

Image Resources

Place all images in the figures/ folder:

• Supported formats: PNG, JPG, PDF, EPS
• Recommended maximum size: 5MB per image
• Use relative paths: ./figures/image.png

Automatically:

• Scan figures folder when inserting images
• Validate file existence before compilation
• Suggest optimal sizing parameters
• Handle path conversion between platforms

Language Support

Chinese Typesetting

When Chinese language is selected:

• Include ctex package automatically
• Configure Chinese fonts by OS:
  • Windows: SimSun (serif), SimHei (sans-serif)
  • macOS: PingFang SC
  • Linux: Noto CJK
• Apply 1.3x line spacing for readability
• Enable Chinese paragraph indentation
• Configure proper punctuation spacing
• Use xelatex compiler (required)

English Typesetting

When English language is selected:

• Use standard Latin Modern fonts
• Apply academic/business optimized layouts
• Enable proper hyphenation
• Configure appropriate spacing

Mixed Content

Support limited language mixing:

• Chinese presentations may include English technical terms
• English presentations may include Chinese characters if needed
• Handle font switching automatically via ctex or fontspec
• Warn user if extensive mixing may cause issues

Error Handling

Compilation Errors

Handle common LaTeX issues gracefully:

Missing Images:

• Detect missing file errors
• Prompt for correct path or image upload
• Offer to skip image or use placeholder

Missing Packages:

• Identify missing package errors
• Suggest installation commands (tlmgr, apt, etc.)
• Offer to use alternative packages if available

Font Issues:

• Detect font not found errors
• Fallback to available system fonts
• Suggest manual font configuration

Syntax Errors:

• Parse LaTeX error logs
• Attempt auto-fix for common issues
• Present clear error messages to user

File System Errors

Disk Space:

• Monitor available space before compilation
• Suggest cleanup if space is low
• Offer to delete old snapshots

Permissions:

• Check write permissions on project directory
• Provide fix instructions for permission issues
• Suggest alternative locations if needed

Special Characters:

• Auto-rename files with problematic characters
• Escape special characters in LaTeX content
• Validate paths before use

Environment Issues

LaTeX Not Installed:

• Detect missing LaTeX installation
• Provide platform-specific installation guides
• Suggest minimal distributions for quick start

Missing Compiler:

• Verify xelatex availability for Chinese
• Suggest lualatex as alternative
• Provide compiler configuration options

Outdated Packages:

• Check package versions when errors occur
• Suggest updates via tlmgr or package manager
• Offer workarounds for compatibility issues

Advanced Features

Batch Operations

Enable modifications across multiple slides:

• "Change all slides to 14pt font"
• "Switch theme to Madrid for entire presentation"
• "Adjust line spacing to 1.5 for all content slides"
• "Replace logo on all slides"

Parse requests and apply changes systematically while validating results.

Page Reordering

Support slide reordering commands:

• "Move page 3 after page 5"
• "Swap page 2 and page 7"
• "Move pages 8-10 to the beginning"
• "Delete pages 4-6"

Update slide numbering and cross-references automatically.

Snapshots and History

Maintain comprehensive history:

• Create automatic snapshots after each confirmed slide
• Support explicit checkpoints: "Save checkpoint named 'before revision'"
• Display history browser with timestamps
• Enable recovery if conversation is interrupted
• Store snapshots in .beamer-skill/snapshots/

Layout Templates

Allow saving custom layouts:

[User] Save current page as template

[Skill] Template name: Three-column timeline
       Description: Timeline with left timestamps, center events, right details
       Saved to: scripts/layouts/custom/
       Available in future projects!

Store user-created layouts for reuse across projects.

Tips and Best Practices

For Users

1. Start Simple: Begin with standard layouts, customize after mastering basics
2. Preview Often: Check each slide immediately to catch issues early
3. Organize Images: Place all images in figures/ before starting
4. Use Checkpoints: Save named checkpoints before major changes
5. Incremental Building: Create one page at a time to avoid overwhelm
6. Project Naming: Use descriptive names for easy project switching

For Skill Execution

1. Validate Paths: Always verify image paths exist before including in LaTeX
2. Check Compilability: Ensure main.tex is valid after each modification
3. Preserve State: Save project state frequently to prevent data loss
4. Clean Output: Remove auxiliary files after successful compilation
5. Error Context: Provide helpful context with error messages

Troubleshooting

Compilation is Slow

Causes and Solutions:

• Large images: Suggest compression or resizing
• Complex layouts: Simplify or use draft mode
• Many slides: Compile only current slide for preview

PDF Preview Not Showing

Diagnostic Steps:

1. Check compilation success in terminal output
2. Verify LaTeX installation: xelatex --version
3. Check file permissions in project directory
4. Verify PDF viewer availability

Chinese Characters Not Displaying

Solutions:

1. Ensure xelatex is used (not pdflatex)
2. Check Chinese font installation: fc-list :lang=zh
3. Try font configuration in .font-config.tex
4. Verify ctex package is included

Lost Work After Crash

Recovery Options:

1. Run "继续上次的编辑" or "resume last session"
2. Check .beamer-skill/snapshots/ for recent versions
3. Look for auto-save files in project directory
4. Restore from git if version controlled

References

For detailed technical information, reference these files:

• @references/latex-basics.md - LaTeX fundamentals and common commands
• @references/beamer-themes.md - Available themes and customization options
• @references/visual-checklist.md - Visual quality inspection checklist
• @README.md - Detailed usage examples and configuration options

License

MIT License - See LICENSE file for details.