playbooks

home / skills / terrylica / cc-skills / latex-setup

latex-setup skill

/plugins/doc-tools/skills/latex-setup

This skill helps you set up a complete LaTeX environment on macOS, including MacTeX, Skim with SyncTeX, and verification.

npx playbooks add skill terrylica/cc-skills --skill latex-setup

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
3.6 KB
---
name: latex-setup
description: LaTeX environment setup on macOS. TRIGGERS - install LaTeX, MacTeX, Skim viewer, SyncTeX setup.
allowed-tools: Read, Edit, Bash
---

# LaTeX Environment Setup

## When to Use This Skill

Use this skill when:

- Installing LaTeX on a new machine
- Setting up MacTeX distribution
- Configuring Skim PDF viewer with SyncTeX
- Verifying LaTeX installation
- Troubleshooting missing packages

## Quick Reference

## Recommended Stack

| Component        | Purpose                                 | Status          |
| ---------------- | --------------------------------------- | --------------- |
| **MacTeX 2025**  | Full LaTeX distribution (TeX Live 2025) | ✅ Recommended  |
| **Skim 1.7.11**  | PDF viewer with SyncTeX support         | ✅ macOS only   |
| **TeXShop 5.57** | Integrated LaTeX IDE (optional)         | ✅ Native macOS |

---

## Quick Start

### Install MacTeX

```bash
brew install --cask mactex
# Size: ~4.5 GB (includes everything)
```

### Verify Installation

```bash
tex --version
# Expected: TeX 3.141592653 (TeX Live 2025)

pdflatex --version
latexmk --version
```

### Test Compilation

```bash
echo '\documentclass{article}\begin{document}Hello World!\end{document}' > test.tex
pdflatex test.tex
ls test.pdf  # Verify PDF created
```

---

## Post-Installation Checklist

- [ ] Verify `tex --version` shows TeX Live 2025
- [ ] Verify `latexmk --version` shows 4.86a+
- [ ] Verify `pdflatex test.tex` creates PDF
- [ ] Install Skim if using mactex-no-gui
- [ ] Test SyncTeX: compile with `-synctex=1` flag
- [ ] Configure Skim preferences for editor integration
- [ ] Add `/Library/TeX/texbin` to PATH if needed
- [ ] Test package installation: `sudo tlmgr install <package>`

---

## Reference Documentation

For detailed information, see:

- [Installation](./references/installation.md) - Full MacTeX vs lightweight options, Skim installation
- [Verification](./references/verification.md) - Check installation, verify PATH, test compilation
- [Package Management](./references/package-management.md) - Check, install, search for packages with tlmgr
- [Skim Configuration](./references/skim-configuration.md) - Enable SyncTeX, configure preferences for editor integration
- [Troubleshooting](./references/troubleshooting.md) - PATH issues, tlmgr problems, permissions

**See Also**:

- Build Workflows: Use `latex/build` skill for latexmk automation
- Table Creation: Use `latex/tables` skill for tabularray usage

---

## Troubleshooting

| Issue                     | Cause                         | Solution                                           |
| ------------------------- | ----------------------------- | -------------------------------------------------- |
| tex command not found     | PATH not configured           | Add `/Library/TeX/texbin` to PATH in shell profile |
| Permission denied (tlmgr) | Need sudo for system packages | Use `sudo tlmgr install <package>`                 |
| Package not found         | Missing from TeX Live         | Run `tlmgr search <package>` to find correct name  |
| Skim not showing PDF      | SyncTeX not enabled           | Compile with `-synctex=1` flag                     |
| Outdated TeX Live         | Old MacTeX version            | Run `sudo tlmgr update --self --all`               |
| Compilation hangs         | Infinite loop in document     | Check for circular includes or missing \end{}      |
| Missing font error        | Font not in TeX distribution  | Install with `tlmgr install <font-package>`        |
| Disk space error          | Full TeX Live too large       | Consider BasicTeX (smaller) if space limited       |

Overview

This skill automates setting up a LaTeX environment on macOS, including installing MacTeX, configuring Skim for SyncTeX, and verifying common tools like pdflatex and latexmk. It guides PATH setup, post-install checks, and basic troubleshooting so you can compile documents reliably. Designed for macOS users who need a ready-to-use LaTeX workflow.

How this skill works

The skill installs MacTeX (or advises on lightweight alternatives), ensures /Library/TeX/texbin is available in PATH, and verifies core binaries (tex, pdflatex, latexmk). It configures Skim as a SyncTeX-capable PDF viewer, tests a sample compilation, and provides tlmgr commands to manage missing packages and updates. It also includes common troubleshooting steps for permissions, PATH, and package issues.

When to use it

  • Setting up LaTeX on a new macOS machine
  • Installing or upgrading MacTeX (TeX Live)
  • Configuring Skim for forward/backward search with SyncTeX
  • Validating LaTeX toolchain (pdflatex, latexmk, tex)
  • Troubleshooting missing packages or PATH issues

Best practices

  • Install full MacTeX for maximum package coverage; use BasicTeX only if disk space is constrained
  • Add /Library/TeX/texbin to your shell profile (e.g., .zshrc) to avoid "command not found" errors
  • Compile with -synctex=1 when using Skim to enable editor-PDF syncing
  • Use sudo tlmgr install <package> for system-wide package installs and sudo tlmgr update --self --all to keep TeX Live current
  • Test a minimal document (Hello World) and verify test.pdf before opening complex projects

Example use cases

  • Provision a new macOS laptop with a complete LaTeX toolchain for academic writing
  • Set up Skim+SyncTeX to enable editor ↔ PDF navigation for fast iterative editing
  • Verify and fix PATH or permission issues that prevent pdflatex or latexmk from running
  • Install missing LaTeX packages on CI or a developer workstation using tlmgr
  • Switch between full MacTeX and a lightweight BasicTeX workflow when disk space changes

FAQ

How do I add TeX binaries to my PATH?

Add export PATH="/Library/TeX/texbin:$PATH" to your shell profile (e.g., ~/.zshrc) and restart the shell or run source ~/.zshrc.

Skim doesn't sync with my editor — what's next?

Recompile with the -synctex=1 flag, enable SyncTeX in Skim preferences, and configure your editor's PDF-forward/backward command to use Skim's sync actions.