How /add-template Registers and Manages Custom LaTeX CV and Cover Letter Templates

The /add-template command executes a six-step pipeline that validates, stores, and activates custom LaTeX templates by creating manifest files, verifying compilation, and inserting managed blocks into guidance files that the /apply workflow consumes.

The /add-template command serves as the entry point for users who want to replace the stock LaTeX templates in the MadsLorentzen/ai-job-search repository with custom designs. This workflow ensures that any custom CV or cover letter template is safely stored, compile-tested, and seamlessly integrated into the automated job application process. Understanding how /add-template registers and manages custom LaTeX CV and cover letter templates reveals the underlying architecture that guarantees idempotent registration and transparent activation.

The Six-Step Registration Pipeline

The /add-template implementation in .claude/commands/add-template.md follows a rigorous six-step pipeline that transforms user-supplied LaTeX source into a fully registered, production-ready template.

Step 0: Parse Command Arguments

The command first detects the operation mode based on input arguments. It recognizes --list to display registered templates, --use <name> to switch active templates, --use default to revert to stock templates, or a file path to trigger registration mode.

Step 1: Determine Template Type and Source

In registration mode, the command queries the user (or reads $ARGUMENTS) to identify whether the template is a CV or cover-letter. It accepts source material as a single .tex file, a directory containing multiple files, or pasted content. The system prompts for any missing custom class (.cls) or style (.sty) files required by the template.

Step 2: Capture Template Metadata

The command extracts critical metadata required by the /apply workflow:

• Name: A unique kebab-case identifier
• Compile engine: lualatex, xelatex, or pdflatex (inferred from \fontspec usage or class declarations)
• Fonts: Bundled (stored in repository) versus system-installed
• Style rules: Color schemes, heading hierarchy, spacing parameters
• Page limit: Defaults to 2 pages for CVs, 1 page for cover letters
• Known pitfalls: Optional warnings about compilation quirks

Step 3: Store Template Files and Manifest

The command creates a directory under templates/cv/<name>/ or templates/cover_letters/<name>/ and writes:

• template.tex: The skeleton with personal data replaced by [PLACEHOLDER] tokens
• TEMPLATE.md: A manifest recording all metadata from Step 2
• .cls and .sty files: Custom LaTeX classes and packages
• fonts/: Subdirectory containing bundled font files

This structure ensures the repository remains safe to commit, as skeletons contain only placeholder tokens, never personal data.

Step 4: Verify Compilation

The pipeline generates a temporary _compile_test.tex populated with dummy data and executes the declared engine. If compilation fails, the system diagnoses missing fonts, incorrect engine selection, or absent class files, attempts automatic fixes, and requests missing assets from the user. Upon successful compilation, temporary files are removed.

Step 5: Activate the Template

The command inserts or replaces a managed block inside guidance files that /apply reads:

• 05-cv-templates.md for CV templates
• 06-cover-letter-templates.md for cover letter templates

The block uses delimiters <!-- BEGIN ACTIVE-TEMPLATE ... --> and <!-- END ACTIVE-TEMPLATE ... --> to specify the skeleton path, manifest location, engine, fonts, and page limit. Only one active block exists at a time; re-registration overwrites the previous entry. Using --use default removes the block entirely, reverting to stock templates.

Step 6: Confirm Registration

The command presents a concise summary including the template name, stored files, compilation result, and activation status, then directs the user to list or switch commands.

Template Storage Architecture

The file system layout isolates custom templates from stock assets under the top-level templates/ directory. Each registered template resides in its own folder with a standardized structure:

templates/
├── cv/
│   └── awesome-cv/
│       ├── template.tex
│       ├── TEMPLATE.md
│       └── fonts/
└── cover_letters/
    └── slick-cover/
        ├── template.tex
        └── TEMPLATE.md

The TEMPLATE.md manifest serves as the single source of truth for template metadata. It records the compile command, style rules, and known pitfalls in a human-readable format that /add-template parses when listing (--list) or switching (--use <name>) templates.

The Managed Block System

The managed block is a self-contained snippet embedded in guidance documents that directs the /apply workflow. Because /apply checks only this block for custom template instructions, the rest of the guidance—including tailoring rules and page-budget calculations—remains untouched when switching templates.

Example managed block structure in 05-cv-templates.md:

<!-- BEGIN ACTIVE-TEMPLATE awesome-cv -->
- **Template Path**: `templates/cv/awesome-cv/template.tex`
- **Engine**: lualatex
- **Page Limit**: 2
<!-- END ACTIVE-TEMPLATE awesome-cv -->

Practical Usage Examples

List all registered templates:

/add-template --list

Register a new CV template from a directory:

/add-template /path/to/my-cv-template/

Switch to a previously registered cover letter template:

/add-template --use slick-cover

Revert to stock moderncv and cover.cls templates:

/add-template --use default

Example TEMPLATE.md Structure

When /add-template completes Step 3, it generates a manifest like this:

# Template: awesome-cv

- **Type**: CV
- **Engine**: lualatex
- **Page limit**: 2 page(s)
- **Fonts**: Raleway (bundled in fonts/)
- **Class/packages**: moderncv (standard)

## Compile command

    cd <output dir> && lualatex -interaction=nonstopmode template.tex

## Style rules

- Use teal accent colour for headings
- Section order: Education → Experience → Projects → Skills

## Known pitfalls

- The `\cventry` macro must not be split across pages; add `\needspace{5\baselineskip}` before each entry.

Summary

• Six-step pipeline: /add-template follows a rigorous process from argument parsing through compilation verification to activation.
• Isolated storage: Custom templates live under templates/cv/ and templates/cover_letters/, never interfering with stock assets.
• Manifest-driven: Each template includes a TEMPLATE.md file recording metadata, compile commands, and style rules.
• Compile-time safety: Mandatory test compilation with dummy data catches missing fonts or class errors before activation.
• Managed block activation: The active template is declared via delimited blocks in 05-cv-templates.md or 06-cover-letter-templates.md, ensuring /apply always uses the correct skeleton.

Frequently Asked Questions

How does /add-template handle missing font files during registration?

If the LaTeX compilation test fails due to missing fonts, /add-template diagnoses the specific missing assets and prompts the user to provide them. The system distinguishes between system-installed fonts and bundled fonts, storing the latter in a fonts/ subdirectory within the template folder to ensure portability.

Can I switch between multiple custom templates without re-registerating?

Yes. Once registered, templates persist in the templates/ directory. Use /add-template --use <name> to activate a previously registered template, which simply rewrites the managed block in 05-cv-templates.md or 06-cover-letter-templates.md. The command is idempotent; switching templates only updates the active block, leaving the stored template files untouched.

What happens if the compilation test fails in Step 4?

The pipeline halts and provides diagnostic feedback about the failure cause—whether missing class files, incorrect engine selection (e.g., using pdflatex with \fontspec commands), or missing fonts. The system attempts automatic fixes where possible, but requires user intervention for missing custom classes or proprietary fonts. The template is not activated until compilation succeeds.

Where does /apply look for the currently active template?

The /apply command checks the guidance files 05-cv-templates.md and 06-cover-letter-templates.md for managed blocks delimited by <!-- BEGIN ACTIVE-TEMPLATE ... --> and <!-- END ACTIVE-TEMPLATE ... -->. If no active block exists, /apply falls back to the stock moderncv template for CVs and the cover.cls class for cover letters.

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