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

sites/CONTRIBUTING.md

View on GitHub
# Contributing to sites/

This directory contains automation guides for specific web applications. Each guide documents validated selectors, API endpoints, flows, and gotchas for automating a particular site with `agent-browser`.

## Who this is for

Both humans and AI agents. An agent reading a guide should be able to automate the site without prior knowledge. A human should be able to verify, debug, and extend the guide.

## What belongs here

- Automation guides for specific web apps (LinkedIn, Gmail, Jira, Teamtailor, etc.)
- Validated selectors, API endpoints, and request/response structures
- Step-by-step flows that reproduce reliably
- Gotchas, anti-patterns, and edge cases discovered through real automation
- Platform-specific patterns (form fields, auth flows, rate limits, captchas)

## What does NOT belong here

- Personal data (names, emails, phone numbers, real URLs with tokens)
- Project-specific business logic (job search strategies, candidate profiles)
- Hardcoded values that should come from a database or config
- One-off hacks that won't reproduce for other users
- Generic browser patterns (those go in the parent `SKILL.md` or `references/`)

## Contribution principles

### 1. Generic and agnostic

Guides must work for any user, any project, any agent. No assumptions about who is running the automation or why.

**Bad:** "Send a message to Gustavo asking what he wants"
**Good:** "Send a message to a conversation by participant name using the bulk inbox fetch to resolve the thread ID"

**Bad:** "Fill the form with salary 5000 USD"
**Good:** "Fill the salary field from your data source. If the value is missing, stop and ask."

### 2. Reproducible

Every flow must be reproducible by another agent from scratch. Include:
- The exact URL to navigate to
- The selectors or API endpoints to use
- The verification step (how to confirm success)
- What to do when it fails

### 3. Validated

Only document what has been tested against the live site. Include the validation date. If a selector or endpoint stops working, update the guide or mark it as deprecated.

**Example:** "Validated 2026-08-12 against live API"

### 4. API-first when possible

Prefer internal APIs over UI scraping. APIs are more stable, faster, and eliminate UI-related errors (clicks that don't navigate, overlays that intercept events, dynamic content that hasn't loaded).

When documenting an API:
- Show the full request (URL, method, headers, body)
- Document the response structure (key fields, types, where to find what)
- Include the verification step (what field in the response confirms success)
- Note when the API structure changed and how to detect it

When UI is the only option:
- Document the exact selector
- Include a verification step that checks the DOM, not just the URL
- Note known failure modes (overlays, timing, dynamic content)

### 5. Safe by default

Guides must prevent irreversible errors. Messages sent to the wrong person, forms submitted with wrong data, emails sent to wrong recipients — these cannot be undone.

Principles:
- **Identify by ID, not by UI position.** Thread IDs, profile IDs, form field names. Never "click the third item in the list."
- **Verify before acting.** Confirm the target is correct before typing, clicking send, or submitting.
- **Show drafts before sending.** When the action has real-world side effects, the flow must include a human-in-the-loop checkpoint.
- **Document failure modes.** What happens when the click doesn't navigate? What does the error response look like? How do you detect it?

### 6. No secrets, no personal data

Guides are public artifacts. Never include:
- Real credentials, tokens, or cookies
- Real names, emails, phone numbers, or profile URLs
- Real thread IDs or conversation content
- Real company names tied to a specific user's history

Use placeholders: `<THREAD_ID>`, `<RECIPIENT_NAME>`, `<company>.teamtailor.com`, `ACoAA...`.

## File structure

Each app has its own directory named after the domain slug (underscore-separated, no dots or hyphens). The main guide is always `guide.md`. Additional reference files live alongside it in the same directory.

```
sites/
  gmail_com/
    guide.md              # Gmail automation guide
  linkedin_com/
    guide.md              # LinkedIn automation guide
    voyager-api.md        # Detailed API endpoint documentation
  jira_com/
    guide.md
  teamtailor_com/
    guide.md
  CONTRIBUTING.md         # This file
```

### Domain slug convention

Derive the directory name from the site's canonical domain:
- Lowercase, replace `.` and `-` with `_`
- Strip `www.` prefix
- Example: `mail.google.com` → `gmail_com`, `www.linkedin.com` → `linkedin_com`, `humand.co` → `humand_co`

### `domains:` frontmatter (required)

Every `guide.md` must declare the hostnames it covers in a `domains:` frontmatter list. The wrapper resolves guides by matching the visited hostname against these entries — this replaces hardcoded alias maps.

```yaml
---
name: gmail
description: ...
domains:
  - mail.google.com
  - gmail.com
  - inbox.google.com
verified: YYYY-MM-DD
---
```

Rules:
- List the **canonical hostname** plus every known alias/subdomain that serves the app
- Subdomains of a declared entry match automatically (`app.linkedin.com` matches `linkedin.com`) — no need to list `www.`
- ccTLD variants are separate domains and must be listed explicitly (`computrabajo.com.ar` ≠ `computrabajo.com`)
- Resolution order: path-based overrides → declared `domains:` (most specific suffix wins) → generic candidates (`host`, `host-minus-first-label`, `first-label` → `<slug>/guide.md`). Declared domains always beat generic candidates, so a guide without `domains:` can be shadowed by one that declares the hostname.
- Verify resolution with `node scripts/browser.js guide-for <url>`

