--- name: typst description: Syntax guide and ecosystem reference for writing Typst (.typ) files. Use this skill when writing, editing, or debugging Typst documents. Covers core syntax, common errors, packages, and best practices. license: MIT enabled: false source: github:clearsmog/claude-skills imported-from: github:clearsmog/claude-skills --- # Typst Skill **Current version**: Typst 0.14.2 (Dec 2025) ## Smart Defaults If you know nothing else, follow these rules: 1. **Always** import `@local/qk:2.1.0` — `#import "@local/qk:2.1.0": *` 2. **Always** use `qk-doc` or `qk-report` preset (unless user specifies custom) 3. **Always** use touying for presentations (not raw page dimensions) — see `references/touying-guide.md` 4. **Always** `#set figure(placement: auto)` — prevents blank half-pages 5. **Always** add `alt:` to images — `image("path.png", alt: "description")` 6. **Always** escape `$` in content — scan for bare `$` before compiling 7. **Default fonts**: Libertinus Serif (body), Inter (headings), New Computer Modern Math (math), Fira Code (code) 8. **Default compile**: `typst compile --root .. Source/.typ` 9. **When in doubt** about template: Study Guide 10. **When in doubt** about visual tool: diagrams → fletcher; charts → see decision tree (simple → cetz-plot, statistical → matplotlib+seaborn, grammar → plotnine, complex → matplotlib) 11. **Always** scan project for existing `.typ` files and match their style (fonts, colors, qk preset) unless user specifies otherwise ## New Document Decision Tree ``` User request → scan for keywords: "resume/CV/job" → CV / Résumé template "slides/presentation" → Presentation (touying — metropolis default) "lecture/class/academic" → Academic Lecture (touying — university theme) "essay/thesis/paper" → Essay "report/brief/client" → Business Report "research/analysis" → Research Report "study guide/revision" → Study Guide "reference/glossary" → Annotated Reference "cheatsheet/reference card/formula sheet" → Cheatsheet template "exam/problem set/homework" → Exam template "flashcard/Q&A/quiz" → Flashcard template ambiguous? → ask purpose + audience → pick template ``` **Steps:** 1. Auto-detect template from keywords above 2. Import `@local/qk:2.1.0` at top 3. Use `qk-doc` or `qk-report` preset when applicable 4. Auto-select template. State choice in Phase 3 summary. User can re-invoke with explicit type override if wrong. 5. Build from `references/templates.md` 6. Custom styles are fine — templates are starting points, not constraints ## Visual Tool Routing (compact) **Diagrams** (always native Typst — NEVER Python): | Need | Tool | |------|------| | Flowcharts, trees, ER, state diagrams | `fletcher` | | Sequence diagrams | `chronos` | | Gantt charts | `timeliney` | | Linear timelines | `herodot` | **Charts** (generate SVG, embed with `#figure(image(...))`): | Need | Tool | |------|------| | Simple charts (< 3 series, < 20 pts) | **cetz-plot** (Typst native, `qk-cycle` colors) | | Statistical plots (violin, kde, pair, heatmap) | **matplotlib + seaborn** (`use()`, SVG) | | Grammar-of-graphics / faceted plots | **plotnine** (`theme_qk()`, SVG) | | Complex charts (4+ series, annotations) | **matplotlib** (full API, SVG) | **Images & layout:** | Need | Tool | |------|------| | Tables, boxes, grids | Typst native | | Mind maps | `/mindmap` (auto-invoke) | | Conceptual illustrations | `gemini-generate-image` MCP (auto-invoke) | | Real photos, logos | `/image-search` (auto-invoke) | Detail and examples in `references/tool-routing.md`. ## Proactive Behaviors ### Visual Auto-detection When writing Typst documents, automatically identify content that benefits from visuals. Do NOT wait for the user to request them. Route by content type: diagrams → native Typst (fletcher/chronos/timeliney/herodot); charts → cetz-plot (simple) / matplotlib or plotnine (complex) — generate SVG, embed; images → `/image-search` / `/mindmap` / `gemini-generate-image` MCP. | Content pattern | Visual to add | Tool | |-----------------|---------------|------| | Comparison grids, attribute tables | Styled table | Typst native | | Callout boxes, styled layouts | `rect()` / `block()` | Typst native | | Sequential steps, decision logic | Flowchart / decision tree | `fletcher` | | Process with inputs/outputs | Workflow diagram | `fletcher` | | System architecture, ER diagrams | Block / entity diagram | `fletcher` | | Hierarchy or taxonomy | Tree diagram | `fletcher` or `/mindmap` | | Topic overview, concept map | Mind map | `/mindmap` | | Request-response, API flows | Sequence diagram | `chronos` | | Project schedule, phases | Gantt chart | `timeliney` | | Historical events, evolution | Timeline | `herodot` or `timeliney` | | Simple data chart (< 3 series, < 20 pts) | Line/bar/scatter chart | cetz-plot (Typst native) | | Statistical/complex chart | Violin/kde/heatmap/faceted chart | matplotlib+seaborn or plotnine | | Company logo, brand mark | Logo image | `/image-search --logo` | | Real-world photograph | Photo | `/image-search` | | Concept with analogy, metaphor | AI illustration | `gemini-generate-image` MCP | See `references/tool-routing.md` for full examples, fallback chains, and auto-invoke rules. ### Content Structure - Suggest TOC (`#outline()`) at 4+ sections - Suggest file split at 40+ pages — see `references/common-patterns.md` "Large Documents" - Convert prose lists to tables when 3+ items with attributes ### Component Library Auto-use When writing content, automatically convert matching patterns to `@local/qk:2.1.0` components: | Content pattern | Use instead | |-----------------|-------------| | Warning paragraph | `warning[...]` | | Key point / takeaway | `keypoint[...]` | | Tip or best practice | `tip[...]` | | Common mistake / trap | `trap[...]` | | Step-by-step procedure | `step-box("Title", [...])` | | Key equation / formula | `formula-box("Title", [...])` | | KPI or metric highlight | `stat-card("value", "label")` | | Frequency indicator | `freq-badge("HIGH")` / `freq-badge("MEDIUM")` / `freq-badge("LOW")` | | MCQ answer explanation | `answerbox("A", "why", "trap", "concept")` | | Analogy / intuition | `analogy[...]` | | "Why this matters" | `whycare[...]` | ### Cross-referencing Add `