playwright-skill: a code-first Agent Skill for browser automation
General-purpose Playwright automation for coding agents
At a glance
- What is it?
- This MIT-licensed Agent Skill hands Playwright code generation to the coding agent, then runs the generated script through a single executor. It is the right shape when the script itself is the deliverable, and the wrong shape when you want a persistent test suite or tool-mediated browsing.
- Who is it for?
- Adopt playwright-skill if your agent needs to produce a Playwright program you can keep and rerun, and you accept that the agent writes the test logic rather than a framework. Do not adopt it if you need a durable CI suite with retries, reporters and sharding, or if you only want tool-mediated browsing with accessibility snapshots.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 32 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap between prompting an agent and shipping a Playwright script
A coding agent can describe a browser flow in prose, but prose is not runnable. The usual workaround is to paste a snippet into a file, fix the import paths by hand, and run it. playwright-skill removes that loop by giving the agent a documented place to write code and a single entry point to execute it. The README frames the scope as writing a real Playwright program: loops, assertions, multiple contexts, network interception, screenshots, video, or a script you want to keep and rerun. That list is the boundary. Simple interactive browsing is explicitly delegated to Microsoft's @playwright/cli and playwright-mcp, so the project is not trying to be a general browser remote control. The intended user is someone whose agent already works in a repository and who wants the automation artifact to survive the session. It is packaged both as a standard Agent Skill and as a Claude Code Plugin, which matters for distribution: the plugin wrapper gives automatic updates and team installation, while the raw skill folder can be dropped into any client that supports the SKILL.md convention.
What run.js actually does, and why module resolution is the hard part
The executor is the load-bearing component. According to the README, the universal executor run.js runs file and inline scripts with proper module resolution. That phrasing points at a real failure mode in agent-generated code: the agent writes a script into a temporary path, and a naive Node invocation resolves node_modules relative to that path rather than relative to the installed skill. The result is a module-not-found error that the agent then tries to fix by editing imports, which is wasted effort. By centralizing execution in run.js, the skill keeps resolution anchored to the installed skill directory no matter where the generated script is written. The README also lists safe cleanup, described as smart temp file management without race conditions, alongside a set of optional helper functions in lib/helpers.js. The helpers are explicitly optional, so a generated script can ignore them entirely. Progressive disclosure is the other architectural choice: SKILL.md is kept concise and API_REFERENCE.md is loaded only when needed, so the agent does not pay the context cost of the full Playwright API on every task. The default is headless: false, meaning the browser opens visibly unless the user asks otherwise. For debugging that is useful; in a headless CI container it is a setting you have to override deliberately.
Installing the skill and running setup
The recommended path is Vercel's skills CLI. A global install for the current user is `npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes`, and dropping --global scopes it to the current project. To target particular agents, pass --agent followed by one or more IDs, for example `npx skills add lackeyjb/playwright-skill --skill playwright-skill --agent claude-code cursor --global --yes`. After any install method, setup runs from inside the installed skill directory with `npm run setup`. The Claude Code plugin route uses three commands: `/plugin marketplace add lackeyjb/playwright-skill`, then `/plugin install playwright-skill@playwright-skill`, then `cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill && npm run setup`. For clients without an installer, the README says to copy only the skills/playwright-skill/ folder into the client's documented skill directory, for example `~/.claude/skills/playwright-skill` globally or `/path/to/your/project/.claude/skills/playwright-skill` per project, and run `npm run setup` there. Verification is `/help` to confirm the skill is loaded, followed by a trivial browser task. Note the nested layout: the repository root is the plugin, and the skill lives one level down, which is why manual copy instructions name the inner folder rather than the repository root.
Configuration keys and the artifact directory question
The configuration surface is small and documented in three keys. Headless defaults to false, so the browser is visible unless the task requests otherwise. Slow motion defaults to 0ms, with SLOW_MO set when useful, which is an environment variable rather than a config file entry. Screenshots taken by the helpers default to the OS temp directory, and PW_ARTIFACT_DIR overrides that location. The artifact directory is the setting most likely to bite in practice. A temp directory is fine for a one-off run, but if you want screenshots and video to land somewhere you can inspect after the agent finishes, you have to set PW_ARTIFACT_DIR before the run. The README does not document a precedence order between SLOW_MO and PW_ARTIFACT_DIR and any per-task configuration the agent might pass, so treat the environment as the source of truth and set both explicitly. There is also no documented config file format for the skill; the three settings are described as defaults, not as a schema you edit.
Where the code-first approach breaks down
The README's own comparison is the clearest statement of limits. For straightforward interactive browsing it points at @playwright/cli, and for tool-based browser control with accessibility snapshots it points at playwright-mcp. That is not marketing modesty; it reflects a real difference. playwright-mcp exposes browser actions as tools the model calls one at a time, which keeps the model grounded in the actual page state between steps. playwright-skill instead has the agent author an entire script up front. If the agent's mental model of the page is wrong, the script fails partway through, and the recovery loop is edit-and-rerun rather than observe-and-adjust. The visible-by-default browser setting softens this, since a human watching the run can see where it diverged, but that assumes someone is watching. A second limitation is durability. Nothing in the supplied material describes test retries, reporters, parallel sharding, or a CI integration. The generated script is a script, not a test framework project. Teams that need those features are looking at a different tool, and the README does not claim otherwise. A third constraint is environmental: the skill assumes Node and npm are available, since setup is an npm script, and it assumes the client supports the Agent Skill convention.
How it differs from Microsoft's Playwright agent tooling
The three options in the README's comparison split along one axis: what the useful artifact is. @playwright/cli is for interactive browsing sessions, and it ships its own agent skills installed with `playwright-cli install --skills`. playwright-mcp exposes browser control as tools, returning accessibility snapshots so the model reasons over a structured view of the page rather than raw DOM. playwright-skill produces source code. That difference determines debugging style, cost profile and reuse. Tool-mediated control spends a model turn per action and keeps the model synchronized with the page, which suits exploratory tasks where the path is unknown. Code generation spends one authoring pass and then runs natively at full speed, which suits flows you already understand and want to repeat. The reuse property is the strongest argument for this project: a script written by the agent can be committed, reviewed and rerun without the agent in the loop. The corresponding weakness is that the script encodes the agent's assumptions, so a page change breaks it silently rather than producing a fresh observation.
Licence, releases and the cost of keeping it current
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, but it says nothing about the Playwright dependency itself, which is installed separately by `npm run setup` and carries its own licence terms. Anyone redistributing the skill inside a product should check the dependency tree rather than assuming the MIT header covers everything. On maintenance, the release history shows v4.0.2 in October 2025, v4.1.0 in December 2025, and v5.0.0 in August 2026, with the last push to main on the same day as the v5.0.0 tag. The v4.0.2 release is labelled a path resolution fix, which is consistent with the executor being the part most exposed to environment differences. Since the skill's behaviour depends on the agent client loading SKILL.md correctly and on run.js resolving modules, a major version bump is the point to re-read SKILL.md rather than assume the install still behaves the same. Pinning to a tag and re-running `npm run setup` after an upgrade is the concrete check.
Editorial conclusion
Adopt playwright-skill if your agent needs to produce a Playwright program you can keep and rerun, and you accept that the agent writes the test logic rather than a framework. Do not adopt it if you need a durable CI suite with retries, reporters and sharding, or if you only want tool-mediated browsing with accessibility snapshots. Before relying on it, verify that `npm run setup` completes in the installed skill directory, confirm which directory PW_ARTIFACT_DIR resolves to on your machine, and check whether the agent loads API_REFERENCE.md on the first task or only after a failed attempt.
Community notes