Resume Weaver

English | 简体中文

Turn career evidence into a truthful, tailored, and visually coherent resume — without mixing facts with presentation.

Resume Weaver is a Codex Skill for creating, revising, retheming, relayouting, and exporting resumes. Give it an existing PDF, notes, structured data, a portrait, or a visual reference; it guides the conversation, separates content from design, renders the result, and checks the final artifacts before delivery.

Current release: v0.5.1 preview. The default path now uses the built-in minimal theme with the classic layout. Other bounded themes/layouts and the bespoke direct-a4 renderer remain explicit options.

Style gallery

Every preview below is generated from the same fictional resume data, so the differences come from presentation rather than rewritten career facts. Names, companies, metrics, and contact details are examples only.

Minimal — default

The default build uses themed + minimal + classic: monochrome sans-serif typography, a centered identity, fine rules, and no displayed portrait. No theme or layout flags are required.

Quiet Moss — built-in alternative

quiet-moss keeps a conventional single-column layout while restoring a restrained professional palette and the local portrait.

Maka Blueprint — custom style example

maka-blueprint.theme.json demonstrates how a website reference can become a custom bounded style. It uses the same themed renderer with the sidebar layout; Maka is not a built-in preset or the default.

Why Resume Weaver

• Evidence first. It improves wording and structure without inventing dates, metrics, responsibilities, seniority, or technologies.
• Minimal by default. Career facts stay in resume.json; the default output is a monochrome, portrait-free minimal + classic A4 document.
• Alternatives without lock-in. The quiet-moss preset, custom theme.json files, classic|sidebar|compact|profile layouts, and the bespoke direct-a4 renderer remain available when explicitly requested.
• Curated references. Extracted colors, typography, and motifs are screened for coherence, contrast, role fit, CJK coverage, and print behavior before becoming tokens.
• Source-order fidelity. Explicit top-level career headings from Markdown are stored in metadata.primarySectionOrder and preserved in both HTML and Markdown exports.
• Distinct career narratives. Research, open-source work, and ordinary projects remain separate categories instead of being flattened into one generic project section.
• Inspectable artifacts. Each default build can produce structured data, Markdown, self-contained resume HTML, a matching Design Plate, a manifest, and PDF.
• Built-in quality gates. Desktop, narrow, and print layouts are checked for overlap, clipping, overflow, broken images, conflicting decoration layers, and weak typographic hierarchy.

Use it when you want to

• create a targeted resume from an existing PDF or career notes;
• add a portrait and translate a screenshot, image, website, or design direction into a printable presentation;
• rewrite selected experience without disturbing verified facts;
• change only the layout or visual treatment while preserving the content;
• diagnose awkward wrapping, excess PDF whitespace, visual imbalance, or export failures;
• export an inspectable, offline-readable resume package.

Install in Codex

Resume Weaver is packaged as a skills-only Plugin under plugins/resume-weaver/ and also remains installable as a standalone Skill.

Install the standalone Skill

Ask Codex to install the Skill from this repository:

Use $skill-installer to install https://github.com/ARE404/weave-resume/tree/main/plugins/resume-weaver/skills/weave-resume

Restart Codex after installation so the Skill is discovered.

Manual installation

Clone the repository, then copy the Skill directory into your personal Codex skills directory:

git clone https://github.com/ARE404/weave-resume.git
cp -R weave-resume/plugins/resume-weaver/skills/weave-resume ~/.codex/skills/weave-resume

Validate the Plugin package locally

The canonical Plugin package includes .codex-plugin/plugin.json, listing metadata, brand assets, screenshots, starter prompts, and submission test cases. Contributors can validate it with the bundled Plugin Creator validator:

uv run --with pyyaml python \
  ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
  plugins/resume-weaver

Public Plugins Directory installation will be added after the skills-only Plugin passes OpenAI review.

Try it

Create a targeted resume:

Use $weave-resume to create an Agent backend resume from my existing PDF.
Use my portrait, and translate the supplied screenshot into a printable visual style.

Retheme an existing build without changing its facts:

Use $weave-resume to give this resume an apple.com-inspired visual direction.
Keep resume.json unchanged and show me the visual translation before rebuilding.

Fix a layout problem:

Use $weave-resume to diagnose why this section wraps early and why the PDF has
too much whitespace at the bottom. Preserve the content and theme.

The Skill asks only about gaps that materially affect the result. Unsupported claims stay out of public artifacts and are reported at delivery.

Choose a presentation path

Theme and layout are independent controls inside the default themed renderer. A complete custom renderer is a separate path for references whose composition cannot be expressed well through the bounded theme system.

The shell examples in this section assume you are working from the Skill package directory:

cd plugins/resume-weaver/skills/weave-resume

