playwright-browser skill

---
name: playwright-browser
description: Headless, reproducible browser automation with Playwright for any project — screenshots of web pages or local dev servers (desktop/tablet/mobile, full page or one element, single page or every page/menu of an app in one batch), frontend audits (console errors, failed requests, broken images/links, responsive overflow, axe accessibility, LCP/CLS performance), before/after visual comparison, scripted E2E flows (log in, click, fill, page through, assert), and logged-in pages via saved sessions. Use this whenever the user wants to screenshot or visually check a site, find frontend bugs, see how a page looks on mobile, compare the UI before and after a CSS/code change, reproduce a bug from an issue or ticket and capture evidence images for it, verify a UI flow works, or run/write a browser test — even if they never say "Playwright" or "browser". If Claude in Chrome could also do the job, briefly ask which to use (with a recommendation) instead of silently picking.
---

# Playwright Browser

Background browser automation that runs locally and produces files (PNG, JSON, Markdown) the user can keep or reuse. The runtime lives in this skill directory and is shared by every project; per-project scripts, sessions and baselines are kept separate.

Respond in the user's language.

**Paths.** `<skill-dir>` means the directory that contains this SKILL.md — Claude Code reports it as the skill's base directory when the skill loads. It may be `~/.claude/skills/playwright-browser`, a project's `.claude/skills/…`, or a plugin folder, so never assume a fixed location. Call the CLI as `node "<skill-dir>/scripts/pw.mjs" <command> …` with the real absolute path substituted; that form works in zsh, bash, PowerShell and cmd (forward slashes are fine on Windows). Below, `pw` is shorthand for exactly that.

## 0. Choose the tool first

This skill does not replace Claude in Chrome. They overlap, so decide deliberately:

| Prefer **Claude in Chrome** | Prefer **Playwright (this skill)** |
|---|---|
| Needs the user's real, already-logged-in browser (SSO, 2FA, extensions) | Runs in the background without touching the user's browser |
| User wants to watch or step in while it operates | Must be reproducible (same script, same result) |
| One quick look at a page | Several viewports / pages in one batch |
| Interacting with something open in a tab right now | Tests, audits, reports, before/after visual diff |

If the request clearly fits one column, just proceed. If both fit (e.g. "take a screenshot of our site"), ask one short question naming both options and recommending one with a reason — e.g. "Use Playwright (background, can do desktop+mobile in one go) or Chrome (your logged-in tab)? I'd suggest Playwright." Don't ask again for follow-up tasks in the same thread unless the situation changes.

## Match the output to the request

Do what was asked, at the size it was asked. "Screenshot the pricing page" → take the shot, check it looks right, hand it over; no audit, no improvement list. "Why does the save button do nothing?" → reproduce and diagnose that button, fix it if you're in the project; don't append unrelated findings from a full audit. Only run `audit` and give a prioritized list of recommendations when the user asks for a review, a health check, or "find problems". If you happen to notice something serious outside the request (a crash, a security issue), mention it in one line — nothing more.

## 1. Make sure the runtime exists

```bash
node "<skill-dir>/scripts/pw.mjs" clean     # cheap check; prints JSON
```
If it returns an `error` with a `hint` about setup, the runtime isn't installed on this machine yet (normal right after someone shares or clones the skill). Tell the user it's a one-time download (~150 MB for Chromium, needs Node.js 18+), then run `node "<skill-dir>/scripts/setup.mjs"`. For other engines: `node "<skill-dir>/scripts/setup.mjs" firefox webkit`. Setup installs npm packages into the skill directory and browsers into Playwright's shared per-user cache, so it never touches the user's projects.

## 2. Commands

Every command prints one compact JSON object on stdout (progress goes to stderr, so use `2>/dev/null` when parsing); long lists are trimmed to 20 items plus a `truncated` count, and `audit` keeps the full data in `report.json`. Output files go to a fresh temp run dir (`$TMPDIR/claude-playwright/<timestamp>_<cmd>/`) unless `--out <dir>` is given — `--out` dirs are yours and are never auto-deleted.

```bash
# pw = node "<skill-dir>/scripts/pw.mjs"
pw inspect --url <url> [--click "<visible text>" ...] [--shot]
pw shot  --url <url> [--viewport desktop,mobile|all|1366x768] [--full] [--selector "<css>"] [--name <label>]