# Competitor Teardown

> Tear down any public website or product from its URL: crawls the whole site with Playwright, captures full-page screenshots and HTML, auto-generates approximate wireframes per page, classifies every page into sections (nav, hero, social proof, features, pricing, FAQ, CTA…), detects the tech stack, then guides a UX/UI critique, information-architecture map, business-model decode (pricing tiers, ICP, sales motion), and hook/funnel analysis (AARRR + Hook Model + persuasion and dark patterns), and assembles a self-contained HTML report that can be published as an Artifact. Use when the user says 'tear down', 'teardown', 'competitor analysis of <url>', 'break down this website/product', 'wireframe this site', 'how does <site> hook/convert users', 'analyse <competitor>', or asks to compare a rival's website, pricing, onboarding, or UX.

- Skill: `emamulmursalin47/competitor-teardown` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add emamulmursalin47/competitor-teardown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/emamulmursalin47/competitor-teardown/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: emamulmursalin47 (https://skillmd.com/u/emamulmursalin47)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/emamulmursalin47/competitor-teardown

---


# competitor-teardown — from URL to a full product teardown

Six stages. Scripts do the deterministic work (crawl, screenshots, HTML, geometry, wireframes, tech stack, report build); you do the judgement (interactive flows, UX critique, business model, hook/funnel). Data flows through JSON files in the output directory, so every stage can be re-run alone.

`$SKILL` below = the directory containing this file (`~/.claude/skills/competitor-teardown`).

## What this produces

```
teardowns/<domain>/<YYYY-MM-DD>/
├── crawl.json            pages[], link graph, stats, errors
├── network.json          third-party hosts per page
├── techstack.json        detected technologies
├── analysis.json         your analysis (validated against templates/analysis.schema.json)
├── analysis.md           readable twin of analysis.json
├── report.html           self-contained report (screenshots + wireframes embedded)
├── report.artifact.html  only with --artifact: downscaled images, < 15 MB, for publishing
├── pages/<slug>/         screenshot.png · page.html · geometry.json · meta.json · wireframe.svg
└── flows/<flow>/         NN-<step>.png from the interactive pass
```

## Stage 0 — Prerequisites

```bash
test -d "$SKILL/scripts/node_modules/playwright" || (cd "$SKILL/scripts" && npm install && npx playwright install chromium)
```
Tell the user if this installs anything (≈100 MB Chromium download once).

## Stage 1 — Intake

Ask only for what is missing; never block on optional items:
- **URL(s)** (required). Competitor name defaults to the hostname.
- **"Our product" context** (optional, one paragraph): who you are, your ICP, your positioning. With it, `opportunities` becomes comparative ("we could…"); without it, it is generic.

Set `OUT=teardowns/<host-without-www>/<YYYY-MM-DD>` relative to the current working directory. State the default scope out loud: *whole site, same host, no page cap*. Flags the user can add: `--max-pages N`, `--depth N`, `--exclude '<regex>'`, `--include-subdomains`, `--concurrency N` (default 3), `--delay ms` (default 500), `--resume`.

## Stage 2 — Crawl

```bash
node "$SKILL/scripts/crawl.mjs" <url> [<url>…] --out "$OUT" [flags]
```
- Watch stderr: one line per page `[n/—] /path  ok  1.8s` or `FAIL <reason>`.
- If more than ~150 pages are discovered (crawl.json is written only at the end, so judge from the counter) and the crawl is still going after a few minutes, tell the user and offer `--max-pages` / `--exclude` / `--depth 2`. Do **not** kill the crawl unilaterally — whole-site is the chosen default.
- Interrupted? Re-run the same command with `--resume`; pages that already have `meta.json` are skipped.
- Exit code 1 means zero pages succeeded — see Failure modes.

## Stage 3 — Wireframes and tech stack

```bash
node "$SKILL/scripts/wireframe.mjs" --out "$OUT"      # one line per page: slug: nav › hero › features › …
node "$SKILL/scripts/techstack.mjs" --out "$OUT"      # prints category  name (confidence)
```
`wireframe.mjs` writes `pages/<slug>/wireframe.svg` and adds `sections[]` into each `geometry.json`. The classifier is heuristic — you will correct types in Stage 5 from the screenshots.

## Stage 4 — Interactive flows (optional, Playwright MCP)

Read `$OUT/crawl.json` and pick **at most 6** flows that a static crawl cannot show: signup start, pricing monthly/annual toggle, "book a demo" modal, onboarding steps reachable without login, in-site search, chat widget, interactive demo. For each:
1. `mcp__plugin_playwright_playwright__browser_navigate` to the page.
2. Act with `browser_click` / `browser_type` / `browser_select_option`.
3. `browser_take_screenshot` after each meaningful step, saving to `$OUT/flows/<flow-slug>/NN-<step>.png` (create the directory first).
4. Note what changed.

Never enter real credentials or submit forms that create accounts or send messages. Skip this stage entirely when nothing interactive matters (docs sites, brochure sites) and say so.

## Stage 5 — Analysis (you)

1. Read `$OUT/crawl.json`. Choose 5–12 key pages per `references/ux-section-taxonomy.md` §2 (landing, pricing, signup/demo, strongest feature/solution pages, about, one docs/blog index).
2. For each key page: Read `pages/<slug>/meta.json` and the `sections` in `geometry.json`; view `screenshot.png` and `wireframe.svg` (Read the image files). Confirm/correct section types, write notes and the five-score critique per `references/ux-section-taxonomy.md` §3–4.
3. Site-level: build `siteMap` from `crawl.json.pages[]`; write `uiArchitecture` from what repeats across screenshots; decode `businessModel` per `references/business-model-patterns.md`; write `hookAndFunnel` per `references/hook-and-funnel.md`; merge `techstack.json.detected[]` with your own reading into `techStack[]` (keep detector rows, add inferred ones as `confidence: "low"`); write `opportunities` (quick wins / medium term / strategic); add `flows[]` from Stage 4.
4. Optional: invoke the `design-craft` skill (AUDIT mode) on 1–3 key screenshots and fold its findings into `critique`.
5. Write `$OUT/analysis.json` conforming to `$SKILL/templates/analysis.schema.json` (all nine top-level keys required; scores are integers 1–5) and `$OUT/analysis.md` with the same content in prose.

Evidence rule: every strength, weakness, funnel item, and persuasion pattern cites `slug § section-type` or `flows/<slug>/NN`. Inferences are labelled as inferences.

## Stage 6 — Report

```bash
node "$SKILL/scripts/build-report.mjs" --out "$OUT"          # → report.html
```
If it exits 1 with `analysis.json invalid:` lines, fix those fields and re-run. Then `open "$OUT/report.html"` (macOS) and tell the user the path.

Offer to publish. If yes:
```bash
node "$SKILL/scripts/build-report.mjs" --out "$OUT" --artifact   # → report.artifact.html (< 15 MB or fails)
```
then use the `Artifact` tool on `report.artifact.html` with favicon `🔍` (artifacts are private by default). If the artifact build fails on size, trim `pages[]` to the most important 8 and drop flow screenshots, rebuild.

## Recap format

End with: pages crawled / failed; the 5 most important findings (one line each, with evidence); the report path and the Artifact URL if published; what was skipped and why.

## Failure modes

| Symptom | What to do |
|---|---|
| Every page `FAIL HTTP 403` or a Cloudflare/“verify you are human” page in screenshots | Bot protection. Retry with `--concurrency 1 --delay 2000`; if still blocked, tell the user and fall back to the Playwright MCP for a handful of pages (headed browsers often pass). |
| Only the seed page crawled on a JS app | Links are read from the rendered DOM, so this usually means client-side routing with no `<a href>`. Use Stage 4 for navigation, or pass more seed URLs. |
| Thousands of pages (blog/docs/pagination) | `--exclude '\?page=|/tag/|/author/'`, `--depth 2`, or `--max-pages 200`. Ask before narrowing. |
| Screenshot cut off or repeating header | Page > 20 000 px (capped) or a sticky element the hider missed; note it in `wireframeNotes`. |
| `analysis.json invalid` | The message lists `$.path: problem` lines; fix exactly those. |
| `report.artifact.html > 15 MB` | Fewer `pages[]`, fewer flow screenshots. |

## Re-running pieces

- New analysis, same crawl: edit `analysis.json`, re-run Stage 6.
- Crawl more pages later: Stage 2 with `--resume`, then Stages 3 and 6.
- Extend tech detection: add a row to `scripts/lib/signatures.mjs`. Extend section types: `scripts/lib/sections.mjs` + the `enum` in `templates/analysis.schema.json`.