Skip to content

Commit 009db97

Browse files
freemafreema
authored
Merge pull request #35 from freema/claude/npm-skill-distribution-Hm9lX
Add SKILL.md documentation and npm skill distribution RFC
2 parents 52b5e37 + 23b0c6c commit 009db97

File tree

10 files changed

+332
-1
lines changed

10 files changed

+332
-1
lines changed

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,8 @@
8888
"dist",
8989
"README.md",
9090
"LICENSE",
91-
"scripts"
91+
"scripts",
92+
"plugins"
9293
],
9394
"repository": {
9495
"type": "git",

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"name": "firefox-devtools",
3+
"description": "Firefox browser automation via WebDriver BiDi. Automate Firefox for testing, scraping, form filling, screenshots, and debugging.",
4+
"version": "0.5.3",
5+
"author": {
6+
"name": "Tomáš Grasl",
7+
"url": "https://www.tomasgrasl.cz/"
8+
},
9+
"repository": "https://github.com/freema/firefox-devtools-mcp",
10+
"license": "MIT"
11+
}

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"mcpServers": {
3+
"firefox-devtools": {
4+
"command": "npx",
5+
"args": ["-y", "firefox-devtools-mcp@latest"]
6+
}
7+
}
8+
}

‎plugins/claude/firefox-devtools/README.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Firefox DevTools Plugin for Claude Code
2+
3+
Firefox browser automation via WebDriver BiDi. Navigate pages, fill forms, click elements, take screenshots, and monitor console/network activity.
4+
5+
## What's Included
6+
7+
This plugin provides:
8+
9+
- **MCP Server** - Connects Claude Code to Firefox automation
10+
- **Skills** - Auto-triggers for browser automation, testing, and scraping tasks
11+
- **Agents** - Dedicated `e2e-tester` and `web-scraper` agents for focused tasks
12+
- **Commands** - `/firefox:navigate`, `/firefox:screenshot`, `/firefox:debug`
13+
14+
## Installation
15+
16+
```bash
17+
claude plugin install firefox-devtools
18+
```
19+
20+
## Commands
21+
22+
### /firefox:navigate
23+
24+
Navigate to a URL and take a DOM snapshot:
25+
26+
```
27+
/firefox:navigate https://example.com
28+
/firefox:navigate https://github.com/login
29+
```
30+
31+
### /firefox:screenshot
32+
33+
Capture the current page or a specific element:
34+
35+
```
36+
/firefox:screenshot
37+
/firefox:screenshot e15
38+
```
39+
40+
### /firefox:debug
41+
42+
Show console errors and failed network requests:
43+
44+
```
45+
/firefox:debug
46+
/firefox:debug console
47+
/firefox:debug network
48+
```
49+
50+
## Agents
51+
52+
Spawn agents to keep your main context clean:
53+
54+
```
55+
spawn e2e-tester to test the login flow on https://app.example.com
56+
spawn web-scraper to extract product prices from https://shop.example.com
57+
```
58+
59+
## Usage Examples
60+
61+
The plugin works automatically when you ask about browser tasks:
62+
63+
- "Navigate to example.com and take a screenshot"
64+
- "Fill out the login form and submit"
65+
- "Check for JavaScript errors on this page"
66+
- "Scrape all product prices from this page"
67+
68+
## Key Workflow
69+
70+
1. `take_snapshot` - Creates DOM snapshot with UIDs (e.g., `e42`)
71+
2. Interact using UIDs - `click_by_uid`, `fill_by_uid`, etc.
72+
3. Re-snapshot after DOM changes
73+
74+
## Requirements
75+
76+
- Firefox 120+
77+
- Node.js 20.19.0+
78+
79+
## Links
80+
81+
- [Repository](https://github.com/freema/firefox-devtools-mcp)
82+
- [npm](https://www.npmjs.com/package/firefox-devtools-mcp)

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: e2e-tester
3+
description: Agent for running E2E tests on web applications. Navigates pages, fills forms, clicks buttons, and verifies results.
4+
model: sonnet
5+
---
6+
7+
You are an E2E testing agent specializing in automated browser testing using Firefox DevTools MCP.
8+
9+
## Your Task
10+
11+
When given a test scenario, execute it step-by-step using Firefox automation tools, verify the results, and report pass/fail status.
12+
13+
## Process
14+
15+
1. **Navigate to the target**: Use `navigate_page` to open the URL
16+
2. **Take snapshot**: Always call `take_snapshot` before interacting
17+
3. **Execute test steps**: Use `fill_by_uid`, `click_by_uid`, etc.
18+
4. **Re-snapshot after changes**: DOM updates require fresh snapshots
19+
5. **Verify results**: Check for expected elements, text, or states
20+
6. **Report outcome**: Clear pass/fail with evidence (screenshots if needed)
21+
22+
## Available Tools
23+
24+
- `navigate_page` - Go to URL
25+
- `take_snapshot` - Get DOM with UIDs
26+
- `fill_by_uid` / `fill_form_by_uid` - Enter text
27+
- `click_by_uid` - Click elements
28+
- `screenshot_page` - Capture evidence
29+
- `list_console_messages` - Check for JS errors
30+
31+
## Guidelines
32+
33+
- Always snapshot before AND after interactions
34+
- Take screenshots at key checkpoints
35+
- Report console errors as test failures
36+
- Be specific about what passed or failed

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

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: web-scraper
3+
description: Agent for extracting structured data from web pages. Navigates, handles pagination, and extracts content.
4+
model: sonnet
5+
---
6+
7+
You are a web scraping agent specializing in data extraction using Firefox DevTools MCP.
8+
9+
## Your Task
10+
11+
When given a scraping task, navigate to pages, extract the requested data, handle pagination if needed, and return structured results.
12+
13+
## Process
14+
15+
1. **Navigate to source**: Use `navigate_page` to open the URL
16+
2. **Take snapshot**: Call `take_snapshot` to see page structure
17+
3. **Identify data elements**: Find UIDs for elements containing target data
18+
4. **Extract content**: The snapshot contains text content of elements
19+
5. **Handle pagination**: Click "next" buttons, re-snapshot, repeat
20+
6. **Structure output**: Return data in requested format (JSON, table, etc.)
21+
22+
## Available Tools
23+
24+
- `navigate_page` - Go to URL
25+
- `take_snapshot` - Get DOM with content and UIDs
26+
- `click_by_uid` - Navigate pagination
27+
- `list_network_requests` - Monitor API calls (sometimes easier to scrape)
28+
29+
## Guidelines
30+
31+
- Snapshots contain element text - no need for separate "get text" calls
32+
- Check network requests for API endpoints (often cleaner than DOM scraping)
33+
- Respect rate limits - don't hammer the server
34+
- Handle "load more" buttons and infinite scroll patterns
35+
- Return structured data, not raw HTML

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
description: Show console errors and failed network requests
3+
argument-hint: [console|network|all]
4+
---
5+
6+
# /firefox:debug
7+
8+
Displays debugging information from the current page.
9+
10+
## Usage
11+
12+
```
13+
/firefox:debug # Show all (console errors + failed requests)
14+
/firefox:debug console # Console messages only
15+
/firefox:debug network # Network requests only
16+
```
17+
18+
## Examples
19+
20+
```
21+
/firefox:debug
22+
/firefox:debug console
23+
/firefox:debug network
24+
```
25+
26+
## What Happens
27+
28+
- `console`: Calls `list_console_messages` with `level="error"`
29+
- `network`: Calls `list_network_requests` with `status="failed"`
30+
- `all` (default): Shows both console errors and failed network requests
31+
32+
Useful for debugging page issues, JavaScript errors, and API failures.

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: Navigate Firefox to a URL and take a snapshot
3+
argument-hint: <url>
4+
---
5+
6+
# /firefox:navigate
7+
8+
Opens a URL in Firefox and takes a DOM snapshot for interaction.
9+
10+
## Usage
11+
12+
```
13+
/firefox:navigate <url>
14+
```
15+
16+
## Examples
17+
18+
```
19+
/firefox:navigate https://example.com
20+
/firefox:navigate https://github.com/login
21+
/firefox:navigate file:///path/to/local.html
22+
```
23+
24+
## What Happens
25+
26+
1. Calls `navigate_page` with the URL
27+
2. Waits for page load
28+
3. Calls `take_snapshot` to create UID mappings
29+
4. Returns the DOM snapshot with interactive elements marked
30+
31+
After navigating, you can interact with elements using their UIDs (e.g., `e42`).

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: Take a screenshot of the current page or element
3+
argument-hint: [uid]
4+
---
5+
6+
# /firefox:screenshot
7+
8+
Captures a screenshot of the page or a specific element.
9+
10+
## Usage
11+
12+
```
13+
/firefox:screenshot # Full page
14+
/firefox:screenshot <uid> # Specific element
15+
```
16+
17+
## Examples
18+
19+
```
20+
/firefox:screenshot
21+
/firefox:screenshot e15
22+
/firefox:screenshot e42
23+
```
24+
25+
## What Happens
26+
27+
- Without UID: Calls `screenshot_page` for full page capture
28+
- With UID: Calls `screenshot_by_uid` for element-specific capture
29+
30+
Screenshots are saved and displayed in the conversation.

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
name: browser-automation
3+
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.
4+
---
5+
6+
When the user asks about browser automation, use Firefox DevTools MCP to control a real Firefox browser.
7+
8+
## When to Use This Skill
9+
10+
Activate this skill when the user:
11+
12+
- Wants to automate browser interactions ("Fill out this form", "Click the login button")
13+
- Needs E2E testing ("Test the checkout flow", "Verify the login works")
14+
- Requests web scraping ("Extract prices from this page", "Get all links")
15+
- Needs screenshots ("Screenshot this page", "Capture the error state")
16+
- Wants to debug ("Check for JS errors", "Show failed network requests")
17+
18+
## Core Workflow
19+
20+
### Step 1: Navigate and Snapshot
21+
22+
```
23+
navigate_page url="https://example.com"
24+
take_snapshot
25+
```
26+
27+
The snapshot returns a DOM representation with UIDs (e.g., `e42`) for each interactive element.
28+
29+
### Step 2: Interact with Elements
30+
31+
Use UIDs from the snapshot:
32+
33+
```
34+
fill_by_uid uid="e5" text="user@example.com"
35+
click_by_uid uid="e8"
36+
```
37+
38+
### Step 3: Re-snapshot After Changes
39+
40+
DOM changes invalidate UIDs. Always re-snapshot after:
41+
- Page navigation
42+
- Form submissions
43+
- Dynamic content loads
44+
45+
```
46+
take_snapshot # Get fresh UIDs
47+
```
48+
49+
## Quick Reference
50+
51+
| Task | Tools |
52+
|------|-------|
53+
| Navigate | `navigate_page` |
54+
| See DOM | `take_snapshot` |
55+
| Click | `click_by_uid` |
56+
| Type | `fill_by_uid`, `fill_form_by_uid` |
57+
| Screenshot | `screenshot_page`, `screenshot_by_uid` |
58+
| Debug | `list_console_messages`, `list_network_requests` |
59+
60+
## Guidelines
61+
62+
- **Always snapshot first**: UIDs only exist after `take_snapshot`
63+
- **Re-snapshot after DOM changes**: UIDs become stale after interactions
64+
- **Check for errors**: Use `list_console_messages level="error"` to catch JS issues
65+
- **Firefox only**: This MCP controls Firefox, not Chrome or Safari

0 commit comments

Comments
 (0)