Resume Builder#

Overview#

Build professional resumes with AI-assisted content management, supporting PDF import/export, HTML styling, and multi-language output.

Canonical resume schema: See references/resume-schema.json and references/data-structure.md Troubleshooting: See references/troubleshooting.md Customization (themes, languages): See references/customization.md

Dependencies#

• HTML generation: Python 3 (no extra deps)
• PDF import: pip install pymupdf==1.26.5
• PDF export: pip install playwright==1.60.0 && playwright install chromium

Work File Convention#

Save resume JSON to resume.json in the current working directory unless the user specifies another path. When importing from PDF, save the extracted JSON alongside the source file.

Always keep the working file in the canonical schema used by the renderer. If imported data is rough or partially parsed, normalize it before presenting edits or exporting.

Workflow#

1. Initial Import (if user provides existing PDF)#

The scripts/extract_from_pdf.py script does basic text extraction, but it produces rough output. For best results, use your AI capabilities to read and understand the PDF content directly, then structure it into the resume JSON schema yourself. The script is available as a fallback:

bash

python3 "$SKILL_DIR/scripts/extract_from_pdf.py" input.pdf output.json

After extraction (by any method), do not export immediately. First:

1. Normalize the data into the canonical schema.
2. Identify obvious gaps, duplicated bullets, or fields that landed as rough text.
3. Present the structured data to the user for review and ask what should be corrected or expanded.

2. Content Management#

When adding or editing sections, gather complete information through natural conversation. The key areas to ask about:

For Education: institution, degree, period, location, GPA (if applicable), honors. For Work Experience: company, position, period, location, responsibilities, quantifiable achievements. For Projects: name, role, period, technologies, description, key achievements.

Keep asking follow-up questions if responses are brief or unclear. The goal is a complete, well-structured entry — not a minimal one.

Portrait photo (optional, ask before adding)

Built-in themes hide personal.photo by default — most regions (US, UK, Canada, Australia, much of the EU) expect resumes without a photo and may discard photo-bearing resumes for legal reasons (anti-discrimination). Do not add a photo unprompted.

Ask about a photo only when the context suggests one is expected, for example:

• Job markets where photos are conventional: mainland China, Hong Kong, Taiwan, Japan, South Korea, much of Southeast Asia, Middle East, Latin America
• Academic / research CVs in some fields, performing-arts applications, certain consulting or sales roles
• The user explicitly says the resume is for a market or role where photos are expected

When in doubt, ask once: "Do you want a portrait on this resume? Some markets expect one, others penalize it."

If the user wants a photo:

1. Require them to provide the image themselves. Accept a file path, https:// URL, or data: base64 URI. Do not invent, fetch, or generate an image.

2. Store the value in personal.photo. Supported values are a relative path, absolute local file path, file:// URL, https:// URL, or data: URI. Relative paths resolve against the HTML output location, so the user should keep the photo next to the generated HTML.

3. Photo rendering is opt-in per theme. Built-in themes don't display it; scaffold a custom theme with scripts/create_theme.py and enable it: css

   .resume-photo {
       display: block;
       width: 96px; height: 96px;
       object-fit: cover;
       border-radius: 50%;   /* or 4px for a square headshot */
   }
   
   

4. Warn the user before they ship a photo resume to a market that penalizes it.

When the user requests meaningful edits, especially after import, prefer an edit-review-export flow:

1. Update resume.json.
2. Generate an editable HTML preview when the user will likely want to iterate visually.
3. Review the resulting content for clarity, grammar, consistency, and scannability before final export.

When the user dislikes the built-in look and wants a more personalized visual style:

1. Identify the closest built-in theme ( modern, classic, minimal, creative).

2. Scaffold a reusable custom theme from that base: bash

   python3 "$SKILL_DIR/scripts/create_theme.py" custom-theme-name --base modern
   
   

3. Tune user-themes/custom-theme-name/style.css based on the user's feedback.

4. If layout structure must change, also adjust user-themes/custom-theme-name/template.html.

5. Reuse that custom theme in future exports with --theme custom-theme-name.

Prefer this path over editing built-in assets directly. It preserves the stock themes and gives the user a reusable personal template.

Important separation principle:

• Work Experience should stay high-level: job responsibilities at a business level, scope (team size, industry sectors), leadership and business impact.
• Projects should go deep on technical specifics: technologies, architecture, quantified achievements with metrics.

This separation makes the resume scannable for HR while providing depth for engineering interviews.

3. Export#

