website-research

name	website-research
description	Use when capturing screenshots of websites for design research, comparing competitor marketing pages, creating annotated HTML galleries, or when the user mentions website reference, competitor analysis, marketing review, or screenshot galleries for public websites.

Website Research

Capture screenshots of public websites, generate annotated HTML galleries, and import to Figma for marketing and design review.

Shared reference: Read shared/common-steps.md for permissions, shell variable rules, Figma MCP setup, gallery generation, Figma import, annotation reference, comparison gallery, and troubleshooting. This file covers only website-specific steps.

Quick Reference

Step	What	Key Decision
0	Permissions	Switch to auto mode
1	Prerequisites	agent-browser required, Figma MCP optional
2	Gather ALL user input in one interaction	URLs or discovery query, pages, objective, annotations, Figma
3	Capture screenshots + journey notes	Handle cookie banners, popups, chat widgets
4	Deduplicate screenshots	Remove near-duplicates before review
5	Write review brief	One per site
6	Dispatch marketing-reviewer subagent(s)	Validate manifest counts after
7	Dispatch marketing-comparator subagent	Multi-site only
8	Generate HTML gallery, verify, get approval	Start server once, keep alive
9	Import to Figma	Optional
10	Cleanup	Kill local HTTP server

BEFORE YOU START: Create Tasks

Use TaskCreate to create a task for each step. Mark each as in_progress when starting and completed when done. This prevents skipping steps.

Tasks to create:

1. "Step 0: Permissions check"
2. "Step 1: Prerequisites"
3. "Step 2: Gather user input"
4. "Step 3: Capture screenshots"
5. "Step 4: Deduplicate screenshots"
6. "Step 5: Write review brief"
7. "Step 6: Dispatch marketing-reviewer"
8. "Step 7: Dispatch marketing-comparator (if multi-site)"
9. "Step 8: Generate HTML gallery"
10. "Step 9: Import to Figma (optional)"
11. "Step 10: Cleanup"

Step 0: Permissions (DO THIS FIRST — MANDATORY)

Read shared/common-steps.md → "Permissions" and "No Shell Variables in Bash Commands" sections. Follow those instructions exactly. Recommend the user switch to auto mode before the command-heavy steps — this skill runs agent-browser screenshots, the local gallery server, and Figma MCP calls.

Step 1: Prerequisites

Check that required tools are available before gathering input.

Check	How	Fix
agent-browser	which agent-browser	npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser
Figma MCP (optional)	Check for mcp__figma__generate_figma_design in available tools	See shared/common-steps.md → "Figma MCP Setup"

Step 2: Gather User Input (Single Interaction)

The user should answer everything in one interaction, then walk away. Use AskUserQuestion to gather all of the following.

Question: How would you like to provide websites?

1. "I'll paste URLs" — user provides specific URLs
2. "Discovery query" — user provides a query like "wpforms competitors" or "best SaaS pricing pages"

If discovery mode: Use WebSearch to find relevant sites. Present a numbered list of discovered sites (name, URL, brief description). Ask the user to pick which ones to capture.

Question: Which pages to capture per site?

For each selected site, ask:

1. Homepage only — just the landing page
2. Homepage + pricing + features — the core marketing pages
3. Specific pages — user lists URLs or page names
4. Let me explore and suggest pages — you'll navigate the site, find key pages, and propose a list before capturing

If the user chooses option 4, navigate the site with agent-browser, build a page list from the navigation, and present it for approval before any screenshots.

Question: Review objective (optional)

• Marketing effectiveness — above-the-fold impact, value prop clarity, social proof, CTAs
• Visual design — layout, typography, color, whitespace, brand coherence
• Conversion flow — landing-to-action path, form UX, pricing presentation, objection handling
• Content strategy — messaging hierarchy, feature-vs-benefit framing, audience targeting, tone
• Specific objective — free text (e.g., "How well does the pricing page handle objections?")
• None (screenshots only) — capture pages with no analysis

Question: Comparison (only if 2+ sites selected)

• "Would you like a side-by-side comparison of these sites?"
• Options: "Yes — include a comparison table" / "No — just individual reviews"

