agentleFS
flonatflonat/flonat-research/skills/latex-health-check/SKILL.md

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.

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
  1. Distinctive:

    After major infrastructure changes (template updates, symlink reorganisation)

    line 32
  2. Distinctive:

    Before submission season to verify all papers compile cleanly

    line 33
  3. Distinctive:

    When the user says "check my LaTeX", "build health", "compile everything"

    line 34
  4. Distinctive:

    Search locations in this order, checking that each exists:

    line 48
  5. Very specific:

    If .latexmkrc is missing, copy the resolved canonical verbatim.

    line 67
  6. Very specific:

    Create out/ directory if missing

    line 69
  7. Very specific:

    Engine selection: Do NOT hardcode -pdf. The canonical recursively infers pdfLaTeX, XeLaTeX, or LuaLaTeX from the requested driver and local …

    line 76
  8. Distinctive:

    After each fix, recompile.

    line 101
  9. Distinctive:

    After all projects are compiled:

    line 121
  10. Very specific:

    When writing the report file, emit an outputs manifest and run the shared verifier per _shared/verify-outputs.md:

    line 155
  11. Very specific:

    Write manifest to <project>/.claude/state/outputs-manifest-<UTC-timestamp>.json listing every file written this invocation, paths relative …

    line 157
  12. Distinctive:

    If the verifier exits non-zero, do not commit.

    line 166
  13. Distinctive:

    Does NOT fix overfull/underfull boxes (requires human judgment on rewording)

    line 172
  14. Distinctive:

    Does NOT modify paper content (only build configuration and missing packages)

    line 173
  15. Distinctive:

    Does NOT push to git (compilation fixes should be reviewed first)

    line 174
  16. Distinctive:

    Does NOT touch Overleaf-synced files without permission (per overleaf-separation rule)

    line 175

≈ “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

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

ModeTriggerWhat it does
Single projectPath argumentCompile + fix + verify one project
All projectsall argumentDiscover and compile every LaTeX project
Quickquick argumentCompile 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 for all mode.

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/.latexmkrc bundle from the installed latex skill; stop if it is unavailable.
  • If .latexmkrc is 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.local for project-specific paths, dependencies, $bibtex_use, $clean_ext, or @default_files, but flag any $pdf_mode assignment.
  • Create out/ directory if missing

2b. Compile

cd <project-dir> && latexmk -interaction=nonstopmode <main.tex> 2>&1

Engine 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 a Warning grep (box lines carry no Warning token)
  • Undefined citation count
  • Missing package count

2d. Auto-fix (up to 3 iterations)

For each error, apply the known fix from the database:

Error patternFix
Missing package XAdd \usepackage{X} — but NEVER try xltabular or ltablex (use longtable instead)
Undefined citation keyCheck .bib file exists and is referenced; check for typos via edit distance
Overfull/underfull boxFlag location + width per ../shared/overfull-boxes.md — do NOT auto-fix prose (only safe auto-fix is adding microtype when absent)
tcolorbox = or , in titleWrap title in braces: title={...}
Font encoding warningAdd \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 dirFlag — 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:

  1. Symlink integrity — verify all symlinks in skills/, agents/, rules/, hooks/ resolve
  2. Shared .bib consistency — if multiple projects reference the same .bib file (e.g., via symlink), verify they're all pointing to the same version
  3. Overleaf separation — scan every paper/ directory for forbidden file types (.py, .R, .csv, .ipynb, etc.)
  4. 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 projects

Print 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:

  1. Write manifest to <project>/.claude/state/outputs-manifest-<UTC-timestamp>.json listing every file written this invocation, paths relative to the project root.
  2. Run:

    uv run python "<skills-root>/_shared/verify_outputs.py" \
        --manifest "$MANIFEST" \
        --project-root "$PROJECT_ROOT"
  3. 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

SkillRelationship
latexSingle-project deep fix (5 iterations). This skill runs a lighter version (3 iterations) at fleet scale. For ERROR projects, recommend running latex directly.
latexCanonical .latexmkrc resolution, migration rules, and single-project deep compilation.
audit-project-researchChecks project structure (directories, files). This skill checks build health.
bib-validateValidates bibliography entries. This skill checks if citations compile.
latex-templateChecks preamble alignment with the working paper template. Complementary: run after health-check to ensure preamble consistency.

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.