claude-skill-playwright-browser

English | 繁體中文

Gives 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

See it in action

_{All images were produced by this skill against a small demo site.}

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?

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).

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)

# 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:

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.

Token usage

Rough extra cost of one use inside an existing conversation:

The main cost is looking at screenshots (~1.5k–2k each). Asking only for the sizes you need, and giving a URL instead of having Claude find the page, saves a lot.

Troubleshooting

Manual use (advanced)

You normally don't need this — Claude calls it for you. To run it yourself:

PW="$HOME/.claude/skills/playwright-browser/scripts/pw.mjs"

node "$PW" inspect --url https://example.com --click "Pricing"        # text outline of the page
node "$PW" shot    --url https://example.com --viewport desktop,mobile --full
node "$PW" audit   --url https://example.com                           # full health check, writes report.md
node "$PW" run     --script flow.mjs --url https://example.com         # custom flow
node "$PW" login   --session admin --url https://example.com/login --until-url dashboard   # log in; saves once you reach dashboard
node "$PW" sessions                                                    # list saved sessions
node "$PW" clean   --days 0                                            # delete all temp screenshots

Each command prints one line of JSON. See SKILL.md for every option.

Update & uninstall

• Update: run git pull in the skill folder; if package.json changed, run node scripts/setup.mjs again
• Uninstall: delete the skill folder and ~/.claude/playwright/. For the browser cache, run npx playwright uninstall --all in the skill folder before deleting it, or remove ~/Library/Caches/ms-playwright (macOS), ~/.cache/ms-playwright (Linux) or %LOCALAPPDATA%\ms-playwright (Windows)

Repository layout

SKILL.md                     Instructions Claude reads (when and how to use the skill)
scripts/pw.mjs               The CLI: inspect / shot / audit / run / login / diff / sessions / clean
scripts/setup.mjs            Cross-platform one-time setup
references/analysis.md       How to read audit results, thresholds, tracing issues to code
references/project-tests.md  Turning flows into real project tests (Playwright Test + CI)
docs/images/                 README screenshots (made with this skill)
CHANGELOG.md                 Release notes

License

MIT © AndyShiu · See CHANGELOG.md for release notes.