How to use the Migrate to Playwright agent skill

What the migrate skill makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions the agent loads when a task matches. The migrate skill is named "migrate" and is described as an interactive migration from Cypress or Selenium to Playwright, done file by file.

The agent first detects which framework your project uses by looking for a cypress/ directory or cypress.config.ts, or for selenium or webdriver in package.json dependencies, or for Python test files that import selenium. It then counts the test files and classifies the migration as small, medium or large, which decides whether it converts files one at a time, in batches, or with /batch.

For each file it applies translation tables from the bundled cypress-mapping.md and selenium-mapping.md files. For example, cy.visit(url) becomes page.goto(url), and cy.intercept() becomes page.route(). It also upgrades selectors toward getByRole, getByTestId and getByText where possible, and converts Cypress custom commands into Playwright fixtures using test.extend().

Install the migrate skill

Download the ZIP for the migrate skill from this page and unzip it. Then place the folder in one of these locations:

Personal skills folder: ~/.claude/skills/ (available across your projects).

Project skills folder: .claude/skills/ inside your project (shared with anyone who works on that repository).

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills

Prepare your project before you start

The skill needs Node.js and npm, because verification runs npx playwright test. It also expects Playwright to be installed. If Playwright is not set up yet, the skill runs the companion /pw:pw-init command first. Your input must be an existing Cypress or Selenium test project; if there are no such tests, there is nothing to convert.

Commit or back up your work before starting, so you can compare or revert the changes.

• Node.js and npm installed
• Playwright installed, or set up with /pw:pw-init
• An existing Cypress or Selenium test project

Trigger the skill with natural requests

You do not need a special command. The skill's description lists trigger phrases, so ask in plain language that mentions your source framework or the goal. Phrases from the skill description include "migrate tests", "convert tests", "switch to playwright", "move from cypress" and "replace selenium".

The skill also accepts an argument. Its input can be "from cypress", "from selenium", a path to a specific test file, or nothing, in which case the agent auto-detects the framework.

• "Migrate our tests from Cypress to Playwright"
• "Convert the Selenium tests in this repo to Playwright"
• "Move from cypress to playwright, start with the login tests"
• "Replace selenium in this project with Playwright"

Review the conversion as it runs

After converting each file, the agent runs the converted file with npx playwright test and the list reporter, and fixes compilation or runtime errors before moving on. Keep an eye on each step rather than letting a large suite run unattended, because automated conversion can silently change what a test means and some tests will need manual rework.

At the end the skill reports the files converted, the total tests migrated, any tests it could not convert automatically, the updated CI config, and a before-and-after comparison of test results.

• Check that assertions still check the same behaviour, not just that the test passes.
• Review any tests listed as needing manual intervention.
• Confirm the converted tests run against your real environment.

Safety notes: scripts and cleanup

This skill runs scripts, according to its listing, and it does not use the network. Its verification step executes Playwright tests in your project. The cleanup step removes Cypress or Selenium dependencies from package.json, deletes old config files such as cypress.config.ts, and updates CI and README files. The skill is written to ask before deleting anything, so read each proposed deletion.

Because cleanup removes the old tooling, do not use this skill if you need Cypress or Selenium to keep running in parallel during the migration.

• Runs scripts: yes. Uses network: no.
• Cleanup removes old dependencies and config files, but asks first.
• Keep a commit or backup so you can revert.

Tips for a smooth migration

Start with a small slice, such as one folder or one test file, to see the output style before converting the whole suite. The skill's size rules convert small suites sequentially, medium suites in batches of five with sub-agents, and large suites with /batch.

Use the locator upgrades as a chance to remove brittle selectors. The mapping prefers getByRole() and getByTestId() over CSS ids and XPath, and XPath is generally avoided.

• Migrate one file or feature first, then expand.
• Expect some tests to need manual work, especially those relying on Cypress-specific behaviour.
• Use the locator upgrades to replace brittle CSS and XPath selectors.