# Best Practices for Using the `clone-website` Skill in Next.js 16

> Master the clone-website skill in Nextjs. Achieve pixel-perfect clones by following best practices: validate scaffolds, sweep interactions, dispatch builders, and verify builds. Learn more now.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: best-practices
- Published: 2026-06-30

---

**The `clone-website` skill guarantees pixel-perfect clones when you validate the base scaffold first, complete a full interaction sweep before writing specs, dispatch builders only after exhaustive component specifications, and verify builds after every merge.**

This automated pipeline reverse-engineers any public website into a clean, maintainable Next.js 16 codebase. The `clone-website` skill in the [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template) repository manages the entire workflow through five auditable phases—each producing artifacts that ensure reproducibility and accuracy.

## The Five-Phase Clone Pipeline

The skill operates sequentially, with each phase generating specific artifacts that feed into the next.

| Phase | Goal | Core Artifacts Created |
|-------|------|------------------------|
| **1️⃣ Reconnaissance** | Capture screenshots, design tokens, and complete interaction behavior | `docs/design-references/…`, [`docs/research/BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/BEHAVIORS.md) |
| **2️⃣ Foundation Build** | Establish global assets and verify the base scaffold | [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx), [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css), `public/seo/…` |
| **3️⃣ Component Specification** | Write exhaustive specs before any code generation | `docs/research/components/<Component>.spec.md` |
| **4️⃣ Parallel Builder Dispatch** | Spin up isolated work-trees for concurrent component building | Work-tree branches, `src/components/…` |
| **5️⃣ Assembly & QA** | Merge components and perform visual diff verification | [`src/app/page.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/page.tsx), diff screenshots |

According to the source code in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md), skipping any phase or creating incomplete artifacts causes downstream failures—particularly during the visual QA diff where every pixel deviation must be traceable to a specific specification.

## Essential Best Practices for `clone-website` Success

### Validate the Base Scaffold Before Invoking the Skill

The repository must build successfully before the skill runs. The scaffold includes Next.js 16, shadcn/ui, and Tailwind v4—any missing dependency causes immediate abort.

```bash
npm install && npm run build

```

Run this verification from the repository root. The `next build` command validates TypeScript, bundle integrity, and asset paths that the skill assumes are functional.

### Execute the Skill with Explicit URLs

The skill accepts multiple URLs and creates isolated research folders per hostname:

```bash
/clone-website https://example.com https://another-site.org

```

Each URL generates a dedicated folder under `docs/research/<hostname>/` containing captured assets, behaviors, and specifications. This isolation prevents cross-contamination when cloning multiple sites.

### Complete the Full Interaction Sweep Before Writing Specs

**Never** begin component specifications until the interaction sweep finishes. The skill captures scroll positions, click states, hover effects, and responsive breakpoints at three widths: desktop (1440px), tablet (768px), and mobile (390px).

This sweep populates [`docs/research/BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/BEHAVIORS.md) with state transition data. Without this file, component specs cannot document behavior changes accurately—leading to incomplete clones that miss interactive elements.

### Write Exhaustive Spec Files for Every Component

Dispatching builders without specifications produces inconsistent results. Each [`.spec.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.spec.md) file must contain:

- **Screenshot reference**: Exact path to captured image
- **Computed styles**: Values from `getComputedStyle()` including all responsive states
- **Interaction model**: Trigger conditions and state transitions
- **Asset inventory**: Fonts, images, SVGs with their public paths
- **Verbatim text**: All copy exactly as rendered

Example specification structure:

```markdown

# HeroSection Specification

## Overview

- Target file: `src/components/HeroSection.tsx`
- Screenshot: `docs/design-references/hero-desktop.png`
- Interaction model: scroll-driven

## Computed Styles

### Container

- display: flex
- padding: 2rem 1rem
- background-color: #1e293b

## States & Behaviors

- Trigger: scroll position ≥ 80px
- State A → B: height 80px → 64px, box-shadow none → 0 2 4 rgba(0,0,0,0.1)

## Assets

- Background image: `public/images/hero-bg.webp`

## Text Content

- "Build your future with AI-powered tools."

```

