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

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 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
2️⃣ Foundation Build	Establish global assets and verify the base scaffold	src/app/layout.tsx, 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, diff screenshots

According to the source code in .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.

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:

/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 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 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:

# 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 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, 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 or the skill definition, regenerate platform-specific copies:

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

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

CI-Ready Build Verification

Add these scripts to package.json for automated validation:

{
  "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	Canonical skill definition with all phases and builder dispatch logic
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	Recreates platform-specific agent configurations
src/lib/utils.ts	Shared cn() utility for Tailwind class composition
src/app/layout.tsx	Global layout where fonts and metadata are configured
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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}