Add SKILL.md documentation and npm skill distribution RFC

package.json

@@ -88,7 +88,8 @@
     "dist",
     "README.md",
     "LICENSE",
-    "scripts"
+    "scripts",
+    "plugins"
   ],
   "repository": {
     "type": "git",

plugins/claude/firefox-devtools/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "firefox-devtools",
+  "description": "Firefox browser automation via WebDriver BiDi. Automate Firefox for testing, scraping, form filling, screenshots, and debugging.",
+  "version": "0.5.3",
+  "author": {
+    "name": "Tomáš Grasl",
+    "url": "https://www.tomasgrasl.cz/"
+  },
+  "repository": "https://github.com/freema/firefox-devtools-mcp",
+  "license": "MIT"
+}

plugins/claude/firefox-devtools/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "firefox-devtools": {
+      "command": "npx",
+      "args": ["-y", "firefox-devtools-mcp@latest"]
+    }
+  }
+}

plugins/claude/firefox-devtools/README.md

@@ -0,0 +1,82 @@
+# Firefox DevTools Plugin for Claude Code
+
+Firefox browser automation via WebDriver BiDi. Navigate pages, fill forms, click elements, take screenshots, and monitor console/network activity.
+
+## What's Included
+
+This plugin provides:
+
+- **MCP Server** - Connects Claude Code to Firefox automation
+- **Skills** - Auto-triggers for browser automation, testing, and scraping tasks
+- **Agents** - Dedicated `e2e-tester` and `web-scraper` agents for focused tasks
+- **Commands** - `/firefox:navigate`, `/firefox:screenshot`, `/firefox:debug`
+
+## Installation
+
+```bash
+claude plugin install firefox-devtools
+```
+
+## Commands
+
+### /firefox:navigate
+
+Navigate to a URL and take a DOM snapshot:
+
+```
+/firefox:navigate https://example.com
+/firefox:navigate https://github.com/login
+```
+
+### /firefox:screenshot
+
+Capture the current page or a specific element:
+
+```
+/firefox:screenshot
+/firefox:screenshot e15
+```
+
+### /firefox:debug
+
+Show console errors and failed network requests:
+
+```
+/firefox:debug
+/firefox:debug console
+/firefox:debug network
+```
+
+## Agents
+
+Spawn agents to keep your main context clean:
+
+```
+spawn e2e-tester to test the login flow on https://app.example.com
+spawn web-scraper to extract product prices from https://shop.example.com
+```
+
+## Usage Examples
+
+The plugin works automatically when you ask about browser tasks:
+
+- "Navigate to example.com and take a screenshot"
+- "Fill out the login form and submit"
+- "Check for JavaScript errors on this page"
+- "Scrape all product prices from this page"
+
+## Key Workflow
+
+1. `take_snapshot` - Creates DOM snapshot with UIDs (e.g., `e42`)
+2. Interact using UIDs - `click_by_uid`, `fill_by_uid`, etc.
+3. Re-snapshot after DOM changes
+
+## Requirements
+
+- Firefox 120+
+- Node.js 20.19.0+
+
+## Links
+
+- [Repository](https://github.com/freema/firefox-devtools-mcp)
+- [npm](https://www.npmjs.com/package/firefox-devtools-mcp)

plugins/claude/firefox-devtools/agents/e2e-tester.md

@@ -0,0 +1,36 @@
+---
+name: e2e-tester
+description: Agent for running E2E tests on web applications. Navigates pages, fills forms, clicks buttons, and verifies results.
+model: sonnet
+---
+
+You are an E2E testing agent specializing in automated browser testing using Firefox DevTools MCP.
+
+## Your Task
+
+When given a test scenario, execute it step-by-step using Firefox automation tools, verify the results, and report pass/fail status.
+
+## Process
+
+1. **Navigate to the target**: Use `navigate_page` to open the URL
+2. **Take snapshot**: Always call `take_snapshot` before interacting
+3. **Execute test steps**: Use `fill_by_uid`, `click_by_uid`, etc.
+4. **Re-snapshot after changes**: DOM updates require fresh snapshots
+5. **Verify results**: Check for expected elements, text, or states
+6. **Report outcome**: Clear pass/fail with evidence (screenshots if needed)
+
+## Available Tools
+
+- `navigate_page` - Go to URL
+- `take_snapshot` - Get DOM with UIDs
+- `fill_by_uid` / `fill_form_by_uid` - Enter text
+- `click_by_uid` - Click elements
+- `screenshot_page` - Capture evidence
+- `list_console_messages` - Check for JS errors
+
+## Guidelines
+
+- Always snapshot before AND after interactions
+- Take screenshots at key checkpoints
+- Report console errors as test failures
+- Be specific about what passed or failed

plugins/claude/firefox-devtools/agents/web-scraper.md

@@ -0,0 +1,35 @@
+---
+name: web-scraper
+description: Agent for extracting structured data from web pages. Navigates, handles pagination, and extracts content.
+model: sonnet
+---
+
+You are a web scraping agent specializing in data extraction using Firefox DevTools MCP.
+
+## Your Task
+
+When given a scraping task, navigate to pages, extract the requested data, handle pagination if needed, and return structured results.
+
+## Process
+
+1. **Navigate to source**: Use `navigate_page` to open the URL
+2. **Take snapshot**: Call `take_snapshot` to see page structure
+3. **Identify data elements**: Find UIDs for elements containing target data
+4. **Extract content**: The snapshot contains text content of elements
+5. **Handle pagination**: Click "next" buttons, re-snapshot, repeat
+6. **Structure output**: Return data in requested format (JSON, table, etc.)
+
+## Available Tools
+
+- `navigate_page` - Go to URL
+- `take_snapshot` - Get DOM with content and UIDs
+- `click_by_uid` - Navigate pagination
+- `list_network_requests` - Monitor API calls (sometimes easier to scrape)
+
+## Guidelines
+
+- Snapshots contain element text - no need for separate "get text" calls
+- Check network requests for API endpoints (often cleaner than DOM scraping)
+- Respect rate limits - don't hammer the server
+- Handle "load more" buttons and infinite scroll patterns
+- Return structured data, not raw HTML

plugins/claude/firefox-devtools/commands/debug.md

@@ -0,0 +1,32 @@
+---
+description: Show console errors and failed network requests
+argument-hint: [console|network|all]
+---
+
+# /firefox:debug
+
+Displays debugging information from the current page.
+
+## Usage
+
+```
+/firefox:debug              # Show all (console errors + failed requests)
+/firefox:debug console      # Console messages only
+/firefox:debug network      # Network requests only
+```
+
+## Examples
+
+```
+/firefox:debug
+/firefox:debug console
+/firefox:debug network
+```
+
+## What Happens
+
+- `console`: Calls `list_console_messages` with `level="error"`
+- `network`: Calls `list_network_requests` with `status="failed"`
+- `all` (default): Shows both console errors and failed network requests
+
+Useful for debugging page issues, JavaScript errors, and API failures.

plugins/claude/firefox-devtools/commands/navigate.md

@@ -0,0 +1,31 @@
+---
+description: Navigate Firefox to a URL and take a snapshot
+argument-hint: <url>
+---
+
+# /firefox:navigate
+
+Opens a URL in Firefox and takes a DOM snapshot for interaction.
+
+## Usage
+
+```
+/firefox:navigate <url>
+```
+
+## Examples
+
+```
+/firefox:navigate https://example.com
+/firefox:navigate https://github.com/login
+/firefox:navigate file:///path/to/local.html
+```
+
+## What Happens
+
+1. Calls `navigate_page` with the URL
+2. Waits for page load
+3. Calls `take_snapshot` to create UID mappings
+4. Returns the DOM snapshot with interactive elements marked
+
+After navigating, you can interact with elements using their UIDs (e.g., `e42`).

plugins/claude/firefox-devtools/commands/screenshot.md

@@ -0,0 +1,30 @@
+---
+description: Take a screenshot of the current page or element
+argument-hint: [uid]
+---
+
+# /firefox:screenshot
+
+Captures a screenshot of the page or a specific element.
+
+## Usage
+
+```
+/firefox:screenshot          # Full page
+/firefox:screenshot <uid>    # Specific element
+```
+
+## Examples
+
+```
+/firefox:screenshot
+/firefox:screenshot e15
+/firefox:screenshot e42
+```
+
+## What Happens
+
+- Without UID: Calls `screenshot_page` for full page capture
+- With UID: Calls `screenshot_by_uid` for element-specific capture
+
+Screenshots are saved and displayed in the conversation.

plugins/claude/firefox-devtools/skills/browser-automation/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: browser-automation
+description: This skill should be used when the user asks about browser automation, testing web pages, scraping content, filling forms, taking screenshots, or monitoring console/network activity. Activates for E2E testing, web scraping, form automation, or debugging web applications.
+---
+
+When the user asks about browser automation, use Firefox DevTools MCP to control a real Firefox browser.
+
+## When to Use This Skill
+
+Activate this skill when the user:
+
+- Wants to automate browser interactions ("Fill out this form", "Click the login button")
+- Needs E2E testing ("Test the checkout flow", "Verify the login works")
+- Requests web scraping ("Extract prices from this page", "Get all links")
+- Needs screenshots ("Screenshot this page", "Capture the error state")
+- Wants to debug ("Check for JS errors", "Show failed network requests")
+
+## Core Workflow
+
+### Step 1: Navigate and Snapshot
+
+```
+navigate_page url="https://example.com"
+take_snapshot
+```
+
+The snapshot returns a DOM representation with UIDs (e.g., `e42`) for each interactive element.
+
+### Step 2: Interact with Elements
+
+Use UIDs from the snapshot:
+
+```
+fill_by_uid uid="e5" text="user@example.com"
+click_by_uid uid="e8"
+```
+
+### Step 3: Re-snapshot After Changes
+
+DOM changes invalidate UIDs. Always re-snapshot after:
+- Page navigation
+- Form submissions
+- Dynamic content loads
+
+```
+take_snapshot  # Get fresh UIDs
+```
+
+## Quick Reference
+
+| Task | Tools |
+|------|-------|
+| Navigate | `navigate_page` |
+| See DOM | `take_snapshot` |
+| Click | `click_by_uid` |
+| Type | `fill_by_uid`, `fill_form_by_uid` |
+| Screenshot | `screenshot_page`, `screenshot_by_uid` |
+| Debug | `list_console_messages`, `list_network_requests` |
+
+## Guidelines
+
+- **Always snapshot first**: UIDs only exist after `take_snapshot`
+- **Re-snapshot after DOM changes**: UIDs become stale after interactions
+- **Check for errors**: Use `list_console_messages level="error"` to catch JS issues
+- **Firefox only**: This MCP controls Firefox, not Chrome or Safari