# Convert Url To Nextjs

> Use if rebuilding a live URL or .html snapshot as a pixel-faithful AS-IS Next.js project.

- **Type:** Skill
- **Install:** `agentstack add skill-yigitkonur-skills-by-yigitkonur-convert-url-to-nextjs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yigitkonur](https://agentstack.voostack.com/s/yigitkonur)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yigitkonur](https://github.com/yigitkonur)
- **Source:** https://github.com/yigitkonur/skills-by-yigitkonur/tree/main/plugins/convert-url-to-nextjs/skills/convert-url-to-nextjs

## Install

```sh
agentstack add skill-yigitkonur-skills-by-yigitkonur-convert-url-to-nextjs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Convert URL or HTML Snapshot to Next.js — AS-IS Pixel-Faithful Rebuild

## The scenario this skill is built for

A company lost the GitHub repo behind its frontend. The only thing left is the production build at `example.com`. The team wants the same-looking site back in their own stack — as a real, editable Next.js codebase — pixel-faithful to the deployed build, AS IS. The skill's job is to *recover what is already in the world*, not to redesign it. Throughout this workflow, when a judgment call surfaces between visual fidelity to the live deployed build and a more idiomatic Next.js choice, fidelity wins until the user explicitly opts out.

The output is one Next.js template per unique page type the source actually uses, plus a route map saying which live URLs are instances of which type. The user's expected next step after this skill finishes is usually to wire dynamic content (TinaCMS, MDX, or any CMS of their choice) onto those templates.

## When to use this skill

- *"Rebuild this URL as a Next.js site"* (live URL, with or without scope filtering).
- *"I lost my frontend repo and only have the build — recover the deployed site"* (the canonical lost-frontend scenario).
- *"Recover this page — the original repo is gone but the prod URL still works"* (production-only recovery).
- *"Convert this `.html` snapshot / SingleFile export into Next.js"* (offline `.html` + `_files/`, adjacent local CSS, or inline `` only).
- *"Clone / recreate / pixel-perfect / faithful rebuild"* of an existing public page in Next.js.
- *"Mirror this site offline as a Next.js app"* with self-hosted fonts, images, and icons.

## Do NOT use this skill when

- The only source is a screenshot, PDF, Figma, or "vibe" reference — there is no parseable HTML/CSS or live route. This skill needs inspectable implementation to rebuild; with no HTML to crawl, use a generic UI-build path instead.
- The user wants a **redesign, simplification, or "same vibe" rewrite** rather than faithful reconstruction.
- The user wants generic Next.js UI work with no source URL or snapshot grounding.
- The user wants a TinaCMS-backed editorial site from scratch — use `build-tinacms-nextjs`.

## Sibling routing

| Need | Route to |
|---|---|
| Browser capture and the back-to-back verification loop in *this* pipeline | `run-agent-browser` is the helper this skill drives. |
| Design-doc-only output for SaaS/dashboard/admin | a generic design-documentation path. Use this skill only when the deliverable is a buildable Next.js page. |
| New CMS-backed Next.js site | `build-tinacms-nextjs`. This skill is for URL/snapshot reconstruction, not CMS scaffolding. The user typically uses `build-tinacms-nextjs` *after* this skill, to wire content onto the recovered templates. |

## Setup contract

| Key | Value |
|---|---|
| **Output location** | `nextjs-project/` plus `.design-soul/` beside the capture or snapshot working root. |
| **Naming** | Routes, capture IDs, manifests, asset folders, CSS classes, and tokens use kebab-case. React component files and exported component symbols use PascalCase. |
| **Minified-CSS warning** | Captured/saved CSS is often minified (no trailing `;` before `}`). Reference grep patterns use `[^;}]+` — do not simplify to `[^;]+`, or extraction will silently miss values. |
| **Allowed deps** | Limited to the scaffold rules in `references/system-template.md`. No icon, animation, or font packages added for convenience. |

## Scripts