Question: Annotation depth

• None — screenshots only, no annotations (fastest)
• Light — brief colored callouts (positive/critical/observation) with 1-2 sentence descriptions
• Impact & Opportunity — each annotation scored on Impact (1-5) and Opportunity (1-5)

Question: Figma import

• "Do you have a Figma file URL for import?"
• Options: "Yes, I'll paste it" / "Skip Figma import"

After gathering input, print a summary:

Website Research Plan:

• Sites: Stripe (stripe.com), Square (squareup.com), Paddle (paddle.com)
• Pages per site: Homepage + pricing + features
• Objective: Conversion flow
• Comparison: Yes
• Annotations: Impact & Opportunity
• Figma import: Yes (fileKey: XXXXX)
• Estimated screens: ~6-9 per site

I'll now work through the capture and review autonomously. I'll check in when the HTML gallery is ready for your approval before importing to Figma.

This lets the user walk away while work happens.

Step 3: Capture Screenshots

For each site and page, navigate with agent-browser and capture screenshots.

Create Directory

mkdir -p screenshots/<site-slug>

Use a URL-derived slug (e.g., stripe.com → stripe, squareup.com → squareup).

Navigate and Capture

agent-browser --session <session> open "<url>"

After navigating, follow shared/common-steps.md → "Screenshot Capture Strategy" — this covers image loading waits and chunked capture for long pages.

Quick summary of the capture flow:

1. Set tall viewport: agent-browser set viewport 1280 1440 --session <session>
2. Scroll the full page top-to-bottom to trigger lazy images (see common-steps for the eval script)
3. Wait for all images to finish loading
4. Measure page height — if > 4× viewport (~5800px+), use chunked capture (scroll by 1440px per chunk, no overlap, named XX-description-p1.png, -p2.png, etc.)
5. If page is short enough, use a single --full screenshot

Rules:

• Naming: XX-description.png (01-homepage.png, 02-pricing.png, 03-features.png, etc.). For chunks: XX-description-p1.png, -p2.png, etc.
• After each screenshot, Read the PNG file to verify it captured correctly. If the Read fails due to image dimensions exceeding limits, switch to chunked capture.

See shared/common-steps.md → "agent-browser Click Syntax" for ref syntax rules.

Auto-Dismiss Popups & Overlays

Before every screenshot, run this eval to automatically detect and remove consent banners, newsletter popups, chat widgets, and other overlays the user did NOT ask to capture:

agent-browser --session <session> eval "(function(){var sels=['[class*=consent]','[class*=cookie]','[id*=cookie]','[class*=gdpr]','[id*=gdpr]','[class*=popup]','[class*=modal]:not([class*=nav])','[class*=overlay]:not([class*=nav])','[class*=newsletter]','[class*=subscribe]','[id*=newsletter]','[class*=chat-widget]','[class*=chat-bubble]','[id*=intercom]','[id*=drift]','[id*=hubspot-messages]','[class*=notification-bar]','[class*=sticky-bar]','[class*=announcement]','[id*=onetrust]','[id*=sp_message]','[id*=CybotCookiebot]','[class*=cc-window]','[id*=truste]','[class*=evidon]'];var removed=[];sels.forEach(function(s){document.querySelectorAll(s).forEach(function(el){if(el.offsetHeight>0&&getComputedStyle(el).position!=='static'){removed.push(s);el.remove()}})});document.querySelectorAll('body > div').forEach(function(el){var st=getComputedStyle(el);if((st.position==='fixed'||st.position==='sticky')&&el.offsetHeight<300&&el.offsetHeight>0){removed.push('fixed-bar');el.remove()}});document.body.style.overflow='auto';document.documentElement.style.overflow='auto';return 'Removed: '+removed.length+' elements'})()"

This script:

