feat: modernize agent skill for v5

.claude-plugin/marketplace.json

@@ -5,15 +5,15 @@
     "email": "github@lackeyjb"
   },
   "metadata": {
-    "description": "Playwright browser automation skill for Claude Code",
-    "version": "1.0.0"
+    "description": "Playwright browser automation skill for coding agents",
+    "version": "5.0.0"
   },
   "plugins": [
     {
       "name": "playwright-skill",
       "source": "./",
-      "description": "Claude Code Skill for general-purpose browser automation with Playwright. Claude autonomously writes and executes custom automation for testing pages, validating UX, and any browser task.",
-      "version": "4.1.0",
+      "description": "Agent Skill for general-purpose browser automation with Playwright. The agent writes and executes custom scripts for testing pages, validating UX, and automating browser tasks.",
+      "version": "5.0.0",
       "author": {
         "name": "lackeyjb"
       },

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "playwright-skill",
-  "version": "4.1.0",
-  "description": "Claude Code Skill for general-purpose browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp, and autonomously handles any browser automation task.",
+  "version": "5.0.0",
+  "description": "Agent Skill for general-purpose Playwright browser automation. Detects dev servers and helps coding agents write, execute, and preserve reusable browser scripts.",
   "author": {
     "name": "lackeyjb"
   },

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Maintainer review is required for changes to the skill and its executor.
+* @lackeyjb

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,24 @@
+name: Bug report
+description: Report a reproducible problem with the skill or executor.
+title: "bug: "
+labels: [bug]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What happened, and what did you expect?
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Include OS, Node.js, Playwright, and agent versions.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Include the smallest script or prompt that reproduces the problem.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,16 @@
+name: Feature request
+description: Suggest a focused improvement.
+title: "feat: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem and proposed solution
+      description: What problem does this solve, and how would you use it?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /skills/playwright-skill
+    schedule:
+      interval: monthly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- What changed and why? -->
+
+## Verification
+
+- [ ] `npm test` passes
+- [ ] The relevant example or smoke test passes
+- [ ] Documentation is updated when behavior changes
+
+## Checklist
+
+- [ ] This PR is focused and keeps the skill's loaded instructions concise.
+- [ ] No credentials or generated browser artifacts are included.

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    name: Validate (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [20, 22, 24]
+    defaults:
+      run:
+        working-directory: skills/playwright-skill
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: skills/playwright-skill/package-lock.json
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm test
+      - run: node skills/playwright-skill/run.js tests/smoke.js
+        working-directory: .
+      - run: npx skills-ref@0.1.5 validate .

.gitignore

@@ -1,7 +1,6 @@
 # Dependencies
 node_modules/
 .npm/
-package-lock.json
 
 # Logs
 *.log
@@ -27,6 +26,10 @@ screenshots/
 *.jpg
 *.jpeg
 
+# Keep checked-in documentation/demo images
+!docs/**/*.png
+!assets/**/*.png
+
 # Environment
 .env
 .env.local

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [5.0.0] - Unreleased
+
+### Changed
+
+- Updated the skill to the current Agent Skills frontmatter specification.
+- Updated the runtime requirement to Node.js 20+ and Playwright 1.62+.
+- Replaced the temporary-file executor with a child-process executor that preserves exit codes.
+- Added explicit inline execution with `node run.js -e` and `PW_SCRIPT_DIR` support.
+- Reduced helpers to focused browser setup, server detection, headers, cookie banners, and screenshots.
+- Modernized examples around accessible locators and web-first waiting.
+- Added CI, fixtures, unit tests, contribution templates, and Dependabot configuration.
+
+### Breaking changes
+
+- Helpers that duplicated Playwright actions, waits, extraction, authentication, and retries were removed. Use Playwright locators and assertions directly.
+- Stdin execution through `run.js` was removed; use a script file or `-e`.
+- `createContext()` no longer accepts a `mobile` option. Use Playwright device descriptors such as `devices['iPhone 15']` instead.
+- `launchBrowser()` no longer passes `--no-sandbox` unconditionally. It is only added for Chromium when running as root; pass `args: ['--no-sandbox']` explicitly in other cases.
+- An empty `PW_HEADLESS=` is now treated as unset and falls back to visible mode rather than headless.
+- `run.js` executes scripts in the caller's working directory instead of the skill directory, so relative paths resolve against the user's project.

CONTRIBUTING.md

@@ -1,135 +1,42 @@
-# Contributing to Playwright Skill
+# Contributing
 
-Thank you for considering contributing to the Playwright Skill plugin for Claude Code!
+Playwright Skill is an Agent Skill packaged as a Claude Code plugin. Focused
+bug fixes, documentation improvements, and portable examples are welcome.
 
-## How to Contribute
+## Development
 
-### Reporting Bugs
+Requirements: Node.js 20+ and npm.
 
-If you find a bug, please create an issue on GitHub with:
-- Clear description of the problem
-- Steps to reproduce
-- Expected vs actual behavior
-- Your environment (OS, Node version, Playwright version)
-- Example code that demonstrates the issue
-
-### Suggesting Enhancements
-
-Enhancement suggestions are welcome! Please:
-- Check existing issues first to avoid duplicates
-- Clearly describe the enhancement and its benefits
-- Provide examples of how it would be used
-
-### Pull Requests
-
-1. **Fork the repository**
-   ```bash
-   git clone https://github.com/lackeyjb/playwright-skill.git
-   cd playwright-skill
-   ```
-
-2. **Create a feature branch**
-   ```bash
-   git checkout -b feature/your-feature-name
-   ```
-
-3. **Make your changes**
-   - Follow the existing code style
-   - Add tests if applicable
-   - Update documentation as needed
-
-4. **Test your changes**
-   ```bash
-   npm run setup
-   # Test your changes with Claude Code
-   ```
-
-5. **Commit your changes**
-   ```bash
-   git add .
-   git commit -m "feat: add your feature description"
-   ```
-
-6. **Push to your fork**
-   ```bash
-   git push origin feature/your-feature-name
-   ```
-
-7. **Create a Pull Request**
-   - Go to the original repository
-   - Click "New Pull Request"
-   - Select your fork and branch
-   - Provide a clear description of your changes
-
-## Development Guidelines
-
-### Code Style
-
-- Use clear, descriptive variable names
-- Add comments for complex logic
-- Keep functions focused on a single responsibility
-- Follow existing patterns in the codebase
-
-### SKILL.md Guidelines
-
-- Keep examples concise (8-15 lines)
-- Always show `headless: false` by default
-- Include error handling in examples
-- Add console.log statements for visibility
-- Reference README.md for advanced topics
-
-### Commit Messages
-
-Use conventional commits format:
-- `feat:` New features
-- `fix:` Bug fixes
-- `docs:` Documentation changes
-- `refactor:` Code refactoring
-- `test:` Adding tests
-- `chore:` Maintenance tasks
-
-Examples:
-```
-feat: add mobile device emulation helper
-fix: resolve module resolution issue in run.js
-docs: update installation instructions
-```
-
-### File Structure
-
-```
-playwright-skill/
-├── SKILL.md           # Keep concise (~300 lines)
-├── README.md          # Full API reference
-├── PLUGIN_README.md   # Plugin distribution docs
-├── run.js             # Universal executor
-├── package.json       # Dependencies
-├── plugin.json        # Plugin metadata
-└── lib/
-    └── helpers.js     # Utility functions
+```bash
+cd skills/playwright-skill
+npm install
+npx playwright install chromium
+npm test
+cd ../..
+node tests/smoke.js
+npx skills-ref@0.1.5 validate skills/playwright-skill
 ```
 
-### Adding New Helpers
+Keep browser artifacts out of the repository. Use the existing fixtures for
+smoke coverage and add a focused `node:test` test for non-trivial helper logic.
 
-When adding functions to `lib/helpers.js`:
-1. Add clear JSDoc comments
-2. Include error handling
-3. Export the function
-4. Update SKILL.md to mention it
-5. Add example usage
+## Pull requests
 
-### Testing
+- Open or reference an issue when the change is contributor-facing.
+- Keep `SKILL.md` concise; put detailed material in `API_REFERENCE.md`.
+- Use accessible locators and web-first assertions in examples.
+- Update documentation when behavior or environment variables change.
+- Include the commands used to verify the change.
+- Use a conventional commit title such as `feat:`, `fix:`, `docs:`, or `test:`.
 
-Before submitting:
-1. Test with a fresh installation
-2. Verify examples in SKILL.md work
-3. Check that `run.js` handles edge cases
-4. Ensure browser opens in visible mode by default
+The v5.0.0 work is tracked in the [roadmap issue](https://github.com/lackeyjb/playwright-skill/issues/39).
 
-## Questions?
+## Reporting problems
 
-Feel free to open an issue for discussion before starting work on major changes.
+Use the issue templates and include the OS, Node.js version, Playwright
+version, agent client, reproduction, and expected behavior. Questions and tool
+comparisons belong in GitHub Discussions when enabled.
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the MIT License.
+By contributing, you agree that your contribution is licensed under MIT.