Preface¶

Having an AI “open a webpage, click buttons, fill out forms, and take a screenshot” sounds simple, but you can easily run into pitfalls in actual operation: pages are dynamically rendered by JavaScript, and element selectors will fail once changed; if an Agent lacks unified operating specifications, it can often only produce unrunable pseudocode. Scenarios such as E2E testing, UI process troubleshooting, and page data crawling all need to be executed step-by-step in a real browser, rather than “imagining” that the operation has been completed in the chat box.

OpenAI provides the playwright Skill in its Codex curated skill library, which wraps Playwright’s official playwright-cli into a reusable Agent workflow: opening pages, taking snapshots, interacting via element references, and capturing screenshots, all completed in the terminal. This article is organized based on verification of the official SKILL.md and Playwright Agent CLI documentation, introducing what it is, how to install it, and how to use it.

What it is¶

The playwright is an Agent Skill (universal SKILL.md format), sourced from the skills/.curated/playwright directory in the openai/skills repository maintained by OpenAI. The positioning of the Skill is very clear:

Use this Skill when tasks require automating a real browser in the terminal—navigation, form filling, snapshots, screenshots, data extraction, and UI process debugging—via playwright-cli or its built-in wrapper script.

It follows a different path from the @playwright/test testing framework: the official Skill defaults to CLI command-based automation, and you should not switch to Playwright Test Spec unless the user explicitly asks to write test files. This is more practical for daily scenarios like “let the Agent run through the login process” compared to “generating a set of CI test suites”.

It should be noted that the README of the openai/skills repository has been marked as deprecated, and subsequent examples may be migrated to OpenAI Plugins; however, the content and usage of the Skill in the current curated directory can still be referenced, and Playwright official also provides independent documentation for the Agent CLI.

Core Features and Highlights¶

After verifying official materials, the core capabilities of this Skill can be summarized as follows:

1. CLI-first, wrapper script eliminates global installation requirement

The Skill comes with scripts/playwright_cli.sh, which internally calls the CLI via npx --yes --package @playwright/cli playwright-cli, without forcing global installation. It is suitable for Agents to use out of the box in various projects.

2. Stable interaction model with snapshots + element references (ref)

The workflow is fixed: open the page → snapshot to get the accessibility tree and element references (such as e15) → use the ref to execute click, fill, type, etc. → re-snapshot after page changes. This is far more reliable than letting the Agent guess CSS selectors out of thin air.

3. Covers common browser automation scenarios

Commands supported by the official CLI reference documentation include: navigation (open, go-back, reload), interaction (click, fill, select, upload, drag), keyboard and mouse operations, multi-tabs (tab-new, tab-select), screenshots and PDFs, console and network logs, Trace recording, named Session isolation, etc.

4. Built-in guardrails to constrain Agent behavior

The official clearly requires: you must take a snapshot before referencing a ref like e12; re-snapshot if the ref becomes invalid; prioritize explicit commands,慎用 eval / run-code; use --headed when you need to view the page with your own eyes; it is recommended to place products in the output/playwright/ directory to avoid polluting the project root directory.

5. Naturally fits E2E/UI debugging scenarios

Playwright itself is one of the mainstream tools in the E2E testing field. This Skill directly hands the ability to “operate step-by-step in a real browser and leave evidence” to the Agent, which is suitable for quickly reproducing bugs, verifying form processes, and crawling dynamic page content—it complements other Skills such as playwright-interactive that require complete test suites or persistent sessions (the latter focuses on iterative debugging of local Web/Electron applications).

Installation and Activation¶

Agent Skills follow a universal directory structure: one folder plus a SKILL.md inside, optionally with scripts and reference documents. The scanning paths vary slightly among different AI programming tools, and the following are all verifiable official or documented methods.

Pre-dependencies: Node.js and npx¶

The Skill requires checking if npx is available before using the command (the wrapper script depends on it). If it is missing, you need to install Node.js/npm, and then optionally install the CLI globally:

# Check environment
command -v npx >/dev/null 2>&1 && echo "npx OK"

node --version
npm --version

# Optional: Install playwright-cli globally
npm install -g @playwright/cli@latest
playwright-cli --help

Installation in Codex CLI¶

According to the OpenAI official README, curated skills can be installed by name via $skill-installer within Codex, with the default path being skills/.curated:

$skill-installer playwright

You can also directly provide the GitHub directory URL:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/playwright

