English | 中文

Frontend Handoff Builder

The purpose of this skill is to improve the inputs to a frontend coding agent, not to replace that agent.

Use it to transform raw user input into a handoff package that another agent can implement with less guessing and less hallucination.

When to use this skill

• The user wants a frontend page, website, app UI, or repo-level frontend project
• The user provides one or more of: screenshot, image, URL, PDF, PRD, markdown, text description
• The raw request is underspecified and would benefit from structure, assets, and explicit constraints
• The user wants better final output from Claude, Codex, OpenClaw, or a similar coding agent

Do not default to this skill for tiny one-step UI clones where a pure screenshot-to-code skill is already sufficient.

Core output contract

The text-first route now has a preflight layer before the handoff package. Use it whenever the request starts from a raw text brief.

Preflight artifacts:

• intake-questions.md
• intake-answers.json
• normalized-brief.md

Downstream handoff package:

• input-profile.json
• collection-plan.md
• content-plan.json
• style-tokens.json
• asset-manifest.json
• generation-spec.md
• agent-handoff.md
• verification-report.md

agent-handoff.md is the main downstream brief. It must use this exact section order:

1. Goal
2. Output target
3. Scenario
4. Inputs and references
5. Non-negotiables
6. Content mapping
7. Asset usage rules
8. Recommended implementation path
9. Agent-specific notes

For important image assets, asset-manifest.json should also describe how the image should be used in layout: whether it should fill with cover, stay intact with contain, what aspect ratio the container should target, and what focal area must survive cropping.

All visual assets used by the final page must be materialized locally inside the package directory. If an image is found by search or remembered by URL, download it into assets/images/ first. Keep the original URL in source, not in path.

Current technical route

The strongest path today is:

1. single-page text brief
2. mandatory intake questions
3. material supplementation
4. handoff synthesis
5. verifier pass

Other input paths can still exist, but the first public-quality route is the text-first one. Treat existing repo as optional engineering_context, not the lead story.

Workflow

Phase 1: Preflight intake

Before collecting assets, stop and lock the task definition.

For text-first single-page work, always ask these three mandatory questions:

1. page use
2. style direction
3. output architecture

The architecture question is mandatory and should stay inside:

• single_html
• react_vite_repo
• vue_vite_repo

Do not ask those three as blank open-ended prompts. First provide 3 to 5 plausible answers, put the best current guess first, and then leave room for a custom answer.

If the request is still ambiguous after those three answers, ask at most two follow-up questions, for example:

• required sections
• explicit no-go content
• named visual references

Material search and handoff assembly should not begin until these decisions are stable.

Write the preflight outputs when useful:

• intake-questions.md
• intake-answers.json
• normalized-brief.md

Use scripts/build_intake.py if you want a deterministic artifact for the intake step.

Phase 2: Intake normalization

Read the user's raw request and normalize it into input-profile.json.

Decide:

• which input types are present
• which scenario fits best: replication, style_transfer, content_migration, hybrid, or from_scratch
• what output target is expected: single_html, react_vite_repo, vue_vite_repo, or other
• what constraints are fixed versus adaptable
• what is missing and should be tracked as a gap

Always surface ambiguity here instead of burying it later in code generation.

Phase 3: Material pack assembly

Collect or infer the materials the downstream agent needs:

• real assets
• content structure
• visual tokens
• missing items and substitutions

For image assets, do not stop at acquisition. Decide presentation rules too:

• should the image be cropped or preserved?
• what container aspect ratio fits the slot?
• what focal point should object-position follow?
• should it behave like full-bleed media, a framed image, or a contained diagram?
• if the image is long, panoramic, or tall, what part matters most?

Use the bundled tools when useful:

• scripts/crop_assets.py
• scripts/extract_palette.py
• scripts/pdf_extract.py
• scripts/image_search.py

Direct extraction beats web search. Web search beats made-up placeholders.

Do not leave remote image URLs in the final package. Search results, remembered URLs, and generated assets all need a local file path before handoff.

For text-only supplementation, the main material strategies are:

1. real image search for hero and supporting photography
2. generated SVG assets for logo, icons, arrows, and simple interface graphics
3. explicit image framing metadata so good images are used well instead of cropped randomly

Phase 4: Parallel sub-tasks

Once the intake answers are stable, split bounded work across sub-tasks if needed. Keep every worker aligned to the same normalized brief.

Recommended ownership split:

• image scout: search and describe image candidates with usage plus crop metadata
• SVG builder: generate local logo or icon assets that match the locked style direction
• handoff synthesizer: assemble plans, tokens, manifest, and final docs
• verifier: check consistency across all generated files before downstream code generation

No worker should reinterpret the raw prompt independently after intake. They should all read the same intake-answers.json, normalized-brief.md, and input-profile.json.

Phase 5: Handoff synthesis

Synthesize the structured material files into:

• generation-spec.md
• agent-handoff.md

Prefer using scripts/build_handoff.py when the structured inputs already exist.

The handoff should be implementation-ready for a separate agent with no extra context.

If intake-answers.json exists, pass it into scripts/build_handoff.py so the final docs carry the same locked decisions forward.

Phase 6: Verification

Before handing the package to a coding agent, run a verification pass.

Use scripts/verify_handoff.py when you have a package directory. The verifier should check:

• intake answers exist and are complete
• output target is valid
• content plan exists
• style tokens contain core values
• gaps are explicit
• image assets carry framing metadata
• agent handoff headings are in the required order
• asset slots map cleanly to content sections

The verifier should write:

• verification-report.md
• verification-report.json

Phase 7: Execution guidance

Give one agent-neutral brief, then add short notes for:

• Claude
• Codex
• OpenClaw

Do not fork into three entirely separate playbooks unless the user explicitly asks for that.

Quality bar

The handoff package should reduce guesswork for the downstream agent. That means it should make these things explicit:

• what the page is for
• what style direction is locked
• what to build
• what kind of codebase to produce
• what content belongs in which sections
• what assets are real and where they come from
• where the local asset files live inside the package
• how those assets should be cropped, fitted, or framed
• what visual language to follow
• what constraints cannot be broken
• what is still missing

If something is missing, record it in asset-manifest.json.gaps or input-profile.json.missing_inputs. Do not hide it.

If the package fails verification, fix the package before asking a downstream coding agent to implement it.

Reference files

• references/schemas.md - schemas for the package outputs
• references/pdf-extraction.md - document extraction strategies
• references/code-generation.md - generation-spec guidance for downstream implementation

Publishing and examples

When preparing public-facing results:

• show how the user answers the intake questions
• show at least one text-only example input
• show a before/after comparison from raw prompt to verified handoff