SKILL.md

$2a

Install the Playwriter Chrome extension from the Web Store (search "Playwriter MCP" or use extension ID jfeammnjpkecdekppnclgkkffahnhfhe).

After installing, click the extension icon on any tab you want to allow automation on. The icon turns green when a tab is enabled for control.

Step 2: Install CLI

npm install -g playwriter

# or run without installing:

npx playwriter@latest --help

The extension auto-starts a WebSocket relay server at localhost:19988.

Core workflow

Always follow the Observe → Act → Observe pattern:

# 1. Create a session

playwriter session new

# 2. Navigate and observe

playwriter -s 1 -e 'await page.goto("https://example.com")'

playwriter -s 1 -e 'await snapshot({ page })'

# 3. Interact based on snapshot output

playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

# 4. Re-observe after action

playwriter -s 1 -e 'await snapshot({ page })'

Session management

# Create a new isolated stateful session

playwriter session new

# List all active sessions (shows browser, profile, state info)

playwriter session list

# Delete a session and clear its state

playwriter session delete <sessionId>

# Reset the CDP connection and clear execution environment

playwriter session reset <sessionId>

The -e / --eval flag

Execute arbitrary Playwright code in a session:

# Navigate to a URL

playwriter -s 1 -e 'await page.goto("https://github.com")'

# Fill a form field

playwriter -s 1 -e 'await page.fill("#search", "playwriter"); await page.keyboard.press("Enter")'

# Get accessibility snapshot (preferred over screenshots for text content)

playwriter -s 1 -e 'await snapshot({ page })'

# Take screenshot with visual accessibility labels (color-coded by element type)

playwriter -s 1 -e 'await screenshotWithAccessibilityLabels({ page })'

# Store state between calls (state object persists within session)

playwriter -s 1 -e 'state.url = page.url(); state.title = await page.title()'

playwriter -s 1 -e 'console.log(state.url, state.title)'

Quoting rules: Wrap code in single quotes. For multiline code, use heredoc:

playwriter -s 1 -e "$(cat <<'EOF'

const text = await page.textContent('h1');

state.heading = text;

await snapshot({ page });

EOF

)"

MCP Integration

Claude Desktop config ( ~/.claude/settings.json or Claude Desktop MCP settings)

{

  "mcpServers": {

    "playwriter": {

      "command": "npx",

      "args": ["-y", "playwriter@latest"]

    }

  }

}

Remote relay server

{

  "mcpServers": {

    "playwriter": {

      "command": "npx",

      "args": ["-y", "playwriter@latest"],

      "env": {

        "PLAYWRITER_HOST": "your-relay-host",

        "PLAYWRITER_TOKEN": "your-secret-token",

        "PLAYWRITER_SESSION": "1"

      }

    }

  }

}

MCP tools exposed

Tool

Description

execute

Run arbitrary JavaScript Playwright code (code, timeout params)

reset

Recreate CDP connection, clear state — use after connection failures

Built-in globals (in execute sandbox)

Global

Description

page

Current Playwright page

context

Browser context

state

Persistent object — survives multiple -e calls in same session

snapshot({ page })

Accessibility tree as text (token-efficient)

screenshotWithAccessibilityLabels({ page })

Screenshot with color-coded element markers

getPageMarkdown()

Article text via Mozilla Readability

waitForPageLoad()

Smart load detection

getLatestLogs()

Browser console errors/logs

getCleanHTML()

Cleaned DOM HTML

getLocatorStringForElement()

Get selector for a DOM element

getReactSource()

React component source tree

Accessibility labeling

screenshotWithAccessibilityLabels({ page }) overlays color-coded markers on interactive elements:

Color

Element type

Yellow

Links

Orange

Buttons

Coral

Inputs

Pink

Checkboxes

Peach

Sliders

Click a labeled element using aria-ref:

playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

Network interception and state persistence

# Intercept network requests

playwriter -s 1 -e 'state.requests = []; page.on("request", r => state.requests.push(r.url()))'

# Check collected requests later

playwriter -s 1 -e 'console.log(state.requests.slice(-5).join("\n"))'

# Screen recording

playwriter -s 1 -e 'await recording.start()'

# ... do actions ...

playwriter -s 1 -e 'const video = await recording.stop(); state.video = video'

Remote access

Control Chrome on a remote machine via tunnel:

# On the machine with Chrome:

playwriter serve --token my-secret --replace

# From agent machine:

playwriter --host <ip-or-hostname> --token my-secret -s 1 -e 'await page.goto("https://example.com")'

Best practices

Observe → Act → Observe: always call snapshot({ page }) before and after each action

**Prefer snapshot() over screenshots** for text inspection (fewer tokens, faster)

Never chain actions blindly — verify state between steps

Use stable selectors: prefer aria-ref, data-testid, or accessible roles

**Store context in state**: avoid repeated navigation by persisting page references

**Use reset on failures**: CDP disconnects recover cleanly with playwriter session reset

Troubleshooting

Issue

Solution

Extension not connecting

Click extension icon on the tab; icon must be green

connection refused :19988

Extension auto-starts server; check Chrome is running with extension installed

Code execution timeout

Increase with --timeout 30000 flag

Click fails silently

Use snapshot({ page }) — a modal likely intercepts the click

Stale session

Run playwriter session reset <id> to restore CDP connection

Remote access failing

Confirm playwriter serve is running and token matches

References

GitHub: remorses/playwriter

Chrome Extension Web Store

playwriter skill — print full usage guide from CLI

playwriter logfile — view relay server + CDP log paths

playwriter