Path	Theme/style	Layout	How to use it
Default	minimal	classic	Build without renderer, theme, or layout flags
Built-in combination	minimal or quiet-moss	classic, sidebar, compact, or profile	Select --theme and --layout independently
Reference-derived custom theme	Generated theme.json	Any named layout	Give Codex a description, image, screenshot, resume, or website as visual direction
Complete custom renderer	Dedicated HTML/CSS renderer	Renderer-owned composition	Explicitly ask Codex for a full custom renderer from another resume or website

Use the default

No presentation flags are required. This resolves to renderer: themed, theme minimal, and layout classic:

node scripts/build-resume.mjs \
  --resume path/to/resume.json \
  --output output/default \
  --name candidate \
  --pdf

Combine a built-in theme and layout

The theme controls colors, typography, spacing, rules, photo treatment, and component styling. The layout controls the content topology. They can be selected independently:

# Minimal typography with a supporting sidebar
node scripts/build-resume.mjs \
  --resume path/to/resume.json \
  --theme minimal \
  --layout sidebar \
  --output output/minimal-sidebar \
  --name candidate-minimal-sidebar \
  --pdf

# Quiet Moss styling with an identity-forward profile layout
node scripts/build-resume.mjs \
  --resume path/to/resume.json \
  --theme quiet-moss \
  --layout profile \
  --output output/quiet-moss-profile \
  --name candidate-quiet-moss-profile \
  --pdf

A layout does not override theme decisions. For example, minimal + profile still hides the portrait because the Minimal theme deliberately sets showPhoto: false; the photo remains in resume.json for another theme.

Generate a custom theme from a reference

You can give Codex a visual description, image, screenshot, another resume, or website URL directly. You do not need to prepare theme.json yourself. Resume Weaver extracts and curates the reference's visual system, writes a validated bounded theme, selects or preserves a named layout, and generates the resume plus a matching Design Plate.

Use $weave-resume. Keep the facts in my current resume unchanged.
Use the attached reference resume only as visual direction, create a custom theme,
pair it with the sidebar layout, and export audited HTML and PDF artifacts.

The bundled Maka Blueprint preview follows this route:

node scripts/build-resume.mjs \
  --resume examples/readme-demo.resume.json \
  --theme examples/maka-blueprint.theme.json \
  --layout sidebar \
  --output output/maka-custom \
  --name readme-demo-maka-custom \
  --pdf

Generate a complete custom renderer from another resume or website

When the reference depends on composition beyond the bounded theme/layout controls, explicitly request a complete renderer. You may attach another resume as a PDF/image or provide a website URL; Codex can inspect it, extract its Visual DNA, and implement a dedicated semantic A4 HTML/CSS renderer around your normalized resume.json.

Use $weave-resume. Use my-resume.pdf as the factual content source and
https://example.com as visual direction. Create a complete custom renderer—not
only a theme.json—then export audited, self-contained HTML and PDF artifacts.
Preserve my facts and do not copy the website's logos, text, images, or code.

Another resume can be used as the factual source, the visual reference, or both; state which role it should play. A website is treated as visual direction only. Reference people, employers, metrics, product copy, logos, proprietary assets, and interactive behavior are never imported as the user's career evidence.

The repository's direct-a4 route is one bundled example of a complete renderer:

node scripts/build-resume.mjs \
  --resume path/to/resume.json \
  --renderer direct-a4 \
  --output output/direct-a4 \
  --name candidate-direct-a4 \
  --pdf

The public builder currently recognizes themed and the bundled direct-a4 renderer. Creating a new complete renderer is a Codex implementation workflow rather than automatic URL-to-template conversion: Codex must inspect the reference, implement and register the renderer, and pass the same desktop, 390px, self-contained HTML, and PDF print gates before delivery.

What you get

Artifact	Purpose
candidate.json	Normalized, source-aware career facts
candidate.md	Portable text version
candidate.html	Self-contained, offline-readable resume
candidate.design-plate.html	Themed-route visual system, tokens, and component specimens
candidate.manifest.json	Input digests, artifact hashes, warnings, and omissions
candidate.pdf	Optional print-ready export

Content structure and section order

Project-like records can declare category as project, research, or open-source. The renderers and Markdown exporter use those values to produce separate Projects, Research Experience, and Open Source Experience sections.

When source Markdown provides an explicit top-level order, Resume Weaver records it in metadata.primarySectionOrder and carries it through HTML and Markdown. Without an explicit order, the narrative defaults to education, custom sections such as competitions, experience, research, open-source work, then projects, followed by skills and languages.

Standard sections may also override their displayed heading through metadata.sectionTitles without changing the underlying data model. For example, use "experience": "Internships" when the source distinguishes internships from general work experience. The override is preserved in themed HTML, direct A4 HTML, and Markdown; omitted values continue to use localized defaults.

{
  "projects": [
    {
      "id": "project-research-example",
      "name": "Research project",
      "category": "research"
    }
  ],
  "metadata": {
    "sectionTitles": {
      "experience": "Internships"
    },
    "primarySectionOrder": [
      "education",
      "custom-sections",
      "experience",
      "research",
      "open-source",
      "projects"
    ]
  }
}

