agentleFS
ChanMeng666ChanMeng666/typst-claude-skill/skills/chanmeng-typst/SKILL.md

chanmeng-typst

Skill14 starsChanged 17 days agoMITView on GitHub

Generate professional PDF documents using the Typst typesetting system. Use when the user asks to create a PDF, write a document, generate a report, typeset a paper, build a presentation, or make a resume / CV / cover letter / letter / invoice / thesis / handout / poster — even when they do not say "Typst" explicitly. Especially trigger when the user mentions one-page CV, two-column resume, academic paper with bibliography, an ATS-friendly resume for a job portal, or any CJK (Chinese / Japanese / Korean) document, including requests such as 简历, 学术论文, 报告, 发票 or 幻灯片. Also use when editing an existing .typ file, or when a Typst PDF has the wrong page count, spacing, fonts or extracted text.

  • Installs packages
  • In this repositoryOne other file it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 4 are distinctive, and 12 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Ask, in this order, before writing any .typ:

    line 25
  2. Very specific:

    Read directly by a person → references/typst-templates.md § 4a Simple or § 4b Typographic Two-Column

    line 30
  3. Distinctive:

    If yes, always layer the CJK font setup from § CJK Document on top of the chosen template — missing this is the #1 source of "tofu" (□) …

    line 39
  4. Very specific:

    If yes, generate a .typ that calls #let data = json("path.json") (or csv(...)) and loops over it — do not hardcode values from the data …

    line 42
  5. Very specific:

    If yes, read references/typst-pitfalls.md before tuning layout.

    line 45
  6. Very specific:

    If yes, set it up as a project with shared tokens and components: references/typst-design-patterns.md § Long-Lived Document Projects.

    line 48
  7. Distinctive:

    Use only facts the user gave you in resumes, letters and reports.

    line 50
  8. Very specific:

    If typst is not installed:

    line 84
  9. Very specific:

    Use the Decision Tree above to pick a template from references/typst-templates.md

    line 94
  10. Very specific:

    Write the .typ file to the user's desired location

    line 97
  11. Very specific:

    Check the exit code, because a failed compile leaves any previous PDF in place.

    line 109
  12. Distinctive:

    Do this before telling the user the document is done.

    line 113
  13. Very specific:

    Check it: Run the bundled checker. It needs poppler, and reports page count, font embedding, text extraction, lost hyphens and bare ~:

    line 121
  14. Very specific:

    Read compilation errors, consult the Recovery Recipes below, fix the .typ file, recompile, and repeat Step 4.

    line 131
  15. Very specific:

    When typst compile fails, paste stderr's first line into this lookup before guessing:

    line 159
  16. Distinctive:

    Read these files on demand (not all at once):

    line 182

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Typst Document Generation Skill

You are an expert Typst typesetter. Generate professional PDF, PNG, SVG, or HTML documents using Typst. This skill is written for Typst 0.14+ and tested on 0.15.1.

A clean compile is where the work starts to be checked, not where it ends: many layout and text bugs produce no error or warning. Step 4 of the Workflow is what catches them.

Decision Tree — pick a template before writing

Ask, in this order, before writing any .typ:

  1. What is the artefact?
    • Resume / CV → ask where it is going if the user has not said.
      • Uploaded to a job portal or applicant tracking system → references/ats-resume.md and examples/resume-ats.typ
      • Read directly by a person → references/typst-templates.md § 4a Simple or § 4b Typographic Two-Column
    • Cover letter / formal letter → § Letter
    • Academic / research paper → § Academic Paper (two-column, abstract, bibliography)
    • Internal report / whitepaper → § Technical Report
    • Slide deck → § Presentation
    • Bill / receipt → § Invoice
    • Anything else → § General Document
  2. Is the language CJK (Chinese / Japanese / Korean)? If yes, always layer the CJK font setup from § CJK Document on top of the chosen template — missing this is the #1 source of "tofu" (□) bugs. Then read references/typst-pitfalls.md § CJK text, because system fonts without bold and source line breaks cause problems that no error reports.
  3. Does the user have a JSON / CSV data source? If yes, generate a .typ that calls #let data = json("path.json") (or csv(...)) and loops over it — do not hardcode values from the data into the template.
  4. Is it dense, page-limited, or read by a machine? If yes, read references/typst-pitfalls.md before tuning layout.
  5. Will it be maintained or reused? If yes, set it up as a project with shared tokens and components: references/typst-design-patterns.md § Long-Lived Document Projects.

