LaTeX/TikZ/Beamer Auditor

Overview

A comprehensive auditing skill for LaTeX documents, including article/report/book classes, TikZ/PGF graphics, pgfplots visualizations, and Beamer presentations. All recommendations are grounded in official CTAN documentation and TeX best practices.

Auto-Invoke Triggers

Use this skill when task mentions:

•"LaTeX check" or "TeX audit"
•"TikZ" or "pgfplots"
•"Beamer" or "slides"
•"compile errors" or "compilation issues"
•"aspectratio" or "16:9"
•"externalize" or "tikzexternalize"
•"latexmk" or "pdflatex"
•"biblatex" or "biber"
•"hyperref" or "cleveref"

Scientific & Standards Foundation

This skill enforces best practices from:

•LaTeX Project Documentation - Official LaTeX kernel and class documentation
•TikZ & PGF Manual (tikz.dev) - Graphics and externalization library
•pgfplots Manual (CTAN) - Data plotting best practices
•Beamer User Guide (CTAN) - Presentation class guidelines
•hyperref Manual (CTAN) - Package loading order and PDF metadata
•cleveref Manual (CTAN) - Type-aware cross-referencing
•biblatex Manual (CTAN) - Modern bibliography with biber backend
•microtype Manual (CTAN) - Character protrusion and font expansion
•csquotes Manual (CTAN) - Locale-aware quotation handling
•WCAG 2.1 - Web Content Accessibility Guidelines (for Beamer contrast)
•ChkTeX Documentation - Semantic LaTeX linting
•latexmk Manual (CTAN) - Automated multi-pass compilation

Audit Scope

1. Document & Engine Configuration

•Document class detection (article, beamer, IEEEtran, etc.)
•Engine compatibility (pdfLaTeX, XeLaTeX, LuaLaTeX)
•Input encoding and font encoding
•Class options validation

2. Package Configuration

•Package loading order (critical for hyperref, cleveref)
•Package compatibility checks
•Required vs. optional packages
•Version-specific requirements

3. Cross-References & Hyperlinks

•hyperref loading position (near end of preamble)
•PDF metadata configuration
•cleveref integration (load after hyperref)
•Label prefix conventions (fig:, tab:, sec:, eq:)

4. Bibliography

•Modern biblatex + biber vs. legacy BibTeX
•Backend configuration verification
•Citation style consistency
•Toolchain completeness (pdflatex → biber → pdflatex)

5. TikZ/PGF & pgfplots

•TikZ library loading
•pgfplots compatibility level
•Data file separation for large plots
•Externalization setup and security
•Shell-escape requirements and warnings

6. Beamer Presentations

•Aspect ratio configuration (43, 169, 1610)
•Theme and color scheme consistency
•Overlay density analysis (≤5 per frame recommended)
•Frame content balance
•WCAG AA contrast compliance (≥4.5:1 normal, ≥3:1 large text)

7. Typography & Formatting

•microtype for improved typography
•Font selection and loading
•Page layout and geometry
•Quotation handling with csquotes

8. Linting & Code Quality

•ChkTeX semantic checks
•latexindent formatting
•Code organization and readability

9. Compilation Workflow

•latexmk usage and configuration
•Shell-escape security considerations
•Multi-pass compilation requirements
•Estimated compilation time

10. Accessibility

•Alternative text for figures (when feasible)
•Color-independent information encoding
•Contrast ratios for Beamer slides
•Logical document structure

Audit Process

Phase 1: Document Analysis

•
Read the LaTeX source file(s)
- •Main .tex file
- •Included files via \input or \include
- •Class files (.cls) if custom
- •Style files (.sty) if custom

•

Extract metadata:

code

- Document class: \documentclass[options]{class}
- Class options: aspectratio, fontsize, paper size, etc.
- Engine hints: fontspec (XeLaTeX/LuaLaTeX), inputenc (pdfLaTeX)

•
Parse preamble:
- •List all \usepackage{...} commands in order
- •Extract package options
- •Note custom commands and environments
•
Detect document type:
- •Article/report/book → Standard academic document
- •Beamer → Presentation (trigger Beamer-specific checks)
- •IEEEtran/ACM/others → Conference/journal template