### Learnings vs guides

- **`guide.md`** is the curated, validated guide for the app. It documents selectors, API endpoints, flows, and gotchas that have been tested against the live site.
- **Other `.md` files** in the same directory (e.g. `login-bypass.md`, `2fa-flow.md`) are **learnings** — smaller, topic-specific files that document a single shortcut, workaround, or failure recovery discovered during real automation.
- Learnings are documentation only. They are never auto-applied by the agent. A human must review and promote useful learnings into `guide.md` or the core `SKILL.md`.

### No scripts

**Do not contribute executable scripts (`.js`, `.py`, `.sh`, `.ts`) to `sites/`.** This directory is markdown-only documentation. Scripts are executable code that runs with the user's privileges — accepting them as contributions would expand the attack surface from prompt injection (text-only) to remote code execution. If a flow is universally reusable and deterministic enough to justify a script, it belongs in the skill's `scripts/` directory (core infrastructure, like `browser.js`), not in `sites/`. That promotion is a manual, human-reviewed decision — never automatic.

## Required sections

Each app guide must include:

1. **Frontmatter** — `name`, `description`, and `domains:` (all hostnames the app serves) for skill discovery and resolution
2. **Prerequisite** — link to parent `SKILL.md` for golden rules and wrapper
3. **Setup** — how to open the site, handle login, save state
4. **Keyboard shortcuts** — **Mandatory.** Every site that has keyboard shortcuts must document them in full. Before writing a guide for a site, investigate whether it has shortcuts: check the app's help/FAQ, search "keyboard shortcuts <app name>", or try common patterns (`?`, `Ctrl+/`, `Shift+?`, `F1`). If the site has shortcuts, document the complete list in a dedicated section with tables grouped by category. Only document shortcuts that have been validated against the live site — do not include shortcuts from documentation that were not tested. Mark shortcuts that require enabling a setting (e.g. LinkedIn's hotkey toggle, Facebook's single-character switch) clearly.
5. **Core flows** — the main automation tasks (messaging, applying, reading, etc.)
6. **API reference** — when internal APIs are available, document endpoints, headers, request/response structures
7. **Anti-patterns** — what NOT to do, with explanations of why it fails
8. **Validation date** — when the guide was last validated against the live site

## When the site changes

Web apps change. Selectors break. APIs evolve. When you discover a change:

1. **Update the guide** with the new selectors or API structure
2. **Note the change** with a date and what broke
3. **Keep the old pattern** as a fallback if it still partially works, marked as deprecated
4. **Add to anti-patterns** if the old approach is now dangerous

Example:
```
**Deprecated (2026-08-10):** `innerText` assignment no longer enables the Send button.
Use `innerHTML` + `beforeinput` with `insertFromPaste` instead.
```

## Messaging sites: writing-rule footer

Guides for sites where the agent composes and sends messages on behalf of the
user (chat apps, webmail, team messaging, social DMs) get an extra footer
injected automatically when their guide is printed: a reminder to verify the
user's writing preferences before drafting or sending anything.

The list of site slugs lives in `MESSAGING_SITES` in
`../scripts/browser.js`. **If your guide is for a messaging site, add its
slug (the directory name under `sites/`) to that array.** If the site is not
a messaging surface, do nothing: the footer only appears for registered slugs.

Current entries: `whatsapp_com`, `gmail_com`, `outlook_office_com`,
`teams_com`, `linkedin_com`, `discord_com`.

## Review checklist before committing

- [ ] No personal data (names, emails, tokens, real URLs with IDs)
- [ ] Uses placeholders for all user-specific values
- [ ] Flows are reproducible from scratch by another agent
- [ ] Includes verification steps (not just "click and hope")
- [ ] API-first when possible, UI fallback documented
- [ ] Anti-patterns section documents known failure modes
- [ ] Validation date included
- [ ] Generic enough to work for any user, not just the author
- [ ] No executable scripts (`.js`, `.py`, `.sh`, `.ts`) — markdown only

## Security review checklist (for PR reviewers)

When reviewing a PR that modifies files under `sites/`, check for these supply-chain attack indicators:

- [ ] No instructions that tell the agent to read env vars, credentials, or secret files (`.env`, `~/.ssh`, `~/.aws`)
- [ ] No network calls to undocumented or external URLs (telemetry, analytics, exfiltration endpoints)
- [ ] No instructions to open PRs or perform git operations without user confirmation
- [ ] No base64-encoded blobs, hex strings, or obfuscated content
- [ ] No instructions that override the scrub/privacy rules in `SKILL.md`
- [ ] No instructions that tell the agent to auto-apply learnings (learnings are documentation only)
- [ ] No modifications to `SKILL.md`, `scripts/`, `references/`, or this file (PRs to `sites/` should only touch `sites/`)
- [ ] Content is paraphrased, not transcribed verbatim from a site (prevents prompt injection)
- [ ] SkillSpector CI check passes with no high/critical findings
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