After installation, the Skill will be located at $CODEX_HOME/skills (default ~/.codex/skills), and you need to restart Codex to load the new Skill.

Usage in Cursor¶

Cursor will automatically discover Skills from the following locations: .cursor/skills/ within the project, user-level ~/.cursor/skills/, and is compatible with directories such as .codex/skills/ and .claude/skills/. The common practices are:

Copy the playwright directory (including SKILL.md and scripts/) to the project’s .cursor/skills/playwright/;
Or fill in the above GitHub directory URL in Cursor Customize → Rules → Add Rule → Remote Rule (Github).

The Agent will automatically determine whether to enable it based on the Skill’s description, or you can manually input /playwright in the conversation to call it.

In other tools such as Claude Code¶

Under the general Agent Skills open standard (agentskills.io), you only need to place the Skill directory in .claude/skills/playwright/ (project-level) or ~/.claude/skills/playwright/ (user-level), with the same structure as Codex.

Set wrapper script path (Codex environment)¶

The official recommends exporting the path variable once in the Shell:

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

Afterwards, use "$PWCLI" instead of directly calling playwright-cli, and you can run it without global installation.

Typical Usage Examples¶

Quick start: Open a page and interact¶

The following example comes from the official SKILL.md Quick Start:

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

Minimal interaction loop:

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

You should re-snapshot after each navigation, popup toggle, tab switching, or significant DOM change, otherwise references such as e3 may have become invalid.

Form filling and submission¶

"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "user@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot

Debug UI workflows with Trace¶

"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start
# ... Execute several interactive commands in between ...
"$PWCLI" tracing-stop

Combined with the console and network commands, you can view the console and network requests after reproducing the problem.

Multi-tabs and Session isolation¶

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

When handling different tasks in parallel, you can use named sessions:

"$PWCLI" --session todo open https://demo.playwright.dev/todomvc
"$PWCLI" --session todo snapshot

Or omit the --session parameter after setting the environment variable export PLAYWRIGHT_CLI_SESSION=todo.

Prompt words in Agent conversations¶

The sample prompt given in the Playwright official Agent CLI documentation:

Use playwright skills to test https://demo.playwright.dev/todomvc/.
Take screenshots for all successful and failing scenarios.

Write down the specific URL and expected products (screenshots, extracted fields, verification steps) clearly, and the Agent will execute according to the CLI workflow in the Skill, instead of generating @playwright/test test files by default.

Optional configuration file¶

The CLI reads playwright-cli.json in the current directory by default, and you can also specify it with --config. The minimal example is as follows:

{
  "browser": {
    "launchOptions": {
      "headless": false
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  }
}

Applicable Scenarios and Notes¶

Who it is suitable for, and what scenarios:

Need the Agent to actually operate the browser in the terminal, rather than just outputting Selenium/Playwright code snippets;
Quickly verify whether UI processes such as login, ordering, and search are smooth;
Perform structured snapshots and text extraction on JavaScript-rendered pages;
Exploratory automation in the early stage of E2E testing—run through the CLI first, then upgrade to a formal test project as needed;
Integrate browser steps as a command sequence in CI or local scripts.

Limitations and notes:

Depends on Node.js environment: The wrapper cannot work without npx, and the Skill will require you to install Node.js/npm first.
Refs are time-sensitive: Clicking without taking a snapshot has a high failure rate; this is by design, not a CLI bug.
Does not generate test Spec by default: If the goal is a regression-ready test suite, you should explicitly tell the Agent to use @playwright/test, or cooperate with other test-oriented Skills.
Product directory: The Skill recommends writing screenshots, Traces, etc. to output/playwright/ to avoid scattered files in the repository.
Repository status: openai/skills has been deprecated, you can pay attention to the updates of OpenAI Plugins and developers.openai.com/codex/skills in the long term; the Skill itself can still be manually imported as a reference implementation for tools such as Cursor and Claude Code.

Summary¶

The playwright Skill固化 the best practices of the Playwright Agent CLI into an executable instruction set for Agents: take a snapshot first, then interact via refs, re-snapshot after changes, and take screenshots or record Traces when needed. For developers, the value lies in letting AI programming assistants actually “operate” the browser, rather than staying at the code suggestion level.

Official repository: https://github.com/openai/skills/tree/main/skills/.curated/playwright
Playwright Agent CLI documentation: https://playwright.dev/agent-cli/quick-start

Drive Real Browsers via Terminal: Getting Started with OpenAI's Official Playwright Skill