Resume Writing skill for Claude Code

#!/usr/bin/env python3
"""Lint a resume in plain text or Markdown for common technical-resume defects.

Standard library only. Checks contact details, section headings, bullet quality
(weak openers, first person, buzzwords, missing scope/result, length, repeated
verbs), characters and layouts that often confuse ATS parsers, and length by
word count. With --jd, lists frequent job-description terms the resume never
mentions (add them only if they are true).

Usage:
  python3 resume_lint.py resume.md
  python3 resume_lint.py resume.txt --jd job.txt --level senior

Exit code 1 if any FIX finding exists; CHECK findings are judgement calls.
Export a PDF or DOCX to text first (for example `pdftotext -layout cv.pdf cv.txt`)
to lint what a parser will actually see.
"""
from __future__ import annotations

import argparse
import re
import sys
from collections import Counter

WEAK_OPENERS = [
    "responsible for", "helped", "helping", "worked on", "working on", "assisted",
    "participated in", "involved in", "tasked with", "duties included", "in charge of",
    "contributed to", "was part of", "handled",
]
BUZZWORDS = [
    "results-driven", "results driven", "team player", "hard-working", "hardworking",
    "detail-oriented", "self-starter", "go-getter", "synergy", "rockstar", "ninja",
    "guru", "passionate", "dynamic", "think outside the box", "proven track record",
    "highly motivated", "best-in-class", "world-class", "wizard", "dedicated professional",
]
FIRST_PERSON = re.compile(r"\b(I|I'm|I've|me|my|mine|myself)\b")
BULLET = re.compile(r"^\s*(?:[-*•▪●–]|\d+[.)])\s+(.*)$")
HEADING = re.compile(r"^\s*(?:#{1,6}\s+)?([A-Z][A-Za-z &/]{2,40})\s*:?\s*$")
EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
PHONE = re.compile(r"\+?\d[\d ()./-]{7,}\d")
LINK = re.compile(r"(github\.com|gitlab\.com|linkedin\.com|https?://)", re.I)
NUMBERISH = re.compile(r"\d|\b(one|two|three|four|five|six|seven|eight|nine|ten|dozens?|hundreds?|thousands?|millions?)\b", re.I)
RISKY_CHARS = re.compile(r"[★☆✓✔✖■-◿☀-➿-\U0001f300-\U0001faff]")
STANDARD_SECTIONS = {"experience", "work experience", "professional experience", "employment",
                     "education", "skills", "technical skills", "projects", "summary",
                     "publications", "certifications", "open source", "awards", "volunteering"}
STOP = set("""a an and are as at be by for from has have in into is it its of on or our
that the their this to we will with you your who what which about across all also any can
etc more must new not other per such than them they using use work working within years year
team teams experience strong ability including role join looking build building help ensure
plus nice well based like etc."""
           .split())
WORDS_BY_LEVEL = {"junior": 600, "mid": 800, "senior": 1100, "staff": 1300}


