# /academic-ppt — Academic Deck Engine
# 学术答辩 PPT 自动生成 | Academic Presentation Generator
> **A Claude Code skill that generates defense-ready .pptx presentations from your paper.**
>
> **一个 Claude Code 技能，从你的论文自动生成答辩级别的 PPT。**
---
## What is this? / 这是什么？
This is a **Claude Code skill** — a set of structured guidelines that Claude reads and follows to generate a complete academic presentation for you. It is NOT a standalone app. You need [Claude Code](https://claude.ai/code) to use it.
这是一个 **Claude Code 技能** — 一套结构化的指导文件，Claude 会读取并按照指令帮你生成完整的学术 PPT。它**不是**一个独立的应用程序，你需要安装 [Claude Code](https://claude.ai/code) 才能使用。
### How it works / 工作原理
```
Your paper (LaTeX/PDF/text)
↓
Claude reads the skill guidelines
↓
Extracts content → Structures slides → Generates figures → Assembles .pptx
↓
A real .pptx file on your disk
```
### Key features / 核心特性
- **Action titles** — Slide titles are complete sentences stating the takeaway, not topic labels
- **Dual-engine figures** — Matplotlib for data charts (precise), Gemini for concept diagrams (visually rich)
- **Speaker notes** — What to say, timing cues, anticipated questions on every slide
- **Q&A prediction** — Auto-generated questions the committee might ask
- **Three scene templates** — Defense, conference talk, seminar
| 特性 | 说明 |
|------|------|
| 行动标题 | 每页标题是完整的结论句，不是"实验结果"这种空泛标题 |
| 双引擎图表 | Matplotlib 画数据图（精确），Gemini 画架构图（好看） |
| 演讲者备注 | 每页都有：该说什么、时间分配、可能被问到的问题 |
| Q&A 预测 | 自动生成答辩委员会可能问的问题和建议回答 |
| 三种场景模板 | 毕业答辩、学术会议、研讨会 |
---
## Quick Start / 快速开始
### 1. Install / 安装
```bash
# Copy skill to Claude Code skills directory
# 复制技能到 Claude Code 技能目录
cp -r claude-skill-academic-ppt ~/.claude/skills/academic-ppt
# Install Python dependencies / 安装 Python 依赖
pip install python-pptx matplotlib seaborn pymupdf Pillow Pygments
# Optional: Gemini image generation (for concept diagrams)
# 可选：Gemini 图片生成（用于架构图等概念图）
pip install google-genai
export GOOGLE_GENAI_API_KEY="your-key"
# Optional: Mermaid (fallback for concept diagrams)
# 可选：Mermaid（概念图的备选方案）
npm i -g @mermaid-js/mermaid-cli
```
### 2. Use / 使用
In Claude Code, just say:
```bash
# From LaTeX source (recommended / 推荐)
/academic-ppt --latex paper/main.tex --scene defense --time 20min
# From PDF
/academic-ppt paper.pdf --scene conference --time 12min
# From text description
/academic-ppt "Paper about X that achieves Y" --scene defense
```
### 3. Scene Templates / 场景模板
| Scene | Slides | Time | Best for |
|-------|--------|------|----------|
| **defense** | 10-20 | 10-20min | Thesis/FYP defense 毕业答辩 |
| **conference** | 10-15 | 10-15min | NeurIPS, ICML, ACL oral 学术会议 |
| **seminar** | 25-35 | 30-45min | Lab seminars, invited talks 研讨会 |
---
## ⚠️ Honest Disclaimer / 诚实声明
**This skill generates a solid first draft, not a final product.**
The output typically needs manual tweaking:
| What works well | What needs tweaking |
|----------------|-------------------|
| Slide structure & narrative flow | Fine-tuning text positions (overlaps happen) |
| Action titles (complete sentences) | Adjusting figure sizes for your specific content |
| Speaker notes & Q&A prediction | Font choices on your specific system |
| Data chart generation (Matplotlib) | Polishing visual details for your taste |
| Content extraction from LaTeX | Animations & transitions (not supported yet) |
**这个技能生成的是一个很好的初稿，不是最终成品。**
生成后通常需要手动微调：
| 做得好的 | 需要微调的 |
|---------|----------|
| 幻灯片结构和叙事逻辑 | 文字位置微调（偶尔有重叠） |
| 行动标题（完整的结论句） | 图片大小调整 |
| 演讲者备注和 Q&A 预测 | 字体在你系统上的显示效果 |
| Matplotlib 数据图表 | 视觉细节打磨 |
| LaTeX 内容提取 | 动画和过渡效果（暂不支持） |
**Expect to spend 15-30 minutes polishing after generation. Still way faster than building from scratch.**
**预计生成后需要 15-30 分钟打磨。但比从零做 PPT 快多了。**
---
## How It Compares / 横向对比
| Tool | Type | Approach | Quality |
|------|------|----------|---------|
| **This skill** | Claude Code skill (guidelines) | Claude reads rules → generates python-pptx code → builds .pptx | Good first draft, needs tweaking |
| [Anthropic pptx skill](https://github.com/anthropics/courses/tree/master/prompt_engineering_interactive_tutorial/skills) | Claude Code skill (guidelines) | Similar approach, uses PptxGenJS (Node.js) | Similar concept |
| [banana-slides](https://github.com/Anionex/banana-slides) | Standalone tool | Nano Banana (Gemini) generates slide images | Fully automated |
| [nbp_slides](https://github.com/grapeot/nbp_slides) | Standalone tool | Multi-model pipeline | Fully automated |
| Manual (PowerPoint/Keynote) | Manual | You do everything | Full control, slow |
---
## File Structure / 文件结构
```
academic-ppt/
├── SKILL.md # Main skill spec (Claude reads this)
│ # 主技能规范（Claude 读这个文件）
├── content_guidelines.md # Pyramid Principle, action titles, design rules
│ # 金字塔原理、行动标题、设计规则
├── figure_patterns.md # Matplotlib/Gemini/Mermaid code patterns
│ # 图表生成代码模板
├── templates/
│ ├── base_style.py # Shared styling (fonts, colors, spacing)
│ ├── defense.py # Defense template (10-20 slides)
│ ├── conference.py # Conference template (10-15 slides)
│ └── seminar.py # Seminar template (25-35 slides)
├── examples/
│ └── sample_prompt.md # Example usage
└── README.md # This file / 本文件
```
---
## Dependencies / 依赖
| Package | Required? | Purpose |
|---------|-----------|---------|
| python-pptx | **Yes** | PPTX file generation |
| matplotlib | **Yes** | Data charts |
| seaborn | **Yes** | Statistical visualizations |
| PyMuPDF | **Yes** | PDF text extraction |
| Pillow | **Yes** | Image processing |
| Pygments | **Yes** | Code syntax highlighting |
| google-genai | Optional | Gemini concept diagrams (Nano Banana 2) |
| @mermaid-js/mermaid-cli | Optional | Diagram fallback when no Gemini |
---
## Contributing / 贡献
Welcome! This is an early-stage skill and I'd love your help making it better.
欢迎！这是一个早期阶段的技能，非常期待你的帮助。
**Ways to contribute / 贡献方式：**
1. **Try it on your paper** and report what works / what breaks
试试用你自己的论文，告诉我什么好用、什么出问题了
2. **Add a new scene template** (e.g., poster, lightning talk, journal club)
添加新的场景模板（如海报展示、闪电演讲、期刊读书会）
3. **Improve figure generation** patterns
改进图表生成模板
4. **Fix layout issues** — text overlap is the #1 problem
修复布局问题 — 文字重叠是目前最大的问题
5. **Add language support** — currently EN/ZH, PRs for other languages welcome
添加语言支持 — 目前支持英文/中文，欢迎 PR 其他语言
### To report issues / 报告问题
Open an issue with:
- Your input type (LaTeX/PDF/text)
- The scene template used
- Screenshot of the problematic slide
- (Optional) The source paper or a minimal reproduction
提 issue 时请附上：
- 输入类型（LaTeX/PDF/文本）
- 使用的场景模板
- 问题幻灯片的截图
- （可选）源论文或最小复现
---
## License
MIT
---
**Made with Claude Code + python-pptx + Matplotlib + Gemini**
**Built by [@PHY041](https://github.com/PHY041) — feedback welcome!**