name: browser-screenshot
description: Take focused, region-specific screenshots from web pages. Navigates to the right page based on user context (URL, search query, social media post), locates the target region via DOM selectors, and crops to a clean, focused screenshot.

Skill: Browser Screenshot

Take focused screenshots of specific regions on web pages — a Reddit post, a tweet, an article section, a chart, etc. — not just a full-page dump.

Prerequisite: agent-browser must be installed and Chrome must have remote debugging enabled. See references/agent-browser-setup.md if unsure.

Overview

This skill handles the full pipeline:

1. Understand what the user wants to capture
2. Navigate to the right page (URL, search, or platform-specific routing)
3. Locate the target element/region on the page
4. Capture a focused, cropped screenshot of just that region

Step 1: Navigate to the Target Page

Always Start by Listing Tabs

agent-browser --auto-connect tab list

Check if the page is already open. Reuse existing tabs — they have login sessions and correct state.

Navigation by Input Type

Platform-Specific Search URLs

Wait for Page Load

After navigation, wait for content to settle:

agent-browser --auto-connect wait --load networkidle

Note: Some sites (Reddit, X, LinkedIn) never reach networkidle. If open already shows the page title in its output, skip the wait. Use wait 2000 as a safe alternative.

Step 2: Locate the Target Region

This is the critical step. The goal is to find a CSS selector that precisely wraps the content to capture.

Primary Method: DOM Selector Discovery

1. Take an annotated screenshot to understand the page layout:
   bash agent-browser --auto-connect screenshot --annotate

2. Take a snapshot to see the page's accessibility tree:
   bash agent-browser --auto-connect snapshot -i

3. Identify the target container element. Look for:

4. Semantic HTML containers: <article>, <main>, <section>
5. Platform-specific components (see Platform Selectors)

6. Data attributes: [data-testid="..."], [data-id="..."]

7. Verify with get box to confirm the element has a reasonable bounding box:
   bash agent-browser --auto-connect get box "<selector>"
   This returns { x, y, width, height }. Sanity-check:

8. Width should be > 100px and < viewport width
9. Height should be > 50px

10. If the box is the entire page, the selector is too broad — refine it

11. If the selector is hard to find, use eval to explore the DOM:
    bash agent-browser --auto-connect eval "document.querySelector('article')?.getBoundingClientRect()"

Platform Selectors

Common container selectors for popular platforms:

These selectors may change over time. Always verify with get box before using.

Multiple Matching Elements

If the selector matches multiple elements (e.g., multiple tweets on a timeline), narrow it down:

# Count matches
agent-browser --auto-connect get count "article[data-testid='tweet']"

# Use nth-child or :first-of-type, or a more specific selector
# Or use eval to find the right one by text content:
agent-browser --auto-connect eval --stdin <<'EOF'
const posts = document.querySelectorAll('article[data-testid="tweet"]');
for (let i = 0; i < posts.length; i++) {
  const text = posts[i].textContent.substring(0, 80);
  console.log(i, text);
}
EOF

Then target a specific one using :nth-of-type(N) or a unique parent selector.

Step 3: Capture the Focused Screenshot

Method A: Scroll + Viewport Screenshot (Preferred for Viewport-Sized Targets)

Best when the target element fits within the viewport.

# Scroll the target into view
agent-browser --auto-connect scrollintoview "<selector>"
agent-browser --auto-connect wait 500

# Take viewport screenshot
agent-browser --auto-connect screenshot /tmp/browser-screenshot-raw.png

Then crop using the bounding box (see Cropping).

Method B: Full-Page Screenshot + Crop (For Any Size Target)

Best when the target might be larger than the viewport or when precise cropping is needed.

# Take full-page screenshot
agent-browser --auto-connect screenshot --full /tmp/browser-screenshot-full.png

# Get the target element's bounding box
agent-browser --auto-connect get box "<selector>"
# Output: { x: 200, y: 450, width: 680, height: 520 }

Then crop (see Cropping).

Cropping

Use ImageMagick to crop the screenshot to the target region. Add padding for visual breathing room.

# Variables from `get box` output (round to integers)
X=200
Y=450
W=680
H=520
PADDING=16

# Crop with padding
convert /tmp/browser-screenshot-full.png \
  -crop $((W + PADDING*2))x$((H + PADDING*2))+$((X - PADDING))+$((Y - PADDING)) \
  +repage \
  <output-path>.png

Important: get box returns floating-point values. Round them to integers before passing to ImageMagick.

Padding: Use 12–20px padding. Increase to ~30px if the target has a distinct visual boundary (card, bordered box). Use 0 if the user wants a tight crop.

Output Path

• If the user specifies an output path, use that
• Otherwise, save to a descriptive name in the current directory, e.g., reddit-post-screenshot.png, tweet-screenshot.png

Step 4: Verify the Result

After cropping, read the output image to verify it captured the right content:

# Use the Read tool to visually inspect the cropped screenshot

If the crop is wrong (missed content, too much whitespace, wrong element), adjust the selector or bounding box and retry.

