resume-evaluator

Resume Evaluator

Evaluate PDF resumes against job criteria and generate an interactive HTML comparison report with color-coded outcomes per requirement.

Supporting files

• Criteria extraction rules: references/criteria-extraction.md
• Evaluation rubric (yes/partial/no): references/evaluation-rubric.md
• Report generator script: scripts/generate_report.py

Step 1 — Resolve the resume folder

Ask the user for the folder path if not already provided. Use Glob to find all *.pdf files in that folder:

Glob("*.pdf", target_directory="<folder>")

Report how many PDFs were found. If none, stop and tell the user.

Step 2 — Gather evaluation criteria

Determine which input mode the user is using:

Mode A — Job description pasted: The user provided a raw job description. Follow the rules in references/criteria-extraction.md to extract a structured list of criteria. Present the extracted criteria to the user as a numbered list in this format:

1. [mandatory] <requirement text>
2. [preferred] <requirement text>
3. [neutral]   <requirement text>

Mode B — Criteria listed directly: The user listed requirements. Normalize each into the same format, assigning mandatory / preferred / neutral based on their wording (must/required → mandatory; nice to have/preferred → preferred; soft skills, unverifiable from resume → neutral).

Assign each criterion a short stable ID: r1, r2, r3, etc.

Ask the user to confirm, add, remove, or edit the criteria before proceeding. Do not continue until explicitly confirmed.

Step 3 — Evaluate each resume

For each PDF file found in Step 1:

1. Read the resume using the Read tool.
2. Extract candidate profile: Full name, email, phone, LinkedIn URL (if present).
3. Evaluate each criterion using the rubric in references/evaluation-rubric.md. For each criterion produce:
   • outcome: "yes", "partial", or "no"
   • analysis: 1–3 sentence explanation citing specific resume evidence.
4. Web search fallback: Only invoke WebSearch or WebFetch for a specific criterion when the resume does not contain enough information to evaluate it and external verification would materially change the outcome (e.g., verifying a degree program's curriculum, looking up a company's known tech stack, finding a public LinkedIn profile). Do not web-search by default.

Keep a running JSON structure for each evaluated candidate:

{
  "name": "Jane Smith",
  "email": "[email protected]",
  "phone": "+1 555-0100",
  "linkedin": "https://linkedin.com/in/janesmith",
  "file": "jane-smith.pdf",
  "requirements": {
    "r1": { "outcome": "yes", "analysis": "Candidate has 8 years of Node.js experience across 3 roles." },
    "r2": { "outcome": "partial", "analysis": "Mentions MySQL but no NoSQL databases are listed." },
    "r3": { "outcome": "no", "analysis": "No mention of TypeORM in the resume." }
  }
}

Step 4 — Write evaluations to disk

After processing all resumes, create the output directory and write the aggregated data:

mkdir -p ./.resume-eval

Write a JSON file ./.resume-eval/evaluations.json with this structure:

{
  "criteria": [
    { "id": "r1", "text": "5+ years of Node.js experience", "type": "mandatory" },
    { "id": "r2", "text": "Experience with NoSQL databases", "type": "preferred" }
  ],
  "candidates": [
    { ...candidate object from Step 3... }
  ]
}

Step 5 — Generate the HTML report

Run the report generator:

python3 ${CLAUDE_SKILL_DIR}/scripts/generate_report.py ./.resume-eval/evaluations.json ./resume-report.html

Report the absolute path of the generated file to the user. The script opens it automatically in the default browser.

Guidelines

• Evaluate criteria in the order: mandatory first, then preferred, then neutral.
• Be strict with time-based requirements: count months precisely using the experience section. When start/end dates are missing, default to partial, not yes.
• Do not invent resume content. If something is not mentioned, the default outcome is no unless partial evidence exists.
• Neutral criteria (soft skills, attitude, "passion for X") should still be evaluated where the resume provides evidence — look for relevant project descriptions, achievements, or stated interests.
• Keep the analysis concise and factual — cite role titles, company names, years, or specific technologies as anchors.