Skip to content
Back to search

jobhuntbot

SkillWorks with Claude CodeGitHub

"A reusable job application workflow for Codex and other AI agents. Use when a user wants to set up or run an AI-assisted job search system: collecting a candidate profile, creating an application dashboard, defining screening and resume-routing rules, finding and ranking job leads, applying to jobs within explicit safety boundaries, recording outcomes, triaging blockers, or iterating a job application workflow."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/danielpan12--jobhuntbot/badge.svg)](/listings/danielpan12--jobhuntbot)

HTML

<a href="/listings/danielpan12--jobhuntbot"><img src="/api/listings/danielpan12--jobhuntbot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Download or clone this repo** to your machine (or point your coding agent at the GitHub URL).

2. **Give the agent browser access — required for actually filling out applications.** Research/lead-finding (step 5 below) can use public web sources, but step 7 in `SKILL.md` (filling out real forms and uploading a resume) needs the agent to control a real browser. Set this up once, before you ask it to apply to anything: - **Claude Code**: add the Playwright MCP server so the agent gets browser tools (navigate, click, type, fill forms, upload files, take snapshots): ```bash claude mcp add playwright npx '@playwright/mcp@latest' ``` Restart/reopen your Claude Code session afterward so it picks up the new tools. - **Codex CLI or another agent**: check whether it has an equivalent browser-automation or computer-use capability (a Playwright-based MCP server, a built-in browser tool, etc.) and enable it the way that agent documents. Without it, the agent can still do everything up through lead-finding and drafting — it just can't open a real application page and submit it for you. - You can skip this entirely if you only want the lead-finding/dashboard-tracking half of the workflow and plan to submit applications yourself.

3. **Create a separate private working directory and put your materials there.** Keep this public repository as the reusable package. Ask the agent to copy its templates and dashboard into the private workspace, then place your resume (ideally an editable DOCX/Markdown source), transcript and project notes in that workspace's `my-materials/` folder. `.gitignore` helps with untracked files but cannot protect changes to already tracked CSVs or templates. Then tell the agent where to look:

   My resume, transcript, and project notes are in my-materials/. Read them before we start.

4. **Start a session with your AI coding agent** (Claude Code, Codex CLI, or any agent that can read local files) in this folder and say:

   Use SKILL.md to initialize my job search workflow.

The agent will ask a small set of minimum-viable questions and create personal copies such as `candidate_profile.json` and `application_rules.md` in the private workspace, using the source materials and your answers. The public `templates/` files stay empty. Missing sensitive facts remain unknown until you confirm them.

5. **Run a safe first trial.** Tell the agent explicitly:

   Do a lead-finding-only trial: find 3-5 jobs, classify them, update the dashboard, and don't open application flows or submit anything.

This step only needs web search, not the browser automation from step 2 — it's the recommended way to see the workflow work before it touches any real application form.