Phase 2: Run Checklist Rules

Load rules from checklists/latex_checklist.yml and execute in order:

2.1 Document Structure

•class_detect: Identify class and validate options
•engine_detect: Determine appropriate LaTeX engine
•encoding_check: Verify UTF-8 input and T1 font encoding (pdfLaTeX)

2.2 Package Configuration

Execute in sequence:

•

hyperref_order: Verify hyperref loaded near end

code

RULE: hyperref must come after most packages
EXCEPTION: cleveref, glossaries must come after hyperref

•

hyperref_metadata: Check PDF metadata

code

VERIFY: \hypersetup{pdftitle=..., pdfauthor=..., pdfsubject=..., pdfkeywords=...}

•

cleveref_present: If cross-refs detected, recommend cleveref

code

DETECT: \ref{}, \label{} usage
RECOMMEND: \usepackage{cleveref} after hyperref

•

cleveref_order: Verify cleveref loaded last

code

RULE: cleveref must be one of the last packages
EXCEPTION: Only microtype may come after

•

bib_backend: Check bibliography system

code

PREFER: biblatex with backend=biber
LEGACY: \bibliography{}, \bibliographystyle{} → flag for migration

•

microtype_enabled: Verify microtype for typography

code

CHECK: \usepackage{microtype} present
NOTE: Works with pdfLaTeX, XeLaTeX, LuaLaTeX

•

csquotes_present: Check quotation handling

code

DETECT: ``, '', \"{}, etc. → recommend csquotes
VERIFY: \usepackage{csquotes} after babel/polyglossia

•

babel_polyglossia: Language support

code

pdfLaTeX: \usepackage[language]{babel}
XeLaTeX/LuaLaTeX: \usepackage{polyglossia}

2.3 TikZ & PGF

Execute if TikZ detected:

•
tikz_present: Confirm TikZ package and usage
code
```
DETECT: \usepackage{tikz}, \begin{tikzpicture}
```

•

tikz_libraries: Verify library loading

code

COMMON: positioning, arrows.meta, shapes, calc
CHECK: \usetikzlibrary{...} before first use

•

pgfplots_present: Check pgfplots usage

code

DETECT: \usepackage{pgfplots}, \begin{axis}

•

pgfplots_compat: Verify compatibility level

code

REQUIRE: \pgfplotsset{compat=1.18} or compat=newest
REASON: Enables modern features and behavior

•

tikz_compile_cost: Estimate compilation time

code

COUNT: Number of tikzpicture environments
ESTIMATE:
  - 1-5 figures: Low
  - 6-15 figures: Medium
  - 16-30 figures: High
  - 31+ figures: Very High
RECOMMEND: Externalization if High or Very High

•

externalize_detection: Check externalization setup

code

DETECT: \usetikzlibrary{external}, \tikzexternalize
VERIFY: prefix=tikz-cache/ or similar

•

externalize_shell_escape: Verify shell-escape awareness

code

IF externalization detected:
  REQUIRE: Compilation with -shell-escape
  WARN: Security implications (only trusted documents)
  RECOMMEND: latexmk -pdf -shell-escape document.tex

•

tikz_naming: Check for explicit figure naming

code

RECOMMEND: \tikzsetnextfilename{descriptive-name}
REASON: Reproducible cache names, easier debugging

2.4 Beamer (if applicable)

Execute if \documentclass{beamer} detected:

•
beamer_class: Confirm Beamer detection

•

aspect_ratio: Check aspectratio option

code

DEFAULT: 43 (4:3)
MODERN: 169 (16:9 widescreen)
OTHER: 1610 (16:10), 149 (14:9)
RECOMMEND: 169 for contemporary displays

•

frame_title: Verify all frames have titles

code

CHECK: \begin{frame}{Title} or \frametitle{Title}
REASON: Structure, navigation, accessibility

•

overlay_detection: Count overlay specifications

code

DETECT: \pause, <n->, \onslide<>, \only<>, etc.
LOAD: lexicons/beamer_overlays.yml patterns

•

overlay_density: Flag excessive overlays

code

THRESHOLD: 5 overlays per frame
IF count > 5:
  WARN: Over-complexity
  SUGGEST: Consolidate or split frame

