latex-health-check
Skill150 starsChanged 13 days agoMITView on GitHub
Compile all LaTeX projects and report cross-project build consistency. Use when checking whether a collection of papers builds cleanly. Not for rendered visual inspection after a clean build; use $latex-polish.
In this repository89 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- beamer-deckSkill
- bib-coverageSkill
- bib-filterSkill
- bib-parseSkill
- brief-compliance-checkSkill
- camera-readySkill
- causal-designSkill
- checkpointSkill
- code-archaeologySkill
- compile-knowledgeSkill
- computational-experimentsSkill
- cross-language-checkSkill
- data-analysisSkill
- devils-advocateSkill
- docs-consistencySkill
- docxSkill
- experiment-designSkill
- grill-meSkill
- handoffSkill
- ideasSkill
- init-project-courseSkill
- init-project-lightSkill
- init-project-orchestrationSkill
- init-projectSkill
- insights-deckSkill
- interview-meSkill
- knowledge-lintSkill
- latex-diffSkill
- latex-polishSkill
- latex-postersSkill
- latex-scaffoldSkill
- latexSkill
- latex-templateSkill
- lean-checkSkill
- math-proofSkill
- mcp-builderSkill
- method-auditSkill
- multi-perspectiveSkill
- numerical-checkSkill
- pdfSkill
- pipeline-manifestSkill
- playwright-cliSkill
- postmortemSkill
- pre-commit-auditSkill
- pre-submission-reportSkill
- project-deckSkill
- project-safetySkill
- proof-readabilitySkill
- proofreadSkill
- python-envSkill
- quarto-deckSkill
- reorgSkill
- replication-auditSkill
- replication-packageSkill
- retarget-journalSkill
- review-clusterSkill
- review-responseSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 11 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
After major infrastructure changes (template updates, symlink reorganisation)
- Distinctive: line 33
Before submission season to verify all papers compile cleanly
- Distinctive: line 34
When the user says "check my LaTeX", "build health", "compile everything"
- Distinctive: line 48
Search locations in this order, checking that each exists:
- Very specific: line 67
If .latexmkrc is missing, copy the resolved canonical verbatim.
- Very specific: line 69
Create out/ directory if missing
- Very specific: line 76
Engine selection: Do NOT hardcode -pdf. The canonical recursively infers pdfLaTeX, XeLaTeX, or LuaLaTeX from the requested driver and local …
- Distinctive: line 101
After each fix, recompile.
- Distinctive: line 121
After all projects are compiled:
- Very specific: line 155
When writing the report file, emit an outputs manifest and run the shared verifier per _shared/verify-outputs.md:
- Very specific: line 157
Write manifest to <project>/.claude/state/outputs-manifest-<UTC-timestamp>.json listing every file written this invocation, paths relative …
- Distinctive: line 166
If the verifier exits non-zero, do not commit.
- Distinctive: line 172
Does NOT fix overfull/underfull boxes (requires human judgment on rewording)
- Distinctive: line 173
Does NOT modify paper content (only build configuration and missing packages)
- Distinctive: line 174
Does NOT push to git (compilation fixes should be reviewed first)
- Distinctive: line 175
Does NOT touch Overleaf-synced files without permission (per overleaf-separation rule)
≈ “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.
Files
LaTeX Health Check: Self-Healing Build Agent
Compile all LaTeX projects, auto-fix known errors iteratively, and verify cross-project consistency (symlinks, shared bibliographies, Overleaf separation).
When to Use
- Periodically (weekly) to catch build rot before it becomes debugging sessions
- After major infrastructure changes (template updates, symlink reorganisation)
- Before submission season to verify all papers compile cleanly
- When the user says "check my LaTeX", "build health", "compile everything"
Modes
| Mode | Trigger | What it does |
| Single project | Path argument | Compile + fix + verify one project |
| All projects | all argument | Discover and compile every LaTeX project |
| Quick | quick argument | Compile only, no fixes, report errors |
Phase 1: Discover LaTeX Projects
Find all directories containing a \documentclass in a .tex file:
Search locations in this order, checking that each exists:
- an explicit path argument;
- the current project;
- project roots declared by the current repository or client guidance;
~/Projects/as a portable fallback forallmode.
For each discovered project, record:
- Project name (directory name)
- Main .tex file path
- Whether it has a
.latexmkrc - Whether it has an
out/directory - Whether it's inside a
paper/subdirectory (Overleaf-linked)
Phase 2: Build Loop (per project)
For each project:
2a. Pre-flight
- Resolve the byte-identical
templates/build-config/.latexmkrcbundle from the installedlatexskill; stop if it is unavailable. - If
.latexmkrcis missing, copy the resolved canonical verbatim. If it exists, compare it byte-for-byte; report divergence and do not overwrite it without explicit migration approval. - Allow
.latexmkrc.localfor project-specific paths, dependencies,$bibtex_use,$clean_ext, or@default_files, but flag any$pdf_modeassignment. - Create
out/directory if missing
2b. Compile
cd <project-dir> && latexmk -interaction=nonstopmode <main.tex> 2>&1Engine selection: Do NOT hardcode -pdf. The canonical recursively infers pdfLaTeX, XeLaTeX, or LuaLaTeX from the requested driver and local dependencies. Passing -pdf overrides this and breaks Unicode-engine projects. Let latexmk read .latexmkrc.
2c. Parse log
Extract from out/*.log:
- Error count (lines starting with
!) - LaTeX/package warning count (
Warning-tagged lines) - Overfull/underfull box count — use the detection recipes in
../shared/overfull-boxes.md, NOT aWarninggrep (box lines carry noWarningtoken) - Undefined citation count
- Missing package count
2d. Auto-fix (up to 3 iterations)
For each error, apply the known fix from the database:
| Error pattern | Fix |
Missing package X | Add \usepackage{X} — but NEVER try xltabular or ltablex (use longtable instead) |
Undefined citation key | Check .bib file exists and is referenced; check for typos via edit distance |
| Overfull/underfull box | Flag location + width per ../shared/overfull-boxes.md — do NOT auto-fix prose (only safe auto-fix is adding microtype when absent) |
tcolorbox = or , in title | Wrap title in braces: title={...} |
| Font encoding warning | Add \usepackage[T1]{fontenc} if missing |
Missing \begin{document} | Check for corrupted preamble |
Broken symlink in \input{} or \includegraphics{} | Find the target and report |
| Build artifacts in source dir | Flag — offer to move to out/ |
After each fix, recompile. Max 3 iterations per project.
Why 3 iterations (not 5)? latex runs up to 5 iterations on a single project with deep error analysis. This skill trades depth for breadth — 3 iterations is enough to catch the common fleet-wide issues (missing packages, broken symlinks, stale cache) without spending excessive time on any one project. If a project still has errors after 3 iterations, mark it as ERROR and recommend running latex on it directly for deeper diagnosis.
2e. Record result
{
"project": "project-name",
"path": "/full/path",
"status": "OK | FIXED | ERROR",
"errors_initial": 3,
"errors_final": 0,
"fixes_applied": ["added fontenc", "fixed tcolorbox title"],
"warnings": 2,
"undefined_citations": 0
}Phase 3: Cross-Project Checks
After all projects are compiled:
- Symlink integrity — verify all symlinks in skills/, agents/, rules/, hooks/ resolve
- Shared .bib consistency — if multiple projects reference the same .bib file (e.g., via symlink), verify they're all pointing to the same version
- Overleaf separation — scan every
paper/directory for forbidden file types (.py, .R, .csv, .ipynb, etc.) - Template consistency — check if projects using the working paper template have diverged from the current template version
Phase 4: Report
Generate a summary report:
LaTeX Health Check — YYYY-MM-DD
Projects scanned: N
Compiled OK: N (list)
Fixed and OK: N (list + fixes applied)
Still broken: N (list + remaining errors)
Skipped: N (list + reason)
Cross-project issues:
Broken symlinks: N
Overleaf violations: N
Template drift: N
Warnings (not auto-fixed):
Overfull hboxes: N across M projects
Underfull hboxes: N across M projectsPrint to stdout. If --save flag or 10+ projects scanned, also write to log/latex-health/YYYY-MM-DD.md.
4.1 Output verification (before commit)
When writing the report file, emit an outputs manifest and run the shared verifier per _shared/verify-outputs.md:
- Write manifest to
<project>/.claude/state/outputs-manifest-<UTC-timestamp>.jsonlisting every file written this invocation, paths relative to the project root. Run:
uv run python "<skills-root>/_shared/verify_outputs.py" \ --manifest "$MANIFEST" \ --project-root "$PROJECT_ROOT"- If the verifier exits non-zero, do not commit. Surface the missing-files list and stop.
Closes the "hallucinated outputs" failure class (commit b2cff75, 2026-04-18). Skip this sub-step entirely if --save was not passed and no log file was written.
What This Skill Does NOT Do
- Does NOT fix overfull/underfull boxes (requires human judgment on rewording)
- Does NOT modify paper content (only build configuration and missing packages)
- Does NOT push to git (compilation fixes should be reviewed first)
- Does NOT touch Overleaf-synced files without permission (per overleaf-separation rule)
Cross-References
| Skill | Relationship |
latex | Single-project deep fix (5 iterations). This skill runs a lighter version (3 iterations) at fleet scale. For ERROR projects, recommend running latex directly. |
latex | Canonical .latexmkrc resolution, migration rules, and single-project deep compilation. |
audit-project-research | Checks project structure (directories, files). This skill checks build health. |
bib-validate | Validates bibliography entries. This skill checks if citations compile. |
latex-template | Checks preamble alignment with the working paper template. Complementary: run after health-check to ensure preamble consistency. |
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
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.

