Skill

Review

Audit score 70

typst

lucifer1004/claude-skill-typst

Create and develop Typst documents, packages, and templates with CLI tools and comprehensive guides.

What is typst?

Typst is a modern markup language for document creation. Use this skill when working with .typ files, creating document templates, developing Typst packages, or converting from Markdown/LaTeX. It includes compilation, styling, tables, academic writing, and package development support.

Compile .typ files to PDF, PNG, or HTML output
Watch files for automatic recompilation on changes
Query document structure and extract metadata using introspection
Create reusable templates and publishable packages
Style pages, headings, tables, and academic content
Search embedded Typst Universe package and API indexes

How to install typst

npx skills add https://github.com/lucifer1004/claude-skill-typst --skill typst

Prerequisites

typst CLI 0.15 or later (install from https://typst.app or via package manager)
Python 3.10+ (optional, for package search and validation scripts)
pdftotext (optional, for text-level output verification)

Claude Code

Cursor

Windsurf

Cline

How to use typst

1.Install typst CLI from https://typst.app or your package manager
2.Create or open a .typ file with Typst markup
3.Use `typst compile document.typ` to generate PDF output, or `typst watch document.typ` for live recompilation
4.Reference the provided guides (basics.md, styling.md, tables.md, academic.md) for syntax and features
5.For packages, follow package.md to structure and publish reusable modules
6.Use `python3 scripts/search-packages.py` to find community packages by keyword or category

Use cases

Good for

Creating professional reports, memos, and multi-section documents with custom styling
Writing academic papers with citations, theorems, and mathematical equations
Building data-heavy documents with tables, CSV/JSON integration, and dynamic content
Developing reusable document templates for recurring document series
Converting existing Markdown or LaTeX documents to Typst format

Who it's for

Document authors and technical writers
Academic researchers and students
Package developers and template creators
Teams standardizing on Typst for document generation

typst FAQ

How do I convert a Markdown or LaTeX document to Typst?

See conversion.md in the skill documentation for syntax mapping and migration strategies. The skill includes examples and common patterns for converting from both formats.

What's the difference between set/show rules and how do I use them?

Set rules apply default styling globally, while show rules customize how specific elements render. Both must be placed before the content they target to take effect.

How do I verify that my Typst document compiled correctly?

Use HTML export for text content and structure, PNG export for visual layout and fonts, or pdftotext as a fallback. See debug.md for detailed verification methods.

Can I use external data (CSV, JSON) in my Typst documents?

Yes. Typst supports loading and processing structured data. See tables.md and types.md for examples of working with arrays and data types.

How do I create a reusable template for multiple documents?

Define a template function in a separate .typ file and import it. See template.md for the full pattern, or copy template-report.typ from examples as a starter.

Full instructions (SKILL.md)

Source of truth, from lucifer1004/claude-skill-typst.

name: typst description: 'Typst document creation and package development. Use when: (1) Working with .typ files, (2) User mentions typst, typst.toml, or typst-cli, (3) Creating or using Typst packages, (4) Developing document templates, (5) Converting Markdown/LaTeX to Typst'

Typst

This skill targets Typst 0.15+. For Typst 0.14.2, use the typst-0.14.2 repository tag for the previous skill snapshot.

Compilation

typst compile document.typ              # compile once → PDF
typst compile document.typ output.pdf   # explicit output path
typst compile document.typ -f png       # export as PNG image
typst compile src/main.typ --root .     # set project root for /path imports
typst watch document.typ                # recompile on change
typst eval --in document.typ 'query(heading).len()'  # Typst 0.15+ introspection

For command options beyond this quick reference, see cli.md.

Agent verification — choose by what you need to check (see debug.md for details):

Method	Command	Best for
HTML export	`typst compile doc.typ /dev/stdout -f html --features html 2>/dev/null`	Text content, structure, headings, tables
PNG export	`typst compile doc.typ page-{p}.png -f png`	Visual layout, alignment, spacing, fonts
pdftotext	`typst compile doc.typ && pdftotext doc.pdf -`	Fallback for page-specific content

Minimal Document

#set page(paper: "a4", margin: 2cm)
#set text(size: 11pt)

= Title

Content goes here.

Writing Documents

Starting a new document? Copy the closest recipe from Examples below — it's faster than starting blank and each row names the docs to read next.

When you need to...	Read
Learn syntax, imports, functions, control flow	basics.md
Learn data types, operators, string/array methods	types.md
Style pages, headings, figures, layout	styling.md
Tables, grids, cell spans, borders, data tables	tables.md
Academic papers, bibliography, theorems, equations	academic.md
Convert from Markdown or LaTeX	conversion.md
Upgrade older Typst code, 0.15 breaking changes	migration.md
Use Typst CLI commands and build options	cli.md
Extract data from documents, multi-pass builds	query.md

Developing Packages and Templates

When you need to...	Read
State, counters, in-document `query()`, XML	advanced.md
CLI introspection, metadata export, multi-pass	query.md
Create a reusable template function	template.md
Create or publish a package	package.md
Verify output (HTML/PNG/pdftotext, repr)	debug.md
Profile performance (--timings, hotspots)	perf.md

basics.md and types.md are also the foundation for developers.

Finding Packages

Search the embedded index of Typst Universe packages (updated weekly):

python3 scripts/search-packages.py "what you need"
python3 scripts/search-packages.py "chart" --category visualization
python3 scripts/search-packages.py --category cv --top 5
python3 scripts/search-packages.py --list-categories

Common Errors

Error	Cause	Fix
"unknown variable"	Undefined identifier	Check spelling, ensure `#let` before use
"expected X, found Y"	Type mismatch	Check function signature in docs
"file not found"	Bad import path	Paths resolve relative to current file
"unknown font"	Font not installed	Use system fonts or web-safe alternatives
"maximum function call depth exceeded"	Deep recursion	Use iteration instead
"can only be used when context is known"	Missing `context` wrapper	Wrap in `context { ... }`
"unexpected argument"	`=` instead of `:` for args	Named args use `:` syntax: `func(name: value)`
"variables from outside are read-only"	Mutating captured variable	Use loop accumulation or `state()` — see advanced.md
"expected content, found string" (or vice versa)	Content/string type mismatch	Use `[#str-var]` to embed string in content
set/show rule has no effect	Rule placed after content	Place set/show rules before the content they target

Examples

Copy the closest starter, adjust, compile. For CVs, letters, or slides, search packages: python3 scripts/search-packages.py --category cv (or letter, presentation).

Example	Start here when you want...	Next read
basic-document.typ	A short note or memo	basics.md, styling.md
styled-document.typ	A multi-section report with page styling	styling.md, tables.md
template-report.typ	A reusable template for a series	template.md
tables-showcase.typ	A data-heavy doc (tables, CSV/JSON)	tables.md, types.md
academic-paper.typ	A paper with citations, theorems, math	academic.md
query-export.typ	Metadata export or multi-pass builds	query.md
package-example/	A publishable package	package.md

Dependencies

typst CLI 0.15+ recommended: Install from https://typst.app or via package manager
- macOS: brew install typst
- Linux: cargo install typst-cli
- Windows: winget install typst
pdftotext (optional): For text-level output verification
Python 3.10+ (optional): For package search and validation scripts
jq (optional): For parsing JSON output from typst eval in shell scripts

API Reference Search

Search the embedded index of Typst API functions, methods, and constructors:

python3 scripts/search-api.py "image width fit"
python3 scripts/search-api.py "color lighten" --kind method
python3 scripts/search-api.py --name str.position -v
python3 scripts/search-api.py "rightarrow" --kind symbol   # LaTeX names work
python3 scripts/search-api.py --list-categories

Ecosystem Tools

Ecosystem tools: tinymist (LSP/editor), typstyle (formatter), typst-package-check (package validator), tytanic (visual test runner). For package tooling details, see package.md.