# playwright-browser

Adopt this skill: https://proskills.md/skills/other/andyshiu-claude-skill-playwright-browser

Page: https://proskills.md/skills/other/andyshiu-claude-skill-playwright-browser
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8042
upstream: https://github.com/andyshiu/claude-skill-playwright-browser/blob/HEAD/SKILL.md

````text
---
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>]
pw audit --url <url> [--viewport ...] [--skip links,axe,perf,visual,layout,images,console,network]
          [--external-links] [--max-links 100] [--update-baseline] [--name <label>]
pw run   --script <file.mjs> [--url <start-url>] [--viewport mobile] [--full] [--trace]   # one viewport per call
pw login --session <name> --url <login-url> [--until-url <path-substring>]
pw diff  <baseline.png> <current.png>
pw sessions [--delete <name>]
pw clean [--days 7]
```

Options shared by page commands: `--mask "<css>"` (blank out dynamic regions such as clocks or carousels in screenshots — use it for visual diffs), `--session <name>` (reuse a login), `--browser chromium|firefox|webkit`, `--headed` (show the window, useful for debugging), `--wait-for "<css>"`, `--wait <ms>`, `--timeout <ms>`, `--insecure` (self-signed HTTPS on intranet hosts), `--header "Name: value"`, `--locale zh-TW`, `--project <slug>` (defaults to the git repo name of the cwd).

Viewport presets: `desktop` 1440×900, `laptop` 1280×800, `tablet` 768×1024 (touch), `mobile` 390×844 (touch, 3x). `audit` defaults to desktop + tablet + mobile; `shot` and `run` default to desktop.

## 3. Finding your way around: `inspect`

Before writing a `run` script or guessing selectors, run `inspect`. It returns a text outline of the page — headings, navigation (including menu items that are buttons, not links), buttons with their disabled state, form fields with labels and required flags, tables with their columns and row counts, tabs, dialogs, alerts and pagination text — plus error counts and login/loading warnings. `--click` (repeatable, in order) clicks elements by their visible text first, so `--click Settings --click "User management"` walks a menu. It costs a few hundred tokens where a screenshot costs ~1.5k and a trial-and-error discovery script costs several round trips; use screenshots when you need to judge how something *looks*, `inspect` when you need to know what's *there*.

## 4. Screenshots

Decide the spec from the request — full page vs viewport vs one element, which sizes — and ask only if it genuinely matters and isn't inferable. Each image you open costs roughly 1.5–2k tokens, so capture only the sizes that were asked for and prefer an element or viewport shot when that answers the question.

Before handing screenshots over, make sure they show the real page. For a few shots, **look at each image** (Read the PNG) so you can describe what's there and catch a blank page, cookie banner, login wall or spinner. For a batch (roughly more than 5), rely on the `warnings` in the JSON, open every shot that has one plus a couple of samples, and tell the user which ones you actually looked at. If the page wasn't ready, retry with `--wait-for "<selector>"` or `--wait 1500` rather than handing over a bad shot.

Then tell the user where the files are — and be accurate about retention: only the default run dir (`$TMPDIR/claude-playwright/…`) is auto-deleted after 7 days; anything written with `--out` or copied elsewhere stays until someone deletes it — and ask where they want them saved (or whether the temp copy is enough for the next step, e.g. attaching to an issue). Copy with `cp`; never move files into the project without being asked.

## 5. Au
````

## File: README.md
upstream: https://github.com/andyshiu/claude-skill-playwright-browser/blob/HEAD/README.md

````text
# claude-skill-playwright-browser

**English** | [繁體中文](README.zh-TW.md)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/AndyShiu/claude-skill-playwright-browser)](https://github.com/AndyShiu/claude-skill-playwright-browser/releases)
![Node.js ≥18](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white)
![Playwright 1.63](https://img.shields.io/badge/playwright-1.63-2EAD33?logo=playwright&logoColor=white)
![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
![Claude Code skill](https://img.shields.io/badge/Claude%20Code-skill-D97757)

Gives [Claude Code](https://claude.com/claude-code) a **browser that runs in the background**. Ask in plain language — "screenshot the homepage on mobile", "why does the Submit button do nothing on this page?", "health-check the checkout page" — and Claude opens a browser, clicks around, takes screenshots, runs checks, and hands you the results and files. It never touches the browser you're using, and it works in any project (frontend, backend, even non-Node projects).

---

## What it does

| Feature | Details |
|---|---|
| 📸 **Screenshots** | Desktop / tablet / mobile, full page or a single element, many pages in one batch |
| 🩺 **Frontend health check** | Console errors, failed API calls (4xx/5xx), broken images, broken links, mobile layout overflow (and which element causes it), accessibility issues (axe), performance (LCP / CLS) |
| 🔍 **Visual comparison** | Save a baseline before a CSS change, compare afterwards, get a diff image with changes highlighted in red |
| 🧭 **UI flows** | Log in, click through menus, fill forms, page through lists, assert results — with a screenshot at each step and an automatic screenshot on failure |
| 🔐 **Sites that need login** | You log in once yourself; Claude then reuses that session in the background (your password is never stored) |
| 🧪 **Real tests** | When you want it, turn a flow into a Playwright Test in your project and run it in CI |

### See it in action

![Screenshots on every screen size](docs/images/responsive-en.png)

![Frontend health check](docs/images/audit-en.png)

![Before / after visual comparison](docs/images/diff-en.png)

<sub>All images were produced by this skill against a small demo site.</sub>

## Examples

Just talk to Claude — no need to mention "Playwright":

```
Take mobile and desktop screenshots of the homepage at localhost:5173
A customer says our site scrolls sideways on iPhone — find the element that's too wide
Health-check the new checkout page before we ship it
I changed the header CSS — compare before and after
On the admin "Orders" page, does going to page 2 actually load different data?
This issue says "Submit" does nothing — reproduce it on dev and capture screenshots
Screenshot every page in the admin menu and save them to my Desktop
```

**Claude sticks to what you asked**: ask for a screenshot and you get a screenshot; ask about one bug and it deals with that bug. A full check with a list of recommendations only happens when you ask for a review or a health check.

### Claude in Chrome or this skill?

| Better with Claude in Chrome | Better with this skill |
|---|---|
| Uses the tab **you have open right now**, in your logged-in browser | Runs **in the background**, doesn't touch your browser |
| You want to **watch it work** | Must be **repeatable** with consistent results |
| A quick one-off look | Several sizes or many pages **in one batch** |
| | Health checks, reports, before/after comparisons, tests |

When both would work, Claude asks which one you prefer and suggests one.

#### Head-to-head test

Same task for both, run by two fresh Claude agents: *"take mobile screenshots of these 3 report pages"* on a logged-in internal admin app (URLs given).

| | Claude in Chrome | This skill |
|---|---|---|
| Tokens | 48,045 | 48,853 |
| Time | 93 s | **47 s** |
| Tool calls | 9 | 7 |
| Mobile size | 500×667 — Chrome windows can't go narrower than 500 px | **390×844** (real iPhone size, 3× scale) |
| Output | JPEG in a temp folder, had to be moved | PNG saved where you asked |
| Full-page capture | Not available | Available |
| Login | Your Chrome's existing login | Session saved earlier with this skill |

**Takeaways**: tokens were a wash for a small job like this — most of both totals is each agent's fixed overhead. The skill was twice as fast and produced true phone-width screenshots; Chrome can't emulate widths below ~500 px, so layout bugs that only appear at 390 px are out of its reach. One run each with URLs provided — tasks with more pages or steps should favour the skill further, but that part hasn't been measured.

---

## Install

**Requirements**: Claude Code, Node.js 18+ (`node -v`), macOS / Linux / Windows, about 150 MB of disk for Chromium.

**1. Clone into a skills directory** (the folder must be named `playwright-browser`)

```bash
# Just for you, available in every project
git clone https://github.com/AndyShiu/claude-skill-playwright-browser.git ~/.claude/skills/playwright-browser