1. Targets common consent/cookie/GDPR banner selectors (OneTrust, CookieBot, TrustArc, Evidon, generic patterns)
2. Targets popup/modal/overlay elements (excluding navigation-related ones)
3. Targets chat widgets (Intercom, Drift, HubSpot, generic)
4. Targets newsletter/subscribe overlays and sticky notification bars
5. Removes any small fixed/sticky bars on <body> (likely banners, not page content)
6. Restores scroll on <body> and <html> (many consent overlays lock scrolling)
7. Only removes elements that are visible (offsetHeight > 0) and positioned (not static), avoiding false positives on hidden template elements

Run this once after page load, before the scroll-to-trigger-lazy-images step. If you see popups reappearing after navigation to a new page, run it again.

First-screenshot verification: After capturing the FIRST screenshot of each site, Read the PNG immediately and check for any visible popups, banners, or overlays. If you see one that the auto-dismiss script missed, dismiss it manually (see fallback below), re-run the auto-dismiss script, and retake the screenshot. Only proceed with the remaining pages once the first screenshot is confirmed clean. This prevents discovering popups only at gallery review time.

If the auto-dismiss script misses a popup: Fall back to manual dismissal — use snapshot -i to identify the element, then either click its close/accept button by [ref=XX] or remove it with a targeted eval.

Cookie banners that reappear after dismiss: Some banners reappear on every page because the consent cookie wasn't set. Use eval to set it directly:

agent-browser --session <session> eval "document.cookie = 'cookie_consent=accepted; path=/; max-age=86400'"

Then reload the page. For known consent platforms:

# OneTrust
agent-browser --session <session> eval "document.cookie = 'OptanonAlertBoxClosed='+new Date().toISOString()+'; path=/; max-age=86400'"
# CookieBot
agent-browser --session <session> eval "document.cookie = 'CookieConsent={stamp:%27-1%27,necessary:true,preferences:true,statistics:true,marketing:true}; path=/; max-age=86400'"

Sites with Anti-Bot Protection

Some sites use Cloudflare, reCAPTCHA, Vercel Security Checkpoint, or other anti-bot measures. If agent-browser is blocked:

1. Note the limitation in the review brief (include which protection was encountered — e.g., "Blocked by Vercel Security Checkpoint")
2. Screenshot what is accessible (the challenge page itself can be a finding)
3. Move on to the next site — do not spend time trying to bypass protection

Known blockers: Cloudflare challenge pages, reCAPTCHA gates, Vercel Security Checkpoint (increasingly common on Next.js/Vercel-hosted sites), Akamai Bot Manager.

Wayback Machine fallback: If a site is blocked by bot protection, try loading it via the Wayback Machine (web.archive.org/web/<url>). The archived version bypasses the protection since it's served from archive.org. The content may be slightly outdated, but for design/UX research purposes the layout and visual design are usually still representative. Note in the review brief that screenshots were captured from the Wayback Machine archive.

Journey Notes

As you capture each screenshot, write a brief journey note describing what you observed. Record things like:

• Page load speed impressions (fast, slow, content jumping around)
• Pop-ups, modals, or banners that appeared before/during the visit
• Scroll depth required to reach key content or CTAs
• Navigation structure observations (clear, confusing, deeply nested)
• Trust signals you noticed (or conspicuous absence of them)

Keep each note to 1-3 sentences. Factual observations, not analysis — the subagent does the analysis.

SPA / JavaScript-Heavy Sites

Problem	Solution
Navigation doesn't trigger page load	Use open with the full URL rather than clicking nav links
Content loads after JS render	Add a short wait: agent-browser --session <session> eval "await new Promise(r => setTimeout(r, 2000))" then snapshot -i

Step 4: Deduplicate Screenshots

Before writing the review brief, list all captured screenshots and Read any with similar names that might be duplicates. Delete near-duplicates — keep the cleanest capture.

Step 5: Write Review Brief

After all screenshots are captured for a site, write a review brief that consolidates everything the subagent needs.

File: screenshots/<site-slug>/review-brief.md

Template:

# Review Brief: <Site Name>

## Objective
<Exact objective text from Step 2>

## Annotation Depth
<"light" or "impact-opportunity">

## Site Metadata
- **Name:** <site name from page title or meta>
- **URL:** <base URL>
- **Description:** <meta description or brief summary of what the site/company offers>

