# typst-slide
A [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) for creating academic presentations with [Typst](https://typst.app/) + [Touying](https://touying-typ.github.io/touying/).
Full lifecycle: **create → compile → review → polish → verify**.
## Why
LLMs generate decent slide *content* but consistently fail on:
- **Animation bloat** — `#pause` subslides explode PDF page counts without `handout: true`
- **Book-style outlines** — `#outline()` + heading numbering produces TOC with page numbers and dotted leaders
- **Sparse slides** — 3-bullet text-only slides with no formulas, diagrams, or tables
- **Missing pedagogy** — definitions without motivation, no worked examples
- **No diagrams** — baseline never uses CeTZ/Fletcher even when the content calls for it
This skill encodes 12 hard rules and a structured multi-phase workflow to fix these systematically.
## Eval Results
Tested on 3 evals (KZG commitment creation, ZKP intro creation, lattice crypto review) with and without the skill:
| Metric | With Skill | Without Skill | Delta |
|--------|-----------|--------------|-------|
| **Pass rate** | 100% | 79.6% | +20.4% |
| **Diagrams included** | Always | Never | Critical gap |
| **Handout mode** | Always on | Usually off | Fixes page bloat |
| **Review depth** | Catches all patterns | Misses 2-3 patterns | Better pedagogy |
Biggest differentiators: diagram inclusion (CeTZ/Fletcher), sparse-slide detection, reference-slide checking, consecutive-definitions-without-example detection.
Token/time overhead is ~85% — driven by the self-review quality loop. Acceptable given the quality delta.
## Install
Copy `SKILL.md` into your Claude Code skills directory:
```bash
# Option 1: project-level skill
mkdir -p .claude/skills
cp SKILL.md .claude/skills/typst-slide.md
# Option 2: user-level skill (available across all projects)
mkdir -p ~/.claude/skills/typst-slide
cp SKILL.md ~/.claude/skills/typst-slide/SKILL.md
```
### Prerequisites
- [Typst](https://typst.app/) CLI installed (`brew install typst` or `cargo install typst-cli`)
- Packages are auto-downloaded on first compile: Touying 0.7.0, CeTZ 0.4.2, Fletcher 0.5.8, Theorion 0.5.0
## Actions
| Action | Description |
|--------|-------------|
| `create [topic]` | Multi-phase slide creation: interview → outline → draft → quality loop |
| `compile [file]` | Compile `.typ` to PDF, report errors and page count |
| `review [file]` | Read-only proofreading report (grammar, typos, overflow, consistency) |
| `audit [file]` | Visual layout audit (overflow, font consistency, block fatigue) |
| `pedagogy [file]` | 13-pattern pedagogical review |
| `cetz [file]` | CeTZ/Fletcher diagram quality review |
| `excellence [file]` | Parallel multi-agent comprehensive review |
| `visual-check [file]` | PDF→image systematic visual inspection |
| `validate [file] [duration]` | Automated quantitative validation against timing table |
| `extract-figures [pdf]` | Extract figures from paper PDF for inclusion |
## Hard Rules
1. **Handout mode by default** — `config-common(handout: true)` collapses `#pause` subslides
2. **Max 2 styled blocks per slide**
3. **Motivation before formalism**
4. **Worked example within 2 slides of every definition**
5. **Typst source is the single source of truth**
6. **Verify after every task** — compile + check PDF
7. **Telegraphic style** — keyword phrases, not sentences
8. **Every slide earns its place** — must contain substantive content
9. **Content density guard** — compile and visually verify
10. **Reference slide** — second-to-last, before Thank You
11. **Color and contrast standards** — WCAG AA, colorblind-safe palette
12. **Backup slides** — 3-5 slides after Thank You for anticipated questions
## Tech Stack
| Package | Version | Role |
|---------|---------|------|
| [Touying](https://touying-typ.github.io/touying/) | 0.7.0 | Slide framework (6 built-in themes) |
| [CeTZ](https://typst.app/universe/package/cetz/) | 0.4.2 | Diagram library (TikZ equivalent) |
| [Fletcher](https://typst.app/universe/package/fletcher/) | 0.5.8 | Node-edge diagrams (built on CeTZ) |
| [Theorion](https://typst.app/universe/package/theorion/) | 0.5.0 | Theorem/definition environments |
## Examples
- [`examples/kzg-slides.typ`](examples/kzg-slides.typ) — KZG polynomial commitment seminar (15 min, grad-level)
- [`examples/test-review.typ`](examples/test-review.typ) — Intentionally flawed lattice crypto slides for testing the review action
## License
MIT