Skill: Chrome Automation (agent-browser)

Prerequisite: agent-browser must be installed and Chrome must have remote debugging enabled. See

references/agent-browser-setup.md

if unsure.

Core Principle: Reuse the User's Existing Chrome

Always Start by Listing Tabs

agent-browser --auto-connect tab list

• If the target page is already open → switch to that tab directly instead of opening a new one. The user likely has it open because they are already logged in and the page is in the right state.
  bash

  agent-browser --auto-connect tab <index>

• If the target page is NOT open → open it in the current tab or a new tab.
  bash

  agent-browser --auto-connect open <url>

Why This Matters

• The user's Chrome has their cookies, login sessions, and browser state
• Opening a new page when one is already available wastes time and may lose login state
• Many marketing platforms (social media dashboards, ad managers, CMS tools) require login — reusing an existing logged-in tab avoids re-authentication

Connection

--auto-connect

agent-browser --auto-connect <command>

references/agent-browser-setup.md

Common Workflows

1. Navigate and Interact

# List tabs to find existing pages
agent-browser --auto-connect tab list

# Switch to an existing tab (if found)
agent-browser --auto-connect tab <index>

# Or open a new page
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect wait --load networkidle

# Take a snapshot to see interactive elements
agent-browser --auto-connect snapshot -i

# Click, fill, etc.
agent-browser --auto-connect click @e3
agent-browser --auto-connect fill @e5 "some text"

2. Extract Data from a Page

# Get all text content
agent-browser --auto-connect get text body

# Take a screenshot for visual inspection
agent-browser --auto-connect screenshot

# Execute JavaScript for structured data
agent-browser --auto-connect eval "JSON.stringify(document.querySelectorAll('table tr').length)"

3. Replay a Chrome DevTools Recording

Step-by-Step Interaction Guide

Taking Snapshots

snapshot -i

@e1

@e2

agent-browser --auto-connect snapshot -i

Step Type Mapping

agent-browser --auto-connect open <url>

wait --load networkidle

open

snapshot -i

click @eN

click @eN

fill @eN "text"

click @eN

keyboard inserttext "text"

press <key>

scroll down <amount>

scroll up <amount>

wait @eN

wait "<css-selector>"

screenshot

screenshot --annotate

get text body

get url

eval <js>

How to Distinguish Input Types

• Standard input/textarea → use

  fill

• Contenteditable div / rich text editor (LinkedIn message box, Gmail compose, Slack, CMS editors) → click/focus first, then use

  keyboard inserttext

Ref Lifecycle

@e1

@e2

• Clicking links or buttons that trigger navigation
• Submitting forms
• Triggering dynamic content loads (AJAX, SPA navigation)

Verification

agent-browser --auto-connect snapshot -i   # check interactive state
agent-browser --auto-connect screenshot     # visual verification

Replaying Recordings

Accepted Formats

1. JSON (recommended) — structured, can be read progressively:
   bash

   # Count steps
   jq '.steps | length' recording.json
   
   # Read first 5 steps
   jq '.steps[0:5]' recording.json

2. @puppeteer/replay JS (

   import { createRunner }

   )
3. Puppeteer JS (

   require('puppeteer')

   ,

   page.goto

   ,

   Locator.race

   )

How to Replay

1. Parse the recording — understand the full intent before acting. Summarize what the recording does.
2. List tabs first — check if the target page is already open.
3. Navigate — execute

   navigate

   steps, reusing existing tabs when possible.
4. For each interaction step:
   • Take a snapshot (

     snapshot -i

     ) to see current interactive elements
   • Match the recording's

     aria/...

     selectors against the snapshot
   • Fall back to

     text/...

     , then CSS class hints, then screenshot
   • Do not rely on ember IDs, numeric IDs, or exact XPaths — these change every page load
5. Verify after each step — snapshot or screenshot to confirm

Iframe-Heavy Sites

snapshot -i

Detecting Iframe Issues

• snapshot -i

  returns unexpectedly short or empty results
• Recording references elements not appearing in snapshot output

• get text body

  content doesn't match what a screenshot shows

Workarounds

