AI Job Search Framework Architecture: A Modular Claude Code System for Autonomous Job Applications

The AI job search framework is a thin-pointer, modular system that transforms Claude Code into a full-stack job-application assistant through four tightly-coupled layers: candidate profile management, command orchestration, pluggable extension points, and infrastructure utilities.

This architecture enables autonomous sourcing, evaluation, and application generation without data duplication. As implemented in MadsLorentzen/ai-job-search, the framework treats Claude Code as the execution engine while maintaining a single source of truth across all operations.

The Four-Layer Architecture

The repository organizes functionality into distinct layers that separate configuration from execution, allowing the AI agent to operate deterministically while remaining extensible.

1. Core Candidate Profile & Evaluation

All personal data, career goals, and evaluation criteria reside in the candidate profile (CLAUDE.md) and the structured skill files under .claude/skills/job-application-assistant/. This directory contains seven ordered modules:

• 01-candidate-profile.md – Core biographical data
• 02-behavioral-profile.md – Interview responses and behavioral patterns
• 03-writing-style.md – Tone and stylistic preferences
• 04-job-evaluation.md – Scoring rubric and deal-breakers
• 05-cv-templates.md – CV structure definitions
• 06-cover-letter-templates.md – Cover letter blueprints
• 07-interview-prep.md – Interview preparation guidelines

These files constitute the single source of truth; every command reads from them but never duplicates data. The evaluation logic in 04-job-evaluation.md drives automated scoring in the /rank and /apply commands, defining weighted criteria and language gates that filter opportunities.

2. Command Layer (Claude Code Commands)

High-level workflows are exposed as Claude Code commands stored in .claude/commands/. Each file represents a self-contained markdown "script" that orchestrates agent workflows:

• setup.md – Onboarding interview that populates profile files
• scrape.md – Discovers and executes portal skills
• apply.md – Executes the drafter-reviewer-verifier loop
• rank.md – Batch-scores postings against evaluation criteria
• outcome.md – Tracks application responses
• interview.md – Generates interview preparation materials
• gmail-sync.md, notion-sync.md, html-report.md – Integration and reporting utilities

Each command interacts with the file system and can trigger external compilers (LaTeX or Typst) to generate PDF artifacts.

3. Extension Points

The framework supports three primary extension mechanisms without requiring code changes:

Portal Skills – Job board integrations live under .agents/skills/ (e.g., jobbank-search, jobindex-search, linkedin-search, freehire-search). Each skill follows a uniform contract: a search CLI executable, JSON or table output, and a SKILL.md description. The /scrape command automatically discovers installed skills using this contract.

Document Templates – Custom CV or cover-letter templates are registered via /add-template and stored under templates/. The framework supports any CLI-compilable toolchain, including LaTeX and Typst.

Evaluation Criteria – Users extend the fit model by editing skill files directly. Adding new deal-breakers to 04-job-evaluation.md immediately affects all future /rank and /apply operations.

4. Infrastructure & Utilities

State management and tooling reside in dedicated directories:

• State files – Scraper outputs, seen-job lists, and application archives live in job_scraper/, gmail_sync/, upskill/, and the central job_search_tracker.csv
• Helper scripts – The tools/ directory contains CI utilities like check_framework_version.py, lint_skills.py, and security_guards.py that enforce version bumps and security policies
• LaTeX assets – Base templates in cv/main_example.tex and cover_letters/cover_example.tex (using cover.cls) provide compilation baselines

Data Flow and Command Execution

The framework follows a linear pipeline where each stage consumes the single source of truth:

# 1. Initialize candidate profile

claude
/setup

# Populates CLAUDE.md and .claude/skills/* through interactive interview

# 2. Search configured portals

/scrape

# Discovers skills under .agents/skills/ and executes their search CLI

# 3. Rank opportunities (optional)

/rank

# Scores postings against 04-job-evaluation.md rubric

# 4. Apply to specific posting

/apply https://jobindex.dk/job/1234567

# Executes drafter → reviewer → PDF verification workflow

All commands execute inside Claude Code; the leading slash denotes the command syntax. The /apply command specifically implements a multi-agent loop: a drafter generates materials, a reviewer checks against profile constraints, and a verifier ensures PDF compilation succeeds.

Extending the Framework

Adding new capabilities requires only file-system operations:

1. New Job Portal: Create a directory under .agents/skills/[portal-name]/ containing a search executable and SKILL.md
2. Custom Template: Run /add-template to register LaTeX/Typst files in templates/
3. Modified Scoring: Edit 04-job-evaluation.md to add weighted criteria or deal-breakers

The tools/lint_skills.py script validates skill file syntax and settings during CI, ensuring extensions maintain the required contract.

Summary

• The AI job search framework operates as a thin pointer system where Claude Code executes commands against immutable profile files
• Configuration isolation ensures CLAUDE.md and .claude/skills/ serve as the single source of truth for all operations
• Pluggable architecture enables job portal integration through standardized skills in .agents/skills/ without core code modifications
• Document generation supports LaTeX and Typst workflows with automated drafter-reviewer verification
• State persistence uses CSV trackers and directory-based archives for full auditability

Frequently Asked Questions

What makes this AI job search framework different from traditional job boards?

Traditional platforms provide search interfaces but require manual application drafting. This framework automates the entire pipeline—from sourcing through .agents/skills/ integrations to generating tailored CVs via /apply—while maintaining your authentic voice through the profile files in .claude/skills/.

How does the framework ensure consistency across job applications?

All commands reference the single source of truth in CLAUDE.md and the numbered skill files (01-07). When /apply generates a cover letter, it pulls from 03-writing-style.md and 06-cover-letter-templates.md, ensuring every document reflects the same candidate profile without manual copy-pasting.

Can I add custom job portals to the framework?

Yes. The portal skills architecture requires only a directory under .agents/skills/ containing a search CLI tool and SKILL.md documentation. The /scrape command auto-discovers these skills, making the framework agnostic to specific job boards.

What file format is used for the candidate profile?

The primary profile lives in CLAUDE.md, with structured evaluation data in Markdown files under .claude/skills/job-application-assistant/. This text-based approach enables version control, diff tracking, and easy editing while the tools/lint_skills.py script enforces schema compliance.

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