resume-jd-fit-scorer

name	resume-jd-fit-scorer
description	Use when a user wants to score how well a resume matches a job description, compare resume and JD keywords, find required/preferred requirement gaps, generate truthful optimization advice, or create a local interactive HTML resume-JD fit report. Works from text, Markdown, or extractable PDFs without API keys.

Resume JD Fit Scorer

Overview

Use this skill to evaluate a resume against a job description and produce:

• a deterministic JD fit score and gap report
• an Agent-generated recruiter semantic review that sits beside, not above, the deterministic score
• JD-specific clarification questions before resume rewriting
• truthful resume optimization advice
• a local single-file interactive HTML comparison report with matched and missing terms highlighted
• a concise non-interactive PDF summary report without the full JD/resume comparison section

The current implementation is a hybrid workflow. The scripts provide a v2 deterministic scorer that derives concepts, responsibilities, hard requirements, keyword coverage, and evidence strength from the current JD while keeping the original v1 fields for compatibility. The Agent may then add a recruiter-style semantic review that uses model judgment for paraphrase, expression-gap, and recruiter-risk analysis without changing the deterministic score. The algorithm design and limits are documented in references/algorithm-roadmap.md; the Agent review rules are documented in references/agent-semantic-review.md.

This is not a real ATS simulation. Describe it as "JD fit" or "resume-JD match", not as a guaranteed ATS score.

Inputs

Preferred inputs are plain text, Markdown, or extractable PDF:

• resume text or resume.md
• job description text or job.md
• resume or JD PDF files when the PDF contains selectable text

PDF support is built into score_match.py and render_report.py. It tries local Python PDF libraries first, including Codex Desktop bundled packages when available. Scanned/image-only PDFs need OCR first. DOCX is not parsed by these scripts; extract DOCX text first with document tools, then pass text/Markdown.

Resume inputs are locally redacted by default before scoring or rendering. The redaction removes common PII such as top-of-resume names, phone numbers, email addresses, URLs, contact lines, and obvious location/contact metadata. Use scripts/redact_pii.py directly when you need a standalone redacted Markdown file. Only pass --no-redact when the user explicitly asks to keep original PII.

Standard Workflow

1. Save the resume and JD to temporary Markdown files.
2. Run the deterministic scorer. Resume PII redaction is on by default:

   python scripts/score_match.py --resume resume.md --jd job.md --format json --output score.json
   

3. Generate JD-specific clarification questions from the score JSON:

   python scripts/generate_questions.py --score score.json --format markdown --output clarification-questions.md
   python scripts/generate_questions.py --score score.json --format json --output clarification-questions.json
   

4. Generate the Agent recruiter semantic review by following references/agent-semantic-review.md. Save it as semantic_review.json when you are rendering a report. The review is enabled by default in Agent-facing reports, but it must not modify score.json or the deterministic score.
5. If the user wants actual resume rewriting, ask the top 3-5 clarification questions before suggesting changes that rely on missing facts.
6. Render the local HTML report. It embeds the redacted resume text, not the original resume text:

   python scripts/render_report.py --resume resume.md --jd job.md --score score.json --questions clarification-questions.json --recruiter-review semantic_review.json --output jd-fit-report.html
   

7. Optionally render a concise PDF summary report. The PDF does not include the JD/resume side-by-side comparison or full resume/JD text:

   python scripts/render_pdf_report.py --score score.json --questions clarification-questions.json --recruiter-review semantic_review.json --output jd-fit-report.pdf
   

8. Read score.json, semantic_review.json, and clarification-questions.md, then summarize both the deterministic score and recruiter semantic review for the user.
9. Link the generated HTML/PDF file using its absolute path.

For a text-only report:

python scripts/score_match.py --resume resume.md --jd job.md --format markdown

PDF example:

python scripts/score_match.py --resume resume.pdf --jd job.pdf --format json --output score.json
python scripts/generate_questions.py --score score.json --format json --output clarification-questions.json
python scripts/render_report.py --resume resume.pdf --jd job.pdf --score score.json --questions clarification-questions.json --recruiter-review semantic_review.json --output jd-fit-report.html
python scripts/render_pdf_report.py --score score.json --questions clarification-questions.json --recruiter-review semantic_review.json --output jd-fit-report.pdf

Standalone redaction example:

python scripts/redact_pii.py --input resume.md --output resume.redacted.md

Report Rules

When writing the Agent report:

• Lead with the deterministic overall score, confidence level, and recruiter fit assessment when available.
• Include "优化简历前的提问" when the score JSON produces meaningful clarification questions.
• Use the resume/JD source language for clarification questions; English resume/JD should receive English questions and example answer scaffolds.
• Separate strong matches, expression gaps, true gaps, missing required requirements, weak evidence, safe optimization opportunities, and unsupported requirements.
• Do not claim this is an ATS score.
• Do not invent skills, companies, certifications, degrees, projects, dates, metrics, user counts, revenue, percentages, or other factual claims.
• Use "if true, add..." wording for facts that are not present in the resume.
• Suggest reframing existing evidence in JD language when the resume supports it.
• Treat user answers to clarification questions as candidate_context, not as automatic resume edits.
• Label suggestions that rely on user answers as candidate-confirmed context.
• Keep deterministic score and Agent recruiter review side by side; do not let the Agent rewrite overall_score.

Read references/suggestion-guide.md before writing detailed optimization advice. Read references/clarification-workflow.md before asking candidate questions or using answers in resume suggestions. Read references/agent-semantic-review.md before writing recruiter-style semantic fit analysis. Read references/scoring-rubric.md when the user asks how the score is calculated. Read references/algorithm-roadmap.md when the user asks about scoring limits, why a score seems wrong, ATS-style algorithms, or the v2 scoring design. Read references/html-report-spec.md when modifying or explaining the HTML report. Read references/pdf-report-spec.md when modifying or explaining the PDF report.

Explaining Scores

When explaining a score:

• Say the current score is a deterministic JD fit score, not an ATS score.
• Show the numeric score together with a fit level.
• Explain whether the deterministic result is driven by keyword coverage, required gaps, weak evidence, or missing explicit wording.
• If recruiter review is present, explain where the Agent sees semantic alignment, expression gaps, true gaps, or hiring risk.
• If a score looks unreasonable, inspect the v2 sub-scores: JD-derived concepts, responsibility matching, keyword coverage, evidence strength, and hard requirements.
• Do not claim the skill reproduces any vendor ATS ranking algorithm.

Output Shape

Final responses should include:

• deterministic overall score, confidence level, and recruiter fit assessment when available
• top 3-5 strong matches
• top clarification questions, when generated
• top required gaps
• top safe improvements
• unsupported requirements that should not be fabricated
• absolute path to the HTML/PDF report, if generated