# How `/add-template` Registers Custom `.tex` Files with Mandatory Test Compilation > Learn how add-template registers custom .tex files with mandatory test compilation. Ensure robust LaTeX compilation for smoother job application generation. - Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search) - Tags: internals - Published: 2026-07-19 --- **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`](https://github.com/MadsLorentzen/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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//` or `templates/cover_letters//` 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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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: ```bash cd templates// && -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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/05-cv-templates.md) or [`06-cover-letter-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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:** ```bash /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:** ```bash /add-template --use awesome-cv ``` This updates the managed block in [`05-cv-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/05-cv-templates.md) to reference the pre-validated template. **Revert to default templates:** ```bash /add-template --use default ``` This removes the managed block, restoring the stock `moderncv` configuration. **List registered templates:** ```bash /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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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//` or `templates/cover_letters//` with their fonts, classes, and manifest. - **Managed activation**: The system uses managed blocks in [`05-cv-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/05-cv-templates.md) or [`06-cover-letter-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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//` for CVs or `templates/cover_letters//` for cover letters. Each directory contains the processed `template.tex`, a [`TEMPLATE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/05-cv-templates.md) or [`06-cover-letter-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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.