Fallback: Visual Highlight Confirmation

When DOM-based location is uncertain — the selector might be wrong, multiple candidates exist, or the target is ambiguous — use JS-injected highlighting to visually confirm before cropping.

How It Works

1. Inject a highlight border on the candidate element:
   bash agent-browser --auto-connect eval --stdin <<'EOF' (function() { const el = document.querySelector('<selector>'); if (!el) { console.log('NOT_FOUND'); return; } el.style.outline = '4px solid red'; el.style.outlineOffset = '2px'; el.scrollIntoView({ block: 'center' }); })(); EOF

2. Take a screenshot and visually inspect:
   bash agent-browser --auto-connect screenshot /tmp/highlight-check.png
   Read the screenshot to check if the red border surrounds the correct content.

3. If correct, remove the highlight and proceed with cropping:
   bash agent-browser --auto-connect eval "document.querySelector('<selector>').style.outline = ''; document.querySelector('<selector>').style.outlineOffset = '';"

4. If wrong, try the next candidate or refine the selector, re-highlight, and re-check.

When to Use This Fallback

• The page has complex/nested components and you're not sure which container is right
• Multiple similar elements exist and you need to pick the correct one
• The user's description is vague ("that chart in the middle of the page")
• The get box result looks suspicious (too large, too small, zero-sized)

Page Preparation: Clean Up Before Capture

Before taking the final screenshot, clean up the page for a better result:

# Dismiss cookie banners, popups, overlays
agent-browser --auto-connect eval --stdin <<'EOF'
(function() {
  // Common cookie/popup selectors
  const selectors = [
    '[class*="cookie"] button',
    '[class*="consent"] button',
    '[class*="banner"] [class*="close"]',
    '[class*="modal"] [class*="close"]',
    '[class*="popup"] [class*="close"]',
    '[aria-label="Close"]',
    '[data-testid="close"]'
  ];
  selectors.forEach(sel => {
    document.querySelectorAll(sel).forEach(el => {
      if (el.offsetParent !== null) el.click();
    });
  });

  // Hide fixed/sticky elements that overlay content (nav bars, banners)
  document.querySelectorAll('*').forEach(el => {
    const style = getComputedStyle(el);
    if ((style.position === 'fixed' || style.position === 'sticky') && el.tagName !== 'HTML' && el.tagName !== 'BODY') {
      el.style.display = 'none';
    }
  });
})();
EOF

Use with caution: Hiding fixed elements might remove important context. Only run this when overlays visibly obstruct the target region.

Viewport Sizing

For consistent, high-quality screenshots, set the viewport before capturing:

# Standard desktop viewport
agent-browser --auto-connect set viewport 1280 800

# Wider for dashboard/data-heavy pages
agent-browser --auto-connect set viewport 1440 900

# Narrower for mobile-like content (social media posts)
agent-browser --auto-connect set viewport 800 600

Choose a viewport width that makes the target content render cleanly — not too cramped, not too stretched.

Complete Example: Screenshot a Reddit Post

User: "Screenshot the top post on r/programming"

# 1. List existing tabs
agent-browser --auto-connect tab list

# 2. Navigate to subreddit
agent-browser --auto-connect open https://www.reddit.com/r/programming/
agent-browser --auto-connect wait 2000

# 3. Find the first post container
agent-browser --auto-connect eval "document.querySelector('shreddit-post')?.getBoundingClientRect()"

# 4. Scroll it into view
agent-browser --auto-connect scrollintoview "shreddit-post"
agent-browser --auto-connect wait 500

# 5. Get bounding box
agent-browser --auto-connect get box "shreddit-post"
# → { x: 312, y: 80, width: 656, height: 420 }

# 6. Take full-page screenshot
agent-browser --auto-connect screenshot --full /tmp/reddit-raw.png

# 7. Crop with padding
convert /tmp/reddit-raw.png \
  -crop 688x452+296+64 +repage \
  reddit-post-screenshot.png

# 8. Verify by reading the output image

Key Commands Quick Reference

Troubleshooting

get box returns null or zero-sized

• The selector doesn't match any element. Use get count "<selector>" to verify.
• The element may be hidden or not yet rendered. Try wait 2000 and retry.

Cropped image is blank or wrong area

• The full-page screenshot coordinates may differ from viewport coordinates. Use screenshot --full with get box (they use the same coordinate system).
• Check if the page has horizontal scroll — get box x values may be offset.

Target element is inside an iframe

• get box and snapshot -i cannot see inside iframes.
• Use eval to access iframe content:
  bash agent-browser --auto-connect eval "document.querySelector('iframe').contentDocument.querySelector('<sel>').getBoundingClientRect()"
  Note: Only works for same-origin iframes.

Page has lazy-loaded content

• Scroll down to trigger loading before taking the screenshot:
  bash agent-browser --auto-connect scroll down 1000 agent-browser --auto-connect wait 1500 agent-browser --auto-connect scroll up 1000