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

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 file serves as the canonical candidate profile—the single source of truth used by all agent runtimes—while AGENTS.md documents the agent-framework versioning and high-level architecture.

Standard open-source metadata files reside here as well:

• README.md – Project overview and quick-start guide
• SETUP.md – Detailed installation and environment-setup instructions
• SECURITY.md – Security policies and vulnerability reporting guidelines
• LICENSE, CHANGELOG.md, CONTRIBUTING.md – Standard governance and version tracking

Core Source Code and Utilities

The top-level 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 – PDF verification helper used in CI pipelines
• lint_skills.py – Validation for agent skill definitions
• 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 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 for specifications and TypeScript helpers at 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 – 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 for continuous integration and 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

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

Verifying PDF Documents for CI

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

Executing a Job-Portal Agent Skill

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

Running the Full Test Suite

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) and setup instructions (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 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 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 utility includes corresponding unit tests at tests/test_verify_pdf.py to ensure document integrity.

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