| Phase | Helper | Use |
|---|---|---|
| Capture | `scripts/capture-url.sh` (read `scripts/capture-url.md`) | Build the route capture skeleton, record expected artifacts, run the supplied browser-capture command. Never write a success signal on failure. |
| Wave 0 | `scripts/extract-styles.sh` (read `scripts/extract-styles.md`) | Detect the page CSS corpus and emit manifests plus custom-property, font, media-query, and keyframe summaries before manual extraction. |
| Verification | `scripts/diff-screenshots.sh` (read `scripts/diff-screenshots.md`) | Compare source vs build screenshots / paired directories and emit `.design-soul/visual/{route}/summary.json`. Do not fabricate diff metrics when tooling is missing. |

## Decide first: which input mode are you in?

| Situation | First action |
|---|---|
| Live URL only — the lost-frontend default | Run the **Capture Wave** on L0, then crawl L1 from the homepage, then run **type extraction**. See `references/type-extraction.md`. |
| Live URL + narrow scope request | Capture only in-scope L0+L1 routes, but still produce the route manifest and per-type cluster before implementing. |
| `.html` + `_files/` folders present | Skip live capture. Treat the snapshot as Wave 0 input directly; if multiple snapshots are present, still run type extraction on them. |
| `.html` + adjacent local `.css` files, no `_files/` | Use **adjacent-asset snapshot mode**. The local CSS and assets are the Wave 0 corpus. |
| `.html` with inline `` only | Use **SingleFile fallback mode**. Extract from inline styles and document reduced confidence. |
| `package.json` + source repo, no live site, no snapshot | **Source-fallback mode**: read source directly. Same grounding/verification rules apply. |
| Request says *extract*, *document*, *design system*, or *tokens* | Stop after the Capture Wave or Waves 0–2 unless the user explicitly asks to build. |
| Request says *rebuild*, *recreate*, *convert*, *clone*, *recover*, or *pixel-perfect* | Run the full pipeline: Capture → Type Extraction → Waves 0–4 → Back-to-back verification → Report back to user. |
| Source spans many routes / templates | The type-extraction phase handles this — cluster L1 URLs into unique types first, finish one type completely, then fan out. |
| Request is ambiguous | Default to grounded extraction first. Do not assume a full rebuild. |

Read `references/input-output-spec.md` for input detection, working-root rules, route normalization, output trees, and ambiguity handling. Read `references/capture-workflow.md` when starting from a live URL.

## Operating contract (load-bearing rules)

1. **Fidelity to the deployed build is the goal.** When a judgment call surfaces between visual fidelity and an "improvement," fidelity wins. Ask the user before deviating.
2. **Capture before extract when the source is live.** Build the L0+L1 route inventory, layout fingerprints, screenshots, runtime metadata, mirrored asset roots, and grounded DOM artifacts before Wave 0. See `references/capture-workflow.md` and `references/type-extraction.md`.
3. **One template per unique page type, not one template per URL.** See `references/type-extraction.md`.
4. **Preserve the strongest offline artifact set.** `_files/` folders, adjacent local CSS, and inline styles are all valid snapshot evidence. Do not discard a snapshot because it does not match one filename convention.
5. **Parse, don't guess.** Every value must trace to captured CSS, HTML, runtime metadata, or documented behavior. See `references/principles-and-rules.md`.
6. **Screenshots are for verification, not invention.** Use full-page and scroll-slice screenshots to detect missed structure and to measure fidelity — not to derive token values when CSS/HTML evidence exists.
7. **Build from extracted values only.** `tokens.ts`, `tailwind.config.ts`, `globals.css`, components, and route data must trace to Capture/Wave 0/Wave 1 artifacts. Mark unverifiable values `UNVERIFIED` rather than substituting defaults.
8. **Self-host everything.** Fonts, images, icons, and other assets must end up local. No CDN fonts. No remote image URLs.
9. **Preserve asset provenance.** Record original source URLs and asset origins. Self-host captured images, fonts, and icons only when the user owns or has permission to use them; otherwise mark replacements `UNVERIFIED` or user-supplied. Workflow guardrail, not legal advice.
10. **Verify back-to-back against the original before claiming a type is done.** See `references/back-to-back-verification.md`.
11. **If something cannot be grounded, mark it `UNVERIFIED`.** Honest gaps are allowed. Invented values are not.

