resume-builder

Resume Builder

Create for users through conversationvisually polished and professionally typesetHTML/PDF resumes, supporting both visual A4 single-page and ATS-safe output modes.

Core Principles

• Output: standalone HTML file, embedded CSS, A4 size (210mm × 297mm), browser print to PDF
• Design: bold and distinctive, reject generic AI aesthetics (see references/design-guidelines.md）
• Before generating, first choose the output mode: visual HTML/PDF or ATS-safe HTML/PDF; both modes share the same factual data.

Prerequisite Rules

Before starting to collect, write, or generate, you must first fully read and follow references/resume-contract.md and references/content-writing.md. These two shared reference documents take precedence over the examples, layout preferences, and process hints in this entry point; when evidence is insufficient, preserve the factual boundaries and do not add content to fill the layout or cater to the format.

Before the first execution of rendering or command-line validation, read rendering environment and command paths, locate the complete runtime and check dependencies. In command examples, skills/... is resolved from the actual runtime root directory; do not assume it is located in the user's current resume directory.

Entry Point and Collaboration

This is the main entry point for creating and updating the master version. If the user provides anexisting resume, first extract it into claims to be confirmed, show the recognized content, ambiguous items, and suspected outdated items; after the user confirms, only doincremental follow-up questions, prioritizing recent changes, missing evidence, and low-confidence fields. Do not treat parsed text directly as final facts, and do not conduct a full interview again.

If the user has no existing resume, interview according to the information collection process below. Save the user-confirmed claims to a private resume-facts.yamloutside the project directory, whose structure uses references/resume-facts.example.yaml; it is the source of facts for subsequent master versions and JD customization. Only after fact confirmation is complete should you choose the output mode and six visual templates.

Skill Collaboration Flow：

• Experience polishing: during the interview, if an experience is found to be duty-oriented, lacking specific contributions, or insufficiently evidenced, directly based on references/content-writing.md guide the user in place to provide evidence of actions and deliverables, and rewrite in place into a strong-verb structure, without interrupting the main interview flow;
• Quality audit: before master delivery, through validate_resume.py(visual single page and density) or --mode ats(ATS format) perform an automated quality audit;
• Layout fine-tuning: after the visual master is generated and PDF verification is complete, if the user needs interactive fine-tuning,route to resume-canvas；
• Job customization: after the master is finalized, if applying to a specific position is needed,route to jd-tailorer(one-stop completion of JD structured analysis, match assessment, and targeted customization);
• Version tracking: after the master is finalized, it is recommended that the user commit the initial master to a local private Git repository (e.g., git commit -m "创建母版简历"), to protect the source of facts.

Workflow

Step 1: Information gathering

Only when conducting an interview from scratch or when an existing resume has gaps, ask questions section by section; do not throw out all questions at once. Follow resume-contract.md to create each claim's section、source、confidence、evidence、metric_status record, and after user confirmation update the private resume-facts.yaml, then write according to content-writing.md .

Collection order: basic information → education background → internship/work experience → project experience → skills → campus experience → self-evaluation

• Prioritize follow-up questions on verifiable metrics, scope, time, quality, role, and deliverables; when there are no credible numbers, use confirmed non-numeric evidence.
• The number of skills, the length/number of sentences of the self-evaluation, and the structure of experience should be subject to facts, job relevance, and layout; do not set mechanical quantity or word-count thresholds.
• For fresh graduates, projects or campus experience may be placed earlier based on job relevance; do not treat a fixed order as a factual rule.
• Fields pending confirmation may only remain in the collection records or analysis report and must not enter the final resume HTML/PDF.

Step 2: Style confirmation

First have the user choose visual HTML/PDF or ATS-safe HTML/PDF mode, then choose or describe the visual style. Visual mode reads the corresponding CSS and HTML reference files; ATS-safe mode uses a single-column, standard-heading, copyable-text structure:

Style	CSS	HTML reference
Modern Minimalist	css/modern-minimal.md	examples/modern-minimal.html
Classic Business	css/classic-business.md	examples/classic-business.html
Creative Individual	css/creative-bold.md	examples/creative-bold.html
Japanese Minimalist	css/japanese-minimal.md	examples/japanese-minimal.html
Tech Feel	css/tech-dark.md	examples/tech-dark.html
Minimalist Blue Business	css/minimal-blue-business.md	examples/minimal-blue-business.html

The CSS file contains 3 sets of color variables + recommended fonts + style CSS.css/common.md for general typography (required every time).

Step 3: Generate HTML

According to the mode selected in Step 2, merge css/common.md typography + corresponding style CSS/layout + user information that has passed the contract threshold to generate standalone HTML. Visual mode uses <姓名>_<岗位>_visual.html; ATS-safe mode uses <姓名>_<岗位>_ats.html, and the corresponding PDF uses the same prefix and .pdf extension.

Visual mode:

• For A4 size, margins, font size, spacing, line height, and other typography parameters, see css/common.md(the sole source of definition); the root <html> must declare data-resume-layout="full-page", and retain --resume-density、--resume-density-min、--resume-density-max: 1.2、--resume-fill-target: 0.98 and --resume-bottom-margin: 9mm variables. The bottom is a total margin of 9mm, with no additional safe area stacked on top; the top/left/right margins keep the template's original values.
• The page body must use an extensible flex/grid layout according to the full-page contract of css/common.md : when content is insufficient, first increase font size, line spacing, and item/section spacing within the density upper limit, then use space-between to distribute the remaining space; when content is excessive, the rendering script automatically compresses above the safe density lower limit; do not fill blank space with fabricated content or use overflow: hidden to silently clip.
• CSS variables uniformly manage colors, system font stack (PingFang SC, Microsoft YaHei)
• When delivered as a single file, local images such as avatars use data URL embedding; if external web fonts are retained, system font fallbacks must also be provided, and verification must explain that offline rendering may differ.
• Skill tags are arranged using <span class="skill-badge"> , and badge styles are defined by the style CSS (ATS-friendly)
• Do not embed an export button in the resume template; PDFs are exported via the browser's print or a local Canvas's 'Print to PDF' operation, to avoid obstructing the resume content
• When using any built-in style, the generated <html> Must include the corresponding data-resume-editor-template（modern-minimal、classic-business、creative-bold、japanese-minimal、minimal-blue-business or tech-dark) and data-resume-editor-version="1". Every real text that requires Canvas fine-tuning must have a stable, unique, semantic data-resume-editor-id; do not rely on runtime backfilling.
• data-resume-editor-id can only be applied to one specific text field, such as a name, job title, date, section heading, single bullet, or single skill tag; do not add a catch-all ID to an entire page or block just to "pass protocol checks."
• It is forbidden to place the editing ID on <html>、<body>、<main>、.page、.resume、header、footer、section、ul、ol、figure or on a container that includes multiple sections/fields. Contact information with links should split the editable text into independent fields; the entire contact line must not be treated as a single editable container.
• The above markers are for recognition by the local Canvas fine-tuner of npx -p @chasen-liao/resume-skills@latest resume-skills editor <resume.html> ; Canvas can edit the plain text of existing fields and save restricted layout overrides, but it is not allowed to insert HTML or add fields. After factual text changes, the facts must be reconfirmed and the PDF verified; do not use the markers for avatars, layout containers, arbitrary HTML, or unconfirmed fields.

ATS-safe mode:

• Use a single column, standard section headings, plain copyable text, and a stable body reading order; important information must not rely on images, text boxes, complex nested tables, headers/footers, or decorative fonts.
• Skills are expressed as a copyable text list; ATS-safe mode must not change claim content, evidence status, or delete facts other than pending-confirmation markers.
• Likewise, only HTML and browser-print PDF are generated; the repository currently has no DOCX generation capability, so do not promise DOCX output.

Step 4: Verify by mode (mandatory, cannot be skipped)

After generating the final visual HTML, first perform Canvas field acceptance, then render the PDF:

• First run the executable validation (stop on failure, strictly forbidden to skip):npx -p @chasen-liao/resume-skills@latest resume-skills validate "<最终_visual.html路径>", repeat until it outputs "validation passed."
• Then manually review according to the following rules: in the final HTML (after completing fact replacement and customization, not just checking the reference template), count data-resume-editor-id, record the total number of fields, duplicate IDs, mislabeled container IDs, and whether profile-* and *-bullet-* fields exist.
• The total number of fields must be greater than 0, IDs must be unique and follow lowercase semantic naming;main/page/resume/section page-level or section containers such as these must not carry IDs.
• The text of each ID node must correspond to a field that can be edited independently; if a node simultaneously contains multiple sections, lists, or a large amount of link text, the markers must be split.
• If any check fails, do not start Canvas, render the PDF, or deliver; fix the HTML or regenerate and re-verify from the beginning. It is forbidden to use a single root container ID in place of field markers.

Visual HTML/PDF: After exporting the PDF, simultaneously check the structure, PDF page count and extractable text, page density, and printable safe area:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/resume-builder/scripts/render_resume.ps1 -HTML "<生成的_visual.html路径>" -OutputPdf "<生成的_visual.pdf路径>"

--check-layout acceptance rules:

• PDF page count must be 1 page; exceeding 1 page fails directly, and cropping or hiding overflow must not be used to disguise it as a single page.
• page fill Estimate by the vertical range of PDF extractable texteffective page areaoccupancy rate, target at least 98%; by default, falling below the target fails directly and clearly indicates a layout density/spacing issue; facts must not be fabricated to fill whitespace.
• vertical balance Check the difference in top and bottom margins of the printable area; exceeding 20mm fails directly, prioritize evenly adjusting section spacing, item spacing, and container padding to avoid content being crowded at the top or bottom.
• vertical gaps Check the maximum consecutive gap between PDF text lines; if it exceeds 25% of the effective height, fail directly to prevent isolated bottom text from masking an underfilled body. Also pass in --html when,--check-layout also performs browser checks, separately measuring the bottom whitespace and internal gaps of the page and the built-in two columns; these measurements cannot replace the full-page screenshot review below.
• bottom safety must not fail; the default total bottom margin is 9mm, PDF validation uses the HTML-measured padding (text boundary estimation tolerance 0.25mm), and reports the actual bottom distance. An effective area occupancy of 100% does not mean there is no physical bottom whitespace; custom margins must change the HTML, be re-rendered, and be recorded in the manifest, and cannot be adjusted only via validation parameters.

Layout adjustment order: first use existing and already confirmed sections and content; for short content, first within --resume-density-max enlarge the variable-controlled font size, line spacing, and spacing, then evenly distribute the remaining space; for long content, the rendering script automatically compresses above --resume-density-min ; if it still overflows, then handle it in the order of “page margins not less than 8mm → spacing → line height not less than 1.25 → body text not less than 9.5px → trim low-relevance content → switch to two columns when suitable.” Keep top and bottom spacing as similar as possible, and after any adjustment, re-export the PDF and run the same command. Do not add unconfirmed experience, metrics, skills, or placeholder text, and do not cram a page with hard-to-read small font sizes.

Before exporting the PDF, the rendering script performs full-page automatic layout: short content expands within the upper limit, long content compresses within the lower limit --resume-density, and at the same time generates a low-resolution file with the same name prefix *.preview.png. Then it performs browser overflow and PDF layout validation, and generates a file with the same name prefix *.resume-manifest.json, which includes the HTML/PDF/preview SHA-256, renderer version, effective margins/actual bottom distance/density, and validation results.degraded、fail or a hash mismatch means it cannot be delivered. After completing the automated checks, the AI must perform the following full-page screenshot visual review, also checking for visible clipping, broken images, photos, font fallback, and print backgrounds, and verifying links; automated checks cannot guarantee these visual details. In visual mode, an A4 single page and an effective area ≥98% are hard targets, and all warnings must have their handling results recorded.

Full-page screenshot visual review (mandatory in visual mode)

