OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add ypares/agent-skills --skill typst-writer
Write correct and idiomatic Typst code for document typesetting. Use when creating or editing Typst (.typ) files, working with Typst markup, or answering questions about Typst syntax and features. Focuses on avoiding common syntax confusion (arrays vs content blocks, proper function definitions, state management).
npx skills add ypares/agent-skills --skill typst-writer
This skill provides guidance for writing correct Typst code, with emphasis on avoiding common syntax errors from conflating Typst with other languages.
Critical distinctions:
(item1, item2) - parentheses(key: value, key2: value2) - parentheses with colons[markup content] - square bracketsFor detailed syntax rules and common patterns, see references/syntax.md.
Typst Universe (the official package registry) doesn't have a programmatic API, but you can search for packages via GitHub:
gh search, or SearXNG's repos search (see the searxng-search Skill)Direct GitHub search examples:
fletcher for diagrams, drafting for margin notes, tablex for advanced tables)Use WebFetch when needed to retrieve current documentation for verification.
(), content with [])#let name(params) = { ... }context blocks when accessing state[] for arrays (use () instead)arr[0] (use arr.at(0))# prefix for code in markup context[] with code blocks {}#set, #show and custom functions should be used to avoid mixing content with layout directives, and more importantly to ensure a visual consistency throughout the document.
Typst functions often have sane default values for layout parameters. When unsure which value a parameter should have, just leave it unspecified.
Likewise, a lot of function parameters admit different types depending on how much control the user wants to have over the layout. For instance:
and
do the exact same thing. Prefer the first one if you don't want to have finer control over the size of one of the columns.
Use to-emphasize instead of #emph[to-emphasize].
For instance just write π instead of $pi$ or #sym.pi, and just write 🧮 instead of #emoji.abacus.
Besides compiling, the typst CLI command can also run queries against a Typst file with typst query, using Typst selectors,
and get the result as JSON.
For instance, typst query the_document.typ "heading.where(level: 1)" | jq ".[].body.text" will list all the level-1 section titles present in
the document. Sadly, it will not tell you their exact positions in the file, but Typst file are easy to grep.
See [https://typst.app/docs/reference/introspection/query/#command-line-queries](the online docs about query) for more info.
When needing specialized functionality:
#import "@preview/package:version"Popular packages:
drafting: annotations/comments for work-in-progress docsgentle-clues: callouts, tips, notes, admonitionsshowybox: general-purpose, customizable text boxes, with headers and footers. E.g. for definitions, theorems or highlighting important paragraphsitemize: nice layouts for item lists, enums, checklists, tree lists, etc.cetz: general diagrams/drawings, with explicit placing (coordinates) - basis of most Typst drawing librariesfletcher: graphs, flowcharts, automata, trees, etc. - automatic placingchronos: sequence diagramstimeliney: Gantt chartsherodot: linear timelineslilaq: data visualization and plotstablem: write tables in markdown-like table format - easy control over strokes, merged cells...cmarker: render Markdown (inlined or from separate file) as part as a Typst docpolylux: presentations, slidessuiji: random number generation in Typst codezebraw: code listings with line numbers, highlighted lines, inlined Typst comments/explanations etc.lovelace: algorithms/pseudo-codeconchord: lyrics with overlayed chord changes, guitar shapes and tabseqalc: math equations to actual, callable Typst functionsjlyfish: Typst as a Julia notebook: embed Julia code inside Typst to generate content, visualizations etc.pyrunner: embed and call non-I/O Python code inside TypstTypst Universe hosts many pre-built templates for reports, papers, CVs, presentations, and more. Templates provide complete document styling and structure.
#import "@preview/template-name:version": *#show: template-name.with(param: value, ...)Example:
Key differences from packages:
#show: to apply styling to the entire document, via one single "main" functionPopular templates: charged-ieee (IEEE papers), bubble (colorful reports), modern-cv (CVs)
Typst supports citations and bibliographies using BibTeX (.bib) or Hayagriva (.yml) format files.
See references/bibliography.md
ALWAYS include proper URLs in the bibliography file AS MUCH AS POSSIBLE.
ALWAYS include @ref-name citations in text WHEREVER A REF IS RELEVANT. A good bibliography is useless if not cited.
This shows an example for academic papers. Most reports you will have to write won't need to be that formal, but it's sort of the canonical example.
If you see "unknown font family" warnings, remove the font specification to use system defaults
Note: Font warnings don't prevent compilation; the document will use fallback fonts
If import fails with "package not found":
@preview/package:version syntaxCommon fixes:
#{ } or use proper syntax# prefix in markup context() for both, dictionaries need key: value, singleton arrays are (elem,)For large documents:
#include "file.typ" to split into multiple filestypst compile doc.typ output.pdf --pages 1-5typst compile --timings doc.typ// Define custom functions for document elements
#let important(body) = {
box(
fill: red.lighten(80%),
stroke: red + 1pt,
inset: 8pt,
body
)
}
// Use state for counters
#let example-counter = state("examples", 1)
#let example(body) = context {
let num = example-counter.get()
important[Example #num: #body]
example-counter.update(x => x + 1)
}
// Arrays for data
#let factions = (
(name: "Merchants", color: blue),
(name: "Artisans", color: green)
)
// Iterate and render
#for faction in factions [
- #text(fill: faction.color, faction.name)
]#table(
columns: 3,
...
)#table(
columns: (auto, auto, auto),
...
)#import "@preview/bubble:0.2.2": bubble
// Some templates (like bubble) don't use the standard metadata set by `#set document(...)` (for now?),
// so we factor it out:
#let doc-md = (
title: [My report],
author: "Claude",
date: datetime(year: 2025, month: 12, day: 8) // ALWAYS include explicit date in code (so we don't default to date of PDF build)
)
#set document(..doc-md)
#show: bubble.with(
..doc-md,
date: doc-md.date.display("[day]-[month]-[year]"), // some templates want a string here, not a `datetime` object, so we override date here
subtitle: "A detailed analysis",
affiliation: "Your Organization",
main-color: rgb("#FF6B35"),
color-words: ("important", "key", "critical"),
)
// Your content follows
= Introduction
...#set document(
title: "Document Title",
author: "Your Name",
date: auto,
)
#set page(
paper: "a4",
margin: (x: 2.5cm, y: 2.5cm),
numbering: "1",
)
#set text(size: 11pt)
#set par(justify: true)
#set heading(numbering: "1.")
// Title page
#align(center)[
#text(size: 24pt, weight: "bold")[Document Title]
#v(1cm)
#text(size: 14pt)[Your Name]
#v(0.5cm)
#datetime.today().display()
]
#pagebreak()
// Table of contents
#outline(title: "Table of Contents", indent: auto)
#pagebreak()
// Main content
= Introduction
Your introduction text...
= Methods
...
= Results
...
= Conclusion
...
#pagebreak()
// Bibliography
#bibliography("refs.bib", title: "References", style: "ieee")#import "@preview/charged-ieee:0.1.4": *
#show: ieee.with(
title: "Your Paper Title",
authors: (
(name: "Author One", email: "author1@example.com"),
(name: "Author Two", email: "author2@example.com"),
),
abstract: [
Your abstract text here...
],
index-terms: ("keyword1", "keyword2", "keyword3"),
bibliography: bibliography("refs.bib"), // the ieee template takes care of bibliography itself. That's not always the case
)
// Content starts immediately
= Introduction
Your introduction text...
= Methods
...
= Results
...
= Conclusion
...