How `/add-template` Registers Custom `.tex` Files with Mandatory Test Compilation

The /add-template command requires every custom LaTeX template to successfully compile against dummy data before activation, ensuring the /apply workflow never encounters runtime LaTeX errors during job application generation.

The ai-job-search repository uses the /add-template command to swap its built-in CV and cover-letter templates with user-provided .tex designs. According to the source definition in .claude/commands/add-template.md, the registration process enforces a mandatory test compilation that validates the template's integrity, engine compatibility, and font availability before it enters the active workflow.

The Six-Step Registration Workflow

The command implementation defined in .claude/commands/add-template.md orchestrates registration through six ordered steps, with Step 4 serving as the critical quality gate.

Step 1: Argument Parsing and Mode Selection

The workflow begins by determining the execution mode. The command checks whether the user wants to list existing templates, switch to a previously registered one, or register a new template. This branching logic ensures that template activation (via --use) bypasses the compilation test, while new registrations must pass the full validation pipeline.

Step 2: Capturing Template Metadata

For new templates, the command conducts an interview to collect essential metadata:

• Template type: CV or cover letter
• Source path: Location of the .tex file or containing directory
• Name: Unique identifier for the template
• Compile engine: lualatex, xelatex, or pdflatex
• Font dependencies: System or bundled fonts required for rendering
• Page limits: Constraints enforced by the /apply command

This metadata determines how the template will be invoked during the application-generation phase.

Step 3: Storing Template Assets

The command creates a dedicated directory under templates/cv/<name>/ or templates/cover_letters/<name>/ and populates it with:

• template.tex: The skeleton file with all personal data replaced by [PLACEHOLDER] tokens
• Auxiliary files: Any bundled .cls, .sty, or configuration files
• fonts/: Sub-directory for font assets that must travel with the template
• TEMPLATE.md: A manifest recording the metadata, style rules, and known pitfalls

This structure ensures the template is self-contained and portable within the repository.

Step 4: Mandatory Test Compilation (Validation Gate)

Step 4 is non-negotiable. The command creates a scratch copy named _compile_test.tex and populates every [PLACEHOLDER] with dummy data. It then executes the declared engine in non-interactive mode:

cd templates/<type>/<name> && <engine> -interaction=nonstopmode _compile_test.tex

If compilation fails, the error output is presented to the user for diagnosis—common causes include missing fonts, incorrect engine selection, or absent document classes. The user must fix the template and retry until the compile succeeds. Upon success, the generated PDF is inspected for layout sanity and page count, with any quirks documented in the TEMPLATE.md Known pitfalls section.

This mandatory test guarantees that the /apply command will never encounter unexpected LaTeX errors when generating application materials.

Step 5: Activating the Template

Once validation passes, the command injects a managed block into either 05-cv-templates.md or 06-cover-letter-templates.md (located in .claude/skills/job-application-assistant/). This block instructs the /apply command which skeleton to use, which engine to invoke, and what page limits to enforce.

Switching templates simply replaces this managed block, while /add-template --use default removes it entirely, causing the system to fall back to the stock moderncv or cover.cls templates.

Step 6: Confirmation

The workflow concludes with a summary displaying the registered template name, confirmation of the successful test compile, and next-step hints for template management.

Practical Usage Examples

Register a new CV template:

/add-template

# Interactive prompts:

# • Type: CV

# • Source: /path/to/my_cv.tex

# • Name: awesome-cv

# • Engine: lualatex

# • Fonts: Lato (bundled), Raleway (system)

# • Page limit: 2

This creates templates/cv/awesome-cv/, writes the manifest, runs the mandatory compilation test, and activates the template.

Switch to an existing template:

/add-template --use awesome-cv

This updates the managed block in 05-cv-templates.md to reference the pre-validated template.

Revert to default templates:

/add-template --use default

This removes the managed block, restoring the stock moderncv configuration.

List registered templates:

/add-template --list

Scans templates/**/TEMPLATE.md to display a table of names, engines, fonts, and activation status.

Summary

• Validation is mandatory: Every custom .tex file must compile successfully against dummy data before activation, enforced in .claude/commands/add-template.md Step 4.
• Scratch-file testing: The command uses _compile_test.tex to validate templates without contaminating the source skeleton.
• Self-contained storage: Templates live in templates/cv/<name>/ or templates/cover_letters/<name>/ with their fonts, classes, and manifest.
• Managed activation: The system uses managed blocks in 05-cv-templates.md or 06-cover-letter-templates.md to route the /apply command to validated templates.
• Fault isolation: Compilation errors are caught during registration, not during job application generation.

Frequently Asked Questions

What happens if the mandatory test compilation fails?

If the engine returns an error when compiling _compile_test.tex, the /add-template command presents the error log to the user and halts registration. The user must resolve the underlying issue—such as installing missing fonts, correcting engine selection, or fixing LaTeX syntax errors—before the template can be activated. This prevents broken templates from entering the job-application pipeline.

Where are custom templates stored in the repository?

Custom templates are stored in templates/cv/<name>/ for CVs or templates/cover_letters/<name>/ for cover letters. Each directory contains the processed template.tex, a TEMPLATE.md manifest, a fonts/ sub-directory for bundled typefaces, and any auxiliary .cls or .sty files required for compilation.

How do I switch back to the default LaTeX templates?

Execute /add-template --use default. This command removes the managed configuration block from 05-cv-templates.md or 06-cover-letter-templates.md, causing the /apply command to fall back to the stock templates (moderncv for CVs and cover.cls for cover letters) provided with the repository.

Can I use any LaTeX engine for my custom template?

The registration workflow supports lualatex, xelatex, and pdflatex, which you specify during the metadata interview in Step 2. The mandatory test compilation uses your selected engine to ensure compatibility, so you must choose an engine that supports your template's specific font and package requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}