## Pages Captured
<Numbered list of all URLs/pages captured>

## Capture Scope
<What the user chose to capture and why. Note any pages skipped or inaccessible.>

## Screenshots & Journey Notes

### 01-homepage.png
**Page:** <URL>
**Journey:** <1-3 sentences of what you observed>

### 02-pricing.png
**Page:** <URL>
**Journey:** <1-3 sentences>

<!-- Continue for every screenshot -->

Step 6: Marketing Review (Subagent — Optional)

If annotation depth is "none": skip this step entirely — go straight to Step 8.

Dispatch a general-purpose subagent to analyze screenshots using the marketing-reviewer prompt template. Do NOT analyze screenshots yourself — delegate to the agent.

Before dispatching, inform the user:

Dispatching marketing review agents now. No action needed on your side — I'll check in when the galleries are ready for your approval.

Dispatch with the Agent tool:

• subagent_type: "general-purpose"
• Prompt: Paste the full content of agents/marketing-reviewer.md into the prompt, then tell the agent to:
  1. Read the review brief at screenshots/<site-slug>/review-brief.md
  2. Read each screenshot PNG listed in the review brief using the Read tool
  3. Analyze and return annotations per the marketing-reviewer instructions

For multi-site reviews: Dispatch one agent per site in parallel.

The agent returns:

• Status: DONE | DONE_WITH_CONCERNS | BLOCKED
• A JSON array of screenshots with annotations, grouped into sections
• An overall summary for the gallery banner

Handling agent status:

• DONE: Proceed to validation below.
• DONE_WITH_CONCERNS: Read the concerns. If the agent couldn't read images, re-dispatch.
• BLOCKED: Check if screenshots are readable (Read the PNGs yourself). If images are fine, re-dispatch with more context.

Post-subagent validation: The reviewer returns a manifest object with screenshots_reviewed and screenshots_with_annotations counts. Before using the output:

1. Check manifest counts — screenshots_reviewed must equal the number of PNGs captured. If not, re-dispatch for the missing screenshots.
2. Spot-check 2-3 annotations for objective relevance
3. Verify section groupings make sense for the gallery layout

Step 7: Marketing Comparison (Subagent — Multi-Site Only)

Only run this step if the user requested a comparison in Step 2.

After ALL marketing-reviewer agents have completed, dispatch a general-purpose subagent using the marketing-comparator prompt template.

Dispatch with the Agent tool:

• subagent_type: "general-purpose"
• model: "sonnet" (comparator is text-only reasoning on structured JSON)
• Prompt: Paste the full content of agents/marketing-comparator.md into the prompt, followed by all context below. Do NOT tell the agent to read the file — inline everything.
• Provide in the prompt:
  1. All site annotations — the full validated JSON output from each marketing-reviewer agent
  2. Review brief paths — tell the agent to read each site's screenshots/<site-slug>/review-brief.md
  3. Review objective — the exact objective text from Step 2
  4. Annotation depth — from Step 2

Use the comparator output to build the comparison gallery in Step 8.

Step 8: Generate HTML Gallery

Read shared/common-steps.md → "Generate HTML Gallery", "Local Server & Gallery Verification" sections. Follow those instructions, using gallery-<site-slug>.html as the filename. Replace header metadata with site name, URL, and description instead of plugin metadata.

Step 9: Import to Figma

Read shared/common-steps.md → "Import to Figma" section.

Step 10: Cleanup

# Kill local HTTP server if started for gallery preview
kill %1 2>/dev/null

No other cleanup needed — this skill doesn't modify any websites.

Annotation & Comparison Reference

Read shared/common-steps.md → "Annotation Reference", "Comparison Gallery", and "Common Mistakes & Troubleshooting" sections.

Website-Specific Troubleshooting

Mistake	Fix
Cookie banner reappears on every page	Set consent cookie via eval (see Step 3) instead of clicking dismiss each time.
SPA site — navigation doesn't reload page	Use agent-browser --session <session> open "<full-url>" for each page instead of clicking nav links.
Cloudflare or anti-bot challenge blocks capture	Note the limitation, screenshot what's accessible, move to the next site.