6. **Open the dashboard** to see progress: - Windows: double-click `dashboard/start-dashboard.bat` - macOS/Linux: run `dashboard/start-dashboard.sh` (requires [Node.js](https://nodejs.org/) installed; `chmod +x` it once if needed) - This opens `http://localhost:8420/dashboard.html` in your browser. It reads the CSVs in the same folder live — every refresh shows the latest state, no build step, no external server, nothing leaves your machine.

7. **Keep applying with the agent's help**, one company at a time — this is where the browser automation from step 2 actually gets used. It updates `job_pool.csv`, `application_log.csv`, `blocker_queue.csv`, and `follow_up.csv` as it goes, and asks for submission approval only when the current application does not already have it.

Faster Form Filling

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 144 lines
  1. ---
  2. name: jobhuntbot
  3. description: "A reusable job application workflow for Codex and other AI agents. Use when a user wants to set up or run an AI-assisted job search system: collecting a candidate profile, creating an application dashboard, defining screening and resume-routing rules, finding and ranking job leads, applying to jobs within explicit safety boundaries, recording outcomes, triaging blockers, or iterating a job application workflow."
  4. ---
  5. # JobHuntBot
  6. JobHuntBot is a job application operating workflow for AI agents. It helps users turn job searching into a repeatable system: profile, dashboard, screening rules, resume strategy, application execution, blocker triage, and follow-up.
  7. ## Core Contract
  8. Optimize for truthful, traceable, interview-generating applications, not blind volume.
  9. Treat setup as an agent-led onboarding flow, not a user homework packet. Ask only for the minimum information needed to start safely, create drafts/templates for the user, then iterate after the first trial run.
  10. Before searching or applying, make sure the user has:
  11. 1. A candidate profile.
  12. 2. A dashboard or workbook for tracking outcomes.
  13. 3. Application screening rules.
  14. 4. A resume strategy.
  15. 5. Clear safety boundaries for browser automation and form answers.
  16. If any source is missing, initialize it first. Do not guess identity, legal, work authorization, compensation, current employment, sponsorship, relocation, or other high-impact facts.
  17. Once an application is authorized, complete all reachable fields supported by confirmed facts before requesting missing information. A missing answer or failed widget normally blocks that field or module, not the whole application. Follow the scope, consolidated handoff and resume rules in `references/application-playbook.md`; reuse existing authorization within its company/role/material scope.
  18. ## Workflow
  19. ### 1. Initialize the System
  20. Read `references/setup-workflow.md` when:
  21. - The user is installing JobHuntBot for the first time.
  22. - The user asks to create a profile, dashboard, rules, templates, or GitHub-ready setup.
  23. - The user has not provided enough information for safe applications.
  24. Use the templates in `templates/` to create user-owned files:
  25. - `candidate_profile.template.json`
  26. - `application_rules.template.md`
  27. - `resume_routing.template.md`
  28. - `answer_bank.template.md`
  29. - `experience_bank.template.md`
  30. - `dashboard-template/*.csv`
  31. ### 2. Confirm the Company and Research the Opening
  32. Read `references/lead-discovery.md` before finding, comparing, excluding or rechecking openings. Work one company at a time, checking the official portal with targeted and broader searches. Verify the full JD and actual eligibility text, retain official role URLs, and record coverage limits rather than equating an empty filter with no openings.
  33. Reuse existing company categories. For a new company, apply the user's category definitions and record sourced recommendation provenance before adding its pool records. Use `record_type=company_summary` for company-level research and `role` for actual jobs. Update `cohort_match_status` explicitly as `Yes`, `No` or `Unclear` for active research rows; do not infer it from notes or inherit company-wide eligibility for every role.
  34. Preserve prior rejected attempts while considering other permitted roles or cycles. Verify current employer limits and available slots before applying again; a rejection does not automatically restore a slot. Research and workflow repair do not authorize a new application or publication.
  35. ### 3. Screen Before Applying
  36. Read the user's current application rules and compare actual duties, verified experience fit, work arrangements, career and business context, compensation and feasibility. A title, keyword or workplace setting alone must not determine fit. Use the configured recruiting-season policy: freshness affects urgency, while an older posting can remain open and relevant.
  37. Skip or defer roles that violate the user's rules, are clearly overleveled, are closed or duplicate, require unsupported work authorization, need missing materials, or involve long account-heavy flows with weak fit.
  38. This is a research/prioritization rule. Once the user authorizes filling a target, missing materials do not automatically cancel the fill pass: complete independent reachable sections, then report the affected scope and remaining prerequisites under the playbook.
  39. ### 4. Compare Specific Positions and Resume Variants
  40. Compare multiple genuine matches at the company when available before filling. Present exact title/ID, team, city, official URL, eligibility, concrete experience evidence and gaps, work arrangements, career/business context, compensation basis and recommended resume. Report fewer matches honestly rather than padding with unrelated roles. Label facts, inferences and unknowns, following `references/lead-discovery.md`.
  41. If a company limits applicants to one or two total submissions in the cycle, say so before the user picks. Present the role, city and recommended resume together when the choice is still open. Reuse an approved pairing or explicitly delegated selection; do not re-ask during filling or resuming. A routing recommendation alone does not authorize an application.
  42. ### 5. Match Experience to the Role
  43. Read the chosen resume before creating structured internship and project entries. Those entries should mirror the resume and any explicit user-required additions; do not independently choose a shorter JD-matched subset from the experience bank. State the intended entries in a brief progress notice and continue the already authorized work. If the site caps entries, reuse an applicable authorized selection or queue that choice while completing independent sections; do not silently omit experiences.
  44. Use `experience_bank.md` earlier to compare resume variants and later to support tailored free-text answers. Emphasize the verified experiences that best fit the specific JD and field length; a relevance matrix is not permission to invent facts or remove structured resume entries. Self-evaluation and cover-letter text should connect the candidate's evidence to this role rather than dump a generic biography. After submission, record which entries and materials were actually used.
  45. ### 6. Route the Resume Strategy
  46. Use the user's chosen strategy:
  47. - Precision mode: screen for high-fit jobs first, then tailor resume/materials before applying.
  48. - Volume mode: use prebuilt resume variants by role family and move quickly.
  49. Default to Volume mode unless the user explicitly asks for Precision. Individual high-fit roles can be promoted from Volume to Precision.
  50. Preserve an approved role/resume pairing. Do not silently switch files during filling; resolve a genuinely new material choice together with other outstanding decisions.
  51. Whenever a resume is created or tailored for a posting, treat these as acceptance criteria:
  52. - Select the internships and projects that best support the JD from the candidate's verified experience inventory; preserve the chosen entries' material facts and avoid repetitive evidence.
  53. - Write every internship and project entry using STAR. Across the entry's bullets, make the situation/task, the candidate's specific actions, and the result explicit. Do not invent a result or metric; if the source material cannot support a complete STAR account, obtain the missing fact or use an honest qualitative outcome.
  54. - Sort education, internships, and projects independently in reverse chronological order. An ongoing entry comes first; otherwise compare end date, then start date when end dates tie. Do not reorder these sections by JD relevance.
  55. - Deliver a PDF that is exactly one page and visually fills that page without overflow or a conspicuously empty bottom area. Iterate on wording, the number and length of non-duplicative bullets, spacing, and readable typography; do not omit material information merely to fit or repeat content merely to fill space.
  56. - Render the final PDF, verify that its page count is exactly one, and inspect the rendered page before considering the tailored resume complete.
  57. Never fabricate experience, credentials, degrees, employers, dates, work authorization, or portfolio artifacts.
  58. ### 7. Fill Out the Application
  59. Read `references/application-playbook.md` before operating browser-based applications, LinkedIn Easy Apply, Simplify, Greenhouse, Lever, Ashby, Workday, or other ATS flows.
  60. Read the user's `application_rules.md` for current execution preferences. Default to the playbook's **Batch Filling & Consolidated Verification**: prepare confirmed answers once, fill the largest predictable group of fields in one tool call, then inspect the saved module together and repair only discrepancies. Group adjacent simple modules when the page and controls remain predictable; avoid a separate model turn or full-page read after each field.
  61. On a new form, prefer uploading the chosen resume first and auditing the parsed entries together. Avoid re-parsing an already repaired form unless necessary, since parsing can overwrite corrections. Fill whatever you confidently can from `candidate_profile.json`, `resume_routing.md`, `experience_bank.md` (for relevant-experience/self-evaluation fields, using the combo picked in step 5), and `answer_bank.md`. Collect questions together for anything on the `never_guess` list, anything requiring a subjective call, or anything not backed by the résumé or profile; leave those fields pending while filling independent confirmed fields. Verify saved-account bio text before retaining it in a real submission.
  62. Do not bypass verification, login, permission or other site controls. Queue local missing facts, materials and widget failures while filling independent reachable sections. Hand off immediately only when a whole-application gate leaves no further authorized form work reachable; report uninspected pages honestly. Use `templates/application-progress.template.json` for a private resumable draft, separate from disposable working files.
  63. ### 8. Verify the Application and Submission Authorization
  64. Before final submission, verify the whole reachable application and show a concise summary of company, role, resume, actual experiences, key answers and gaps. Reuse existing explicit submission authorization for this unchanged application, including “complete it and submit,” once required facts/materials and checks are complete. Otherwise request approval together with the consolidated missing-information review; permission to fill or an informative preview is not submission consent. A consequential change outside the authorization needs a focused decision. Verify real confirmation evidence before recording `Submitted`; inspect application history before retrying an uncertain submission to avoid duplicates.
  65. ### 9. Sync Everything — Dashboard and Profile
  66. The bundled dashboard has separate Applied, Pending, Rejected and Offer views plus a consolidated action queue. Pending groups active leads by company and excludes companies with submitted or ended history; this display rule does not exclude permitted additional applications from research. The other progress views count role records, not `company_summary` rows. The action queue combines open/retry-later blockers and `Needs user` / `Blocked` jobs, including gaps at companies already applied to.
  67. Every job lead or attempt must end in one of these states:
  68. - `Submitted`: explicit confirmation was seen.
  69. - `Skipped`: not worth applying, with reason.
  70. - `Blocked`: automation could not proceed, with blocker and next step.
  71. - `Needs user`: user must provide a missing high-impact fact, complete CAPTCHA/login/upload, answer a sensitive question, or make a required judgment before the agent can decide.
  72. - `Pending`: selected for later action because it appears worth reviewing or applying after known prerequisites are satisfied.
  73. - `Rejected`: a confirmed rejection for this application; keep its history.
  74. - `Offer`: the user or reliable evidence confirms an offer was received. Passing an interview stage is not an offer, and receipt is not acceptance.
  75. Count only confirmed submissions. Saved jobs, trackers, autofill badges, or "quick apply" labels do not count.
  76. For a first trial or demo run, default to lead finding only: find, screen, classify, and update the dashboard without opening real application flows or submitting anything. In lead-finding-only runs, update `job_pool`, `daily_dashboard`, `blocker_queue`, and `automation_rules` as needed; leave `application_log` empty because no application attempt occurred.
  77. For an existing tracker, preserve historical application logs during lead-only work. Record an externally reported offer or rejection with its confirmation source and known facts; do not fabricate a submission, receipt date, acceptance or calendar event. Preserve the original compensation wording and label any annualized calculation and unknown assumptions.
  78. For a real submission, update the same dashboard files (`job_pool` status, `application_log` with the resume version/evidence/answers used, `follow_up` if a next step is already known, `daily_dashboard` summary) *and* the candidate's own profile: if filling the form surfaced a fact that isn't already in `candidate_profile.json` (a new internship detail, an updated exam/grade result, a preference the user stated on the spot, anything), write it back into the profile before moving on — don't let it live only in the one application you just filed. Same discipline as everywhere else in this skill: record what you've confirmed, don't invent what you haven't.
  79. When recording a submission in `application_log`, also capture the full job description text (responsibilities and requirements) from the official posting into the `job_description` field, copied verbatim from the source — not summarized or paraphrased. This is what makes later interview prep possible without having to re-find a posting that may since have been taken down.
  80. For the bundled CSV dashboard, use `dashboard/csv-store.js` snapshot reads and atomic writes, preserve unrelated rows, and match dates/JDs by exact role rather than borrowing another role at the company. Run `node dashboard/scripts/audit-data.js` after data edits and `node dashboard/scripts/company-categories.js --check` after discovery/classification changes. Use the relevant dashboard tests for code changes. Report historical gaps without inventing missing evidence.
  81. ### 10. Learn From Blockers
  82. After each run, summarize blockers and convert repeated issues into rules. JobHuntBot should improve through use: address matching, dropdown handling, resume upload checks, account/session checks, and ATS-specific lessons belong in the dashboard and rules.
  83. ## Safety
  84. Read `references/safety-and-boundaries.md` when the user asks about automation limits, CAPTCHA, email verification, account login, privacy, public sharing, or what should not be included in a repo.
  85. Do not publish or copy private resumes, phone numbers, emails, addresses, immigration documents, application history, browser sessions, cookies, OTPs, or user-specific secrets into a public JobHuntBot package.
README.md · README · 255 lines
  1. # JobHuntBot
  2. **English** below · [中文](#中文说明) 在下方
  3. An agent-led job application workflow and local progress-tracking dashboard. It works with any AI coding agent that can read a file and follow written instructions (Claude Code, Codex CLI, Cursor, etc.) — there's no special integration required, you just point the agent at `SKILL.md` and tell it to follow the workflow. It turns scattered job hunting into a repeatable system: candidate profile, screening rules, resume strategy, application execution, blocker triage, follow-up, and a browser-based dashboard to see it all at a glance.
  4. This is not a one-click auto-apply bot. It is a structured workflow plus explicit safety boundaries — the agent fills all reachable, confirmed fields before collecting missing facts in one handoff. Final submission requires authorization, and an existing authorization remains valid within its stated scope.
  5. ## What's in this repo
  6. ```
  7. SKILL.md Core agent workflow and safety contract — start here
  8. references/
  9. setup-workflow.md Step-by-step onboarding the agent should follow
  10. application-playbook.md Browser/ATS handling playbook (forms, uploads, CAPTCHA, etc.)
  11. lead-discovery.md Official-source coverage, role comparison and evidence checks
  12. safety-and-boundaries.md Privacy, consent, and what should never be automated
  13. templates/
  14. candidate_profile.template.json Your facts: identity, contact, work authorization, targets
  15. application_rules.template.md What to prioritize, consider, skip, or hand off to you
  16. resume_routing.template.md Which resume/version to use for which role family
  17. answer_bank.template.md Reusable truthful answers for common application questions
  18. experience_bank.template.md Which internships/projects to feature per role family and JD
  19. application-progress.template.json Private checkpoint for resuming unfinished forms
  20. dashboard-template/ Empty CSV dashboard + field reference (see its README.md)
  21. dashboard/ A ready-to-run local dashboard (same CSV schema as the template)
  22. server.js Local Node.js server with validated outcome/calendar updates
  23. dashboard.html The dashboard UI itself
  24. csv-store.js / dashboard-model.js CSV integrity and dashboard counting/matching rules
  25. scripts/ / tests/ Data checks and regression tests
  26. start-dashboard.bat / .sh One-click launcher (Windows / macOS-Linux)
  27. *.csv Empty starter data files
  28. ```
  29. ## Quick Start
  30. 1. **Download or clone this repo** to your machine (or point your coding agent at the GitHub URL).
  31. 2. **Give the agent browser access — required for actually filling out applications.** Research/lead-finding (step 5 below) can use public web sources, but step 7 in `SKILL.md` (filling out real forms and uploading a resume) needs the agent to control a real browser. Set this up once, before you ask it to apply to anything:
  32. - **Claude Code**: add the Playwright MCP server so the agent gets browser tools (navigate, click, type, fill forms, upload files, take snapshots):
  33. ```bash
  34. claude mcp add playwright npx '@playwright/mcp@latest'
  35. ```
  36. Restart/reopen your Claude Code session afterward so it picks up the new tools.
  37. - **Codex CLI or another agent**: check whether it has an equivalent browser-automation or computer-use capability (a Playwright-based MCP server, a built-in browser tool, etc.) and enable it the way that agent documents. Without it, the agent can still do everything up through lead-finding and drafting — it just can't open a real application page and submit it for you.
  38. - You can skip this entirely if you only want the lead-finding/dashboard-tracking half of the workflow and plan to submit applications yourself.
  39. 3. **Create a separate private working directory and put your materials there.** Keep this public repository as the reusable package. Ask the agent to copy its templates and dashboard into the private workspace, then place your resume (ideally an editable DOCX/Markdown source), transcript and project notes in that workspace's `my-materials/` folder. `.gitignore` helps with untracked files but cannot protect changes to already tracked CSVs or templates. Then tell the agent where to look:
  40. ```text
  41. My resume, transcript, and project notes are in my-materials/. Read them before we start.
  42. ```
  43. 4. **Start a session with your AI coding agent** (Claude Code, Codex CLI, or any agent that can read local files) in this folder and say:
  44. ```text
  45. Use SKILL.md to initialize my job search workflow.
  46. ```
  47. The agent will ask a small set of minimum-viable questions and create personal copies such as `candidate_profile.json` and `application_rules.md` in the private workspace, using the source materials and your answers. The public `templates/` files stay empty. Missing sensitive facts remain unknown until you confirm them.
  48. 5. **Run a safe first trial.** Tell the agent explicitly:
  49. ```text
  50. Do a lead-finding-only trial: find 3-5 jobs, classify them, update the dashboard, and don't open application flows or submit anything.
  51. ```
  52. This step only needs web search, not the browser automation from step 2 — it's the recommended way to see the workflow work before it touches any real application form.
  53. 6. **Open the dashboard** to see progress:
  54. - Windows: double-click `dashboard/start-dashboard.bat`
  55. - macOS/Linux: run `dashboard/start-dashboard.sh` (requires [Node.js](https://nodejs.org/) installed; `chmod +x` it once if needed)
  56. - This opens `http://localhost:8420/dashboard.html` in your browser. It reads the CSVs in the same folder live — every refresh shows the latest state, no build step, no external server, nothing leaves your machine.
  57. 7. **Keep applying with the agent's help**, one company at a time — this is where the browser automation from step 2 actually gets used. It updates `job_pool.csv`, `application_log.csv`, `blocker_queue.csv`, and `follow_up.csv` as it goes, and asks for submission approval only when the current application does not already have it.
  58. ### Faster Form Filling
  59. The workflow defaults to filling a complete form section, or several predictable adjacent sections, in one browser-tool call. The agent prepares confirmed answers once, checks saved values and validation errors together, and repairs only differences. If a batch is interrupted, it checks what was saved and resumes from unfinished fields. Dependent controls still wait for real options. Local gaps do not stop independent sections; inaccessible pages and unsaved fields are recorded honestly. Existing submission authorization is reused within scope. See [the application playbook](references/application-playbook.md#batch-filling--consolidated-verification) for the execution rules.
  60. ## The Dashboard
  61. The dashboard is a static HTML page + a tiny local Node server (no framework, no build, no external dependencies). It presents four progress views plus a consolidated action queue:
  62. - **Applied** — rows with `status = Submitted`, with follow-up timeline and how each was submitted. Expand a card and click **"记录投递结果" (Record outcome)** at the bottom, then **"拿到 Offer" (Offer received)** or **"已挂" (Rejected)** — this writes the new status straight back into `job_pool.csv` and the job moves to the matching Offer or Rejected view on next refresh. (The local server also confirms the row still matches company + job title before writing, in case the agent updated the same file in the meantime.)
  63. - **Pending** — companies with `status = Pending` / `Needs user` roles and no submitted/ended history, grouped by company and split into "confirmed open, not yet applied" vs. "not open / unclear" using the `cohort_match_status` column (see `templates/dashboard-template/README.md` for the full field reference).
  64. - **Rejected** — rows marked `Rejected`, with its own count, search and category filter.
  65. - **Offer received** — rows marked `Offer`, separately counted and filtered; passing an interview stage is not an offer.
  66. The **Action queue** combines open `blocker_queue.csv` items with `Needs user` / `Blocked` roles, preserving multiple gaps and post-submission corrections. Applied/Rejected/Offer counts exclude `record_type=company_summary`; dates and JD match the exact role. CSV writes validate snapshots and roll back failed multi-file updates.
  67. Below the views, a **7-day calendar** shows upcoming events (tests, interviews, anything you schedule) for jobs in the Applied bucket. Click **"+ 添加日程"** to add one: pick the date/time, search for the company/job from your already-submitted list, and type the event content freely (e.g. "二轮面试", "笔试") — whatever you type is used verbatim, since every company's process reads differently. Saving an event also stamps that job's `current_stage` in `job_pool.csv` with the same text, so the Applied card immediately shows it. Events can be edited or deleted later from the calendar; deleting one does not revert `current_stage` (there's no reliable "previous stage" to roll back to — edit it manually if needed). Calendar data lives in `follow_up.csv`.
  68. You can open the CSVs directly in Excel/Google Sheets/Numbers too — the dashboard is a view on the same files, with writes limited to the outcome and calendar actions above.
  69. **Important:** open the dashboard through `start-dashboard.bat`/`start-dashboard.sh`, not by double-clicking `dashboard.html` directly — the page fetches the CSVs over `http://`, which browsers block when a file is opened directly from disk.
  70. ## Safety Boundaries (read `references/safety-and-boundaries.md` for the full list)
  71. The agent should never:
  72. - Guess identity, work authorization, compensation, or legal facts.
  73. - Bypass CAPTCHA, Cloudflare, or anti-bot checks, or auto-login through unknown accounts/2FA.
  74. - Fabricate experience, credentials, or portfolio work.
  75. - Count a saved/tracked job as a submitted application.
  76. - Click final submit without authorization covering the current application; an unchanged, already authorized submission does not require another confirmation.
  77. ## Privacy
  78. This repo ships empty templates and an empty dashboard — no personal data. Once you fill in `candidate_profile.json`, `job_pool.csv`, and the rest with your own information, **do not publish that filled-in copy publicly** (don't push your personal fork's data to a public repo, don't screenshot it into an issue, etc.). Keep your working copy private; only the workflow/template layer is meant to be shared.
  79. ## Validation and Public Releases
  80. From the repository root:
  81. ```sh
  82. node scripts/check-public-package.js
  83. node --test scripts/check-public-package.test.js
  84. node --test dashboard/tests/*.test.js
  85. ```
  86. The public-package check rejects filled starter databases and forbidden private artifacts. Inspect the staged diff as well; no automated check can prove that free text or Git history is anonymous. The regression suite covers CSV parsing/atomic writes, role matching, outcome separation and the action queue. Its browser test runs when Playwright and a compatible browser are available; otherwise that test is skipped. CI runs the public-package check and available tests.
  87. After editing data in a private operational copy, use `node dashboard/scripts/audit-data.js` and `node dashboard/scripts/company-categories.js --check`. Preserve historical gaps explicitly instead of inventing facts to clear warnings.
  88. ## License
  89. MIT — see `LICENSE`. This project is a renamed/adapted derivative of Yvonne He's open-source *ApplyPilot* workflow; the original copyright notice is preserved in `LICENSE` (as required by its MIT license) alongside a copyright line for this adaptation.
  90. ---
  91. ## 中文说明
  92. 一个由 AI Agent 驱动的求职投递工作流,配一个本地的求职进度追踪看板。它适用于任何能读文件、能听懂并执行文字指令的编程 Agent(Claude Code、Codex CLI、Cursor 等)——不需要任何特殊的官方集成,你只需要让 Agent 打开 `SKILL.md` 并按照里面的工作流执行即可。它会把零散的投递过程变成一套可重复的系统:候选人信息、筛选规则、简历策略、投递执行、卡点处理、后续跟进,外加一个网页版进度看板。
  93. 这不是一个"一键自动海投"的机器人。它是一套结构化流程 + 明确的安全边界——先填完所有可达且已确认的内容,再集中询问未知事实。最终提交需有授权;在范围不变时沿用已经取得的授权,不重复确认。
  94. ### 这个仓库里有什么
  95. ```
  96. SKILL.md Agent 核心工作流与安全约定 —— 从这里开始
  97. references/
  98. setup-workflow.md Agent 应遵循的分步初始化流程
  99. application-playbook.md 浏览器/ATS 操作手册(表单、上传、验证码等)
  100. lead-discovery.md 官方岗位搜索覆盖、比较与证据规则
  101. safety-and-boundaries.md 隐私、知情同意、以及绝不应自动化的事项
  102. templates/
  103. candidate_profile.template.json 你的基本信息:身份、联系方式、工作资格、目标岗位
  104. application_rules.template.md 哪些优先投、需要人工复核、直接跳过或转交给你决定
  105. resume_routing.template.md 不同岗位族使用哪个简历版本
  106. answer_bank.template.md 常见申请问题的可复用真实回答
  107. experience_bank.template.md 针对不同岗位族/JD该用哪几段实习或项目经历
  108. application-progress.template.json 私有续填检查点
  109. dashboard-template/ 空白CSV看板 + 字段说明(见其中的 README.md)
  110. dashboard/ 开箱即用的本地进度看板(CSV结构与模板一致)
  111. server.js 本地 Node.js 服务及结果/日程写入校验
  112. dashboard.html 看板界面本体
  113. csv-store.js / dashboard-model.js CSV完整性及看板计数/关联逻辑
  114. scripts/ / tests/ 数据检查与回归测试
  115. start-dashboard.bat / .sh 一键启动脚本(Windows / macOS-Linux)
  116. *.csv 空白起始数据文件
  117. ```
  118. ### 快速开始
  119. 1. **下载或克隆本仓库**到本地(或者直接把 GitHub 地址发给你的编程 Agent)。
  120. 2. **给 Agent 配上操作浏览器的能力——真正投递表单时必须要有。** 下面第5步的"仅找岗位"调研可以使用公开网页来源,但 `SKILL.md` 第7步(填真实表单、上传简历)需要 Agent 能真正操作浏览器。建议在真正开始投递前先配好:
  121. - **Claude Code**:装上 Playwright MCP,让 Agent 拿到浏览器操作工具(打开页面、点击、输入、填表单、上传文件、截图等):
  122. ```bash
  123. claude mcp add playwright npx '@playwright/mcp@latest'
  124. ```
  125. 装完之后重新开一个 Claude Code 会话,让它加载上新工具。
  126. - **Codex CLI 或其他 Agent**:去查一下它有没有对应的浏览器自动化/computer-use 能力(比如基于 Playwright 的 MCP、内置的浏览器工具等),按它自己的文档启用。没配这个也不影响"仅找岗位"调研和草拟材料这部分,只是没法真的帮你打开表单页面并点提交。
  127. - 如果你只想用"找岗位+看板追踪"这一半功能,自己手动投递,这一步可以完全跳过。
  128. 3. **另建私有工作目录,把原始材料放在那里。** 本仓库保留为可复用发布包,让 Agent 把模板和看板复制到私有工作区。简历(最好包含可编辑的 DOCX/Markdown 源文件)、成绩单和项目文档放到私有工作区的 `my-materials/`。`.gitignore` 能帮助排除未跟踪文件,但无法阻止已经跟踪的 CSV 或模板被填入个人数据后提交。然后告诉 Agent 去哪找:
  129. ```text
  130. 我的简历、成绩单和项目经历都在 my-materials/ 里,开始之前先读一下。
  131. ```
  132. 4. **在这个文件夹里跟你的 AI 编程助手**(Claude Code、Codex CLI,或任何能读取本地文件的 Agent)开一个新会话,说:
  133. ```text
  134. 使用 SKILL.md 帮我初始化求职工作流。
  135. ```
  136. Agent 会问一小组必要问题,结合材料和回答,在私有工作区创建 `candidate_profile.json`、`application_rules.md` 等个人文件;公开仓库的 `templates/` 保持空白。尚未确认的敏感事实留空,不会猜测。
  137. 5. **先做一次安全的试运行**,明确告诉 Agent:
  138. ```text
  139. 先做一次"仅找岗位"的试运行:找3-5个岗位、分类、更新看板,不要打开投递流程也不要提交任何申请。
  140. ```
  141. 这一步只需要网页搜索,不需要第2步配的浏览器自动化——建议先用这种方式看工作流跑起来是什么样子,再让它真正接触投递表单。
  142. 6. **打开进度看板**查看情况:
  143. - Windows:双击 `dashboard/start-dashboard.bat`
  144. - macOS/Linux:运行 `dashboard/start-dashboard.sh`(需要先安装 [Node.js](https://nodejs.org/);如有需要先执行一次 `chmod +x`)
  145. - 会在浏览器打开 `http://localhost:8420/dashboard.html`,实时读取同目录下的 CSV——每次刷新都是最新状态,不需要构建、不需要外部服务器,数据也不会离开你的电脑。
  146. 7. **在 Agent 的帮助下继续投递**,一次处理一家公司——这一步才会真正用到第2步配的浏览器自动化。它会持续更新 `job_pool.csv`、`application_log.csv`、`blocker_queue.csv`、`follow_up.csv`,尚未取得本次提交授权时才在完整核验后集中请求确认,已有授权不重复索取。
  147. ### 填报提速
  148. 工作流默认在一次浏览器工具调用中填写完整模块,条件明确时合并多个相邻模块。Agent 会集中准备已确认信息,统一核对保存结果和报错,只修复差异;批次中断后先核对已保存内容,再从未完成处续填。局部缺失不打断其他可填模块;记录尚未检查的页面和未保存内容。联动控件仍等待真实选项,最终提交沿用适用范围内的已有授权。具体执行规则见[填报操作手册](references/application-playbook.md#batch-filling--consolidated-verification)。
  149. ### 关于看板
  150. 看板是一个纯静态网页 + 一个很小的本地 Node 服务器(没有框架、不需要构建、没有外部依赖)。它提供四类进度视图及集中待办入口:
  151. - **已投递** —— `status = Submitted` 的记录,附带后续跟进时间线和投递方式。展开某张卡片,点最下方的 **"记录投递结果"**,再选 **"拿到 Offer"** 或 **"已挂"**——会直接把新状态写回 `job_pool.csv`,刷新后这条记录就会进入对应的"拿到 Offer"或"已挂"列表。(本地服务器写入前会先核对这一行的公司+职位是否还对得上,防止 Agent 恰好同时改过这份文件导致写错行。)
  152. - **未投递** —— `status = Pending` / `Needs user` 的岗位按公司合并,并排除已有投递或终态历史的公司,根据 `cohort_match_status` 列区分"已确认开放但还没投"和"未开放/状态不明"(完整字段说明见 `templates/dashboard-template/README.md`)。
  153. - **已挂** —— 标记为 `Rejected` 的岗位,单独计数、搜索与分类筛选。
  154. - **拿到 Offer** —— 标记为 `Offer` 的岗位,单独计数、搜索与分类筛选;面试过关仍记录在当前阶段,不记为Offer。
  155. 你也可以直接用 Excel/Google Sheets/Numbers 打开这些 CSV;看板使用同一份数据,通过“记录投递结果”和日程操作写回文件。
  156. **集中待办** 汇总开放阻塞项与 `Needs user` / `Blocked` 岗位,同岗多个缺漏与提交后问题都保留。已投/已挂/Offer按准确岗位关联日志,`company_summary` 不重复计数。后端严格校验CSV、核对编辑快照,并在联动文件写入失败时回滚。
  157. **注意:** 请通过 `start-dashboard.bat`/`start-dashboard.sh` 打开看板,不要直接双击 `dashboard.html`——页面需要通过 `http://` 读取 CSV 数据,直接从磁盘打开文件时浏览器会拦截这类请求。
  158. ### 安全边界(完整清单见 `references/safety-and-boundaries.md`)
  159. Agent 不应该:
  160. - 猜测身份、工作资格、薪资或法律相关的事实。
  161. - 绕过验证码、Cloudflare 或反爬机制,或用未知账号/二次验证自动登录。
  162. - 编造经历、学历或作品集内容。
  163. - 把"已收藏/已追踪"的岗位算作"已投递"。
  164. - 在没有覆盖当前申请的授权时点击最终提交;范围未变的已有授权无需重复确认。
  165. ### 隐私说明
  166. 本仓库提供的是空白模板和空白看板——不包含任何个人数据。当你按自己的信息填好 `candidate_profile.json`、`job_pool.csv` 等文件后,**请不要把填好个人信息的版本公开发布**(不要把自己 fork 出来的、填了真实数据的仓库推成公开仓库,也不要把内容截图发到 issue 里)。你自己在用的那份数据请保持私有,只有工作流/模板这一层是设计给别人复用的。
  167. ### 验证与公开发布
  168. 在仓库根目录执行:
  169. ```sh
  170. node scripts/check-public-package.js
  171. node --test scripts/check-public-package.test.js
  172. node --test dashboard/tests/*.test.js
  173. ```
  174. 发布检查会拒绝已填入数据的起始数据库和禁止发布的私有文件;仍须检查暂存区差异,自动检查不能保证自由文本或 Git 历史完全匿名。回归测试覆盖 CSV解析和原子写入、岗位关联、结果分离与集中待办。浏览器测试需要 Playwright 和兼容浏览器,否则跳过这一项;CI运行发布检查及可运行的测试。
  175. 私有工作区的数据变更后,运行 `node dashboard/scripts/audit-data.js` 和 `node dashboard/scripts/company-categories.js --check`;历史缺口应明确保留,不靠猜测清除警告。
  176. ### 许可证
  177. MIT —— 见 `LICENSE`。本项目是 Yvonne He 的开源工作流 *ApplyPilot* 的改名/改编衍生版本;按照其 MIT 许可证要求,`LICENSE` 文件中保留了原始版权声明,同时也加上了这份改编版本自己的版权行。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.