1. Use

   eval

   to access iframe content:
   bash

   agent-browser --auto-connect eval --stdin <<'EVALEOF'
   const frame = document.querySelector('iframe[data-testid="interop-iframe"]');
   const doc = frame.contentDocument;
   const btn = doc.querySelector('button[aria-label="Send"]');
   btn.click();
   EVALEOF

   Note: Only works for same-origin iframes.
2. Use

   keyboard

   for blind input: If the iframe element has focus,

   keyboard inserttext "..."

   sends text regardless of frame boundaries.
3. Use

   get text body

   to read full page content including iframes.
4. Use

   screenshot

   for visual verification when snapshot is unreliable.

When to Ask the User

• The page uses iframes that cannot be accessed via snapshot
• Which element you need and what you expected
• Ask the user to perform that step manually, then continue

Handling Unexpected Situations

Handle Automatically (do not stop):

• Popups or banners → dismiss them (

  find text "Dismiss" click

  or

  find text "Close" click

  )
• Cookie consent dialogs → accept or dismiss
• Tooltip overlays → close them first
• Element not in snapshot → try

  find text "..." click

  , or scroll to reveal with

  scroll down 300

Pause and Ask the User:

• Login / authentication is required
• A CAPTCHA appears
• Page structure is completely different from expected
• A destructive action is about to happen (deleting data, sending real content) — confirm first
• Stuck for more than 2 attempts on the same step
• All iframe workarounds have failed

Key Commands Reference

tab list

tab <index>

tab new

tab close

open <url>

snapshot -i

click @eN

fill @eN "text"

type @eN "text"

keyboard inserttext "text"

press <key>

scroll down/up <amount>

wait @eN

wait --load networkidle

wait <ms>

screenshot [path]

screenshot --annotate

eval <js>

get text body

get url

set viewport <w> <h>

find text "..." click

close

Known Limitations

1. Iframe blindness:

   snapshot -i

   cannot see inside iframes. See Iframe-Heavy Sites.

2. find text

   strict mode: Fails when multiple elements match. Use

   snapshot -i

   to locate the specific ref instead.

3. fill

   vs contenteditable:

   fill

   only works on

   <input>

   and

   <textarea>

   . For rich text editors, use

   keyboard inserttext

   .

4. eval

   is main-frame only: To interact with iframe content, traverse via

   document.querySelector('iframe').contentDocument...

Multi-Platform Operations

Why Subagents

How to Execute

1. Prepare the content — confirm the post text, title, tags, and any platform-specific adaptations with the user.
2. For each platform, launch a

   general-purpose

   Agent subagent with a prompt that includes:
   • The full content to publish
   • Instructions to read the relevant reference file (e.g.,

     Read /path/to/skills/chrome-automation/references/x.md

     )
   • Instructions to read the agent-browser skill file for command reference
   • The specific task (post, comment, reply, etc.)
   • Any platform-specific instructions (e.g., "use these hashtags on LinkedIn")
3. Run subagents sequentially (one at a time), because they all share the same Chrome browser via

   --auto-connect

   . Parallel subagents would cause tab conflicts.
4. After each subagent completes, report the result to the user before launching the next one.

Prompt Template for Subagents

You are automating a browser task on [PLATFORM].

First, read these files for context:
- /absolute/path/to/skills/chrome-automation/references/[platform].md
- /absolute/path/to/.claude/skills/agent-browser/SKILL.md (agent-browser command reference)

Then connect to the user's Chrome browser using `agent-browser --auto-connect` and perform the following task:

[TASK DESCRIPTION]

Content to publish:
[CONTENT]

Important:
- Always list tabs first (`tab list`) and reuse existing logged-in tabs
- Re-snapshot after every navigation or action
- Confirm with the user before submitting/publishing (destructive action)
- If login is required or a CAPTCHA appears, stop and explain

When NOT to Use Subagents

• Single platform — just do it directly in the current conversation.
• Read-only tasks (browsing, searching, extracting data) — context usage is lighter; a single conversation can handle 2-3 platforms.

Platform References

references/reddit.md

faceplate-*

networkidle

find text

references/x.md

open

tab list

data-testid="tweetTextarea_0"

networkidle

references/linkedin.md

networkidle

references/devto.md

<textarea>

networkidle

references/hackernews.md

link "reply"

networkidle

For installation and Chrome setup instructions, see

references/agent-browser-setup.md

.