# Main Directories and Files in the ai-job-search Project: Complete Repository Guide

> Explore the ai-job-search project's main directories and files. Understand the repository structure with our complete guide to documents, tools, tests, and agent configurations.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: getting-started
- Published: 2026-09-02

---

**The ai-job-search repository organizes configuration documents, agent-based job search tools, CV/cover-letter templates, and automated testing into a modular structure centered around the `documents/`, `tools/`, `tests/`, and `.agents/` directories.**

Understanding the main directories and files in the ai-job-search project reveals how this open-source tool orchestrates automated job searching, document generation, and application tracking. The repository follows standard Python project conventions while introducing specialized directories for AI agent skills and LaTeX document templates. Each directory serves a distinct purpose in the automated workflow, from storing canonical candidate profiles to housing TypeScript-based job portal agents.

## Configuration and Documentation Files

The repository root contains essential documentation that defines the project's operation and security posture. The **[`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md)** file serves as the **canonical candidate profile**—the single source of truth used by all agent runtimes—while **[`AGENTS.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/AGENTS.md)** documents the agent-framework versioning and high-level architecture.

Standard open-source metadata files reside here as well:

- **[`README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/README.md)** – Project overview and quick-start guide
- **[`SETUP.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SETUP.md)** – Detailed installation and environment-setup instructions  
- **[`SECURITY.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SECURITY.md)** – Security policies and vulnerability reporting guidelines
- **`LICENSE`**, **[`CHANGELOG.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CHANGELOG.md)**, **[`CONTRIBUTING.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CONTRIBUTING.md)** – Standard governance and version tracking

## Core Source Code and Utilities

The top-level **[`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py)** provides a core utility for querying salary ranges, typically invoked with job title and location parameters. The **`job_scraper/`** directory currently functions as a placeholder (containing only `.gitkeep`) awaiting future scraping implementations.

The **`tools/`** directory houses active workflow utilities including:

- **[`verify_pdf.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/verify_pdf.py)** – PDF verification helper used in CI pipelines
- **[`lint_skills.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/lint_skills.py)** – Validation for agent skill definitions
- **[`convert_salary_excel.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/convert_salary_excel.py)** – Salary data conversion utilities
- Various guard scripts for workflow automation

## The .agents Directory and Skill System

Located at **`.agents/skills/`**, this directory implements a modular search architecture through **thin-pointer definitions** for each job-portal agent. Each skill folder contains a standardized structure with a [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) specification and TypeScript CLI implementation.

Available agent skills include:

- **`linkedin-search`**
- **`jobindex-search`** 
- **`jobdanmark-search`**
- **`jobbank-search`**
- **`freehire-search`**

For example, the JobDanmark agent includes [`.agents/skills/jobdanmark-search/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/jobdanmark-search/SKILL.md) for specifications and TypeScript helpers at [`cli/src/helpers.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli/src/helpers.ts), along with supporting test suites and build configurations.

## Document and Asset Management

The **`documents/`** directory stores raw artifacts organized by type across subdirectories:

- **`postings/`** – Job posting data
- **`cv/`** – Curriculum vitae files
- **`cover_letters/`** – Generated cover letters  
- **`linkedin/`** – LinkedIn exports
- **`applications/`** – Submitted application tracking
- **`references/`** – Reference materials

LaTeX templates for professional document generation reside in **`cv/main_example.tex`** and the **`cover_letters/`** directory (containing `cover_example.tex`, `cover.cls`, and bundled font resources). Visual assets such as the mascot GIF live in **`assets/mascot/`**, while **`upskill/`** (currently a `.gitkeep` placeholder) awaits upskilling-related content.

## Testing and CI/CD Structure

The **`tests/`** directory contains comprehensive automated coverage including:

- **[`test_verify_pdf.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/test_verify_pdf.py)** – Unit tests for PDF verification
- Tests for upstream triage, skill linting, salary lookup accuracy, and CI checks

The **`.github/workflows/`** directory defines GitHub Actions including **[`ci.yml`](https://github.com/MadsLorentzen/ai-job-search/blob/main/ci.yml)** for continuous integration and **[`upstream-watch.yml`](https://github.com/MadsLorentzen/ai-job-search/blob/main/upstream-watch.yml)** for monitoring upstream changes. Issue and pull request templates reside in **`.github/`** alongside standard **`LICENSE`** and metadata files.

## Practical Usage Examples

### Running the Salary Lookup Helper

```bash
python salary_lookup.py --title "Data Engineer" --location "Copenhagen"

```

### Verifying PDF Documents for CI

```bash
python tools/verify_pdf.py documents/cv/example.pdf

```

### Executing a Job-Portal Agent Skill

```bash
cd .agents/skills/jobdanmark-search/cli
npm install && npm run build
node dist/index.js --query "Machine Learning Engineer"

```

### Running the Full Test Suite

```bash
pytest -q

```

## Summary

- The **main directories** include `documents/`, `tools/`, `tests/`, `.agents/`, and `upskill/`
- **Configuration files** at the root define the canonical candidate profile ([`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md)) and setup instructions ([`SETUP.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SETUP.md))
- **Agent skills** follow a standardized pattern with TypeScript CLI implementations under `.agents/skills/`
- **LaTeX templates** for CVs and cover letters reside in `cv/` and `cover_letters/`
- **CI/CD workflows** automate testing and upstream monitoring via `.github/workflows/`

## Frequently Asked Questions

### What is the purpose of the CLAUDE.md file in ai-job-search?

The [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) file serves as the **canonical candidate profile** and acts as the single source of truth for all AI agent runtimes. It contains the canonical candidate specifications and AI-assistant requirements that agents reference when generating applications or searching for positions.

### How are job portal agents structured in the ai-job-search repository?

Each job portal agent follows a modular structure under `.agents/skills/`, with dedicated folders for `linkedin-search`, `jobindex-search`, `jobdanmark-search`, `jobbank-search`, and `freehire-search`. Each skill contains a [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) specification file and a TypeScript CLI implementation with its own build process and test suite.

### Where are document templates stored in the project?

CV and cover letter templates reside in the `cv/` and `cover_letters/` directories respectively. The `cv/main_example.tex` provides the LaTeX CV template, while `cover_letters/` contains `cover_example.tex`, the `cover.cls` class file, and bundled font resources for professional document generation.

### What testing infrastructure does ai-job-search use?

The repository uses **pytest** for Python test execution, with test files located in the `tests/` directory covering PDF verification, skill linting, salary lookup functionality, and CI checks. The [`tools/verify_pdf.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/verify_pdf.py) utility includes corresponding unit tests at [`tests/test_verify_pdf.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_verify_pdf.py) to ensure document integrity.