•

frame_content_balance: Check frame content volume

code

HEURISTIC: >20 lines of content → potentially overcrowded
RECOMMEND: Split across multiple frames

•

contrast_check: Assess WCAG compliance

code

ANALYZE: Theme colors (if standard theme)
REFERENCE: lexicons/beamer_overlays.yml contrast guidelines
WARN: Potential contrast failures
RECOMMEND: Test with contrast checker

Phase 3: Optional Compilation Test

If user requests or document is problematic:

•

Invoke compilation (if code-capable helper available):

code

COMMAND: latexmk -pdf -interaction=nonstopmode -halt-on-error document.tex
IF externalization detected:
  ADD: -shell-escape flag

•
Parse compilation output:
- •Errors → severity: error
- •Warnings → severity: warn
- •Overfull/underfull boxes → severity: info
•
Check auxiliary files:
- •.log file for detailed errors
- •.bcf file for biblatex backend
- •.bbl file for bibliography compilation

Phase 4: Generate Outputs

4.1 Create Audit Report

Use templates/audit_report_template.md:

•
Fill executive summary:
- •Overall status (excellent/good/needs_improvement/critical_issues)
- •Count findings by severity
- •Highlight top 3-5 issues
•
Document analysis section:
- •Class, engine, packages
- •TikZ/Beamer specifics
•
Findings by category:
- •Group by checklist section
- •Include evidence (line numbers, code snippets)
- •Reference official documentation
•
Detailed findings:
- •
  Each finding with:
  - •ID (from checklist)
  - •Severity (error/warn/info)
  - •Message
  - •Evidence
  - •Reference (CTAN manual, page number if applicable)
  - •Fix recommendation
•
Compilation guidance:
- •Recommended command
- •Shell-escape notes
- •Estimated compilation time
•
MWE references:
- •Link to generated minimal working examples

4.2 Create Fix Plan

Use templates/fix_plan_template.md:

•
Priority 1 actions (errors):
- •Step-by-step fix instructions
- •Code snippets for corrections
- •Expected outcome
•
Priority 2 actions (warnings):
- •Recommended improvements
- •Impact explanation
•
Priority 3 actions (info):
- •Best practices
- •Optional enhancements
•
Package loading order:
- •Complete preamble template
- •Organized by category
- •Comments explaining order
•
Specialized fixes:
- •TikZ externalization setup (if needed)
- •Beamer aspect ratio and overlay fixes (if applicable)
- •Bibliography migration guide (if needed)

4.3 Generate JSON Output

Conform to schema/tex_audit_schema.json:

json

{
  "metadata": {...},
  "document": {...},
  "packages": {...},
  "tikz": {...},
  "beamer": {...},
  "findings": [...],
  "compilation": {...},
  "mwe_paths": [...],
  "summary": {...}
}

4.4 Create Minimal Working Examples

Generate MWEs for relevant fixes:

•
TikZ Externalization (if applicable):
- •Copy mwes/tikz_externalization.tex
- •Customize for user's specific setup
•
Beamer 16:9 with Overlays (if applicable):
- •Copy mwes/beamer_16_9_overlays.tex
- •Adapt to user's theme
•
Modern Bibliography (if BibTeX detected):
- •Copy mwes/modern_bibliography.tex
- •Show migration path
•
Best Practices Template:
- •Always provide mwes/best_practices_article.tex
- •Demonstrates complete modern setup

4.5 Provide Lint Configurations

•
ChkTeX configuration:
- •Copy lint/.chktexrc to project
- •Explain usage: chktex -v0 -l document.tex
•
latexindent configuration:
- •Copy lint/indentconfig.yaml to project
- •Explain usage: latexindent -l=indentconfig.yaml -w document.tex

Phase 5: Safeguards & Notes

•

Shell-escape warning:

code

IF -shell-escape required:
  EMPHASIZE: Security implications
  NOTE: Only use with trusted documents
  EXPLAIN: Restricted shell escape in modern distributions

•

Package conflicts:

code

IF known conflicts detected:
  WARN: Specific incompatibilities
  SUGGEST: Alternative approaches

•

Manual references:

code