def lint(text: str, jd: str | None, level: str) -> list[tuple[str, str]]:
    out: list[tuple[str, str]] = []
    lines = text.splitlines()
    words = re.findall(r"\b[\w'+#.-]+\b", text)

    if not EMAIL.search(text):
        out.append(("FIX", "No email address found; put contact details in the body, not a header/footer."))
    if not PHONE.search(text):
        out.append(("CHECK", "No phone number found (optional in some markets, expected in most)."))
    if not LINK.search(text):
        out.append(("CHECK", "No GitHub, LinkedIn, or portfolio link found."))

    headings = set()
    md_mode = any(l.startswith("#") for l in lines)
    seen_h1 = False
    for l in lines:
        st = l.strip()
        if md_mode:
            mh = re.match(r"^(#{1,6})\s+(.+)$", st)
            if not mh:
                continue
            if mh.group(1) == "#" and not seen_h1:
                seen_h1 = True  # the name line
                continue
            if mh.group(1) in ("#", "##") and len(mh.group(2).split()) <= 4:
                headings.add(mh.group(2).strip().rstrip(":").lower())
        elif (m := HEADING.match(st)) and len(st.split()) <= 4:
            label = m.group(1).strip()
            if label.isupper() or st.endswith(":") or label.lower() in STANDARD_SECTIONS:
                headings.add(label.lower())
    if not any("experience" in h or h == "employment" for h in headings):
        out.append(("FIX", "No 'Experience' heading found; ATS parsers look for standard section names."))
    odd = sorted(h for h in headings if h not in STANDARD_SECTIONS and not any(s in h for s in ("experience", "skill", "project")))
    if odd:
        out.append(("CHECK", f"Non-standard headings (fine if intentional): {', '.join(odd[:6])}"))

    limit = WORDS_BY_LEVEL[level]
    if len(words) > limit:
        out.append(("CHECK", f"{len(words)} words; typical ceiling for {level} is about {limit}. Cut older or weaker bullets."))

    verbs: Counter[str] = Counter()
    bullets = 0
    for n, line in enumerate(lines, 1):
        if RISKY_CHARS.search(line):
            out.append(("FIX", f"line {n}: icon/symbol character may not parse: {line.strip()[:60]}"))
        if "\t" in line.strip() or re.search(r"\S {4,}\S", line):
            out.append(("CHECK", f"line {n}: tab or wide gap suggests a column layout; parsers may merge columns."))
        m = BULLET.match(line)
        if not m:
            continue
        b = m.group(1).strip()
        bullets += 1
        low = b.lower()
        first = re.sub(r"[^a-z-]", "", low.split()[0]) if low.split() else ""
        if first:
            verbs[first] += 1
        for w in WEAK_OPENERS:
            if low.startswith(w):
                out.append(("FIX", f"line {n}: weak opener '{w}'; start with what you did: {b[:70]}"))
                break
        if FIRST_PERSON.search(b):
            out.append(("FIX", f"line {n}: first person in a bullet: {b[:70]}"))
        for w in BUZZWORDS:
            if w in low:
                out.append(("FIX", f"line {n}: buzzword '{w}' claims a trait instead of showing evidence."))
        if not NUMBERISH.search(b):
            out.append(("CHECK", f"line {n}: no scope or measurable result; ask the user for a real number, never invent one: {b[:60]}"))
        if len(b) > 220:
            out.append(("CHECK", f"line {n}: bullet is {len(b)} chars; aim for one to two lines (under ~200)."))
        elif len(b) < 35:
            out.append(("CHECK", f"line {n}: bullet is very short; add scope or result: {b}"))

    for verb, c in verbs.most_common():
        if c >= 4:
            out.append(("CHECK", f"'{verb}' opens {c} bullets; vary verbs so each names the specific action."))
    if bullets == 0:
        out.append(("CHECK", "No bullets detected; experience reads faster as 3-6 bullets per recent role."))

    if jd:
        res_low = text.lower()
        tokens = (t.rstrip(".-") for t in re.findall(r"[a-z][a-z0-9+#.-]{1,}", jd.lower()))
        jd_terms = Counter(t for t in tokens if t not in STOP and len(t) > 2)
        missing = [t for t, c in jd_terms.most_common(60) if c >= 2 and t not in res_low]
        if missing:
            out.append(("CHECK", "JD terms used 2+ times but absent from the resume (add only where true): "
                        + ", ".join(missing[:20])))
    return out


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("resume", help="resume as .txt or .md")
    ap.add_argument("--jd", help="job description as plain text")
    ap.add_argument("--level", choices=sorted(WORDS_BY_LEVEL), default="mid")
    a = ap.parse_args()
    try:
        text = open(a.resume, encoding="utf-8").read()
        jd = open(a.jd, encoding="utf-8").read() if a.jd else None
    except OSError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    findings = lint(text, jd, a.level)
    for sev, msg in findings:
        print(f"{sev:5} {msg}")
    fixes = sum(1 for s, _ in findings if s == "FIX")
    print(f"\n{a.resume}: {fixes} FIX, {len(findings) - fixes} CHECK")
    return 1 if fixes else 0


if __name__ == "__main__":
    sys.exit(main())