Skip to content

galiprandi/job-seeker / .agents/skills/browser-automation

browser-automation

Verified

Control a dedicated browser via agent-browser (Vercel). Use when automating web apps, scraping authenticated sites, filling forms, or navigating SPAs. Do NOT use for desktop apps or API-only integrations.

FileKindSize
SETUP.mdmarkdown3.0 KB
SKILL.mdskill md39.4 KB
references/agent-browser.mdmarkdown4.6 KB
references/api-capture.mdmarkdown1.8 KB
references/ats-patterns.mdmarkdown4.5 KB
references/audio-transcription.mdmarkdown2.4 KB
references/custom-combobox.mdmarkdown5.0 KB
references/efficiency-patterns.mdmarkdown2.6 KB
references/golden-rules.mdmarkdown5.7 KB
references/key-patterns.mdmarkdown4.4 KB
references/network-console.mdmarkdown1.2 KB
references/parallel-agents.mdmarkdown6.2 KB
references/profile-management.mdmarkdown6.3 KB
references/token-extraction.mdmarkdown2.8 KB
scripts/README.mdmarkdown6.0 KB
scripts/agent-browser.template.jsonconfig333 B
scripts/browser-share.jsscript20.0 KB
scripts/browser.jsexecutablescript17.1 KB
scripts/teams.jsscript7.1 KB
scripts/test-find-guide.jsscript6.3 KB
scripts/transcribe-audio.jsscript3.6 KB
scripts/viewer.htmlother8.6 KB
sites/CONTRIBUTING.mdmarkdown11.0 KB
sites/LEARN.mdmarkdown5.4 KB
sites/afip_gob_ar/guide.mdmarkdown9.0 KB
sites/app_web3forms_com/guide.mdmarkdown7.1 KB
sites/buk_co/guide.mdmarkdown1.5 KB
sites/calendar_google_com/calendar-deeplink.mdmarkdown1.9 KB
sites/calendly_com/guide.mdmarkdown1001 B
sites/careers_epam_com/guide.mdmarkdown4.4 KB
sites/dash_cloudflare_com/guide.mdmarkdown7.7 KB
sites/discord_com/guide.mdmarkdown9.9 KB
sites/discord_com/login-flow.mdmarkdown3.2 KB
sites/docs_google_com/guide.mdmarkdown7.3 KB
sites/facebook_com/guide.mdmarkdown9.8 KB
sites/gmail_com/guide.mdmarkdown35.6 KB
sites/google_com/guide.mdmarkdown1.1 KB
sites/google_com/login-flow.mdmarkdown3.3 KB
sites/google_home_com/guide.mdmarkdown2.1 KB
sites/google_maps_com/guide.mdmarkdown8.4 KB
sites/groq_com/signup-apikey.mdmarkdown6.6 KB
sites/humand_co/guide.mdmarkdown6.9 KB
sites/jira_com/guide.mdmarkdown10.8 KB
sites/linkedin_com/guide.mdmarkdown27.4 KB
sites/linkedin_com/outreach-strategy.mdmarkdown1.2 KB
sites/linkedin_com/posting.mdmarkdown14.0 KB
sites/linkedin_com/voyager-api.mdmarkdown8.1 KB
sites/mercadolibre_com/guide.mdmarkdown4.5 KB
sites/onstrider_com/draftjs-editor-fill.mdmarkdown2.3 KB
sites/onstrider_com/guide.mdmarkdown11.3 KB
sites/onstrider_com/react-autocomplete-inputs.mdmarkdown4.0 KB
sites/outlook_office_com/calendar-deeplink.mdmarkdown2.2 KB
sites/outlook_office_com/guide.mdmarkdown14.0 KB
sites/property_directory/guide.mdmarkdown3.7 KB
sites/reddit_com/guide.mdmarkdown16.2 KB
sites/teams_com/guide.mdmarkdown10.3 KB
sites/teamtailor_com/guide.mdmarkdown6.5 KB
sites/vea_com_ar/guide.mdmarkdown8.8 KB
sites/whatsapp_com/guide.mdmarkdown21.3 KB
sites/whatsapp_com/login-flow.mdmarkdown3.0 KB
sites/whatsapp_com/message-extraction.mdmarkdown5.7 KB
sites/whatsapp_com/voice-notes.mdmarkdown7.1 KB
sites/workatastartup_com/guide.mdmarkdown1.5 KB

references/golden-rules.md

View on GitHub
# Golden Rules (validated empirically)

These rules were validated through extensive testing. Breaking them causes failure.

### Rule 0: Verify identity before acting

The first action on any logged-in site must confirm WHICH account is active (account avatar, aria-label, profile corner). If it is not the repo owner's account, STOP and report. A shared daemon or stale profile can attach you to someone else's session.

```bash
node .agents/skills/browser-automation/scripts/browser.js exec eval "document.querySelector('img[alt*=\"profile\"], [aria-label*=\"Account\"]')?.getAttribute('aria-label') || document.title"
```

### Rule 1: eval > ref-based clicks