• The AI must use an image viewing tool to open the *.preview.pnggenerated by this final render, and actually view the complete A4 page (including top and bottom); if the preview is incomplete or unclear, additionally capture the complete A4 page of the same final HTML under print styles, or render the final PDF page as an image and view it. It is not acceptable to only generate a screenshot, check that the image file exists, or claim the review is complete after only looking at a partial screenshot.
• Focus on checking whether the whitespace from the end of the body text to the bottom of the page is too large, whether the top and bottom whitespace are balanced, and whether there are abrupt large gaps between sections. For two columns, each column must be checked separately; do not judge the whole page as even just because the other column or a single line of text at the bottom reaches the bottom edge. Keep the necessary print safe margins; whitespace is allowed, but it should be evenly distributed, and the body text must not be concentrated at the top with an obvious gap at the bottom.
• Even if CI,page fill, overflow checks, and the manifest all pass, as long as the screenshot shows an obvious bottom gap, an underfilled single column, or imbalanced whitespace, it is still considered a failed visual acceptance and cannot be delivered directly. First adjust font size, line height, item/section spacing, and page margins within the layout constraints; if the two columns are still imbalanced, the layout may be adjusted during the generation stage or switched to a single column, but content must not be fabricated to fill whitespace or disguised as occupancy using isolated bottom text.
• After each modification, re-render the PDF, run automated validation, and open the new screenshot for review until the whitespace is even and there is no overflow or cropping. When delivering, briefly describe the screenshot path and the review conclusions for bottom whitespace, top-bottom balance, and column distribution. If the screenshot cannot be viewed, clearly mark the visual review as incomplete and do not claim that visual acceptance has passed.

ATS-safe HTML/PDF: Check whether the DOM is single-column, whether the relationships among headings and dates/organizations/job titles are clear, whether the body text order is correct after copying, and whether the PDF text is extractable; then check for text in images, complex nested tables, critical header/footer information, and non-copyable decorative fonts. Check the HTML/PDF format according to the target platform's requirements, and do not claim that ATS will necessarily pass.

Step 5: Delivery

After the visual mode completes A4/PDF validation, first ask the user whether they need to open the local Canvas preview. Canvas is an optional fine-tuning tool for the visual version, not a prerequisite for Skills, HTML, or PDF delivery: only run the command below when the user chooses that they need it; if the user does not need it for now, directly deliver the verified HTML/PDF and explain that it can be enabled later on demand.

npx -p @chasen-liao/resume-skills@latest resume-skills editor "<生成的_visual.html路径>"

After the user selects Canvas, the command will start a service on the local machine and open the browser. Inform the user of the locations of the original HTML and PDF; when Canvas saves, it will directly overwrite that HTML and mark the associated PDF manifest as invalid. After saving, the rendering script must be run again, and delivery is allowed only if the hash and validation results of the new manifest are valid. Canvas only allows editing the plain text and limited typography of existing fields; it cannot insert HTML, perform JD matching, or adjust structure. If the user selects Canvas but the current environment cannot execute npx, clearly report that it was not started, and provide the complete command with the actual HTML path; do not claim that it has been started.

If the user needs in-depth typographic fine-tuning (font size/spacing/color/page margins), collaborative work using Live Preview hot reload, or advanced CLI automation (--json / --no-open / --port），route to the resume-canvas skill。

ATS-safe mode does not use Canvas (its single-column HTML is not among the visual templates supported by Canvas); inform the user of the file locations and the browser print-to-PDF method. Both modes can later use jd-tailorer to customize for a JD.

Reference document index

references/ Read on demand under the directory:

• design-guidelines.md — design aesthetics, typography, single-page parameter details
• resume-contract.md — source of truth, evidence, confidence, metric status, and output thresholds
• resume-facts.example.yaml — private resume-facts.yaml minimal structure
• color-palettes.md — index of six style-color schemes
• content-writing.md — evidence-first writing, the two ATS output modes, self-check checklist
• css/README.md — CSS usage and color selection strategy
• css/common.md — general compact typography CSS (must be used every time)
• css/<style>.md + examples/<style>.html — a pair of reference files for each style