Typst Skill

Current version: Typst 0.15.x

Smart Defaults

Defaults, unless the user or the project's existing files say otherwise:

1. Import @local/qk:2.2.0 — #import "@local/qk:2.2.0": *
2. Use the qk-doc or qk-report preset
3. Use touying for presentations (not raw page dimensions) — see references/touying-guide.md
4. #set figure(placement: auto) — prevents blank half-pages
5. Add alt: to images — image("path.png", alt: "description")
6. 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/<file>.typ
9. Template when the request doesn't settle it: Study Guide
10. Visual tool when the content doesn't settle it: diagrams → fletcher; charts → see decision tree (default → lilaq; extremely simple → cetz-plot (rare); statistical kde/pair → matplotlib+seaborn; grammar → plotnine; complex with Python data → matplotlib)
11. Scan the project for existing .typ files and match their style (fonts, colors, qk preset)

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.2.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):

Charts (generate SVG, embed with #figure(image(...))):

Images & layout:

Detail and examples in references/tool-routing.md.

Proactive Behaviors

Visual Auto-detection

When writing Typst documents, add a visual wherever it makes the content clearer, without waiting to be asked. Route by content type: diagrams → native Typst (fletcher/chronos/timeliney/herodot); charts → follow the Charts table above (cetz-plot for very simple, lilaq for most, matplotlib/seaborn/plotnine for statistical or grammar-of-graphics) — generate SVG, embed; images → /image-search / /mindmap / 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.2.0 components:

Cross-referencing

Add <label> + @ref for recurring concepts across sections.

Accessibility (Typst 0.14+)

• alt: on all figures — image("path.png", alt: "description")
• Semantic heading hierarchy — don't skip levels
• table.header() for repeating headers — improves PDF/UA accessibility

Fallback Chains

Reference File Index

Offline API and Package Search

Look up the exact signature before writing an unfamiliar function or parameter; don't guess from memory. Index covers Typst 0.15.1 (the installed version).

python3 -I ${CLAUDE_SKILL_DIR}/scripts/search-api.py --name text            # exact: text, str.position, table.cell
python3 -I ${CLAUDE_SKILL_DIR}/scripts/search-api.py "rotate content angle" --top 5
python3 -I ${CLAUDE_SKILL_DIR}/scripts/search-packages.py "gantt chart" -n 5   # Typst Universe, filtered to installed compiler
python3 -I ${CLAUDE_SKILL_DIR}/scripts/search-packages.py --category cv -n 5

Scripts and data/ come from lucifer1004/claude-skill-typst (MIT). After a Typst upgrade, or to refresh the package index, copy skills/typst/data/{api,api-bm25,packages,packages-bm25}.json from that repo into ${CLAUDE_SKILL_DIR}/data/.

Text-level check without rendering: typst compile doc.typ /dev/stdout -f html --features html 2>/dev/null dumps headings, paragraphs and tables as HTML — cheaper than PNG when only content or structure needs checking.

Version Notes (0.13–0.15)

Removed in 0.15 (were deprecated, now gone): path element → use curve · pdf.embed → pdf.attach · image.decode / scoped decode fns → pass bytes directly · pattern type → tiling Other migrations: polylux:0.3.1 → polylux:0.4.0 or touying Breaking (0.15): file paths must use forward slashes only (no backslashes)

| touying 0.8.0 | 0.6+ | Presentation framework — #show: theme.with(...) API (not the old register() pattern) |

CLI Commands

typst compile document.typ                     # Compile to PDF
typst compile document.typ --root ..           # Set project root
typst compile document.typ out.pdf --pages 1-5 # Specific pages
typst watch document.typ                       # Watch and recompile
typst fonts                                    # List available fonts
typst eval doc.typ "heading.where(level: 1)"   # Introspect structure (supersedes `typst query`)
typst query doc.typ "heading.where(level: 1)"  # Older form — still works

--root flag: When a .typ file uses #import or #image() with paths outside its directory, set --root to the project root.

Batch compile: for f in *.typ; do typst compile "$f"; done

Conventions

• Source files in Source/, compiled PDFs in PDFs/
• Compile with --root .. when .typ references parent directory assets
• For multi-file projects: main.typ + #include sections + shared lib.typ
• File naming: lowercase-kebab-case (e.g., portfolio-theory-guide.typ)

Fonts

Variable fonts (supported since 0.15): Apple variable fonts and others now load directly — no need to install static .otf/.ttf versions. Select an axis with #set text(font: "New York", variations: (wght: 600)). The "Variable"/"Var"/"VF" suffix in a font's name is trimmed automatically, so reference the base family name. Note Apple's exposed family names differ from marketing names: San Francisco is SF NS (not "SF Pro"), and the serif is New York — run typst fonts to confirm. (On Typst ≤ 0.14 these failed with "variable fonts are not currently supported" — only relevant if pinned to an old binary.)

CJK fallback: #set text(font: ("New Computer Modern", "Songti SC"))

Documentation

• Official Reference
• Package Registry
• Tutorial
• Changelog