## Do this / not that

| Do this | Not that |
|---|---|
| Treat the live deployed page as ground truth; recover AS IS | "Improve," modernize, or redesign while rebuilding |
| Capture L0 + every L1 link; cluster L1 by layout fingerprint into unique page types | Generate one Next.js route per URL |
| Produce one Next.js template per unique page type | Duplicate similar layouts as bespoke per-route JSX |
| Use CSS Module prefixes, semantic tags, heading outlines, and screenshot coverage together to identify sections | Infer structure from generic `` nesting or above-the-fold screenshots alone |
| Search across the full discovered CSS corpus per page, then deduplicate shared files | Read minified CSS by eye or treat each hashed CSS file as an isolated system |
| Carry exact source values through Capture / Wave 0 → Wave 4 | Round, normalize, or replace values because they look "close enough" |
| Run the back-to-back verification loop at 1440/768/375 per type before declaring done | Declare success from build success or spot-checking only the top viewport |
| Keep deps to the scaffold rules in `references/system-template.md` | Add UI, icon, animation, or font packages for convenience |

## The phased workflow at a glance

| Phase | Goal | Required reference | Primary outputs | Gate |
|---|---|---|---|---|
| 1. Capture (L0 + L1) | Crawl homepage and every same-origin link from it; capture hydrated DOM, screenshots, runtime metadata, and mirrored assets per URL | `references/capture-workflow.md` + `references/input-output-spec.md` | `.design-soul/capture/{route}/dom.html`, `mirror/`, screenshots, `runtime-metadata.json` | per-route capture artifacts present |
| 2. Type extraction (NEW NAMED PHASE) | Cluster L1 URLs into **unique page types** by layout fingerprint; choose a canonical exemplar per type; emit `route-map.json` | `references/type-extraction.md` | `.design-soul/types/route-map.json`, `page-types.md`, per-URL fingerprints | `route-map.json` complete, one exemplar per type |
| 3. Per-type rebuild | For each type, extract tokens (Wave 0), unify family (Wave 1), brief the build (Wave 2), scaffold (Wave 3), render (Wave 4) into **one** Next.js template per type | `references/foundations-agent.md`, `references/sections-agent.md`, `references/section-template.md`, `references/system-template.md`, `references/wave-pipeline.md`, `references/website-patterns.md` | `nextjs-project/app/...` (one template per type) | `wave3/foundation-ready.signal` + per-type Wave 4 build passes |
| 4. Back-to-back verification (NEW NAMED PHASE) | Per type, drive `run-agent-browser` to load the **original** exemplar URL and the **candidate** Next.js URL at the same viewport; compare; pass/iterate/escalate | `references/back-to-back-verification.md` + `scripts/diff-screenshots.md` | `.design-soul/verify/{type}/iterations.json`, screenshots, `summary.md`, `verification-report.md` | all types pass at desktop/tablet/mobile, or user-approved residual drift |
| 5. Report back to the user (NEW NAMED PHASE) | Surface every type found, the L1 URLs it covers, the template path, the verification evidence, the residual drift, and the recommended next step | This SKILL.md — "Report back to the user" section below | `RECOVERY-REPORT.md` at the working root | user has the complete map of what was rebuilt and what is optional from here |

If the user only asked for extraction or documentation, stop after Phase 2 or Wave 1 instead of pushing to build.

## Phase 1: Capture L0 and L1

The crawl is the homepage (L0) plus every same-origin link reachable from it (L1). The capture contract per URL is unchanged from the existing capture workflow.

- Open L0 with `run-agent-browser`. Wait for the page to settle. Capture hydrated `dom.html`, headings, runtime metadata, screenshots at 1440/768/375, and mirror the route's CSS/JS/fonts/images.
- Extract every same-origin in-DOM link from L0 (skip `mailto:`, `tel:`, `javascript:`, `#` anchors, external hosts, and obvious tracking/locale duplicates).
- Repeat the capture contract for each L1 URL. Treat sticky headers, lazy content, and modals as default-state captures unless the user asks otherwise.
- Crawl deeper than L1 only when the user explicitly opts in.