Refs (`@eN`) are per-snapshot and **do not persist** reliably across separate CLI calls. A ref from one `snapshot` call may be stale by the next `click` call (agent-browser tries to re-resolve by role+name, but ambiguous matches fail).

**Wrong:**
```
snap = snapshot()
ref = findRef(snap, "Message")
clickRef(ref)  # may fail, ref may be stale
```

**Right:**
```bash
# Use find (semantic locator + action in one call)
node .agents/skills/browser-automation/scripts/browser.js exec find text "Message" click

# Or eval to find and click by text in one atomic call
node .agents/skills/browser-automation/scripts/browser.js exec eval "(function(){
  const els = document.querySelectorAll('a, button, [role=\"link\"]');
  for (const el of els) {
    if (el.textContent.includes('Message')) { el.click(); return 'clicked'; }
  }
  return 'not_found';
})()"
```

### Rule 2: In-page polling > shell sleep

Shell `sleep` between browser commands wastes round-trips and races async page updates: the page keeps mutating while the shell sleeps, and you still don't know if it is ready.

**Wrong:**
```bash
node .agents/skills/browser-automation/scripts/browser.js goto "https://example.com"
sleep 4                        # blind wait, page may not be ready
node .agents/skills/browser-automation/scripts/browser.js exec snapshot
```

**Right:**
```bash
# wait --fn polls inside the page until a real condition is true
node .agents/skills/browser-automation/scripts/browser.js goto "https://example.com"
node .agents/skills/browser-automation/scripts/browser.js exec wait --fn "!!document.querySelector('div.target-element')"

# or eval with in-page polling
node .agents/skills/browser-automation/scripts/browser.js exec eval "(async function(){
  for (let i = 0; i < 50; i++) {
    if (document.querySelector('div.target-element')) return 'ready';
    await new Promise(r => setTimeout(r, 200));
  }
  return 'timeout';
})()"
```

### Rule 3: Scope snapshots, retry on failure

`exec snapshot` on a complex SPA can be huge, truncated, or momentarily fail. Retry scoped:

```bash
# Interactive elements only (much smaller)
node .agents/skills/browser-automation/scripts/browser.js exec snapshot -i
# Scoped to a subtree
node .agents/skills/browser-automation/scripts/browser.js exec snapshot -i -s "#main"
# Or skip the snapshot entirely: read the page as text
node .agents/skills/browser-automation/scripts/browser.js exec read
```

### Rule 4: Use URLs directly, not clicks for navigation

Navigating to a specific URL is more reliable than clicking navigation links.

**Wrong:** Click "Messaging" icon in header
**Right:** `node .agents/skills/browser-automation/scripts/browser.js goto "https://www.linkedin.com/messaging/"`

**Wrong:** Click "Saved Jobs" menu item
**Right:** `node .agents/skills/browser-automation/scripts/browser.js goto "https://www.linkedin.com/jobs-tracker/?stage=saved"`

### Rule 5: Verify with DOM content, not URL

SPAs (LinkedIn, Gmail, React apps) update the right panel without changing the URL.

**Wrong:** Check if URL changed after clicking a conversation
**Right:** Check if the target container exists and matches expected content

```bash
node .agents/skills/browser-automation/scripts/browser.js exec eval "(function(){
  const panel = document.querySelector('.msg-s-message-list-container');
  const header = document.querySelector('h2');
  if (panel && header && header.textContent.includes('Person Name')) return 'ok';
  return 'not_loaded';
})()"
```

### Rule 6: Batch operations into a single eval call

Doing wait + click + verify in one `eval` call is more robust than multiple separate CLI calls: fewer process spawns, no race between steps.

**Wrong:**
```bash
node .agents/skills/browser-automation/scripts/browser.js exec eval "document.querySelector('#btn')"
node .agents/skills/browser-automation/scripts/browser.js exec eval "document.querySelector('#btn').click()"
node .agents/skills/browser-automation/scripts/browser.js exec eval "document.querySelector('#result')"
```

**Right:**
```bash
node .agents/skills/browser-automation/scripts/browser.js exec eval "(function(){
  const btn = document.querySelector('#btn');
  if (!btn) return 'not_found';
  btn.click();
  const result = document.querySelector('#result');
  return result ? result.textContent : 'no_result';
})()"
```

For non-JS sequences (open + wait + press), prefer `batch` over chained shell calls:

```bash
node .agents/skills/browser-automation/scripts/browser.js exec batch "navigate https://example.com" "wait --load load" "press Enter"
```

### Rule 7: Verify before send (irreversible actions)

Before any action that cannot be undone (send message, submit application, post, delete, pay): verify recipient, account identity, and the FULL content in the compose area via `get text` / `eval`. Show a draft when the flow requires it. Only then trigger the send. Never send on assumption.

### Rule 8: Empirical learnings only

Never write a hypothesis about site behavior ("paste doesn't register", "that selector fails") into a guide or reference without a controlled test confirming it (e.g. send to yourself first). A false learning is worse than none.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall