How to use the Playwright browser automation agent skill

What the Playwright skill makes the agent do

Once installed, the agent can open a website, read a structured snapshot of the page that lists elements by reference ids such as e3, click buttons, type into fields, press keys, switch tabs, take screenshots, save PDFs and record debugging traces. The skill is built for step-by-step browser tasks.

The skill explicitly avoids writing Playwright test files. Its instructions say to stay CLI-first and not switch to @playwright/test unless you specifically ask for test files.

• Open a page and read a snapshot of its elements
• Click, double-click, hover, fill, type, select and upload
• Manage multiple tabs and navigate back, forward or reload
• Take screenshots and save PDFs
• Start and stop tracing to debug a UI flow

Install the Playwright skill

Download the skill ZIP from this page. You can then install it in one of two ways. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the ZIP.

The skill's own paths are written against $CODEX_HOME, which defaults to ~/.codex. If you install under ~/.claude/skills instead, point the PWCLI variable at the wrapper script in your install location, for example ~/.claude/skills/playwright/scripts/playwright_cli.sh.

Check and install the requirements

The skill needs Node.js and npm, because the wrapper script uses npx. It also needs network access to download the @playwright/cli npm package the first time it runs, and to open the websites you ask for. A global install of playwright-cli is optional. The skill checks for npx before it proposes any commands.

If Node.js is missing, install it, then verify both tools. If you want a global install, run the second command.

• Node.js and npm (provides npx) are required
• @playwright/cli is fetched automatically by the wrapper script
• A global install is optional

Trigger the skill with natural requests

You do not need special syntax. The skill is meant to be used when a task requires automating a real browser from the terminal, such as navigation, form filling, snapshots, screenshots, data extraction or UI-flow debugging. Say what you want done on a real site and name the outcome you need, such as a screenshot, a filled form or a trace file.

Be specific about the site and the steps. The agent works from snapshots, so it will read the page before clicking anything.

• Open https://example.com, take a snapshot and tell me the main heading
• Fill in the contact form at this URL and show me a snapshot before submitting
• Take a screenshot of the pricing page in a visible browser window
• Record a trace while I reproduce the checkout bug on my staging site

Run the core workflow: open, snapshot, act, re-snapshot

The agent follows a simple loop. It opens the page, takes a snapshot to get element refs, interacts using refs from the latest snapshot, and takes a fresh snapshot after navigation or large page changes. Refs can go stale, so if a command fails because a ref is missing, the agent should snapshot again.

Snapshot again after navigation, after clicks that change the UI a lot, after opening or closing modals or menus, and after tab switches.

• Open the page
• Snapshot to get refs
• Interact using those refs
• Re-snapshot after navigation or big DOM changes
• Capture screenshots, PDFs or traces when useful

Examples: form fill, trace debugging and multi-tab work

Form fill and submit: the agent opens the form, snapshots it, fills two fields by ref, clicks the submit button and snapshots the result. Use this only on sites you own or are allowed to test.

Debugging with traces: the agent opens the page in headed mode, starts tracing, performs the interactions, then stops tracing so you can inspect what happened.

Multi-tab work: the agent opens a new tab, lists tabs, selects one by index and snapshots it.

Safety notes before you run it

The skill runs scripts and uses the network. The wrapper script downloads the npm package and opens the websites you request. The agent acts with a real browser, so any credentials you type and any live data it touches are used for real. The skill does not sandbox browser actions or typed passwords.

Use it for sites you own or have permission to test. Avoid production accounts for sensitive work. The skill's guardrails say to prefer explicit commands over eval and run-code, and to use --headed when a visual check will help, so you can watch what happens.

• Do not automate logins or form submissions on sites you do not own or have permission to test
• Avoid sensitive work on production accounts
• Watch headed runs when the stakes are high
• Artifacts in a repo go to output/playwright/

Tips for better results

Ask for a snapshot before any click so you can check the refs. When a step fails, ask the agent to re-snapshot rather than guess. Keep each request to one flow on one site so the agent's steps stay easy to review.

The bundled reference files cover the full CLI command list and practical workflows and troubleshooting. The agent opens these only when it needs them.

• Request a snapshot before and after important actions
• Use headed mode to see what the browser does
• Ask for traces when reproducing a UI bug
• Keep one flow per request