The template lives in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) under Step 2.

### Respect the Complexity Budget

When a specification exceeds approximately 150 lines, split the component into sub-components. This constraint keeps builder prompts manageable, reduces token consumption, and minimizes merge conflicts during the assembly phase.

### Dispatch Builders Immediately After Spec Completion

The skill automatically injects spec content inline into builder prompts—never as file references. According to the dispatch logic in [`SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/SKILL.md), builders receive the full specification text directly, ensuring consistent context without file system dependencies.

### Verify Build Success After Every Merge

Run `npm run build` immediately after each work-tree merge. TypeScript errors or missing imports block subsequent phases. Fix these before dispatching additional builders to prevent cascading failures.

### Perform Rigorous Visual QA

The final phase requires side-by-side screenshots of the original site and the cloned version at desktop and mobile widths. Any pixel discrepancy must be traced to its specification, corrected in the spec file, and the component rebuilt.

### Synchronize Repository Changes

After modifying shared configuration files like [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) or the skill definition, regenerate platform-specific copies:

```bash
bash scripts/sync-agent-rules.sh        # Regenerate AGENTS for all agents

node scripts/sync-skills.mjs            # Regenerate /clone-website skill

```

These scripts maintain consistency across supported AI platforms.

## Practical Implementation Examples

### Basic Skill Invocation

```bash
/clone-website https://my-awesome-site.com

```

### CI-Ready Build Verification

Add these scripts to [`package.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json) for automated validation:

```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "lint": "eslint . --ext .ts,.tsx",
    "typecheck": "tsc --noEmit",
    "check": "npm run lint && npm run typecheck && npm run build"
  }
}

```

Run `npm run check` before and after skill execution to ensure code integrity.

## Critical Files in the Repository

| File | Purpose |
|------|---------|
| [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) | Canonical skill definition with all phases and builder dispatch logic |
| [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) | Central source of truth for agent instructions across platforms |
| `scripts/sync-skills.mjs` | Regenerates skill files for all supported platforms |
| [`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh) | Recreates platform-specific agent configurations |
| [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) | Shared `cn()` utility for Tailwind class composition |
| [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) | Global layout where fonts and metadata are configured |
| [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md) | Manual inspection guide for custom skill modifications |

## Summary

- **Validate first**: Ensure `npm run build` succeeds before invoking the skill
- **Capture completely**: Document all interactions, states, and responsive breakpoints during reconnaissance
- **Specify exhaustively**: Write detailed component specs before dispatching any builders
- **Build incrementally**: Verify TypeScript and bundle integrity after every work-tree merge
- **Verify visually**: Perform pixel-perfect diffs against the original site before considering the clone complete

Following these best practices for the `clone-website` skill produces reproducible, maintainable Next.js 16 codebases that match target sites with high fidelity.

## Frequently Asked Questions

### What happens if I skip the interaction sweep and start building components immediately?

The [`BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/BEHAVIORS.md) file will remain incomplete, causing component specifications to omit scroll-driven animations, hover states, and responsive transformations. This results in static clones that fail to replicate the original site's interactive behavior. The visual QA phase will catch these omissions, but remediation requires restarting the specification process.

### Can I clone multiple websites in parallel using the same repository?

Yes. The skill automatically creates isolated folders under `docs/research/<hostname>/` for each URL provided. However, ensure adequate disk space and consider sequential execution if the sites share component names that might cause naming collisions in the global `src/components/` directory.

### Why does the skill require explicit build verification before starting?

The `clone-website` pipeline assumes a functional Next.js 16, Tailwind v4, and shadcn/ui environment. Compilation errors in the base scaffold propagate into every builder dispatch, causing silent failures or incomplete component generation. The `npm run build` validation confirms all dependencies and configurations are operational.

### How do I handle components that change significantly based on user interaction?

Document every state transition in the specification file's **States & Behaviors** section. Include the trigger condition (e.g., scroll position, click event), the CSS properties that change, and their computed values for each state. The builder receives this inline and implements the transition logic accordingly.