See `references/capture-workflow.md` for the full per-route capture contract, working-root selection, route normalization, and failure recovery. Use `scripts/capture-url.sh` to scaffold the per-route artifact skeleton; the script delegates to the browser command and verifies artifacts before returning success.

## Phase 2: Type extraction — one template per unique page type

This is the discrete named phase that converts the L1 URL set into the small number of **unique page types** the site actually uses. It runs before any rebuild work. Read `references/type-extraction.md` for the full procedure.

### What this phase produces

- `.design-soul/types/fingerprints/{slug}.json` — one layout fingerprint per L1 URL
- `.design-soul/types/route-map.json` — `{ typeId → { exemplarUrl, instances, nextjsTemplate, captureRoots } }`
- `.design-soul/types/page-types.md` — human-readable rationale per cluster (signal evidence, exemplar choice, notable instance differences)

### What goes into a layout fingerprint

Compute these for each L1 URL from the hydrated DOM:

- pathname pattern with slug/numeric segments replaced by `:slug`
- `` and `` class set (sorted, deduplicated)
- top-level section sequence — ordered CSS Module prefixes or semantic tags of the direct children of ``
- direct-child section count
- recognizable widget set — hero, pricing table, FAQ accordion, logo wall, testimonial cards, blog metadata, contact form, legal heading rhythm, etc.
- header/footer shell hash (hashed class names normalized)
- top-N CSS class prefixes across the body

### How clusters form

Two L1 URLs join the same type cluster when **all three** hold:

1. pathname template matches
2. section-sequence overlap ≥ ~70%
3. header/footer shell hash matches OR top class-prefix overlap ≥ ~60%

Homepage is always its own type. A cluster of size 1 is valid. A cluster of 20+ visually diverse instances is a signal to ask the user before continuing.

### Output to the rebuild phase

One Next.js template per type:

- single-instance type → `app/{type-route}/page.tsx`
- multi-instance type → `app/{type-route}/[slug]/page.tsx`

The rebuild phase reads `route-map.json` as its plan. Do not write any Next.js code until this phase has finished and `route-map.json` is on disk.

## Phase 3: Per-type rebuild

For each type in `route-map.json`, run the existing waves against the type's canonical exemplar (and any instance-specific overrides that surfaced in Phase 2):

- **Wave 0** — per-page exploration and deobfuscation. See `references/foundations-agent.md`. Use `scripts/extract-styles.sh` first to inventory the CSS corpus before manual extraction.
- **Wave 1** — unified design soul for the type's family. See `references/sections-agent.md`. Anatomy heuristics live in `references/website-patterns.md`.
- **Wave 2** — self-contained build brief per type. See `references/section-template.md`.
- **Wave 3** — Next.js scaffold and shared design-system foundation. See `references/system-template.md`. Allowed deps and `foundation-ready.signal` gate are defined there.
- **Wave 4** — render the type's template under `app/`. Full orchestration and quality gates live in `references/wave-pipeline.md`.

Think first:

- **Capture:** Which browser helper produces the complete evidence contract for this source? (Use `run-agent-browser`.)
- **Type extraction:** Are any clusters borderline? If yes, ask before committing.
- **Wave 0:** Which CSS corpus is strongest for this type — mirrored live capture, `_files/`, adjacent CSS, inline CSS, or source fallback?
- **Wave 3:** Which types stay static, and which exact interactions justify Client Components?
- **Wave 4:** Ha

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yigitkonur](https://github.com/yigitkonur)
- **Source:** [yigitkonur/skills-by-yigitkonur](https://github.com/yigitkonur/skills-by-yigitkonur)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yigitkonur-skills-by-yigitkonur-convert-url-to-nextjs
- Seller: https://agentstack.voostack.com/s/yigitkonur
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.