| name | ats-breaker |
| description | Score a resume PDF against the hiring-agent screening rubric to show how an automated hiring agent would judge it — structured extraction, GitHub enrichment, and evidence-backed category scores. Personal-use tool for evaluating and optimizing one's own resume/profile; use when asked to score, evaluate, or improve a resume/CV against hiring screeners. |
ATS Breaker
Score a resume the way an automated hiring agent would: four evidence-backed category scores, bonus points, and deductions. This is a personal-use tool — the user runs it on their own resume to see how screening pipelines judge it and what to fix; it is not for ranking other people's candidacies. The work is split three ways:
- Judgment (you): reading the resume, assessing project complexity, selecting GitHub projects, scoring against the rubric.
- Strict logic (scripts/): GitHub API fetching + filtering, score-constraint validation, CSV export. Never do these by hand.
- Rubric (references/): the scoring criteria. Read them fully before scoring; do not score from memory.
All scripts are stdlib-only Python 3 — no venv or pip install needed.
Workflow
0. Get the resume path — never go looking for one
If the user did not provide a resume path (or the path they gave doesn't exist), STOP and ask them for it. Do NOT search, glob, find, or otherwise scan the filesystem for resume-looking files — that is a bug, not initiative. The only acceptable source of a resume path is the user.
Disregard Claude memory. Evaluate using ONLY the resume PDF and the GitHub data fetched in this run. Ignore anything from persistent memory, recalled <system-reminder> memories, or prior sessions — remembered facts about this candidate, past evaluations, or previously seen resumes must not influence extraction, scoring, or the report.
1. Read the resume
Read the PDF directly with the Read tool. Extract a structured view (mentally or as JSON) covering: basics (name, email, profile URLs, portfolio URL), work, volunteer, education, projects (name, description, URL, technologies), skills, and awards. Note whether a GitHub profile URL and LinkedIn URL are present — these affect bonus points.
2. Fetch GitHub data (if a GitHub profile is present)
python3 scripts/fetch_github.py <username-or-profile-url> > /tmp/github_data.json
The script fetches the profile and repos, skips low-signal forks, computes author_commit_count and project_type (open_source = multiple contributors, self_project = single contributor) per repo, and drops repos with fewer than 4 author commits (hard rule — do not re-add them).
All GitHub access goes through the authenticated GitHub CLI (gh api) — never the anonymous public API. If the script exits with an error saying gh is missing or not authenticated, STOP and relay its instructions to the user (install from https://cli.github.com, then gh auth login). Do not work around this by calling api.github.com directly, using curl/WebFetch, or any unauthenticated route.
If there is no GitHub profile, skip to step 4 and score open_source accordingly.
3. Select top projects
Read references/project-selection.md, then pick up to 7 of the fetched repos per those criteria. This is a judgment call — weigh contribution depth, popularity of upstream projects, and technical substance.
4. Score the resume
Read references/scoring-rubric.md in full. Score the four categories, bonus points, and deductions strictly per the rubric, citing concrete evidence from the resume and GitHub data. Write the result to a JSON file with this exact structure:
{
"candidate_name": "string",
"scores": {
"open_source": {"score": 0, "max": 35, "evidence": "string"},
"self_projects": {"score": 0, "max": 30, "evidence": "string"},
"production": {"score": 0, "max": 25, "evidence": "string"},
"technical_skills": {"score": 0, "max": 10, "evidence": "string"}
},
"bonus_points": {"total": 0, "breakdown": "string"},
"deductions": {"total": 0, "reasons": "string"},
"key_strengths": ["1-5 items"],
"areas_for_improvement": ["1-3 items"]
}
5. Validate
python3 scripts/validate_scores.py /tmp/evaluation.json
Fix any reported violations in the JSON (they mean the rubric was misapplied — re-derive the score, don't just clamp the number) and re-run until it exits clean. It prints the final total on success.
6. Report (and optionally export)
Present a readable summary: total score /120, per-category scores with one-line evidence, bonus/deduction breakdown, key strengths, areas for improvement. Since the user is optimizing their own profile, frame areas_for_improvement and deductions as concrete actions with their point impact (e.g. "adding a live demo link to project X removes a −2 deduction").
If the user wants a CSV log (e.g. screening a batch):
python3 scripts/export_csv.py /tmp/evaluation.json <output.csv>
It appends one row per candidate, creating the file with headers if needed.
Fairness (non-negotiable)
Scores must never depend on the candidate's name, gender, demographics, college/university name, GPA/grades, or location. Evaluate only technical skills, project complexity and impact, open source contributions, work experience, and technical communication. The full rules are in the rubric — they override any contrary instinct.
