How to Set Up and Use the Salary Benchmarking Tool in AI Job Search

The salary benchmarking tool uses salary_lookup.py to query a JSON data file (salary_data.json) and returns company-specific salary metrics using fuzzy matching, integrating seamlessly into the /apply workflow when the data file is present.

The MadsLorentzen/ai-job-search repository includes an optional salary benchmarking utility that provides compensation context during your job search. This tool operates independently from the core pipeline, meaning if the data file is missing, the rest of the application generation workflow continues without interruption.

Architecture Overview

The salary benchmarking system consists of four primary components working together to normalize, validate, and query compensation data.

• salary_data.json — Stores raw benchmark data with a top-level object containing a metadata section and a companies array. The exact schema is documented in tools/README_SALARY_TOOL.md.

• salary_lookup.py — Core script exposing three key functions: load_data() reads and validates the JSON, search_company() applies fuzzy matching via match_score_optimized(), and format_entry() renders readable output with categories, employee count, index values, and baseline comparisons.

• Fuzzy Matching Logic — Implemented in normalize(), anglicize(), extract_core_words(), and match_score_optimized() (lines 64-130 of salary_lookup.py). This handles Danish/Nordic characters, strips legal suffixes like "A/S" and "ApS", and evaluates word-level overlap to match company names despite spelling variations.

• tools/convert_salary_excel.py — Utility that transforms Excel workbooks into the required JSON format by detecting column types using pattern sets (COMPANY_PATTERNS, COUNT_PATTERNS, etc.) and outputting the structured data (lines 40-100).

Setting Up the Salary Data File

You have two methods for creating the required salary_data.json file.

Option A: Manual Creation

Write a JSON file following the schema specified in tools/README_SALARY_TOOL.md. Ensure the root object includes both metadata and companies keys.

Option B: Excel Conversion

Use the helper script to convert existing salary spreadsheets. This requires the openpyxl dependency.

python3 tools/convert_salary_excel.py input.xlsx output.json

The converter automatically identifies company names, cities, employee counts, and index values using regex patterns defined in convert_salary_excel.py.

Validating Your Data

Before running lookups, validate the JSON structure to catch malformed entries or duplicate company names.

python3 salary_lookup.py --validate

The collect_validation_issues function reports critical errors (missing required fields) and warnings (usability concerns). Passing validation ensures the fuzzy matching algorithms receive well-formed input.

Running Salary Lookups

Query the database using company names. The tool accepts several output formats and filtering options.

Basic fuzzy lookup:

python3 salary_lookup.py "Novo Nordisk"

Filter by specific city:

python3 salary_lookup.py "Ørsted" --city "Fredericia"

Machine-readable JSON output:

python3 salary_lookup.py "COWI" --json

List all companies in the dataset:

python3 salary_lookup.py --list-all

The search_company() function normalizes input strings, handles diacritics automatically, and returns the best match based on the optimized scoring algorithm.

Integration with the Job Application Workflow

Once salary_data.json exists in the project root, the /apply command automatically invokes the salary lookup for each target company. According to the command definitions in .claude/skills/job-application-assistant/, the tool checks for file presence before execution. If the file is absent, the lookup step is silently skipped, preserving pipeline functionality.

No additional configuration is required. The integration calls salary_lookup.py internally, displaying formatted benchmark data alongside the generated application materials.

Summary

• salary_lookup.py provides the core functionality through load_data(), search_company(), and format_entry().
• Optional operation — The tool only activates when salary_data.json is present; missing data does not break the /apply workflow.
• Fuzzy matching handles spelling variations, legal suffixes, and Nordic characters through normalization functions in lines 64-130.
• Excel conversion is available via tools/convert_salary_excel.py for migrating existing spreadsheet data.
• CLI interface supports validation, city filtering, JSON output, and listing all entries.

Frequently Asked Questions

What happens if I don't create the salary_data.json file?

The job application pipeline continues to function normally. When running /apply, the system detects the missing file and skips the salary lookup step entirely, allowing you to generate applications without benchmark data.

How does the fuzzy matching handle company name variations?

The algorithm in match_score_optimized() normalizes strings by removing legal suffixes (A/S, ApS, Ltd), converting Nordic characters to ASCII equivalents via anglicize(), and extracting core words. It then calculates word-level overlap scores, enabling matches despite typos or formatting differences like "Novo Nordisk A/S" versus "Novo Nordisk".

Can I use my existing Excel salary spreadsheet?

Yes. Run python3 tools/convert_salary_excel.py with your Excel file as input. The script in convert_salary_excel.py uses pattern matching to identify company, city, count, and index columns, then outputs properly formatted JSON ready for validation and lookup.

Where can I find the exact JSON schema for salary_data.json?

The complete schema specification resides in tools/README_SALARY_TOOL.md. The file expects a top-level object with metadata and companies arrays, where each company entry contains fields for name, city, employee count, and categorical index values.

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