Use only facts the user gave you in resumes, letters and reports. Where something is missing, ask or leave a visible placeholder, because an invented metric or date is hard to spot once typeset.

Quick Reference

TaskCode / Command
Compile to PDFtypst compile doc.typ
Compile to PNGtypst compile doc.typ --format png --ppi 300
Compile & opentypst compile doc.typ --open
Set page#set page(paper: "a4", margin: 2.5cm)
Set font#set text(font: "Libertinus Serif", size: 11pt)
CJK font#set text(lang: "zh", font: ("Source Han Serif SC", "Noto Serif CJK SC", "SimSun"))
Heading= Title / == Subtitle / === Sub-subtitle
Math$ integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $
Import package#import "@preview/cetz:0.5.3": canvas, draw
Load data#let data = json("data.json") or csv("data.csv")
Evaluate expressiontypst eval "1 + 2"
Conditional format#context if target() == "html" { ... } else { ... }
List fontstypst fonts

Workflow

1. Verify the environment

typst --version

For a deeper check (CJK fonts available, write permissions, version ≥ 0.14), run the bundled script from this skill's directory:

bash scripts/verify-typst.sh

If typst is not installed:

  • Windows: winget install --id Typst.Typst
  • macOS: brew install typst
  • Any platform with Rust: cargo install --locked typst-cli

To update an existing install, use winget upgrade --id Typst.Typst, brew upgrade typst, or typst update for a standalone binary.

2. Create the .typ source file

  • Use the Decision Tree above to pick a template from references/typst-templates.md
  • Consult references/typst-language-reference.md for syntax
  • For advanced layouts, see references/typst-design-patterns.md
  • Write the .typ file to the user's desired location

3. Compile to output

typst compile document.typ                          # PDF (default)
typst compile document.typ --format png --ppi 300   # High-res PNG
typst compile document.typ output.svg               # SVG

See references/typst-cli-reference.md for all options.

Check the exit code, because a failed compile leaves any previous PDF in place. Treat unknown font family as a problem to fix: the fallback font changes line breaks and page count.

4. Verify the output

Do this before telling the user the document is done.

Look at it. Render the pages and read each image, since spacing, overflow, orphaned lines and wrong icon colours only show on a render:

typst compile document.typ "page-{p}.png" --ppi 150

Check it. Run the bundled checker. It needs poppler, and reports page count, font embedding, text extraction, lost hyphens and bare ~:

python scripts/check-pdf.py document.pdf --source document.typ --pages 2

Pass --pages N when the user gave a page limit, --ats for a job-portal resume, and --require "text" ... for facts that must survive extraction, such as names, dates and contact details. If poppler is missing and cannot be installed, say which checks were skipped.

5. Iterate

Read compilation errors, consult the Recovery Recipes below, fix the .typ file, recompile, and repeat Step 4. Re-check the page count after every layout change.

Gotchas / Common Mistakes

MistakeFix
CJK glyphs missing or tofu (□)Set lang AND provide a CJK font fallback chain: #set text(lang: "zh", font: ("Source Han Serif SC", "SimSun"))
Chinese *bold* looks like body textSimSun, SimHei and KaiTi have no bold face. Map strong to a font that does
Stray space between Chinese charactersA source line break becomes a space. Keep each paragraph on one line
First Chinese paragraph is not indentedUse first-line-indent: (amount: 2em, all: true)
Windows path errors in #image() / #include()Use forward slashes: image("images/photo.jpg"). Backslashes are an error since 0.15
~85% loses its tilde~ is a non-breaking space in markup. Write \~85%
Email address breaks the compile@ starts a reference in markup. Write name\@example.com
Gap between blocks ignores your editBlock margins collapse to the larger one, not the sum. See references/typst-pitfalls.md
A title sits closer to the next line after adding v()v() replaces the leading between two lines. Give each line its own block
SVG icon is black despite text(fill: ...)image() does not inherit currentColor. Write the colour into the SVG
web-vitals extracts as webvitalsBox hyphenated compounds: references/typst-pitfalls.md § Line-end hyphens vanish on extraction
Font not foundRun typst fonts to list available fonts; bundle custom fonts with --font-path ./fonts
context errors in Typst v0.14+Accessing counter(), state(), or text.fill requires wrapping in a context block
show rules leaking to other sectionsWrap scoped show rules in a block { ... } to limit their effect
Multi-page PNG/SVG produces single fileUse {p} placeholder in output: typst compile doc.typ "page-{p}.png"
Package download failsFirst compile with a new @preview package requires internet; check --package-cache-path
Paragraph spacing looks wrongSet #set par(justify: true, leading: 0.8em) explicitly; defaults vary
Math script styles not workingUse scr(), cal(), frak(), bb() — not LaTeX \mathscr, \mathcal
typst compile works locally but the PDF is blank from a Vercel / serverless functionThe Vercel runtime does not include the Typst CLI. Either ship a static prebuilt binary in the deploy bundle (vercel.json includeFiles) or call a separate compile service (Fly.io / Railway). See references/typst-design-patterns.md § Serverless.

Recovery Recipes

When typst compile fails, paste stderr's first line into this lookup before guessing:

stderr starts withMost likely causeFirst thing to try
error: file not found (...) image(...)wrong relative pathcd to the .typ file's directory; use forward slashes
error: path must not contain a backslashWindows-style pathuse forward slashes
error: path ... would escape the project rootfile sits outside --rootpass a higher --root, or move the file inside it
error: label `<...>` does not exist in the documentbare @ in markup, often an email addressescape it as \@, or define the label
error: expected integer, found string on .at("key")() is an empty array, not a dictionaryuse (:) as the default value
error: unknown variable: <name>typo or missing #let <name>grep the file for the symbol; check that imports use the right alias
error: failed to load packageoffline / firewall blocks @previewretry with internet; or vendor the package locally and import by path
error: cannot apply fill to ... (context error)v0.14 introspection requires contextwrap the access in context { ... }
error: type mismatch: expected ..., found ...passed wrong shape from JSON to a functionlog the data with #repr(data) once, inspect, then narrow the access

When NOT to use

  • Existing LaTeX projects — use LaTeX directly for .tex files
  • Simple plain-text documents — Markdown is simpler
  • Spreadsheet / tabular data output — use CSV or Excel tools
  • Interactive web pages — use HTML/CSS directly (Typst HTML export available via --features html but limited)

Reference Documentation

Read these files on demand (not all at once):

ReferencePathContent
CLI Referencereferences/typst-cli-reference.mdAll CLI commands, options, environment variables
Language Referencereferences/typst-language-reference.mdComplete syntax, functions, and features
Templatesreferences/typst-templates.mdReady-to-use templates (general, CJK, academic, resume, letter, report, slides, invoice)
Design Patternsreferences/typst-design-patterns.mdAdvanced patterns (project layout, themes, components, PDF capabilities)
Pitfallsreferences/typst-pitfalls.mdBugs the compiler does not report: spacing, lost text, icons, fonts, page budgets
ATS Resumesreferences/ats-resume.mdRules, skeleton and verification for resumes read by machines

Output Formats

FormatExtensionNotes
PDF.pdfDefault. Supports PDF/A standards and tagged PDF.
PNG.pngOne image per page. Use --ppi for resolution (default 144).
SVG.svgOne file per page. Vector graphics.
HTML.htmlExperimental. Use --features html.
BundlefolderExperimental. Several files from one source: --features bundle --format bundle.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.