LaTeX Manuscript Skill

Write publication-ready LaTeX research papers with automated citation checking, asset validation, and submission packaging.

Overview

This skill guides the complete manuscript workflow:

Phase	Action	Gate
A	Plan paper structure	-
B	Draft/update LaTeX	-
C	Check citations	Citation Integrity Gate
D	Check assets	Asset Audit Gate
E	Build PDF	-
F	Package submission	-

Script Locations

skills/latex-manuscript/scripts/
├── init_project.py       # Initialize project with template
├── index_bib.py          # Extract valid citation keys
├── check_citations.py    # Validate cite commands
├── check_assets.py       # Verify figures/files exist
├── build.py              # Compile LaTeX (latexmk preferred)
├── flatten.py            # Expand \input/\include
└── package_submission.py # Create submission zip

---

Quick Start

1. Initialize Project

python skills/latex-manuscript/scripts/init_project.py \
  --template springer-nature-sn \
  --output ./manuscript

This creates:

• paper_project.yml - project configuration
• main.tex - from template
• references.bib - empty bibliography
• figures/ - directory for figures

2. Write Paper

Edit main.tex following the template structure. Claude will:

• Follow the paper plan
• Use only valid citation keys from references.bib
• Reference figures that exist in figures/

3. Build PDF

python skills/latex-manuscript/scripts/build.py --project ./manuscript

---

Template System

Available Templates

Template ID	Publisher	Class	Source
springer-nature-sn	Springer Nature	sn-jnl.cls	CTAN
ieee-conference	IEEE Conference	IEEEtran.cls	CTAN
ieee-journal	IEEE Journal	IEEEtran.cls	CTAN
acm-sigconf	ACM SIGCONF	acmart.cls	CTAN
acm-journal	ACM Journal	acmart.cls	CTAN
elsevier-num	Elsevier	elsarticle.cls	CTAN
aps-prb	APS (Phys Rev)	revtex4-2.cls	CTAN
acs-journal	ACS Chemistry	achemso.cls	CTAN

Template Details

IEEE (IEEEtran v1.8b)

• Conference: ieee-conference - Two-column format for proceedings
• Journal: ieee-journal - Two-column format for Transactions
• Source: https://ctan.org/pkg/ieeetran
• Official: https://www.ieee.org/conferences/publishing/templates

ACM (acmart v2.16)

• SIGCONF: acm-sigconf - Most common ACM conference format
• Journal: acm-journal - For JACM, TODS, etc.
• Source: https://ctan.org/pkg/acmart
• Official: https://www.acm.org/publications/proceedings-template

Elsevier (elsarticle v3.4c)

• Numerical: elsevier-num - Numerical citation style
• Source: https://ctan.org/pkg/elsarticle
• Official: https://www.elsevier.com/researcher/author/policies-and-guidelines/latex-instructions

APS (RevTeX v4.2f)

• PRB: aps-prb - Physical Review B (change prb to prl, pra, etc.)
• Source: https://ctan.org/pkg/revtex
• Official: https://journals.aps.org/revtex

ACS (achemso v3.14)

• Journal: acs-journal - For JACS, Nano Letters, etc.
• Source: https://ctan.org/pkg/achemso
• Official: https://pubs.acs.org/page/4authors/submission/tex.html

Template Pack Structure

Each template in assets/templates/<id>/ contains:

├── manifest.yml      # Build rules, requirements
├── cls/              # Document class files (optional if in TeXLive)
├── bst/              # Bibliography style files
├── tex/main.tex.template  # Starter template
└── latexmkrc         # Build configuration

Selecting a Template

python skills/latex-manuscript/scripts/init_project.py \
  --template ieee-conference \
  --output ./my-paper

Or manually edit paper_project.yml:

template_id: ieee-conference
main_tex: main.tex
bib_files: ["references.bib"]
figures_dir: figures
mode: draft  # or: submission

---

Workflow (ALWAYS FOLLOW)

Phase A: Plan

Before writing, create or update paperplan.json:

{
  "title": "Paper Title",
  "sections": [
    {"id": "abstract", "claims": ["Main claim 1"]},
    {"id": "introduction", "claims": ["Background", "Gap", "Contribution"]},
    {"id": "methods", "claims": ["Approach description"]},
    {"id": "results", "claims": ["Finding 1", "Finding 2"]},
    {"id": "discussion", "claims": ["Implications", "Limitations"]},
    {"id": "conclusion", "claims": ["Summary"]}
  ],
  "figures": [
    {"id": "fig1", "file": "figures/fig1.png", "caption": "..."}
  ],
  "key_citations": ["smith2021", "jones2022"]
}

Phase B: Draft LaTeX

Write/update main.tex:

• Use the selected template's structure
• Keep changes incremental
• Compile frequently to catch errors early

Phase C: Citation Integrity Gate (CRITICAL)

HARD RULE: Never generate \cite{KEY} unless KEY exists in references.bib

Before building, run:

# Index valid keys
python skills/latex-manuscript/scripts/index_bib.py --project ./manuscript

# Check all citations
python skills/latex-manuscript/scripts/check_citations.py --project ./manuscript

