# lackeyjb/playwright-skill: Playwright Automation for Coding Agents

> An Agent Skill that lets a coding agent write and run real Playwright programs instead of clicking through a fixed tool API. It is the code-first option, and the trade-off is that the browser work lands in your repository as a script you own.

**lackeyjb/playwright-skill** — General-purpose Playwright automation for coding agents

- Repository: https://github.com/lackeyjb/playwright-skill
- Stars: 3,162 · Forks: 244
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/lackeyjb-playwright-skill

## What lackeyjb/playwright-skill actually solves

Most browser automation for agents is tool-shaped. The agent calls a fixed set of verbs (navigate, click, snapshot) and the harness decides what those verbs can express. lackeyjb/playwright-skill takes the opposite position. The agent writes a Playwright program for the task at hand, and the skill supplies the executor, the API reference and a small helper library so that program runs with working module resolution.

The README frames the boundary clearly. Use it when the agent needs "a real Playwright program: loops, assertions, multiple contexts, network interception, screenshots, video, or a script you want to keep and rerun." That last clause is the honest one. The artifact is code, and code is something you can commit, review and run in CI. If you never intend to keep the script, the skill is heavier than the problem.

Who it is for: engineers who already have a coding agent in the loop and want the browser work to end up as a file in the repository rather than as a transcript of tool calls. The topics list on the repository points at the same audience (agent-skills, coding-agents, playwright-automation, e2e-testing-tools). It assumes you are comfortable reading JavaScript and debugging a failing assertion, because that is what you will be doing when something breaks.

## The executor, the SKILL.md and progressive disclosure

The mechanism is deliberately small. A skill directory holds SKILL.md, which the agent reads first, plus run.js, package.json, lib/helpers.js and API_REFERENCE.md. The README describes run.js as a "universal executor" that "runs it with proper module resolution" and handles both file and inline scripts. The point of a dedicated executor is that generated code often lands in a temporary path where a bare require('playwright') would not resolve; run.js exists to make that path work.

Progressive disclosure is the second half. SKILL.md stays concise and API_REFERENCE.md is loaded only when the task needs it. That is a real design decision with a real cost: the agent's first pass sees less of the Playwright surface, so it may reach for a pattern that the reference would have replaced with something better. The README's own claim is that Claude "autonomously decides when to use this skill" and loads "only the minimal information required."

Cleanup is the third piece. The README promises "safe cleanup" with "smart temp file management without race conditions," and notes that helper screenshots go to the OS temp directory unless you set PW_ARTIFACT_DIR. That environment variable is the only documented way to redirect artifacts, which matters if your test runner expects screenshots in a known folder.

One structural detail is easy to miss. The repository is a plugin root with the skill nested inside skills/playwright-skill/. The README says installers handle that layout automatically and that manual copying is a fallback for clients without an installer. If you copy the wrong directory level, the client will not find SKILL.md.

## Installing it and running a first browser task

The README recommends Vercel's skills CLI. This installs the skill globally for your user:

```bash
npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes
```

Drop --global to install only for the current project. To target specific agents, add --agent followed by one or more agent IDs, for example:

```bash
npx skills add lackeyjb/playwright-skill --skill playwright-skill --agent claude-code cursor --global --yes
```

After installation, run setup from the installed skill directory. The README does not print the path for the CLI route, only the command:

```bash
npm run setup
```

If you prefer Claude Code's plugin system, the README gives a marketplace-based route that also installs dependencies:

```bash
/plugin marketplace add lackeyjb/playwright-skill
/plugin install playwright-skill@playwright-skill
cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
npm run setup
```

Verify the install by running /help and confirming the skill is listed. Then ask the agent for a trivial task, exactly as the README suggests: "Test if google.com loads." What you should see is a browser window, because headless defaults to false, plus console output and screenshots when the run finishes. If no window appears, the agent has overridden the default or setup did not complete.

For clients with no installer, the README's fallback is to copy skills/playwright-skill/ into the client's documented skill directory (globally ~/.claude/skills/playwright-skill, or .claude/skills/playwright-skill inside a project) and run npm run setup there. The release-download route follows the same copy-then-setup pattern.

## Where the skill is the wrong tool

The README is unusually direct about this, and it deserves credit for it. For "straightforward interactive browsing," it tells you to start with Microsoft's official @playwright/cli and install its agent skills with playwright-cli install --skills. For tool-based browser control with accessibility snapshots, it points at playwright-mcp. The project positions itself as "the code-first option when the automation itself is the useful artifact."

That is a genuine architectural difference, not a marketing line. A tool-based integration keeps the agent inside a fixed verb set and returns structured snapshots; the model never writes a program, so there is no script to review and nothing to break at the module-resolution layer. This skill inverts that. You get arbitrary Playwright, and you also get arbitrary Playwright's failure modes: a generated selector that drifts, a missing await, a run that leaves a browser process behind.

The execution model is the second limitation. The README documents run.js as handling module resolution but does not document its resolution order, what it does on failure, or how it behaves when two runs overlap. Temp file cleanup is described as race-free, but the README does not explain the mechanism, so you cannot reason about it from the documentation alone.