FOR each recommendation:
  CITE: Specific manual section
  PROVIDE: CTAN link or official documentation URL

•

Beamer accessibility:

code

IF Beamer detected:
  NOTE: Contrast recommendations are WCAG 2.1 AA guidelines
  ACKNOWLEDGE: Theme customization may be needed
  PROVIDE: Contrast checking tools

Detection Rules Implementation

Package Loading Order

Correct order (with rationale):

latex

% 1. ENCODING & FONTS (pdfLaTeX only)
\usepackage[utf8]{inputenc}    % UTF-8 input
\usepackage[T1]{fontenc}        % T1 font encoding

% 2. LANGUAGE
\usepackage[english]{babel}     % Or polyglossia for XeLaTeX/LuaLaTeX
\usepackage{csquotes}           % After babel

% 3. MATHEMATICS (early for other packages to use)
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{amsthm}

% 4. GRAPHICS & FLOATS
\usepackage{graphicx}
\usepackage{float}
\usepackage{caption}
\usepackage{subcaption}

% 5. TABLES
\usepackage{booktabs}
\usepackage{array}
\usepackage{multirow}

% 6. TIKZ (if needed)
\usepackage{tikz}
\usetikzlibrary{positioning,arrows.meta,shapes,calc}
\usepackage{pgfplots}
\pgfplotsset{compat=newest}

% 7. BIBLIOGRAPHY
\usepackage[backend=biber,style=authoryear]{biblatex}
\addbibresource{references.bib}

% 8. PAGE LAYOUT
\usepackage{geometry}

% 9. HYPERLINKS (near end!)
\usepackage[colorlinks=true,...]{hyperref}

% 10. CROSS-REFERENCES (after hyperref!)
\usepackage{cleveref}

% 11. TYPOGRAPHY (last!)
\usepackage{microtype}

Rationale:

•Encoding/fonts first: Affects character processing
•Language early: Affects hyphenation patterns
•Math early: Other packages may need math commands
•Graphics/tables: Independent, can be anywhere in middle
•TikZ: May use math, graphics facilities
•Bibliography: Needs to hook into referencing
•Hyperref late: Redefines many commands, needs others loaded first
•cleveref after hyperref: Needs hyperref's reference system
•microtype last: Fine-tunes final typography

TikZ Externalization Detection

code

IF \usetikzlibrary{external} present:
  CHECK for \tikzexternalize command
  VERIFY prefix setting
  COUNT tikzpicture environments
  ESTIMATE cache size

  IF count > 10:
    STRONGLY RECOMMEND externalization
  IF count 5-10:
    RECOMMEND externalization
  IF count < 5:
    NOTE: Optional, may not provide significant benefit

  ALWAYS WARN: Requires -shell-escape

Beamer Overlay Analysis

code

FOR each \begin{frame}...\end{frame}:
  COUNT occurrences of:
    - \pause
    - <n-> patterns (extract n)
    - \onslide<...>
    - \only<...>
    - \item<...>

  COMPUTE max overlay number for frame

  IF max > 5:
    WARN: Excessive overlays
    PROVIDE frame title/line number
    SUGGEST: Consolidation strategies

  ACCUMULATE global overlay statistics

Contrast Estimation (Beamer)

code

FOR standard Beamer themes:
  LOAD known color schemes
  ESTIMATE contrast ratios

FOR custom themes:
  WARN: Manual contrast checking required
  PROVIDE: Online contrast checker tools
  REFERENCE: WCAG 2.1 SC 1.4.3

ALWAYS NOTE:
  - Normal text: ≥4.5:1 (AA)
  - Large text (≥18pt): ≥3:1 (AA)
  - Don't rely solely on color

Example Usage Patterns

Pattern 1: Basic Article Audit

code

User: "Check my LaTeX document for issues"

Process:
1. Read document.tex
2. Detect class: article
3. Run document/packages/crossref/bib checks
4. Generate audit report
5. Provide fix plan
6. Include best_practices_article.tex as reference

Pattern 2: Beamer Presentation Audit

code

User: "Review my presentation slides for LaTeX issues"

