How to Extend the AI-Job-Search Framework with Custom Document Templates

Use the /add-template command to register LaTeX or Typst templates by providing metadata, storing skeleton files with [PLACEHOLDER] tokens, and passing a mandatory compilation test that inserts an activation block into the framework's guidance files.

The AI-Job-Search framework ships with stock templates for CVs and cover letters, but you can extend it with custom document templates using a structured registration system. By utilizing the /add-template command defined in .claude/commands/add-template.md, you can integrate your own LaTeX or Typst toolchains without modifying core framework code. This guide explains the six-step architecture that ensures every custom template compiles correctly before activation.

Understanding the Template Registration Architecture

The framework implements a plug-and-play extension system through the /add-template command. According to the source code in .claude/commands/add-template.md, the command orchestrates a six-step workflow that handles everything from argument parsing to template activation, ensuring that only functional templates enter the production workflow.

The Six-Step Registration Workflow

The registration process follows these discrete steps:

1. Argument Parsing: Detects --list, --use <name>, or a file path to determine the workflow mode.
2. Metadata Collection: Captures template type (CV or cover letter), source extension, compile command, fonts, style rules, and page limits.
3. File Storage: Creates templates/cv/<name>/ or templates/cover_letters/<name>/ and stores the skeleton file, auxiliary class/style files, bundled fonts, and a TEMPLATE.md manifest.
4. Verification: Copies the skeleton to _compile_test.<ext>, fills placeholders with dummy data, and runs the declared compile command to verify PDF generation, page count, and layout.
5. Activation: Inserts a managed block (<!-- BEGIN ACTIVE-TEMPLATE … -->) into .claude/skills/job-application-assistant/05-cv-templates.md or 06-cover-letter-templates.md, which the /apply command reads.
6. Confirmation: Summarizes results and provides helper command references.

Registering a New Custom Template

To extend the framework with a custom LaTeX or Typst template, you must prepare your files and run the interactive registration command.

Preparing Your Template Files

Before running the command, ensure your template uses [PLACEHOLDER] tokens for dynamic content that the framework will replace during the /apply phase. Organize your source directory with:

• template.tex (or .typ) containing placeholder tokens for personal data
• Companion files like .cls, .sty, or configuration files required for compilation
• A fonts/ directory if using bundled fonts rather than system-wide installations

Running the /add-template Command

Execute the command and follow the interactive interview:

/add-template

During the interview, provide:

• Name: A unique identifier (e.g., awesome-cv)
• Source extension: .tex or .typ
• Compile command: Full command such as lualatex -interaction=nonstopmode <file>.tex
• Fonts: Description of font requirements and locations
• Page limit: Maximum pages allowed (e.g., 2 pages)

The command stores files in templates/cv/<name>/ or templates/cover_letters/<name>/ and generates a TEMPLATE.md manifest that stores the metadata for future activations.

The Mandatory Compilation Test

Step 4 performs a critical verification that prevents broken templates from entering the workflow. The framework:

• Copies your skeleton to a temporary _compile_test.<ext>
• Replaces [PLACEHOLDER] tokens with dummy data
• Executes your declared compile command
• Validates PDF output, page count, and visual layout against your specifications

If compilation fails or produces incorrect output, the registration aborts immediately, ensuring that only functional templates are activated.

Managing Existing Templates

Once registered, you can switch, list, or revert templates without re-running the full registration process.

Switching Between Templates

To activate a previously registered template:

/add-template --use awesome-cv

This extracts metadata from templates/cv/awesome-cv/TEMPLATE.md and replaces the managed block in .claude/skills/job-application-assistant/05-cv-templates.md or the cover letter equivalent. No further compilation occurs until the next /apply invocation.

Listing Available Templates

View all registered templates with their active status:

/add-template --list

This command globs templates/**/TEMPLATE.md and displays a formatted table showing name, type, source extension, toolchain, fonts, and whether the template is currently active.

Reverting to Stock Templates

To remove custom templates and restore default behavior:

/add-template --use default

This removes the managed block from 05-cv-templates.md or 06-cover-letter-templates.md, restoring the stock moderncv or cover.cls templates that ship with the repository.

Key Files and Directory Structure

Understanding where the framework stores configuration ensures you can troubleshoot effectively:

• .claude/commands/add-template.md: Contains the full command implementation, steps 0-6, argument parsing, storage logic, and verification procedures.
• .claude/skills/job-application-assistant/05-cv-templates.md: Guidance file for CVs; receives the ACTIVE-TEMPLATE managed block.
• .claude/skills/job-application-assistant/06-cover-letter-templates.md: Guidance file for cover letters; analogous to the CV file.
• templates/cv/<name>/TEMPLATE.md: Manifest storing metadata for each custom CV template.
• templates/cover_letters/<name>/TEMPLATE.md: Manifest for cover letter templates.
• templates/.../template.<ext>: The skeleton file with [PLACEHOLDER] tokens compiled by /apply.

The managed block approach ensures that .claude/skills/job-application-assistant/05-cv-templates.md and 06-cover-letter-templates.md are the only guidance files the framework mutates, preserving your manual edits elsewhere in the codebase.

Summary

• Use /add-template to register custom LaTeX or Typst templates through a six-step workflow defined in .claude/commands/add-template.md.
• Store templates in templates/cv/<name>/ or templates/cover_letters/<name>/ with a TEMPLATE.md manifest and [PLACEHOLDER] tokens in the skeleton file.
• Pass the mandatory compilation test that validates PDF generation before the activation block is inserted.
• Activate templates via managed blocks in 05-cv-templates.md or 06-cover-letter-templates.md that the /apply command reads.
• Switch between templates with --use, list all options with --list, and revert to stock behavior with --use default.

Frequently Asked Questions

What document formats does the framework support for custom templates?

The framework supports any PDF-generating toolchain, including LaTeX (.tex) and Typst (.typ). You define the specific compilation command during registration, allowing flexibility for lualatex, xelatex, pdflatex, or typst compile based on your template requirements.

Where does the framework store my custom template files?

Custom templates reside in templates/cv/<name>/ for CVs or templates/cover_letters/<name>/ for cover letters. Each directory contains the skeleton file, auxiliary class/style files, bundled fonts in a fonts/ subdirectory, and a TEMPLATE.md manifest that stores metadata for the activation block.

Why is there a mandatory test compile during registration?

The test compile ensures your template generates a valid PDF with correct page counts and layout before entering the workflow. The framework copies your skeleton to _compile_test.<ext>, fills [PLACEHOLDER] tokens with dummy data, and executes your compile command. Errors abort registration immediately, preventing broken templates from disrupting the /apply command.

Can I modify a template after registration?

Yes. Update the files in your template directory (e.g., templates/cv/awesome-cv/) and edit the TEMPLATE.md manifest if metadata changes. Re-run /add-template --use <name> to reactivate the updated template, which will refresh the managed block in the guidance files with the new configuration.

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