# Or for a single project (commit it with the project to share with your team)
git clone https://github.com/AndyShiu/claude-skill-playwright-browser.git <project>/.claude/skills/playwright-browser
```

On Windows the personal location is `%USERPROFILE%\.claude\skills\playwright-browser`.

> **Windows / Git Bash**: Claude Code on Windows uses Git Bash by default, which rewrites arguments that start with `/` into Windows paths (`--until-url /dashboard` becomes `C:/Program Files/Git/dashboard`). The skill undoes this for its own options automatically. If you run other commands by hand and hit the same thing, drop the leading `/` (e.g. `--until-url dashboard`), prefix the command with `MSYS_NO_PATHCONV=1`, or use PowerShell / cmd.

**2. That's it.** The first time Claude uses the skill it notices the runtime isn't installed, tells you, and runs the one-time setup. To install up front instead:

```bash
node ~/.claude/skills/playwright-browser/scripts/setup.mjs                  # Chromium only
node ~/.claude/skills/playwright-browser/scripts/setup.mjs firefox webkit   # also Firefox and WebKit (Safari's engine)
```

npm packages go into `node_modules/` inside the skill folder (git-ignored); browsers go into Playwright's shared cache, so every project and every copy of the skill shares one download. **Your projects are never touched.**

---

## Sites that need login

1. Tell Claude you want to work on a site that needs login — it opens a browser window for you
2. **Log in yourself** in that window (only you type your credentials; they're never stored)
3. Close the window when you're done — or Claude sets it to save and close automatically once you reach a given page

From then on Claude can use that session in the background. After every run, any tokens the site refreshed are saved back, so **a session you keep using stays logged in**. If it sits idle past the site's login lifetime, Claude detects the redirect to the login page and asks you to log in again — it will never hand you a login screen as the result.

---

## Where files go

The skill folder contains **no personal data**, so it's safe to share or commit.

| What | Where | Notes |
|---|---|---|
| Login sessions | `~/.claude/playwright/sessions/<project>/` | Contain cookies / tokens, readable only by you. **Never commit or share them** |
| Visual baselines | `~/.claude/playwright/baselines/<project>/` | Reference screenshots for before/after comparisons |
| Screenshots & reports | `claude-playwright/` in the system temp dir | **Deleted after 7 days**; Claude asks where to save anything you want to keep |

---

## Token usage

Rough extra cost of one use inside an existing conversation:

| Task | Approx. tokens |
|---|---|
| One screenshot | 5k–7k |
| Three screen sizes | 8k–10k |
| Full health check of one page | 12k–18k |
| Investigating one
````
