---
name: website-clone
description: Clone any website into a pixel-perfect Next.js App Router project. Use when asked to "clone", "replicate", or "copy" a website.
metadata:
  tags: clone, scrape, playwright, firecrawl, nextjs, react, tailwind
---

# Website Clone Skill

Clone any website into a **pixel-perfect** Next.js project.

## Requirements

- Firecrawl API key (`FIRECRAWL_API_KEY` env or `getFirecrawlApiKey()`)
- Playwright: `npx playwright install chromium`

---

## Workflow

Execute these steps in order:

| Step | Task | Guide |
|------|------|-------|
| 0 | Scaffold Next.js + shadcn/ui project | [workflow/step0-scaffold.md](workflow/step0-scaffold.md) |
| 1 | Render the target website | [workflow/step1-render.md](workflow/step1-render.md) |
| 2 | Scrape assets and content | [workflow/step2-scrape.md](workflow/step2-scrape.md) |
| 3 | Analyze page structure | [workflow/step3-analyze.md](workflow/step3-analyze.md) |
| 4 | Generate TSX components | [workflow/step4-generate.md](workflow/step4-generate.md) |
| 5 | Validate the clone | [workflow/step5-validate.md](workflow/step5-validate.md) |

---

## Rules Reference

| Topic | Guide |
|-------|-------|
| Prohibited actions | [rules/dont-do.md](rules/dont-do.md) |
| Generating pixel-perfect code | [rules/generating.md](rules/generating.md) |
| Handling JS animations & non-extractable elements | [rules/manual-replication.md](rules/manual-replication.md) |
| Tailwind v4 styling | [rules/styling.md](rules/styling.md) |
| Asset handling | [rules/assets.md](rules/assets.md) |
| Validation checklist | [rules/validating.md](rules/validating.md) |

---

## Plugin API

The plugin at `plugin/index.ts` provides these utilities:

| Function | Purpose |
|----------|---------|
| `scaffoldProject()` | Copy boilerplate files (Next.js + shadcn/ui) |
| `installShadcnComponents()` | Install additional shadcn components |
| `renderPageWithExtraction()` | Render page + auto-extract fonts/colors |
| `scrapePage()` | Download assets via Firecrawl |
| `getFirecrawlApiKey()` | Load Firecrawl API key from config/env |
| `extractComputedStyles()` | Get exact CSS values from rendered elements |
| `compareScreenshots()` | Visual diff between original and clone |
| `generateAgentsMd()` | Generate AGENTS.md for the project |
| `writeFile()` | Write files to disk |

Full API documentation: [README.md](README.md)

## Templates

The `templates/` directory contains ready-to-use boilerplate:

```
templates/
├── package.json        # Next.js 15 + Tailwind 4 + shadcn dependencies
├── next.config.ts      # Next.js configuration
├── tsconfig.json       # TypeScript configuration
├── components.json     # shadcn/ui configuration
├── postcss.config.mjs  # PostCSS for Tailwind
├── eslint.config.mjs   # ESLint configuration
├── .gitignore
└── src/
    ├── lib/utils.ts    # cn() helper for shadcn
    ├── app/
    │   ├── layout.tsx  # Root layout
    │   └── globals.css # Tailwind 4 @theme
    └── components/ui/
        └── button.tsx  # Example shadcn component
```

---

## Quick Start

```ts
import {
  createProjectStructure, 
  scaffoldProject,
  renderPageWithExtraction, 
  scrapePage, 
  generateAgentsMd,
  writeFile,
  getFirecrawlApiKey
} from './plugin';
import FirecrawlApp from '@mendable/firecrawl-js';

// 0. Scaffold
await createProjectStructure('./output');
await scaffoldProject('./output', './templates');

// 1. Render
const render = await renderPageWithExtraction({url: 'https://example.com'});

// 2. Scrape
const firecrawl = new FirecrawlApp({apiKey: getFirecrawlApiKey()});
const scrape = await scrapePage({...});

// 3. Analyze (YOU do this - look at render.html and screenshot)
// 4. Generate (YOU do this - write TSX components)

// 5. Generate AGENTS.md
const agentsMd = generateAgentsMd({
  sourceUrl: 'https://example.com',
  siteName: 'Example Site',
  sections: ['Navigation', 'Hero', 'Features', 'Footer'],
});
await writeFile('./output/AGENTS.md', agentsMd);

// 6. Validate (compare screenshots)
```

---

## Critical Reminders

Read [rules/dont-do.md](rules/dont-do.md) before generating any code.

The goal is a clone that is **indistinguishable** from the original:

- Exact hex colors, not Tailwind approximations
- Exact pixel values, not rounded spacing
- Local assets, not remote URLs
- Preserved complexity, not simplified layouts

**When HTML extraction fails, look at the screenshot and replicate manually.**