Agent Skills

1---
2name: "playwright"
3description: "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."
4---
5 
6 
7# Playwright CLI Skill
8 
9Drive 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.
10Treat this skill as CLI-first automation. Do not pivot to `@playwright/test` unless the user explicitly asks for test files.
11 
12## Prerequisite check (required)
13 
14Before proposing commands, check whether `npx` is available (the wrapper depends on it):
15 
16```bash
17command -v npx >/dev/null 2>&1
18```
19 
20If it is not available, pause and ask the user to install Node.js/npm (which provides `npx`). Provide these steps verbatim:
21 
22```bash
23# Verify Node/npm are installed
24node --version
25npm --version
26 
27# If missing, install Node.js/npm, then:
28npm install -g @playwright/cli@latest
29playwright-cli --help
30```
31 
32Once `npx` is present, proceed with the wrapper script. A global install of `playwright-cli` is optional.
33 
34## Skill path (set once)
35 
36```bash
37export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
38export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
39```
40 
41User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
42 
43## Quick start
44 
45Use the wrapper script:
46 
47```bash
48"$PWCLI" open https://playwright.dev --headed
49"$PWCLI" snapshot
50"$PWCLI" click e15
51"$PWCLI" type "Playwright"
52"$PWCLI" press Enter
53"$PWCLI" screenshot
54```
55 
56If the user prefers a global install, this is also valid:
57 
58```bash
59npm install -g @playwright/cli@latest
60playwright-cli --help
61```
62 
63## Core workflow
64 
651. Open the page.
662. Snapshot to get stable element refs.
673. Interact using refs from the latest snapshot.
684. Re-snapshot after navigation or significant DOM changes.
695. Capture artifacts (screenshot, pdf, traces) when useful.
70 
71Minimal loop:
72 
73```bash
74"$PWCLI" open https://example.com
75"$PWCLI" snapshot
76"$PWCLI" click e3
77"$PWCLI" snapshot
78```
79 
80## When to snapshot again
81 
82Snapshot again after:
83 
84- navigation
85- clicking elements that change the UI substantially
86- opening/closing modals or menus
87- tab switches
88 
89Refs can go stale. When a command fails due to a missing ref, snapshot again.
90 
91## Recommended patterns
92 
93### Form fill and submit
94 
95```bash
96"$PWCLI" open https://example.com/form
97"$PWCLI" snapshot
98"$PWCLI" fill e1 "user@example.com"
99"$PWCLI" fill e2 "password123"
100"$PWCLI" click e3
101"$PWCLI" snapshot
102```
103 
104### Debug a UI flow with traces
105 
106```bash
107"$PWCLI" open https://example.com --headed
108"$PWCLI" tracing-start
109# ...interactions...
110"$PWCLI" tracing-stop
111```
112 
113### Multi-tab work
114 
115```bash
116"$PWCLI" tab-new https://example.com
117"$PWCLI" tab-list
118"$PWCLI" tab-select 0
119"$PWCLI" snapshot
120```
121 
122## Wrapper script
123 
124The wrapper script uses `npx --package @playwright/cli playwright-cli` so the CLI can run without a global install:
125 
126```bash
127"$PWCLI" --help
128```
129 
130Prefer the wrapper unless the repository already standardizes on a global install.
131 
132## References
133 
134Open only what you need:
135 
136- CLI command reference: `references/cli.md`
137- Practical workflows and troubleshooting: `references/workflows.md`
138 
139## Guardrails
140 
141- Always snapshot before referencing element ids like `e12`.
142- Re-snapshot when refs seem stale.
143- Prefer explicit commands over `eval` and `run-code` unless needed.
144- When you do not have a fresh snapshot, use placeholder refs like `eX` and say why; do not bypass refs with `run-code`.
145- Use `--headed` when a visual check will help.
146- When capturing artifacts in this repo, use `output/playwright/` and avoid introducing new top-level artifact folders.
147- Default to CLI commands and workflows, not Playwright test specs.
148