beamer-ppt — Claude Code skill: what it does, how to install
beamer-ppt is a Claude Code skill that builds LaTeX Beamer presentations one slide at a time and shows PDF previews in chat.
MIT ★ 240 updated 2026-09-18
npx skills add franklee16/academic-research-skills --skill beamer-ppt -a claude-codeWhat beamer-ppt does
This skill guides you through building LaTeX Beamer decks incrementally. It asks for content slide by slide, compiles the code after each step, and renders instant previews. You can pick academic layouts for thesis defenses or conference talks, as well as business and lecture templates.
Slide review depends on local tools. With pdftoppm or ImageMagick present, the skill converts compiled pages into 150 DPI images and checks for text overflows or stretched figures. Without those utilities, visual mode turns off and you inspect the compiled PDF files yourself.
Project state and session snapshots are saved to beamer-skill.json. That design lets you run multiple slide decks side by side, revert bad edits, and resume work without losing previous changes.
What it helps with
- build academic Beamer presentations without writing raw LaTeX by hand
- inspect slide layout right after compiling each page
- typeset slides in English or Chinese using the
ctexpackage - manage several slide projects with rollback history
Example prompts for the agent
- Create a Beamer presentation for my conference talk in English
- /mode visual
- Switch to my thesis defense project and resume editing
How to install beamer-ppt
1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill beamer-ppt -a claude-code2Manually: put the files in place
~/.claude/skills/Beamer_PPT/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/Beamer_PPT/
1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill beamer-ppt -a codex2Manually: put the files in place
.agents/skills/Beamer_PPT/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill beamer-ppt -a cursor2Manually: put the files in place
.cursor/skills/Beamer_PPT/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install franklee16/academic-research-skills presentations/Beamer_PPT/SKILL.md2Manually: put the files in place
.github/skills/Beamer_PPT/SKILL.md1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill beamer-ppt -a gemini-cli2Platform CLI
gemini skills install https://github.com/franklee16/academic-research-skills --path presentations/Beamer_PPTManually: put the files in place
.devin/skills/Beamer_PPT/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about beamer-ppt
How to install beamer-ppt in Claude Code?
Run npx skills add franklee16/academic-research-skills --skill Beamer_PPT -a claude-code. Alternatively, place the file directly into ~/.claude/skills/Beamer_PPT/SKILL.md.
What does beamer-ppt do?
It writes LaTeX Beamer presentations through interactive prompts, compiles slides into PDF files, and validates slide layouts with visual or text-guided checks.
What tools are required for visual slide inspection?
It relies on pdftoppm from poppler-utils, ImageMagick, or the Python pdf2image package to convert PDFs into PNG images. If none are installed, it falls back to text mode.
Source text
SKILL.md · MIT
---
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`:
```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:**
```bash
# 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):
```bash
# 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]` | Switch preview mode |
| `/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.
© franklee16 · MIT · franklee16/academic-research-skills