Adom Browser Extension - skills/driving-sites/SKILL.md

by adom

Your AI's hands in your real, signed-in browser. The Adom Browser Extension (abe) works with both Chrome and Edge: build, drive, and test web apps, and log past vendor walls, in the browser you already use - cookies, SSO, saved logins and captcha trust intact. The nbrowser_* bridge (pup's counterpart) runs in your actual logged-in profile.

Overview Files Skills Discover Packages Releases Dependencies Issues1 Breadcrumbs Pull Requests Activity

Download

Parent: driving-the-extension · generic OS/popup mechanics: driving-the-desktop.

Every website is idiosyncratic — split login forms, where the Sign-out lives, whether the password autofills, SSO vs password, 2FA quirks. Without a recipe the AI re-discovers all of it every time (a fresh vendor login cost hours once). A site recipe captures a site's playbook ONCE so the next run is fast and safe.

Known recipes (in this repo)

Recipe	Site	What it covers
reading-google-messages	Google Messages PWA	Read SMS / retrieve a 2FA code from the desktop Messages app (UIA, since PrintWindow is blank) — the helper that makes SMS-2FA logins fully automatic

How a site recipe is USED

When you're about to drive a login/site, the nbrowser_login_form detector tells you the smart path (submit / sso / autofill-popup / 2fa). Pair it with the site's recipe for the site-specific bits.
Recipes trigger on the domain + "log into ", so the AI matches the right one automatically.

How to CONTRIBUTE a site recipe (two ways)

In this repo (curated/common sites): add skills/driving-<site>/SKILL.md, wire it into install.sh, uninstall.sh, and package.json files[], and add a row to the table above. Open a PR on the adom-browser-extension wiki page.
Your own page, breadcrumbed (the scaling path): publish driving-<site> (or "I built a driver for ") as its OWN wiki page — you own + version it — and breadcrumb it to the adom-browser-extension anchor (see the wiki wiki-breadcrumbs / wiki-family skills). This is exactly the wiki Family pattern: site recipes are children with independent owners/cadences. The anchor lists them; discovery routes by domain.

Site-recipe TEMPLATE (copy this)

---
name: driving-<site>
description: Site recipe for <Site> (<domain>) with the Adom browser extension — login flow, selectors,
  gotchas, 2FA, logout. Match on "log into <site>", "<domain>", "open <site>". Part of the
  adom-browser-extension site-recipe set (see driving-sites).
---
Part of the **adom-browser-extension** site-recipe set → **driving-sites**. Generic mechanics live in
**driving-the-desktop**; this page is <Site>'s quirks only.

## ✅ Logging IN (prefer the most-background path)
- Always `nbrowser_login_form` FIRST; follow its `action` (submit / sso / autofill-popup).
- <does the form autofill on load? → just submit (background). Split form? SSO? exact submit selector?>

## 🔒 2FA
- <what gate, what options (authenticator/SMS), remember-device checkbox?>

## ⛔ Logging OUT
- <use the site's own Sign-out; where is it; does a CDP click open the menu or need a desktop click?>
- <⚠️ does wiping cookies break device-trust / force 2FA? if so, say so.>

## Selectors / controls (verified <date>)
| Thing | Selector / UIA |
|---|---|
| Email/username | `...` |
| Password | `...` |
| Submit | `...` |
| Logout menu | `...` |

The hard-won rules every recipe should encode