1. Confirm format (HTML or PDF), theme, and language with the user.

2. Use the unified export script: bash

   python3 "$SKILL_DIR/scripts/export_resume.py" --format html --theme modern --lang en resume.json output.html
   
   

3. For PDF export, use: bash

   python3 "$SKILL_DIR/scripts/export_resume.py" --format pdf --theme modern --lang en resume.json output.pdf
   
   

The PDF flow always renders a clean HTML intermediary first, then converts it to PDF. Do not use editable HTML as the final PDF source. The PDF renderer blocks external network requests by design. Prefer local assets, data: URIs, or bundled files for anything that must appear in the PDF.

Available themes: modern, classic, minimal, creative Custom themes: Any folder under user-themes/<name>/ with a style.css, or a direct path to a custom theme directory Available languages: en, zh, ja, fr, de, es

--lang only switches UI labels (section titles like "Work Experience", the edit-mode toolbar strings, and the html lang attribute). It does not translate resume body content. When a user asks to "translate my resume to X", translate the JSON content yourself first, then export with --lang X so labels and content stay consistent.

4. Interactive Edit Mode (Edit-Review-Export)#

For collaborative refinement with the user, generate an editable HTML that includes inline editing capabilities:

bash

python3 "$SKILL_DIR/scripts/export_resume.py" --format html --theme modern --lang en --editable resume.json output.html

Workflow:

1. Generate the editable HTML and tell the user to open it in a browser.
2. Guide the user explicitly:
   • Hover near the top-right corner to reveal the pencil button.
   • Click it to enter edit mode.
   • Edit text directly, add/remove bullet items where controls appear.
   • In body fields (summary, descriptions, achievement/responsibility list items, project achievements, honors), the user can select text and apply B / I / U / color from the toolbar. Title and short fields stay plain by design.
   • When finished, click Save in the toolbar — this writes the edited resume back to resume.json on disk through a local sync server that the export step starts automatically.
3. Once the user tells you they clicked Save, re-read resume.json yourself to pick up the changes. Do not ask the user to paste JSON.
4. Final review: Check the updated content for grammar, spelling, consistency, formatting, and section separation quality. Suggest corrections if needed.
5. Apply any corrections to resume.json.
6. Generate the final, non-editable version for export (HTML or PDF) using the standard export command without --editable.

Rich-text markup. Body fields support a small Markdown subset for emphasis. Both the agent (when authoring JSON) and the user (via the toolbar) use the same syntax, so they round-trip:

SyntaxEffect**text**bold*text*italic_text_underline==text|#rrggbb== or ==text|namedcolor==colored run

Example: "Achieved **30%** growth with *custom* analytics.". The renderer applies a strict whitelist — invalid color specs are left as literal text, and HTML/script tags are escaped. Title-like fields ( name, company, position, degree, institution, project-name, role, category-title, period, location, gpa, technologies, skill items) render plain to keep layouts clean.

Notes:

• Edit UI is hidden during print/PDF export, so the visual output is unaffected.
• The toolbar labels are localized with the selected output language.
• The local sync server binds to 127.0.0.1 only, validates the target path against the resume JSON it was started with, and requires a bearer token. Its PID/port are written next to the output HTML as <output>.sync.json for explicit cleanup.
• If --no-sync is passed (or the server failed to start), the Save button is disabled and the user falls back to Copy JSON; in that case ask them to paste.
• If you have Playwright access, you can evaluate JSON.stringify(window.extractToJson ? extractToJson() : 'N/A') to read edits programmatically without Save.

Content Best Practices#

• Quantify achievements: Include numbers and metrics (e.g., "Improved efficiency by 30%")
• Action verbs: Use strong action verbs (e.g., "Led", "Architected", "Built")
• Consistency: Maintain consistent formatting and tense across entries
• Proofread: Review for typos and grammatical errors before export

Scripts#

ScriptPurposescripts/extract_from_pdf.pyExtract text from PDF resumes (fallback — prefer AI-based parsing)scripts/generate_html.pyGenerate styled HTML from resume JSONscripts/generate_pdf.pyConvert HTML resume to PDFscripts/export_resume.pyUnified entrypoint for HTML/PDF exportscripts/create_theme.pyScaffold a reusable custom themescripts/validate_resume.pyValidate a resume JSON against the canonical schemascripts/_edit_sync_server.pyLocal-only HTTP server (background) that the editable toolbar POSTs edits to — writes them back to resume.json. Started automatically by generate_html.py when --editable is set and --no-sync is not. Not invoked directly.