How it works

Sources
  ↓ inspect and normalize
resume.json + minimal theme + classic layout
  ↓ themed render
resume HTML + Design Plate → audit → deliver

Optional: another built-in/custom theme or explicit bespoke direct A4 renderer

1. Route — classify the request as create, content revision, retheme, relayout, export, diagnose, or a combination.
2. Ground — inspect every supplied source, preserve provenance and explicit section order, categorize research and open-source work, and mark unsupported claims as uncertain.
3. Propose — use minimal + classic by default; select another theme/layout or direct-a4 only when explicitly requested.
4. Build — generate all requested artifacts from the structured inputs.
5. Gate — inspect the resume, responsive layouts, every requested PDF page, and the Design Plate when the themed route produces one.

Presentation system

The default presentation is the bounded minimal theme with the classic layout: white paper, black sans-serif text, centered identity, aligned dates, fine rules, compact spacing, and no displayed portrait. Theme and layout remain separate controls.

The bundled Maka Blueprint file is the custom-style example: it translates an external visual reference into validated theme tokens and pairs them with the sidebar layout. The separate direct-a4 renderer remains available when a fully bespoke A4 composition is explicitly requested.

Layout	Best for
classic	Formal, spacious, ATS-conscious delivery
sidebar	Fast human scanning with supporting information in a rail
compact	Longer histories that still need readable print typography
profile	Identity-forward presentation with optional portrait emphasis

In the themed route, a visual reference is extracted, curated, then translated — not copied. The Skill identifies its dominant signature, compares coherent palette/type/composition directions, rejects weaker options, and records the winning rationale before writing four to eight concrete mappings plus deliberate omissions. The Design Plate exposes this curation record. Arbitrary JavaScript, remote fonts, and third-party assets are not injected into either output path.

Built-in theme presets:

Theme	Character	Suggested layout
default	Alias of the minimal default	classic
minimal	White paper, black sans-serif text, no portrait, restrained document hierarchy	classic
quiet-moss	Legacy restrained professional color	classic

The Minimal preset hides a portrait during rendering without deleting it from resume.json, so switching themes restores the original photo.

Custom styles use the same schema and quality gates as the built-in presets. For example:

node scripts/build-resume.mjs \
  --resume examples/readme-demo.resume.json \
  --theme examples/maka-blueprint.theme.json \
  --layout sidebar \
  --output output/maka-custom \
  --name readme-demo-maka-custom \
  --pdf

Quality and safety

• Unconfirmed claims are excluded, not silently completed.
• Presentation-only changes preserve structured content digests.
• Portraits are local PNG, JPEG, or WebP files embedded into the HTML.
• Generated HTML stays semantic, text-extractable, and free of active scripts.
• Overlap, clipping, horizontal overflow, broken images, and unreadable print output are build failures.
• Long primary-column entries may continue across pages between complete bullet items, while headings and opening content stay together. This avoids forcing whole entries onto a new page and reduces excessive whitespace.
• Printed continuation pages preserve the main grid surface and padding instead of restarting content against a bare page edge.
• Output is ATS-conscious, but no compatibility guarantee is made for every applicant-tracking system.

Roadmap: editable design sources

Editable design-source export is intentionally deferred beyond v0.3.1. The planned public build option is --design-format none|pencil|figma, with HTML remaining the canonical rendered artifact.

• Pencil: generate a native, editable .pen document from the same audited layout geometry, pin the supported .pen schema version, and validate the result before adding it to the manifest.
• Figma: create an editable Figma document through an officially supported API or plugin workflow. Resume Weaver will not fabricate a proprietary .fig binary; an importable fallback must be labeled accurately if direct Figma creation is unavailable.
• Shared contract: both exporters must preserve the selected content, renderer/presentation, portrait treatment, layer names, and safety clearances without introducing a second independent resume template.
• Delivery contract: design exports remain opt-in, appear in the build manifest with hashes or remote identifiers, and fail clearly when authentication, a required application, or format validation is unavailable.

Development

Requires Node.js 20+ and a local Chrome, Chromium, or Edge installation for browser layout audits and PDF fallback. Playwright is used when available. Rebuilding the README gallery also requires Poppler's pdftoppm.

Build and test commands

cd plugins/resume-weaver/skills/weave-resume
npm test
npm run build:sample
npm run build:readme-previews
npm run layouts
npm run themes

Rebuild the GitHub social preview from the repository root:

node scripts/build-social-preview.mjs

Build a complete artifact set:

node scripts/build-resume.mjs \
  --resume path/to/resume.json \
  --output path/to/output-directory \
  --name candidate \
  --pdf

npm run build:readme-previews rebuilds the Minimal, Quiet Moss, and custom Maka Blueprint gallery images from the same fictional source. Add --renderer direct-a4 when a fully bespoke renderer is required instead of a custom theme.

The conversation contract and rendering behavior are documented in references/. Schemas live in schemas/.