screenshotting-apps
Generates annotated screenshot documentation for web apps and websites — local dev servers or live sites. Use when asked to "screenshot the app", "document the app", "visual docs", "screenshot documentation", "show me the app", "screenshot <url>", or "document this website".
How do I install this agent skill?
npx skills add https://github.com/alexanderop/app-screenshots --skill screenshotting-appsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill generates annotated screenshot documentation for web applications and live websites. It utilizes the agent-browser tool to automate navigation, handle interactions like cookie banners, and inject visual annotations directly into the browser viewport before capturing screenshots. All identified behaviors, including session persistence and code injection into the browser context, are standard for browser automation and are intended for the skill's primary purpose.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Annotated Screenshot Documentation
Generate a markdown document with annotated screenshots of any web app or live website.
Prerequisites
agent-browserCLI installed globally (npm i -g agent-browser && agent-browser install)
Phase 1: Determine the Target
A) Live website
- Normalize URL (add
https://if missing):agent-browser open https://example.com && agent-browser wait --load networkidle - Dismiss cookie/consent banners using semantic locators (most reliable):
Or snapshot to find the accept button ref, then click the ref directly:agent-browser find text "Accept" click
Verify it's gone:agent-browser snapshot -i -s "[role=dialog], [class*=cookie], [class*=consent]" -c agent-browser click @e1 # Use the ref from snapshotagent-browser is visible "[role=dialog]"oragent-browser wait "[role=dialog]" --state hidden - For login walls or anti-bot issues, see references/live-sites.md.
B) Local dev server
- Find or start the dev server (check ports 3000/5173/4321/8080, or start via
package.json) - For self-signed certs:
agent-browser --ignore-https-errors open https://localhost:<port>
Phase 2: Map the Site
- Open homepage:
agent-browser open <url> && agent-browser wait --load networkidle - Take a quick auto-annotated screenshot to survey the page — this labels all interactive elements with numbered refs:
Read the output legend to understand what's on the page (buttons, links, inputs mapped toagent-browser screenshot --annotate docs/screenshots/_survey.png@erefs). - Snapshot navigation to discover pages:
For deep DOM:agent-browser snapshot -i -s "header, nav, [role=navigation]" -cagent-browser snapshot -i -c -d 3 - For SPAs with client-side routing: also check route definitions in the source code (
grep -r "path:" src/routeror similar) since not all routes may be linked from the nav. - 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 <url> && 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 <url> && 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.
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 <<'EVALEOF'
const sels = ['selector1', 'selector2'];
sels.map(s => {
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 "<selector>"
If MISSING, use agent-browser snapshot -i -c to discover correct selectors and refs. Do not annotate with broken selectors. See references/selectors.md for tips.
For elements below the fold, scroll them into view first: agent-browser scrollintoview "<selector>"
Step 4: Inject annotations
Use eval --stdin to inject the annotation script safely:
agent-browser eval --stdin <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([
{sel: 'selector', label: 'Label', type: 'box'},
{sel: 'selector', label: 'Label', type: 'click'}
])
EVALEOF
CRITICAL: If output starts with FAILED:, fix selectors before screenshotting. Clear and retry:
agent-browser eval "clearAnnotations()"
Annotation types:
click— filled circle + arrow + numbered label. Use for buttons, links, inputs.box— dashed border + numbered label. Use for sections, cards, containers.circle(default) — capped-radius dashed circle + arrow + numbered label. General callouts.
Colors auto-rotate: red, blue, green, amber, purple. Each annotation is auto-numbered (1, 2, 3...) for cross-referencing in markdown.
MAX 3 annotations per screenshot. Split into multiple screenshots if needed (e.g., 03a-top.png, 03b-actions.png).
Type selection rules:
clickfor small elements (buttons, links, icons) — capped circle won't explodeboxfor medium regions (cards, form groups, sidebars) — follows element shape- Never use
circleorboxon full-width elements (navbars, headers) — annotate specific items within them instead
What to annotate per page type:
- Homepage: hero CTA, search input, one nav example
- Product listing: one product card, filter toggle, sort dropdown
- Product detail: price, add-to-cart, size/variant selector
- Search results: search input, one result card, filter sidebar
- Dashboard: one metric card, one chart, primary action
- Table/data view: column header, filter control, data area
- Settings/form: key form fields, submit button
Step 5: Screenshot
agent-browser screenshot <NN>-<page-name>.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 <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([{sel: '[class*=suggest]', label: 'Suggestions', type: 'box'}])
EVALEOF
# 4. Screenshot
agent-browser screenshot 05-search-results.png
# 5. Verify — read the screenshot and check quality
Note: Refs inside iframes work directly — no frame switching needed for interaction.
Recording interactive flows (optional)
For complex interactions (checkout flows, multi-step wizards), record a video alongside screenshots:
agent-browser record start docs/screenshots/checkout-flow.webm
# ... perform the interaction steps, taking screenshots along the way ...
agent-browser record stop
Link the video in the markdown: [Watch checkout flow](screenshots/checkout-flow.webm)
Mobile / responsive screenshots
To document mobile layouts:
# Use device emulation (sets viewport + user agent together)
agent-browser set device "iPhone 14"
Then follow the same annotate → screenshot → verify workflow. Name files with a -mobile suffix: 01-homepage-mobile.png.
To return to desktop: agent-browser set viewport 1440 900
Note: On narrow viewports, prefer max 2 annotations per screenshot to avoid crowding.
Phase 4: Generate Markdown
Filename: docs/<domain>-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.
# <Site/App Name> - Visual Guide
Brief description of the site/app.
**URL:** <base-url>
**Date:** <today's date>
**Annotation key:** Red = primary actions, Blue = secondary elements, Green = content areas
---
## <Page Name>
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
- Live site tips (cookies, lazy loading, rate limiting, geo): See references/live-sites.md
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/alexanderop/app-screenshots/screenshotting-apps">View screenshotting-apps on skillZs</a>