How to use the Playwright Expert agent skill

What the Playwright Expert skill makes the agent do

Once the skill is installed, the agent acts as a Playwright testing specialist when your request matches its trigger terms, such as E2E test, browser testing, Page Object Model or test flakiness. The skill's description says it can write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking and perform visual regression testing.

The skill's written rules push the agent toward a consistent style. It prefers role-based selectors such as getByRole and getByLabel over CSS class selectors, relies on Playwright's auto-waiting instead of arbitrary timeouts, keeps tests independent of each other, and uses the Page Object Model. For debugging, it follows a workflow of running the test, checking the trace, identifying the issue, fixing it and verifying the fix.

Install the playwright-expert skill

Skills are folders of instructions that an agent loads. This skill is distributed as a ZIP file from the skill's page in this directory. Download the ZIP, then choose one of the two install routes below.

For Claude Code, unzip the folder into your personal skills directory ~/.claude/skills/, or into a project-specific .claude/skills/ folder if you want the skill to apply only to one repository. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Set up Playwright in your project first

The skill does not install Playwright for you. Its requirements are that @playwright/test is installed in your project and that you have a Node.js/TypeScript environment in which to run the generated tests. The generated output is TypeScript test code, so someone has to run and maintain it.

Install Playwright in your project using your normal workflow before asking the agent to write tests. The skill's configuration reference shows a playwright.config.ts file that sets testDir, reporters, retries, projects for browsers, and a baseURL.

Trigger the skill with natural requests

You do not need special syntax. Describe the testing task in plain language and include one of the skill's trigger terms where it fits naturally. The skill's description lists the kinds of work it covers, so requests that name those tasks are the most likely to load it.

Useful requests name the user flow, the page and the output you want. Mention the framework by name, since the guidance is specific to Playwright and will not transfer directly to Cypress or Selenium.

• Write Playwright E2E tests for the login flow, using a page object for the login page.
• Set up playwright.config.ts with trace capture on first retry and an HTML reporter.
• Debug this flaky Playwright test and explain what is causing it.
• Add API mocking for the /api/users endpoint so the users page can be tested without a backend.

Examples of what the skill produces

The skill includes a page object example for a login page. The page object defines locators such as getByLabel('Email address') and getByRole('button', { name: 'Sign in' }) in its constructor, and exposes methods such as goto() and login(). A separate spec file imports that page object and checks that a successful login redirects to /dashboard and that invalid credentials show an error.

For flaky tests, the skill's debugging example enables trace: 'on-first-retry' and screenshot: 'only-on-failure' in the config, re-runs with retries, opens the trace in the viewer, and replaces a fixed waitForTimeout call with a wait for the element's visible state. It ends by suggesting a repeat run to confirm stability.

Safety notes: scripts and network

According to the skill's listing, it does not run scripts and does not use the network. It is a set of written guidance and code examples that the agent reads. The tests it writes are code you own, so review them before running them, especially if they touch real accounts or data.

Some example code in the skill uses placeholder credentials such as <test-password>. Replace these with test accounts from your own environment, and never paste real production credentials into a prompt.

Tips for better results

Give the agent real context: the URL paths, the visible labels and the roles of the elements on the page. Role-based selectors work best when the labels exist in your markup.

Ask for the trace viewer and retries when a test is intermittent, since the skill's workflow is built around capturing a trace and then fixing the cause rather than adding delays.

Review every generated test for correct assertions. The skill's own output template asks for page objects, test files with assertions, fixture setup and configuration recommendations, so check each part.