Third, visibility is the default. headless: false means a real browser window opens unless the agent is told otherwise. That is excellent for watching a flow and wrong for a headless CI box. SLOW_MO defaults to 0ms and is described as something to set "when useful," but the README does not list accepted values or units, so treat it as an experiment rather than a documented knob. Finally, the plugin packaging is Claude Code specific; the skill format is broader, but automatic updates and team distribution are described only for that plugin route.

## How it compares with playwright-mcp and @playwright/cli

The comparison is about where the intelligence sits. With playwright-mcp, the server exposes browser actions as tools and returns accessibility snapshots; the model chooses among those tools and never authors a file. With @playwright/cli, the interaction is command-driven and the README recommends it as the starting point for plain interactive browsing. In both cases the unit of work is a call.

In lackeyjb/playwright-skill the unit of work is a program. That changes what you can express. Multi-step flows with branching, assertions that fail the run, several browser contexts in one script, network interception and video capture are all ordinary Playwright features that a fixed verb set has to model explicitly and this approach gets for free. It also changes what you maintain: a script that lives somewhere, needs a browser binary, and will be read by whoever debugs it next.

There is a cost to the code-first route that the README does not spell out. Generated code is only as good as the model's knowledge of the Playwright API at that moment, which is why API_REFERENCE.md exists and why it is loaded on demand. A tool-based integration cannot write a subtly wrong selector chain, because it does not write selectors at all. If your team's tolerance for reviewing generated automation code is low, the tool route is the safer default and the README says so.

## Maintenance, packaging and the MIT licence

The repository is not archived, and the last push was on 2026-08-14. Release v5.0.0 is dated 2026-08-11, following v4.1.0 on 2025-12-02 and v4.0.2 on 2025-10-21. The gap between v4.1.0 and v5.0.0 is roughly eight months, with a major version bump at the end of it. That pattern suggests a project that moves in larger steps rather than continuous small releases, so pin a version if you depend on it.

The upgrade surface is the skill directory itself: SKILL.md, run.js, package.json, lib/helpers.js and API_REFERENCE.md. Because the agent reads SKILL.md and the API reference at runtime, an upgrade can change agent behaviour without changing any code you wrote. That is the unusual part. There is no lockfile protecting you from a rewritten instruction file.

Licensing is MIT, which is permissive and places few obligations on how you redistribute or embed the skill. The README does not discuss third-party licence terms for Playwright itself, and this is not legal advice; check the licences of the dependencies your setup pulls in if you ship the result commercially.

Operationally, the two environment variables the README names are PW_ARTIFACT_DIR for screenshot location and SLOW_MO for pacing. Neither is documented with a full list of accepted values, so verify behaviour in your own environment before wiring them into a pipeline.

## Conclusion

Adopt it when the automation script itself is the deliverable: a flow you want to keep, rerun and edit, with loops, assertions, multiple contexts or network interception. Skip it when you only need a browser driver for a single interactive session, because the README points that case at Microsoft's @playwright/cli or playwright-mcp instead. Before trusting it, verify three things yourself: that npm run setup completed in the installed skill directory, that your client's skill path matches the nested skills/playwright-skill layout, and that you are comfortable with the executor resolving modules for you, since the README does not document how run.js resolves them or what happens when it fails.

## FAQ

### What is lackeyjb/playwright-skill used for?

It is an Agent Skill that lets a coding agent write and execute Playwright automation for a specific request, from simple page tests to multi-step flows. The README says to use it when the agent needs a real Playwright program with loops, assertions, multiple contexts, network interception, screenshots or video.

### How do I install lackeyjb/playwright-skill?

The README recommends Vercel's skills CLI: npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes. Afterwards you run npm run setup from the installed skill directory. A Claude Code plugin route using /plugin marketplace add and /plugin install is also documented.

### How do I use lackeyjb/playwright-skill after installing it?

Ask your agent to test or automate a browser task. The README's flow is: describe the task, the agent writes custom Playwright code, run.js executes it with proper module resolution, the browser opens visibly by default, and results come back with console output and screenshots.

### Should I use lackeyjb/playwright-skill or playwright-mcp?

The README recommends playwright-mcp for tool-based browser control with accessibility snapshots, and @playwright/cli for straightforward interactive browsing. It describes this project as the code-first option when the automation itself is the useful artifact, meaning a script you keep and rerun.

### Does lackeyjb/playwright-skill work with Codex or Cursor?

Agent Skills are described as supported by Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, OpenCode and other clients. The README shows targeting agents with --agent, for example --agent claude-code cursor, and for clients without an installer it says to copy skills/playwright-skill/ into the documented skill directory and run npm run setup there.

## Sources

- [Issues](https://github.com/lackeyjb/playwright-skill/issues)
- [lackeyjb/playwright-skill on GitHub](https://github.com/lackeyjb/playwright-skill)
- [License: MIT](https://github.com/lackeyjb/playwright-skill/blob/main/LICENSE)
- [README](https://github.com/lackeyjb/playwright-skill/blob/main/README.md)
- [Releases](https://github.com/lackeyjb/playwright-skill/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lackeyjb-playwright-skill