playwright

name	playwright
description	Use when the task requires automating a real browser from the terminal (navigation, form filling, snapshots, screenshots, data extraction, UI-flow debugging) via `playwright-cli` or the bundled wrapper script.
policy_doc_kind	skill
classification	canonical
canonical_owner	self
authority_level	procedural
in_verifier_scope	true
lexical_guard_profile	stale_names,destructive_rollback,branch_policy_live

Playwright CLI Skill

Drive a real browser from the terminal using playwright-cli. Prefer the bundled wrapper script so the CLI works even when it is not globally installed. Treat this skill as CLI-first automation. Do not pivot to @playwright/test unless the user explicitly asks for test files.

This skill owns browser automation workflow only. Global policy owns routing, review expectations, and workspace artifact conventions outside the browser flow itself.

Prerequisite check (required)

Before proposing commands, check whether npx is available (the wrapper depends on it):

command -v npx >/dev/null 2>&1

If it is not available, pause and ask the user to install Node.js/npm (which provides npx). Provide these steps verbatim:

# Verify Node/npm are installed
node --version
npm --version

# If missing, install Node.js/npm, then:
npm install -g @playwright/cli@latest
playwright-cli --help

Once npx is present, proceed with the wrapper script. A global install of playwright-cli is optional.

Skill path (set once)

export CLAUDE_HOME="${CLAUDE_HOME:-$HOME/.claude}"
export PWCLI="$CLAUDE_HOME/skills/playwright/scripts/playwright_cli.sh"

User-scoped skills install under $CLAUDE_HOME/skills (default: ~/.claude/skills).

Quick start

Use the wrapper script:

"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" press Enter
"$PWCLI" screenshot

If the user prefers a global install, this is also valid:

npm install -g @playwright/cli@latest
playwright-cli --help

Core workflow

1. Open the page.
2. Snapshot to get stable element refs.
3. Interact using refs from the latest snapshot.
4. Re-snapshot after navigation or significant DOM changes.
5. Capture artifacts (screenshot, pdf, traces) when useful.

Minimal loop:

"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e3
"$PWCLI" snapshot

When to snapshot again

Snapshot again after:

• navigation
• clicking elements that change the UI substantially
• opening/closing modals or menus
• tab switches

Refs can go stale. When a command fails due to a missing ref, snapshot again.

Recommended patterns

Form fill and submit

"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "[e-mail]"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot

Debug a UI flow with traces

"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start
# ...interactions...
"$PWCLI" tracing-stop

Multi-tab work

"$PWCLI" tab-new https://example.com
"$PWCLI" tab-list
"$PWCLI" tab-select 0
"$PWCLI" snapshot

Wrapper script

The wrapper script uses npx --package @playwright/cli playwright-cli so the CLI can run without a global install:

"$PWCLI" --help

Prefer the wrapper unless the repository already standardizes on a global install.

References

Open only what you need:

• CLI command reference: references/cli.md
• Practical workflows and troubleshooting: references/workflows.md

Guardrails

• Always snapshot before referencing element ids like e12.
• Re-snapshot when refs seem stale.
• Prefer explicit commands over eval and run-code unless needed.
• When you do not have a fresh snapshot, use placeholder refs like eX and say why; do not bypass refs with run-code.
• Use --headed when a visual check will help.
• When capturing artifacts in this repo, use output/playwright/ and avoid introducing new top-level artifact folders.
• Default to CLI commands and workflows, not Playwright test specs.