If citations fail:

1. Check for typos in citation keys
2. Add missing entries to references.bib
3. Use placeholder \cite{TODO:description} for unfound refs
4. Re-run check until it passes

Phase D: Asset Audit Gate

python skills/latex-manuscript/scripts/check_assets.py --project ./manuscript

This verifies:

• All \includegraphics{...} files exist
• All template files (.cls, .bst) are present
• No absolute paths used
• Bibliography file exists

Phase E: Build

python skills/latex-manuscript/scripts/build.py --project ./manuscript

The build script:

1. Prefers latexmk (handles multi-pass automatically)
2. Falls back to: pdflatex → bibtex → pdflatex → pdflatex
3. Scans logs for undefined citation warnings
4. Reports errors clearly

Phase F: Submission Packaging

When ready to submit:

# Set mode to submission
# Edit paper_project.yml: mode: submission

# Flatten to single .tex (if required by journal)
python skills/latex-manuscript/scripts/flatten.py --project ./manuscript

# Create submission package
python skills/latex-manuscript/scripts/package_submission.py --project ./manuscript

Output: build/submission.zip with all required files.

---

Citation Integrity (Detailed)

Why This Matters

AI can hallucinate citation keys that don't exist. This causes:

• Build failures (undefined citations)
• Embarrassing errors in submissions
• Wasted time debugging

How It Works

1. Index Phase: index_bib.py extracts all valid keys from .bib files:

   {"keys": ["smith2021", "jones2022"], "sources": ["references.bib"]}
   

2. Check Phase: check_citations.py parses LaTeX for cite commands:

   • \cite{}, \citep{}, \citet{}, \autocite{}, etc.
   • Handles multi-key cites: \cite{a,b,c}
   • Ignores commented lines

3. Enforcement:

   • Draft mode: warnings only (unless strict)
   • Submission mode: fails on any missing key

Valid Citation Key Sources

Only these count as valid:

• Keys in references.bib (or configured .bib files)
• Keys in .bbl file (if pre-generated)

Placeholder Convention

When a citation is needed but not yet in bib:

\cite{TODO:smith-deep-learning}  % Will fail check - intentional

This makes missing refs explicit and prevents accidental submission.

---

Asset Audit (Detailed)

What Gets Checked

1. Figures: Every \includegraphics{path} must resolve
2. Template files: Class/style files from manifest
3. Bibliography: .bib file must exist
4. Path policy: No absolute paths (if template requires)

Output

build/asset_report.md

✓ figures/fig1.png exists
✓ figures/fig2.pdf exists
✗ figures/fig3.png MISSING
✓ sn-jnl.cls exists
✓ references.bib exists

SUMMARY: 1 error, 0 warnings

---

Build System (MacTeX)

Prerequisites

• MacTeX installed (provides pdflatex, bibtex, latexmk)
• Path includes /Library/TeX/texbin

latexmk (Preferred)

latexmk automates multi-pass compilation:

latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex

Fallback Chain

If latexmk unavailable:

pdflatex -interaction=nonstopmode main.tex
bibtex main
pdflatex -interaction=nonstopmode main.tex
pdflatex -interaction=nonstopmode main.tex

Log Scanning

Build script checks for:

• "Citation key undefined" (LaTeX warning)
• "I didn't find a database entry for" (BibTeX warning)

These are surfaced as actionable errors.

---

Project Configuration

paper_project.yml

template_id: springer-nature-sn
main_tex: main.tex
bib_files:
  - references.bib
figures_dir: figures
mode: draft  # draft | submission

# Optional overrides
strict_citations: false  # fail on missing in draft mode
output_dir: build

Directory Layout

my-paper/
├── paper_project.yml   # Project config
├── paperplan.json      # Paper outline (optional)
├── main.tex            # Main document
├── references.bib      # Bibliography
├── figures/            # Figure files
│   ├── fig1.png
│   └── fig2.pdf
└── build/              # Generated outputs
    ├── main.pdf
    ├── citekeys.json
    ├── citation_report.json
    └── asset_report.md

---

Reference Documentation

File	Content
references/paperplan_schema.md	Paper plan JSON schema
references/template_pack_spec.md	Template manifest spec
references/citation_integrity_spec.md	Citation checking details
references/asset_audit_spec.md	Asset validation rules

---

Common Issues

"Citation undefined"

1. Run index_bib.py to refresh key index
2. Run check_citations.py to find invalid keys
3. Fix typos or add missing bib entries
4. Re-run build

"File not found" for figures

1. Check path in \includegraphics{}
2. Ensure file exists in figures/ directory
3. Use relative paths, not absolute

latexmk not found

Install via MacTeX's TeX Live Utility or:

sudo tlmgr install latexmk

Build fails with cryptic error

1. Check build/main.log for details
2. Look for "! " lines (LaTeX errors)
3. Common: missing packages, unbalanced braces

---

Environment

# Verify MacTeX installation
which pdflatex  # Should show /Library/TeX/texbin/pdflatex
which latexmk   # Should show /Library/TeX/texbin/latexmk

No additional Python dependencies required beyond standard library.