Process:
1. Read slides.tex
2. Detect class: beamer
3. Run all standard checks
4. ADDITIONALLY run Beamer-specific checks:
   - Aspect ratio
   - Overlay density
   - Contrast estimation
   - Frame content balance
5. Generate audit report with Beamer section
6. Provide beamer_16_9_overlays.tex as reference
7. Highlight WCAG contrast requirements

Pattern 3: TikZ-Heavy Document Audit

code

User: "My document with lots of TikZ figures compiles very slowly"

Process:
1. Read document.tex
2. Count tikzpicture environments
3. IF count > 15:
   - STRONGLY recommend externalization
   - Generate externalization setup guide
   - Provide tikz_externalization.tex MWE
   - Explain shell-escape security
   - Show Makefile integration
4. Estimate compilation time savings

Pattern 4: Bibliography Migration

code

User: "How do I modernize my bibliography setup?"

Process:
1. Detect legacy BibTeX usage:
   - \bibliographystyle{}
   - \bibliography{}
2. Recommend migration to biblatex + biber
3. Provide modern_bibliography.tex as guide
4. Show step-by-step migration:
   - Remove old commands
   - Add biblatex package
   - Change compilation workflow
5. Explain benefits:
   - UTF-8 support
   - Flexible formatting
   - Better sorting

False Positive Mitigation

Conference Templates

code

IF document uses conference class (IEEEtran, ACM, etc.):
  SUPPRESS warnings about:
    - Package loading order (template may have specific requirements)
    - Class options (conference-mandated)
    - Bibliography style (often required by venue)

  STILL CHECK:
    - Compilation issues
    - TikZ externalization opportunities
    - Code quality (ChkTeX, indentation)

Legacy Documents

code

IF document appears to be legacy (pre-2010 packages):
  NOTE: Document may be intentionally using older packages
  DISTINGUISH:
    - Critical issues (will cause errors)
    - Modernization opportunities (optional improvements)
  PROVIDE migration path but acknowledge may not be desired

Minimal Documents

code

IF document is very short (<100 lines, simple structure):
  REDUCE recommendations to essentials
  DON'T recommend:
    - microtype (minimal benefit)
    - Complex cross-reference systems
    - Externalization (overhead not worth it)

Integration Points

With tex-runner Skill (if available)

code

IF tex-runner skill available:
  INVOKE for compilation test:
    tex-runner.compile(
      path=document.tex,
      engine=detected_engine,
      shell_escape=externalization_detected,
      timeout=300
    )

  PARSE results:
    - Errors → add to findings with severity=error
    - Warnings → add to findings with severity=warn
    - Success → note in report

With File Organization Skills

code

IF large project with multiple files:
  ANALYZE structure:
    - Main file
    - \input{} and \include{} files
    - figures/ directory
    - data/ directory for pgfplots

  RECOMMEND:
    - Organized directory structure
    - Separation of content and presentation
    - Version control (.gitignore for auxiliary files)

Output Format Standards

Audit Report Structure

•Executive Summary (1 page)
•Document Analysis (class, engine, packages)
•Findings by Category (grouped, prioritized)
•Detailed Findings (with evidence and references)
•TikZ Analysis (if applicable)
•Beamer Analysis (if applicable)
•Compilation Guidance (commands, toolchain)
•MWE References (links to examples)
•Lint Configuration (ChkTeX, latexindent setup)
•Action Items (prioritized checklist)

Fix Plan Structure

•Overview (summary of fixes)
•Priority 1 (critical errors)
•Priority 2 (warnings)
•Priority 3 (improvements)
•Package Loading Order (complete preamble)
•Specialized Fixes (TikZ, Beamer, bibliography)
•Compilation Checklist (verification steps)
•Testing (how to verify fixes)
•Makefile (reproducible builds)
•Resources (documentation links)

Performance Notes

•Fast checks (< 1 second): Document structure, package order, basic pattern matching
•Medium checks (1-5 seconds): Detailed preamble analysis, overlay counting
•Slow checks (5-30 seconds): Full compilation test (if invoked)

Prioritize fast checks; only invoke compilation test if:

•User explicitly requests it
•Static analysis reveals ambiguous issues
•Document has known compilation problems

Version: 1.0.0 License: MIT Maintained by: Claude Skills Library