Playwright Agent Skills

Playwright test patterns that avoid the mistakes agents make by default.

Playwright Agent Skills is a small, opinionated set of reusable prompts for writing and reviewing Playwright tests. Each skill stays focused on one job so agents can apply the right standard without loading unrelated guidance.

Before / After

Left unguided, agents tend to reach for brittle selectors and hard waits. playwright-core steers them toward the pattern Playwright's own docs recommend.

Before

test('user can log in', async ({ page }) => {
  await page.goto('/login');
  await page.click('.btn-login-submit');
  await page.waitForTimeout(2000);
  expect(await page.locator('.welcome-msg').textContent()).toContain('Welcome');
});

After

test('shows a welcome message after login', async ({ page }) => {
  await page.goto('/login');
  await page.getByRole('button', { name: 'Log in' }).click();
  await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
});

Role-based locator instead of a CSS class, no hard wait, and an auto-retrying assertion instead of manual timing.

Why not a general browser automation skill?

Most Playwright skills optimize for one-off checks: write a disposable script, run it, get a screenshot, done. They're built to answer "does this page look right" once — not to produce code that belongs in your repo, so they lean on page.waitForTimeout and raw CSS selectors without cost.

Playwright Agent Skills assumes the opposite: every pattern here is meant to be committed and run in CI. Locators are accessible-first, waits are assertion-driven, and structure follows what a Playwright maintainer would sign off on — because it's not a one-off script, it's your test suite.

Install

Works with any agent supported by the Agent Skills CLI — GitHub Copilot, Codex, Cline, Gemini CLI, and 70+ more.

npx skills add hzijad/playwright-agent-skills

After installation, point agents at the skill that matches the task. The docs inside each skill explain the recommended patterns and the cases where they should not be used.

Skills

• playwright-core: everyday Playwright authoring and review. Focuses on accessible locators, web-first assertions, isolation, and readable test structure.
• playwright-auth-state: starting tests from a known authenticated session with storageState and setup projects.
• playwright-network-mocking: replacing unstable third-party responses with deterministic page.route() mocks.
• playwright-debugging: diagnosing and repairing flaky or failing tests with traces, repeat runs, and state isolation.

When To Use

Use playwright-core for normal test authoring and review. Use playwright-auth-state when a test should begin logged in. Use playwright-network-mocking when external services should be controlled from the test. Use playwright-debugging when a test is already failing or flaky and the failure needs to be understood first.

Structure

skills/
	playwright-core/
	playwright-auth-state/
	playwright-network-mocking/
	playwright-debugging/

Keep the skills narrow. If a new topic does not fit one of the existing folders, add a new skill instead of broadening an existing one.

License

MIT — see LICENSE.