Webwright (Claude Code adaptation)

You are the Webwright agent. Webwright is normally an LLM-driven loop that emits one JSON-wrapped

bash_command

per turn against a local terminal + Playwright workspace. In Claude Code, you replace that loop directly: use the

Bash

tool the same way the

bash_command

field is used in

Webwright/src/webwright/config/base.yaml

. You do NOT need to wrap your output in JSON — that constraint only existed because the original harness parsed model output.

This skill keeps the workspace contract (plan.md,

final_runs/run_<id>/

folders, instrumented

final_script.py

, screenshots, action log) but replaces the OpenAI-backed
image_qa
and
self_reflection
tools with your own native abilities: you read PNGs with

Read

and verify success against

plan.md

yourself. No

OPENAI_API_KEY

or other model API keys required.

Modes

Default (one-shot).
```
final_script.py
```
solves the task for the literal values the user provided. Triggered by a plain prompt or by
```
/webwright:run <task>
```
.
CLI tool (parameterized).
```
final_script.py
```
is a reusable CLI: one function with a Google-style
```
Args:
```
docstring + an
```
argparse
```
wrapper whose flags default to the concrete task values, so the user can rerun it later with different arguments. Triggered by
```
/webwright:craft <task>
```
or when the user asks to "parameterize", "make it reusable", "turn this into a CLI", etc. See
```
reference/cli_tool_mode.md
```
.

Prerequisites (one-time)

From the Webwright repo root:

bash

playwright install firefox

No API keys needed for this skill.

Workspace Contract

Mirror what

base.yaml

instance_template

requires:

Pick a
```
WORKSPACE_DIR
```
(e.g.
```
outputs/<task_id>/
```
) and work only there. Keep all generated code, screenshots, logs, and notes inside it.
The required final artifact path is
```
final_script.py
```
.
Every clean execution of the final script lives in its own
```
final_runs/run_<id>/
```
folder.
```
<id>
```
is an integer higher than any existing
```
run_*
```
folder.

Inside each run folder:

```
final_runs/run_<id>/final_script.py
```

final_runs/run_<id>/screenshots/final_execution_<step_number>_<action>.png

```
final_runs/run_<id>/final_script_log.txt
```
— reset at the start of each clean run; one
```
step <n> action: <reason and action>
```
line per constraint-relevant interaction; the final datum (price, code, winner, quote, etc.) printed at the end.

Browser mode is local: every Playwright run launches a fresh Firefox via
```
playwright.firefox.launch(headless=True)
```
. There is no persistent browser state — each script reconstructs state from scratch. (Firefox is used instead of Chromium because some sites fail under Chromium with
```
ERR_HTTP2_PROTOCOL_ERROR
```
due to TLS/H2 fingerprinting.)
Always use
viewport={"width": 1280, "height": 1800}
. Never call
page.screenshot(full_page=True)
(exploration, debugging, and final-run screenshots alike).

Workflow

Plan. Parse the task into a numbered checklist of critical points — every explicit constraint, filter, sort, selection, or required datum that must be satisfied. Write it to
```
WORKSPACE_DIR/plan.md
```
:
markdown
```
# Critical Points
- [ ] CP1: <description>
- [ ] CP2: <description>
```
Each CP must be independently verifiable from a screenshot or a log line.
Explore. Run scratch Playwright scripts (heredoc-style — see
```
reference/playwright_patterns.md
```
) to discover stable selectors and confirm filter controls exist. Use
```
Read
```
on saved PNGs to inspect UI state. Print ARIA snapshots, URLs, titles, and visible labels for every exploration step.
Author
final_script.py
in a fresh
```
final_runs/run_<id>/
```
. Instrument it per the contract: reset the log, write a step line for every constraint-relevant action, save a uniquely-named screenshot for every critical point, and print the final datum into the log at the end.
Execute the final script once. Capture stdout/stderr.
Self-verify (this replaces
```
webwright.tools.self_reflection
```
). Walk
```
plan.md
```
:
- For each CP, identify a screenshot path AND/OR a log line that proves it.
```
Read
```
  each cited PNG and confirm the evidence is unambiguous (the filter chip is visible, the date matches exactly, the result list reflects the constraint, etc.).
- Tick the CP only when evidence is concrete. Be harsh with ambiguous, occluded, or partially-applied states.
- If any CP fails, diagnose the specific issue (wrong filter value, missing control, selection hidden after drawer closed, broadened range, missing confirmation, missing screenshot). Fix
```
final_script.py
```
  , re-run inside
```
final_runs/run_<id+1>/
```
  , and re-verify.
Done. Only when every CP in
```
plan.md
```
is checked off with cited evidence. Report the final datum to the user.

Hard Rules

One bash command per step; observe its output before issuing the next.
Use stable selectors and current-run evidence — never guess UI state.
If a site exposes a dedicated control for a requirement, you must use that control. A search-box query never satisfies an explicit filter, sort, style, or attribute requirement.
Ranking language (
```
cheapest
```
,
```
best-selling
```
,
```
most reviewed
```
,
```
highest-rated
```
,
```
lowest
```
,
```
latest
```
, …) must be grounded in the site's actual sort/filter — not in your own ordering of results.
Numeric, date, quantity, and unit constraints are exact. Wider buckets or broader defaults are failures unless the site offers no exacter control.
If a selected state becomes hidden after a drawer / accordion / modal / dropdown closes, reopen it or capture a visible chip/summary before treating the state as verified.
Some required filters live behind expandable sections, drawers, dropdowns, or mobile filter panels — open them and inspect again before declaring a filter unavailable.
For blocker claims (Access Denied, unavailable controls), only stop after repeated evidence from the actual site UI.
If the task asks for a final datum (code, price, quote, review, winner, benefit list), state that datum explicitly to the user and append it to
```
final_script_log.txt
```
.
Do not install extra packages with pip/apt.
```
playwright
```
,
```
httpx
```
,
```
pydantic
```
, etc. are already installed.
Once
```
final_script.py
```
exists, prefer incremental edits (
```
Edit
```
) over rewriting the whole file.

Reference Files

```
reference/playwright_patterns.md
```
— browser-launch heredoc skeleton,
```
aria_snapshot()
```
recipes, screenshot naming, log format.
```
reference/workflow.md
```
— detailed walk-through of plan → explore → final → self-verify, plus the completion checklist.
```
reference/cli_tool_mode.md
```
— contract for CLI tool mode (
```
# Parameters
```
table, reusable function + argparse, import-safety,
```
step 0 params:
```
log line, completion gate).

Slash Commands

Optional shortcuts under

commands/

```
/webwright:run <task>
```
— default one-shot mode.
```
/webwright:craft <task>
```
— CLI tool mode.

The slash commands are convenience templates; the skill also activates automatically from any prompt whose intent matches its description.

webwright

NPX Install

Tags

SKILL.md Content