Detect first, act second — nbrowser_login_form; if the form is already autofilled, JUST SUBMIT (background).
Never wipe cookies to log out unless you know it won't drop the device-trust/2FA-remember cookie — use the site's own Sign-out (one HR vendor's cookie-wipe caused a 2FA lockout).
Prefer CDP/background; reserve the ~1s foreground only for the autofill popup a site won't auto-fill.
Submit by selector, not button text when text-clicks prove flaky.

---
name: driving-sites
description: "The index of SITE RECIPES for the Adom browser extension — per-site playbooks that teach the AI how to drive a specific website (login flow, key selectors, gotchas, 2FA, logout) so it doesn't re-discover them every time. Read this when about to automate a known site, when you keep fighting a site's quirks, or when you (or a third party) want to CONTRIBUTE a new site recipe. Match on: site recipe, driving a website, how to log into <site>, site-specific automation, contribute a site recipe, add a site playbook, navigate <vendor> site. Lists the known recipes (reading-google-messages, …) and the template + breadcrumb flow for adding more."
---
Parent: **driving-the-extension** · generic OS/popup mechanics: **driving-the-desktop**.

Every website is idiosyncratic — split login forms, where the Sign-out lives, whether the password autofills,
SSO vs password, 2FA quirks. Without a recipe the AI re-discovers all of it every time (a fresh vendor login cost
hours once). A **site recipe** captures a site's playbook ONCE so the next run is fast and safe.

## Known recipes (in this repo)
| Recipe | Site | What it covers |
|---|---|---|
| **reading-google-messages** | Google Messages PWA | Read SMS / retrieve a 2FA code from the desktop Messages app (UIA, since PrintWindow is blank) — the helper that makes SMS-2FA logins fully automatic |

## How a site recipe is USED
1. When you're about to drive a login/site, the **`nbrowser_login_form`** detector tells you the smart path
   (`submit` / `sso` / `autofill-popup` / `2fa`). Pair it with the site's recipe for the site-specific bits.
2. Recipes trigger on the **domain** + "log into <site>", so the AI matches the right one automatically.

## How to CONTRIBUTE a site recipe (two ways)
- **In this repo** (curated/common sites): add `skills/driving-<site>/SKILL.md`, wire it into `install.sh`,
  `uninstall.sh`, and `package.json` `files[]`, and add a row to the table above. Open a PR on the
  `adom-browser-extension` wiki page.
- **Your own page, breadcrumbed (the scaling path):** publish `driving-<site>` (or "I built a driver for
  <site>") as its OWN wiki page — you own + version it — and **breadcrumb it to the `adom-browser-extension`
  anchor** (see the wiki `wiki-breadcrumbs` / `wiki-family` skills). This is exactly the wiki Family pattern:
  site recipes are children with independent owners/cadences. The anchor lists them; discovery routes by domain.

## Site-recipe TEMPLATE (copy this)
```markdown
---
name: driving-<site>
description: Site recipe for <Site> (<domain>) with the Adom browser extension — login flow, selectors,
  gotchas, 2FA, logout. Match on "log into <site>", "<domain>", "open <site>". Part of the
  adom-browser-extension site-recipe set (see driving-sites).
---
Part of the **adom-browser-extension** site-recipe set → **driving-sites**. Generic mechanics live in
**driving-the-desktop**; this page is <Site>'s quirks only.

## ✅ Logging IN (prefer the most-background path)
- Always `nbrowser_login_form` FIRST; follow its `action` (submit / sso / autofill-popup).
- <does the form autofill on load? → just submit (background). Split form? SSO? exact submit selector?>

## 🔒 2FA
- <what gate, what options (authenticator/SMS), remember-device checkbox?>

## ⛔ Logging OUT
- <use the site's own Sign-out; where is it; does a CDP click open the menu or need a desktop click?>
- <⚠️ does wiping cookies break device-trust / force 2FA? if so, say so.>

## Selectors / controls (verified <date>)
| Thing | Selector / UIA |
|---|---|
| Email/username | `...` |
| Password | `...` |
| Submit | `...` |
| Logout menu | `...` |
```

## The hard-won rules every recipe should encode
- **Detect first, act second** — `nbrowser_login_form`; if the form is already autofilled, JUST SUBMIT (background).
- **Never wipe cookies to log out** unless you know it won't drop the device-trust/2FA-remember cookie — use
  the site's own Sign-out (one HR vendor's cookie-wipe caused a 2FA lockout).
- **Prefer CDP/background**; reserve the ~1s foreground only for the autofill popup a site won't auto-fill.
- **Submit by selector, not button text** when text-clicks prove flaky.