/compile-latex

name: compile-latex
description: Use when compiling a LaTeX paper, debugging LaTeX errors, building a paper PDF, or when a .tex file fails to produce output. Handles engine detection (xelatex vs pdflatex), bibliography systems (biber vs bibtex), and multi-pass compilation.

Compile LaTeX

Overview

This skill compiles LaTeX documents correctly with the right engine and bibliography system, handles multi-pass compilation, and parses errors to suggest fixes. It ships with a wrapper script (`scripts/compile.sh`) that detects everything automatically and can be invoked directly.

When to Use

• Compiling any `.tex` file
• "The paper won't compile"
• LaTeX error messages appearing in output
• Generating the final PDF for submission
• CI or automated builds of a paper
• Verifying that cross-references and citations resolve correctly

Mandatory Steps

1. **Detect the engine from the preamble.** Look for `\usepackage{fontspec}`. If present, use `xelatex`. Otherwise use `pdflatex`. The wrapper script does this automatically.

2. **Detect the bibliography system.** `\usepackage{biblatex}` in the preamble implies biber. `\bibliography{...}` at the end of the document implies bibtex. Neither implies no bibliography pass.

3. **Prefer `latexmk` if available.** It handles multi-pass logic automatically and is more robust than running passes manually.

4. **If `latexmk` is unavailable, run the manual sequence:** engine → bib (if applicable) → engine → engine.

5. **On error, parse the log file** (`<base>.log`). Extract lines starting with `!`, report the line number and file, and suggest a likely fix from the error table below.

6. **Verify the PDF was produced** after successful compilation and that it is non-empty.

Using the Wrapper Script

Invoke the compile script directly:

./skills/compile-latex/scripts/compile.sh paper/paper.tex

The script detects engine and bibliography system, runs `latexmk` if available, falls back to manual multi-pass otherwise, and exits non-zero on failure. All detection and pass logic is handled internally — no flags needed beyond the path to the `.tex` file.

Common Errors and Fixes

| Error | Cause | Fix | |-------|-------|-----| | `Undefined control sequence \foo` | Missing package | Add `\usepackage{pkg}` providing `\foo` | | `File 'x.sty' not found` | Missing package | Install TeX package (`tlmgr install x`) | | `Citation 'X' undefined` | Bib pass not run | Run biber or bibtex, then re-run engine | | `Missing \begin{document}` | Preamble typo | Check brace balance in preamble | | `Package fontspec Error` | Used pdflatex instead of xelatex | Switch engine | | `Overfull \hbox` | Typographical warning | Usually safe to ignore, or rephrase the offending line | | `LaTeX Error: File 'x.tex' not found` | Missing `\input{}` target | Verify path relative to the main file |

Anti-Patterns

• Running `pdflatex` on a document that needs `xelatex`
• Ignoring `Citation undefined` warnings — they mean the bibliography is broken
• Single-pass compilation when cross-references exist (`\ref`, `\cite`, `\label`)
• Committing `.aux`, `.log`, `.bbl`, `.out`, `.toc`, `.fls`, `.fdb_latexmk` auxiliary files to git
• Ignoring errors and just "running it again" until it compiles

Verification Before Completion

• [ ] Engine detected matches preamble requirements
• [ ] Bibliography system correctly identified
• [ ] Multi-pass executed when needed (engine → bib → engine → engine)
• [ ] Exit code 0 from the compile step
• [ ] `<base>.pdf` exists and is non-empty
• [ ] No `Undefined` warnings in the final log
• [ ] Auxiliary files not staged in git