Screenshotting Apps

Annotated Screenshot Documentation

Generate a markdown document with annotated screenshots of any web app or live website.

Prerequisites

• agent-browser CLI installed globally (npm i -g agent-browser && agent-browser install)

Phase 1: Determine the Target

A) Live website

1. Normalize URL (add https:// if missing):

``bash agent-browser open https://example.com && agent-browser wait --load networkidle ``

1. Dismiss cookie/consent banners using semantic locators (most reliable):

``bash agent-browser find text "Accept" click ` Or snapshot to find the accept button ref, then click the ref directly: `bash agent-browser snapshot -i -s "[role=dialog], [class*=cookie], [class*=consent]" -c agent-browser click @e1 # Use the ref from snapshot ` Verify it's gone: agent-browser is visible "[role=dialog]" or agent-browser wait "[role=dialog]" --state hidden`

1. For login walls or anti-bot issues, see [references/live-sites.md](references/live-sites.md).

B) Local dev server

1. Find or start the dev server (check ports 3000/5173/4321/8080, or start via package.json)
2. For self-signed certs: agent-browser --ignore-https-errors open https://localhost:

Phase 2: Map the Site

1. Open homepage: agent-browser open && agent-browser wait --load networkidle
2. Take a quick auto-annotated screenshot to survey the page — this labels all interactive elements with numbered refs:

``bash agent-browser screenshot --annotate docs/screenshots/_survey.png ` Read the output legend to understand what's on the page (buttons, links, inputs mapped to @e` refs).

1. Snapshot navigation to discover pages:

``bash agent-browser snapshot -i -s "header, nav, [role=navigation]" -c ` For deep DOM: agent-browser snapshot -i -c -d 3`

1. For SPAs with client-side routing: also check route definitions in the source code (grep -r "path:" src/router or similar) since not all routes may be linked from the nav.
2. Ask the user to confirm the page list. For live sites, suggest 5-10 pages max.

Phase 3: Screenshot Each Page

Workflow per page: validate selectors → annotate → check for FAILED → verify screenshot → fix or continue.

Setup (run once before all screenshots):

agent-browser set viewport 1440 900
export AGENT_BROWSER_SCREENSHOT_DIR=docs/screenshots

Block ads and tracking scripts that create overlays or slow page loads (live sites):

agent-browser network route "**/*.doubleclick.net/**" --abort
agent-browser network route "**/googlesyndication.com/**" --abort
agent-browser network route "**/analytics.js" --abort
agent-browser network route "**/gtm.js" --abort

Resolve the annotation script path (checks common install locations):

ANNOT_JS="$(find . .claude .agents ~/skills -path '*/app-screenshots/references/annotate.js' 2>/dev/null | head -1)"
[ -z "$ANNOT_JS" ] && echo "ERROR: annotate.js not found — check skill installation"

For each page:

Step 1: Navigate

agent-browser open  && agent-browser wait --load networkidle

For live sites, add agent-browser wait 2000 for lazy-loaded content. Chain when you don't need intermediate output: agent-browser open && agent-browser wait --load networkidle && agent-browser wait 2000

Step 2: Dismiss cookie/consent banners (live sites)

agent-browser find text "Accept" click
agent-browser wait "[class*=overlay]" --state hidden

For complex or iframed banners, see [references/live-sites.md](references/live-sites.md).

Step 3: Validate selectors BEFORE annotating

Always test selectors first. Failed selectors produce invisible annotations.

Use eval --stdin with heredoc for complex JS (avoids shell quoting issues):

agent-browser eval --stdin  {
  const el = document.querySelector(s);
  if (!el) return 'MISSING: ' + s;
  const r = el.getBoundingClientRect();
  return 'OK: ' + s + ' (' + Math.round(r.width) + 'x' + Math.round(r.height) + ')';
}).join('\n')
EVALEOF

Quick match count check: agent-browser get count ""

If MISSING, use agent-browser snapshot -i -c to discover correct selectors and refs. Do not annotate with broken selectors. See [references/selectors.md](references/selectors.md) for tips.

For elements below the fold, scroll them into view first: agent-browser scrollintoview ""

Step 4: Inject annotations

Use eval --stdin to inject the annotation script safely:

agent-browser eval --stdin -.png

Zero-padded numbering: 01-homepage.png, 02-category.png, etc. Use --full for full-page screenshots when content extends below the fold.

Step 6: Verify screenshot quality

Read the screenshot file you just captured and check:

• Annotations are visible and not overlapping each other
• Labels are not cut off at viewport edges
• The page content loaded correctly (no spinners, broken images)
• Cookie banners or overlays are not blocking the view

If any issues: agent-browser eval "clearAnnotations()", fix the problem, re-annotate, and re-screenshot. Do not proceed with a bad screenshot.

Interactive screenshots

For search, menus, modals, hover states — use the snapshot → refs → interact pattern:

# 1. Snapshot to get refs
agent-browser snapshot -i
# 2. Interact using refs (more reliable than CSS selectors)
agent-browser click @e5          # Click search input by ref
agent-browser type @e5 "shoes"
agent-browser wait 2000
# 3. Annotate the result
agent-browser eval --stdin -screenshots.md` (live sites) or `docs/app-screenshots.md` (local).

Use numbered references **(1)**, **(2)**, **(3)** in descriptions to cross-reference the annotation badges visible in each screenshot.

```markdown
#  - Visual Guide

Brief description of the site/app.

**URL:** 
**Date:** 

**Annotation key:** Red = primary actions, Blue = secondary elements, Green = content areas

---

## 

1-3 sentences describing the page. Reference annotations by number:
"The **Search bar** (1) supports autocomplete. Use the **Category nav** (2) to browse departments.
The **Hero banner** (3) rotates seasonal promotions."

---

Phase 5: Compare environments (optional)

When documenting differences between staging and production, or before/after a redesign:

# Visual pixel diff between two URLs
agent-browser diff url https://staging.example.com https://prod.example.com

# Diff against a baseline screenshot
agent-browser diff screenshot --baseline docs/screenshots/01-homepage-before.png

# Accessibility tree diff (detect structural changes)
agent-browser diff snapshot

Include diff screenshots in the markdown to highlight what changed.

Phase 6: Cleanup

# Remove network intercepts
agent-browser network unroute
agent-browser close

Reference

• Selector tips and troubleshooting: See [references/selectors.md](references/selectors.md)
• Live site tips (cookies, lazy loading, rate limiting, geo): See [references/live-sites.md](references/live-sites.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alexanderop
• Source: alexanderop/app-screenshots
• License: MIT

Install and usage instructions live in the source repository linked above.