Immutable. This exact content is served forever at /api/v1/blob/22dc1d556bf2f793.
---
name: browser-workbench-setup
description: Set up browser automation and UI QA for a new repository using playwright-interactive as the primary interactive tool and agent-browser as the secondary CLI smoke-check tool. Use when a user wants to bootstrap browser testing, screenshots, auth-state reuse, or local UI debugging conventions in a fresh repo.
---
# Browser Workbench Setup
Use this skill to configure a new repository for browser-based UI work with the smallest durable setup.
Default tool split:
- `playwright-interactive` is the primary tool for iterative UI/UX work, auth flows, layout debugging, screenshots, and deeper investigation.
- `agent-browser` is the secondary tool for quick smoke checks, annotated screenshots, fast snapshots, and lightweight CLI automation.
Do not create a custom framework, wrapper package, or shared browser helper layer unless the user explicitly asks for one.
Load references only as needed:
- Read [references/playwright-interactive.md](references/playwright-interactive.md) when setting up the primary interactive workflow.
- Read [references/agent-browser.md](references/agent-browser.md) when setting up CLI smoke checks, session persistence, or annotated screenshots.
- Read exactly one provider file when the repository auth stack is clear:
- [references/auth-clerk.md](references/auth-clerk.md)
- [references/auth-supabase.md](references/auth-supabase.md)
- [references/auth-auth0.md](references/auth-auth0.md)
- [references/auth-neon.md](references/auth-neon.md)
If the repo uses Neon with an upstream identity provider such as Clerk or Auth0, read both `auth-neon.md` and the upstream provider file. Neon may be the database auth verifier while the browser login still belongs to the upstream provider.
## Preconditions
- Confirm `playwright-interactive` is installed and available in Codex.
- Confirm `agent-browser` CLI is installed.
- Confirm Codex has `js_repl = true`.
- Confirm the session can run with `danger-full-access` when using `playwright-interactive`.
If any of those are missing, fix that first before touching the repository.
## Setup Goals
For a normal web repository, finish with:
- repo-local Playwright dependency installed with the repository's package manager
- browser binaries installed
- stable artifact directories for screenshots, traces, and auth state
- ignore rules for local browser artifacts
- a clear convention for when to use `playwright-interactive` vs `agent-browser`
## Workflow
1. Inspect the repository first.
- Read `package.json`, lockfiles, and any repo `AGENTS.md`.
- Detect the package manager from the repo, not from habit.
- Reuse existing test/artifact conventions if they already exist.
- Detect the auth provider from dependencies, env vars, routes, and middleware before making changes.
- Provider detection hints:
- Clerk: `@clerk/`, `CLERK_`, `NEXT_PUBLIC_CLERK_`
- Supabase: `@supabase/`, `SUPABASE_URL`, `SUPABASE_`, `createBrowserClient`, `createServerClient`
- Auth0: `@auth0/`, `AUTH0_`, `/auth/login`, `Auth0Client`
- Neon Auth: `neon_auth`, Neon auth endpoints, Neon JWT/JWKS setup, provider-owned auth integration
2. Install Playwright in the repo with the repo's package manager.
- For Bun repos, prefer:
```bash
bun add -d playwright
bunx playwright install chromium
```
- For pnpm/npm/yarn repos, match the repo standard.
- Install only what is needed. Default browser is Chromium unless the user asked for more.
3. Create a minimal artifact convention.
- Preferred defaults:
- `output/playwright/screenshots/`
- `output/playwright/traces/`
- `output/playwright/auth/`
- `output/agent-browser/`
- Reuse an existing `reports/` or `output/` convention if the repo already has one.
4. Add ignore rules for local-only artifacts.
- Typical entries:
```gitignore
output/playwright/
output/agent-browser/
playwright/.auth/
```
- Do not add duplicate ignore entries.
5. Standardize auth-state handling.
- Prefer Playwright `storageState` for authenticated iteration and reusable test sessions.
- Use `agent-browser` profiles or session names only for quick local smoke work.
- Keep auth files out of git.
- Prefer provider-supported test helpers when they exist.
- If the provider has no first-party Playwright helper, prefer seeded test users plus saved browser state.
- Avoid MFA in automated browser runs unless the provider explicitly supports it in test helpers.
- Rotate or delete saved auth state (profiles, `storageState`) when switching users, rotating credentials, after a security incident, or on a regular schedule.
- Enable the tool's encryption and expiry controls when available — for example, `AGENT_BROWSER_ENCRYPTION_KEY` for at-rest encryption and `AGENT_BROWSER_STATE_EXPIRE_DAYS` for auto-purging old state.
6. Keep the responsibility split explicit.
- Use `playwright-interactive` for:
- serious interactive debugging
- auth-heavy flows
- desktop/mobile passes
- console/network inspection
- screenshots and trace evidence
- Use `agent-browser` for:
- quick smoke checks
- annotated screenshots
- fast snapshots
- simple DOM or screenshot diffs
7. Avoid unnecessary additions.
- Do not add Playwright test scaffolding unless the user asked for formal test coverage.
- Do not add helper scripts, custom CLIs, or wrapper packages by default.
- Do not add CI config unless the user asked for CI.
- For auth setup, add only the minimum repo changes needed to make interactive browser work repeatable.
- User-level tools such as `~/.agent-browser/config.json` belong outside the repo.
## Provider Routing
After the initial repo scan:
- Read `playwright-interactive.md` for the primary workflow.
- Read `agent-browser.md` for CLI setup and persistence.
- Read one provider auth file for the active identity stack.
- For Neon-backed repos:
- if Neon Auth owns the user lifecycle, read `auth-neon.md`
- if Neon is only verifying JWTs from Clerk/Auth0/etc., read `auth-neon.md` plus that upstream provider file
Do not load every provider reference by default.
## Automation Standard
When the user asks to set this up in a repo, complete the work end to end:
- install the repo-local Playwright dependency
- install browser binaries
- create artifact directories
- add ignore rules
- add or align formal auth bootstrap only if the repo already has Playwright tests or the user asked for them
- configure `agent-browser` persistence with either a profile path or a session name convention
- report the exact auth path chosen and why
## Preferred Defaults
When no repo convention conflicts:
- install only `playwright`
- install only Chromium first
- keep artifacts under `output/`
- use repo-local ignores, not global git excludes
- keep setup changes small and reviewable
## Deliverable
When you finish, report:
- package manager used
- dependency added
- directories added
- ignore rules added
- any user-level config that must exist outside the repo
- provider-specific auth path selected
- the exact command the user should run first with `playwright-interactive`
## UI Audit Contract
When setup or QA evidence needs a structured handoff, use `ui_audit.v1` with
`target.framework` set to `browser-workbench`.
- Use `findings` for missing or broken verification capabilities, such as no
repeatable auth-state path, screenshots/traces written to tracked locations,
or unavailable browser tooling that blocks UI validation.
- Use `observations` for chosen package manager, installed browser, artifact
directories, auth provider, and the selected `playwright-interactive` versus
`agent-browser` responsibility split.
- Use `severity: error` only when a missing browser workflow blocks release or
verification; use `warning` for setup gaps that are important but not
release-blocking.
- Keep local auth-state paths and repository roots redacted unless the user
explicitly asks for machine-local evidence.
## First-Run Prompt
After setup, suggest a first real task such as:
`Use $playwright-interactive to open the local app, verify sign-in, test theme persistence, run desktop and mobile passes, and capture screenshots.`