playwright-skill

Claude autonomously detects browser automation needs and generates custom Playwright code without explicit user commands, using a model-invoked pattern where the skill is registered as a claude-skill type in plugin metadata. The skill provides SKILL.md instructions (314 lines) that guide Claude's code generation patterns, enabling task-specific script creation rather than template-based execution. Claude reads progressive documentation and generates complete, executable Playwright automation scripts tailored to each specific testing or validation scenario.

The run.js executor handles dynamic path resolution using $SKILL_DIR environment variable substitution, ensuring Playwright and helper modules are correctly resolved regardless of installation location (plugin directory, standalone skill, or nested structure). The executor normalizes paths at runtime and manages module loading through Node.js require() with proper context isolation, eliminating module resolution errors that typically occur when skills are installed in different directory structures or nested plugin hierarchies.

Provides patterns and helpers for Claude-generated code to automate authentication flows including login forms, multi-factor authentication, OAuth flows, and session management. The skill documents authentication patterns in SKILL.md and provides helpers for common scenarios like filling login forms, handling redirects, and managing authentication state. Claude can generate code that handles complex authentication workflows without hardcoding credentials in scripts.

Enables Claude-generated code to intercept network requests and responses, mock API endpoints, and validate API behavior through Playwright's network interception capabilities. The skill provides patterns for inspecting request/response headers, mocking API responses, and testing error scenarios without relying on real backend services. Claude can generate code that validates frontend behavior against different API responses and error conditions.

Provides documentation and patterns for Claude-generated code to implement the Page Object Model (POM) pattern, where page interactions are encapsulated in reusable page objects rather than scattered throughout test code. The skill documents POM patterns in SKILL.md, enabling Claude to generate well-structured, maintainable automation code that separates page structure from test logic. This pattern improves code reusability and makes tests more resilient to UI changes.

Supports integration with CI/CD pipelines through environment variable configuration and headless mode support for server environments. The skill can detect CI/CD environment variables and adjust execution mode (headless vs visible), timeout settings, and retry behavior accordingly. Claude-generated code can be configured to run in CI/CD environments without modification by using environment-aware configuration patterns documented in SKILL.md.

Provides a lib/helpers.js library of reusable utility functions that Claude-generated code can import and use, including common patterns for page navigation, element interaction, form filling, screenshot capture, and network interception. These helpers abstract away boilerplate Playwright code and provide consistent patterns for authentication flows, responsive testing, and visual validation, reducing the amount of code Claude needs to generate while improving consistency and reliability of generated automation scripts.

Implements automatic scanning of common development server ports (3000, 5173, 8080, etc.) to detect and target local applications without requiring explicit URL configuration. The skill detects running dev servers at startup and provides Claude with available targets, enabling automation against locally-running applications without users needing to specify ports or URLs. This pattern is documented in SKILL.md and integrated into the executor's initialization logic.

Configures Playwright to run with headless: false by default, displaying the browser window during automation execution for real-time observation and debugging. This default configuration is set in SKILL.md instructions and allows developers to watch automation progress, see failures as they occur, and debug issues visually rather than relying solely on logs. The visible browser mode enables interactive debugging where developers can pause execution and inspect page state.

Implements a two-tier documentation system where SKILL.md (314 lines) provides concise instructions for Claude to understand basic automation patterns, while a comprehensive API reference (630 lines) is loaded on-demand when Claude needs detailed information. This progressive disclosure pattern reduces token usage and context overhead by providing only essential information upfront, with detailed API documentation available when Claude requests it. The documentation is structured to guide Claude's code generation while remaining accessible for human developers.

Executes Claude-generated Playwright code as artifacts through the run.js executor, providing isolated execution context where generated code runs in a separate Node.js process with proper module scope and error handling. The executor captures stdout/stderr, handles execution errors gracefully, and returns results back to Claude, enabling a feedback loop where Claude can see execution results and iterate on generated code. This artifact execution pattern prevents generated code from interfering with the skill's own runtime.

Distributes the skill as a Claude Code Plugin with metadata in .claude-plugin/plugin.json and .claude-plugin/marketplace.json, supporting both plugin installation (nested structure) and standalone skill installation. The plugin metadata registers the skill as a claude-skill type, enabling automatic discovery and invocation by Claude Code. The nested structure allows the skill to be distributed as a plugin while maintaining compatibility with standalone skill installations.

Enables Claude-generated code to capture screenshots at various points in automation execution and perform visual testing through Playwright's screenshot API. The skill provides helpers and patterns for capturing full-page screenshots, element-specific screenshots, and visual regression testing by comparing screenshots across test runs. This capability allows validation of UI rendering, responsive design, and visual consistency without relying solely on DOM assertions.

Enables Claude-generated code to test responsive design and mobile layouts by configuring Playwright's viewport settings and device emulation. The skill provides patterns for testing multiple viewport sizes, mobile device emulation (iPhone, Android), and responsive behavior validation. Claude can generate code that tests the same automation flow across different viewport configurations to validate responsive design without manual multi-device testing.