Tampermonkey Developer

Comprehensive toolkit for developing, testing, and debugging Tampermonkey userscripts. Supports DOM manipulation, API integration, XHR/fetch interception, styling injection, and modern JavaScript patterns. Use for building browser automation scripts, web page enhancements, and custom browser extensions.

nero2465 Updated Sep 22, 2026

Integrations & APIs

Install

Press C to copy

$ npx skillmds@latest add nero2465/tampermonkey-developer

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/nero2465/tampermonkey-developer.svg)](https://skillmd.com/skills/nero2465/tampermonkey-developer)

Trust & safety

Audits pending

Not yet audited · commit 273d0cd

Permissions this skill uses

Executes scripts
The instructions run shell commands or bundled script files.
Makes network calls
The instructions fetch remote URLs or call external services.

License: Apache 2
Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Tampermonkey Developer

A comprehensive skill for developing professional Tampermonkey userscripts with modern JavaScript patterns, best practices, and debugging capabilities.

Quick Start

Step 1: Understand the Requirements

Before building a userscript:

Identify target website(s) and URL patterns
Determine what DOM elements need manipulation
Understand timing requirements (DOMContentLoaded vs window.onload)
Check for SPA (Single Page Application) requirements

Step 2: Generate Userscript Structure

Use the template generator to create a new userscript:

bash scripts/generate-userscript.sh <script-name> <target-url>

This creates a fully structured userscript with:

✅ Complete metadata block with proper @grant declarations
✅ Modern ES6+ JavaScript structure
✅ Mutation observer for dynamic content handling
✅ Error handling and logging framework
✅ Common utility functions

Step 3: Develop the Userscript

Edit the generated .user.js file following these principles:

DOM Manipulation Best Practices:

Always wait for DOM ready state
Use MutationObserver for dynamic content
Prefer querySelector/querySelectorAll over jQuery
Cache DOM references for performance
Use requestAnimationFrame for visual changes

Timing Considerations:

@run-at document-start - Before any DOM elements exist
@run-at document-body - When <body> exists (default)
@run-at document-end - After DOM is loaded (like DOMContentLoaded)
@run-at document-idle - After page fully loaded (like window.onload)

Security & Permissions: Only request grants you actually need:

GM_setValue / GM_getValue - Persistent storage
GM_xmlhttpRequest - Cross-origin requests
GM_addStyle - Inject CSS
GM_setClipboard - Clipboard access
GM_notification - Browser notifications
GM_openInTab - Open new tabs
unsafeWindow - Access page's window object (use with caution)

Step 4: Testing & Debugging

Local Testing:

Install in Tampermonkey
Enable debug mode in script settings
Use console.log with script prefix for filtering
Monitor with browser DevTools

Common Debugging Commands:

// Script info logging
console.log('[YourScript]', 'Initialized');

// DOM element checking
console.assert(element, 'Element not found!');

// Performance monitoring
console.time('operation');
// ... your code
console.timeEnd('operation');

Anti-Pattern Detection: Use the validator script to check for common issues:

bash scripts/validate-userscript.sh your-script.user.js

Checks for:

Missing @grant declarations
Inefficient selectors
Memory leaks (unremoved event listeners)
CSP violations
Insecure patterns (eval, innerHTML with user input)

Step 5: Optimization

Performance Tips:

Debounce/throttle event handlers
Use event delegation for dynamic elements
Minimize DOM queries (cache results)
Avoid synchronous XHR
Use GM_addStyle instead of inline styles

Example - Debounce Function:

function debounce(func, wait) {
    let timeout;
    return function executedFunction(...args) {
        clearTimeout(timeout);
        timeout = setTimeout(() => func.apply(this, args), wait);
    };
}

// Usage
const handleScroll = debounce(() => {
    console.log('Scrolled!');
}, 250);
window.addEventListener('scroll', handleScroll);

Common Patterns

Pattern 1: Waiting for Elements

// Using Mutation Observer (recommended for dynamic content)
function waitForElement(selector, callback, timeout = 10000) {
    const startTime = Date.now();

    // Check if element already exists
    const element = document.querySelector(selector);
    if (element) return callback(element);

    // Setup observer
    const observer = new MutationObserver((mutations, obs) => {
        const element = document.querySelector(selector);
        if (element) {
            obs.disconnect();
            callback(element);
        } else if (Date.now() - startTime > timeout) {
            obs.disconnect();
            console.warn(`Timeout waiting for: ${selector}`);
        }
    });

    observer.observe(document.body, {
        childList: true,
        subtree: true
    });
}

// Usage
waitForElement('.target-class', (element) => {
    element.style.backgroundColor = 'yellow';
});

Pattern 2: Cross-Origin API Requests

// Using GM_xmlhttpRequest for CORS-free requests
function fetchAPI(url, options = {}) {
    return new Promise((resolve, reject) => {
        GM_xmlhttpRequest({
            method: options.method || 'GET',
            url: url,
            headers: options.headers || {},
            data: options.body,
            onload: (response) => {
                if (response.status >= 200 && response.status < 300) {
                    try {
                        resolve(JSON.parse(response.responseText));
                    } catch {
                        resolve(response.responseText);
                    }
                } else {
                    reject(new Error(`HTTP ${response.status}`));
                }
            },
            onerror: (error) => reject(error),
            ontimeout: () => reject(new Error('Request timeout'))
        });
    });
}

// Usage
fetchAPI('https://api.example.com/data')
    .then(data => console.log(data))
    .catch(err => console.error('API Error:', err));

Pattern 3: Persistent Settings

// Settings manager with defaults
class ScriptSettings {
    constructor(defaults = {}) {
        this.defaults = defaults;
    }

    get(key) {
        const value = GM_getValue(key);
        return value !== undefined ? value : this.defaults[key];
    }

    set(key, value) {
        GM_setValue(key, value);
    }

    getAll() {
        const settings = {};
        for (const key in this.defaults) {
            settings[key] = this.get(key);
        }
        return settings;
    }
}

// Usage
const settings = new ScriptSettings({
    enabled: true,
    theme: 'dark',
    maxItems: 50
});

if (settings.get('enabled')) {
    // Run script logic
}

Pattern 4: Style Injection

// Inject CSS with GM_addStyle (CSP-safe)
GM_addStyle(`
    .custom-element {
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        padding: 12px 24px;
        border-radius: 8px;
        color: white;
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
        transition: transform 0.2s;
    }

    .custom-element:hover {
        transform: translateY(-2px);
        box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15);
    }
`);

Pattern 5: SPA Navigation Detection

// Detect route changes in Single Page Applications
let lastUrl = location.href;

function onLocationChange(callback) {
    new MutationObserver(() => {
        const currentUrl = location.href;
        if (currentUrl !== lastUrl) {
            lastUrl = currentUrl;
            callback(currentUrl);
        }
    }).observe(document, { subtree: true, childList: true });
}

// Usage
onLocationChange((url) => {
    console.log('Navigation detected:', url);
    // Re-initialize script logic for new page
    initializeScript();
});

Advanced Techniques

Intercepting XHR/Fetch Requests

// Intercept and modify fetch requests
(function(fetch) {
    window.fetch = function(...args) {
        console.log('Fetch intercepted:', args[0]);

        // Modify request if needed
        if (args[0].includes('api.example.com')) {
            const modifiedInit = args[1] || {};
            modifiedInit.headers = {
                ...modifiedInit.headers,
                'X-Custom-Header': 'MyValue'
            };
            args[1] = modifiedInit;
        }

        return fetch.apply(this, args)
            .then(response => {
                console.log('Fetch response:', response.url, response.status);
                return response;
            });
    };
})(window.fetch);

Creating Draggable UI Panels

function createDraggablePanel(content) {
    const panel = document.createElement('div');
    panel.innerHTML = `
        <div class="panel-header" style="cursor: move; background: #333; color: white; padding: 10px;">
            Drag Me
            <button class="close-btn" style="float: right;">×</button>
        </div>
        <div class="panel-content" style="background: white; padding: 15px;">
            ${content}
        </div>
    `;

    panel.style.cssText = 'position: fixed; top: 50px; right: 50px; width: 300px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.3); z-index: 99999;';

    // Make draggable
    const header = panel.querySelector('.panel-header');
    let isDragging = false;
    let currentX, currentY, initialX, initialY;

    header.addEventListener('mousedown', (e) => {
        isDragging = true;
        initialX = e.clientX - panel.offsetLeft;
        initialY = e.clientY - panel.offsetTop;
    });

    document.addEventListener('mousemove', (e) => {
        if (isDragging) {
            e.preventDefault();
            currentX = e.clientX - initialX;
            currentY = e.clientY - initialY;
            panel.style.left = currentX + 'px';
            panel.style.top = currentY + 'px';
            panel.style.right = 'auto';
        }
    });

    document.addEventListener('mouseup', () => isDragging = false);

    // Close button
    panel.querySelector('.close-btn').addEventListener('click', () => panel.remove());

    document.body.appendChild(panel);
    return panel;
}

// Usage
createDraggablePanel('<h3>Settings</h3><p>Your content here</p>');

Keyboard Shortcuts

// Register keyboard shortcuts
function registerHotkey(keys, callback) {
    const keysArray = keys.toLowerCase().split('+').map(k => k.trim());

    document.addEventListener('keydown', (e) => {
        const pressed = [];
        if (e.ctrlKey) pressed.push('ctrl');
        if (e.altKey) pressed.push('alt');
        if (e.shiftKey) pressed.push('shift');
        if (e.metaKey) pressed.push('meta');
        pressed.push(e.key.toLowerCase());

        if (pressed.sort().join('+') === keysArray.sort().join('+')) {
            e.preventDefault();
            callback(e);
        }
    });
}

// Usage
registerHotkey('ctrl+shift+x', () => {
    console.log('Hotkey triggered!');
    // Your action here
});

Troubleshooting

Script Not Running

Check @match or @include patterns match current URL
Verify @run-at timing is appropriate
Check console for JavaScript errors
Ensure Tampermonkey is enabled for the site
Try incognito mode to rule out conflicts

Element Not Found

Check if page is SPA (needs navigation detection)
Increase wait timeout
Verify selector is correct (use DevTools)
Check if element is in iframe
Use MutationObserver instead of fixed delays

Performance Issues

Remove unused @grant declarations
Debounce/throttle event handlers
Cache DOM queries
Use event delegation
Check for memory leaks (console → Memory profiler)

CSP (Content Security Policy) Errors

Use GM_addStyle instead of inline styles
Use @grant unsafeWindow if accessing page context
Avoid inline event handlers (use addEventListener)
Use GM_xmlhttpRequest for external requests

Best Practices Summary

Always declare @grant - Even if using none
Use MutationObserver - For dynamic content
Cache DOM references - Query once, use many times
Handle errors gracefully - Wrap in try-catch blocks
Prefix console logs - Easy filtering in DevTools
Version your scripts - Use @version for updates
Document dependencies - List in @description or comments
Test in incognito - Catch extension conflicts
Respect site performance - Don't block rendering
Follow site ToS - Don't abuse automation

Templates Available

templates/basic-template.user.js - Minimal starter template
templates/advanced-template.user.js - Full-featured with utilities
templates/api-integration.user.js - Cross-origin API requests
templates/ui-enhancement.user.js - DOM manipulation & styling
templates/spa-compatible.user.js - Single Page Application support

Scripts Available

scripts/generate-userscript.sh - Generate new userscript from template
scripts/validate-userscript.sh - Validate script for common issues
scripts/extract-metadata.sh - Extract and validate metadata block
scripts/bundle-library.sh - Bundle external libraries into script

Reference

Tampermonkey Documentation: https://www.tampermonkey.net/documentation.php
GreasyFork Best Practices: https://greasyfork.org/help/code-rules
GM API Reference: https://wiki.greasespot.net/Greasemonkey_Manual:API
UserScript Examples: examples/ directory

---name: tampermonkey-developerdescription: Comprehensive toolkit for developing, testing, and debugging Tampermonkey userscripts. Supports DOM manipulation, API integration, XHR/fetch interception, styling injection, and modern JavaScript patterns. Use for building browser automation scripts, web page enhancements, and custom browser extensions.license: Apache 2.0---# Tampermonkey DeveloperA comprehensive skill for developing professional Tampermonkey userscripts with modern JavaScript patterns, best practices, and debugging capabilities.## Quick Start### Step 1: Understand the RequirementsBefore building a userscript:1. Identify target website(s) and URL patterns2. Determine what DOM elements need manipulation3. Understand timing requirements (DOMContentLoaded vs window.onload)4. Check for SPA (Single Page Application) requirements### Step 2: Generate Userscript StructureUse the template generator to create a new userscript:```bashbash scripts/generate-userscript.sh <script-name> <target-url>```This creates a fully structured userscript with:- ✅ Complete metadata block with proper @grant declarations- ✅ Modern ES6+ JavaScript structure- ✅ Mutation observer for dynamic content handling- ✅ Error handling and logging framework- ✅ Common utility functions### Step 3: Develop the UserscriptEdit the generated `.user.js` file following these principles:**DOM Manipulation Best Practices:**- Always wait for DOM ready state- Use `MutationObserver` for dynamic content- Prefer `querySelector`/`querySelectorAll` over jQuery- Cache DOM references for performance- Use `requestAnimationFrame` for visual changes**Timing Considerations:**- `@run-at document-start` - Before any DOM elements exist- `@run-at document-body` - When `<body>` exists (default)- `@run-at document-end` - After DOM is loaded (like DOMContentLoaded)- `@run-at document-idle` - After page fully loaded (like window.onload)**Security & Permissions:**Only request grants you actually need:- `GM_setValue` / `GM_getValue` - Persistent storage- `GM_xmlhttpRequest` - Cross-origin requests- `GM_addStyle` - Inject CSS- `GM_setClipboard` - Clipboard access- `GM_notification` - Browser notifications- `GM_openInTab` - Open new tabs- `unsafeWindow` - Access page's window object (use with caution)### Step 4: Testing & Debugging**Local Testing:**1. Install in Tampermonkey2. Enable debug mode in script settings3. Use `console.log` with script prefix for filtering4. Monitor with browser DevTools**Common Debugging Commands:**```javascript// Script info loggingconsole.log('[YourScript]', 'Initialized');// DOM element checkingconsole.assert(element, 'Element not found!');// Performance monitoringconsole.time('operation');// ... your codeconsole.timeEnd('operation');```**Anti-Pattern Detection:**Use the validator script to check for common issues:```bashbash scripts/validate-userscript.sh your-script.user.js```Checks for:- Missing @grant declarations- Inefficient selectors- Memory leaks (unremoved event listeners)- CSP violations- Insecure patterns (eval, innerHTML with user input)### Step 5: Optimization**Performance Tips:**1. Debounce/throttle event handlers2. Use event delegation for dynamic elements3. Minimize DOM queries (cache results)4. Avoid synchronous XHR5. Use `GM_addStyle` instead of inline styles**Example - Debounce Function:**```javascriptfunction debounce(func, wait) { let timeout; return function executedFunction(...args) { clearTimeout(timeout); timeout = setTimeout(() => func.apply(this, args), wait); };}// Usageconst handleScroll = debounce(() => { console.log('Scrolled!');}, 250);window.addEventListener('scroll', handleScroll);```## Common Patterns### Pattern 1: Waiting for Elements```javascript// Using Mutation Observer (recommended for dynamic content)function waitForElement(selector, callback, timeout = 10000) { const startTime = Date.now(); // Check if element already exists const element = document.querySelector(selector); if (element) return callback(element); // Setup observer const observer = new MutationObserver((mutations, obs) => { const element = document.querySelector(selector); if (element) { obs.disconnect(); callback(element); } else if (Date.now() - startTime > timeout) { obs.disconnect(); console.warn(`Timeout waiting for: ${selector}`); } }); observer.observe(document.body, { childList: true, subtree: true });}// UsagewaitForElement('.target-class', (element) => { element.style.backgroundColor = 'yellow';});```### Pattern 2: Cross-Origin API Requests```javascript// Using GM_xmlhttpRequest for CORS-free requestsfunction fetchAPI(url, options = {}) { return new Promise((resolve, reject) => { GM_xmlhttpRequest({ method: options.method || 'GET', url: url, headers: options.headers || {}, data: options.body, onload: (response) => { if (response.status >= 200 && response.status < 300) { try { resolve(JSON.parse(response.responseText)); } catch { resolve(response.responseText); } } else { reject(new Error(`HTTP ${response.status}`)); } }, onerror: (error) => reject(error), ontimeout: () => reject(new Error('Request timeout')) }); });}// UsagefetchAPI('https://api.example.com/data') .then(data => console.log(data)) .catch(err => console.error('API Error:', err));```### Pattern 3: Persistent Settings```javascript// Settings manager with defaultsclass ScriptSettings { constructor(defaults = {}) { this.defaults = defaults; } get(key) { const value = GM_getValue(key); return value !== undefined ? value : this.defaults[key]; } set(key, value) { GM_setValue(key, value); } getAll() { const settings = {}; for (const key in this.defaults) { settings[key] = this.get(key); } return settings; }}// Usageconst settings = new ScriptSettings({ enabled: true, theme: 'dark', maxItems: 50});if (settings.get('enabled')) { // Run script logic}```### Pattern 4: Style Injection```javascript// Inject CSS with GM_addStyle (CSP-safe)GM_addStyle(` .custom-element { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 12px 24px; border-radius: 8px; color: white; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); transition: transform 0.2s; } .custom-element:hover { transform: translateY(-2px); box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15); }`);```### Pattern 5: SPA Navigation Detection```javascript// Detect route changes in Single Page Applicationslet lastUrl = location.href;function onLocationChange(callback) { new MutationObserver(() => { const currentUrl = location.href; if (currentUrl !== lastUrl) { lastUrl = currentUrl; callback(currentUrl); } }).observe(document, { subtree: true, childList: true });}// UsageonLocationChange((url) => { console.log('Navigation detected:', url); // Re-initialize script logic for new page initializeScript();});```## Advanced Techniques### Intercepting XHR/Fetch Requests```javascript// Intercept and modify fetch requests(function(fetch) { window.fetch = function(...args) { console.log('Fetch intercepted:', args[0]); // Modify request if needed if (args[0].includes('api.example.com')) { const modifiedInit = args[1] || {}; modifiedInit.headers = { ...modifiedInit.headers, 'X-Custom-Header': 'MyValue' }; args[1] = modifiedInit; } return fetch.apply(this, args) .then(response => { console.log('Fetch response:', response.url, response.status); return response; }); };})(window.fetch);```### Creating Draggable UI Panels```javascriptfunction createDraggablePanel(content) { const panel = document.createElement('div'); panel.innerHTML = ` <div class="panel-header" style="cursor: move; background: #333; color: white; padding: 10px;"> Drag Me <button class="close-btn" style="float: right;">×</button> </div> <div class="panel-content" style="background: white; padding: 15px;"> ${content} </div> `; panel.style.cssText = 'position: fixed; top: 50px; right: 50px; width: 300px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.3); z-index: 99999;'; // Make draggable const header = panel.querySelector('.panel-header'); let isDragging = false; let currentX, currentY, initialX, initialY; header.addEventListener('mousedown', (e) => { isDragging = true; initialX = e.clientX - panel.offsetLeft; initialY = e.clientY - panel.offsetTop; }); document.addEventListener('mousemove', (e) => { if (isDragging) { e.preventDefault(); currentX = e.clientX - initialX; currentY = e.clientY - initialY; panel.style.left = currentX + 'px'; panel.style.top = currentY + 'px'; panel.style.right = 'auto'; } }); document.addEventListener('mouseup', () => isDragging = false); // Close button panel.querySelector('.close-btn').addEventListener('click', () => panel.remove()); document.body.appendChild(panel); return panel;}// UsagecreateDraggablePanel('<h3>Settings</h3><p>Your content here</p>');```### Keyboard Shortcuts```javascript// Register keyboard shortcutsfunction registerHotkey(keys, callback) { const keysArray = keys.toLowerCase().split('+').map(k => k.trim()); document.addEventListener('keydown', (e) => { const pressed = []; if (e.ctrlKey) pressed.push('ctrl'); if (e.altKey) pressed.push('alt'); if (e.shiftKey) pressed.push('shift'); if (e.metaKey) pressed.push('meta'); pressed.push(e.key.toLowerCase()); if (pressed.sort().join('+') === keysArray.sort().join('+')) { e.preventDefault(); callback(e); } });}// UsageregisterHotkey('ctrl+shift+x', () => { console.log('Hotkey triggered!'); // Your action here});```## Troubleshooting### Script Not Running1. Check @match or @include patterns match current URL2. Verify @run-at timing is appropriate3. Check console for JavaScript errors4. Ensure Tampermonkey is enabled for the site5. Try incognito mode to rule out conflicts### Element Not Found1. Check if page is SPA (needs navigation detection)2. Increase wait timeout3. Verify selector is correct (use DevTools)4. Check if element is in iframe5. Use MutationObserver instead of fixed delays### Performance Issues1. Remove unused @grant declarations2. Debounce/throttle event handlers3. Cache DOM queries4. Use event delegation5. Check for memory leaks (console → Memory profiler)### CSP (Content Security Policy) Errors1. Use `GM_addStyle` instead of inline styles2. Use `@grant unsafeWindow` if accessing page context3. Avoid inline event handlers (use addEventListener)4. Use `GM_xmlhttpRequest` for external requests## Best Practices Summary1. **Always declare @grant** - Even if using `none`2. **Use MutationObserver** - For dynamic content3. **Cache DOM references** - Query once, use many times4. **Handle errors gracefully** - Wrap in try-catch blocks5. **Prefix console logs** - Easy filtering in DevTools6. **Version your scripts** - Use @version for updates7. **Document dependencies** - List in @description or comments8. **Test in incognito** - Catch extension conflicts9. **Respect site performance** - Don't block rendering10. **Follow site ToS** - Don't abuse automation## Templates Available- `templates/basic-template.user.js` - Minimal starter template- `templates/advanced-template.user.js` - Full-featured with utilities- `templates/api-integration.user.js` - Cross-origin API requests- `templates/ui-enhancement.user.js` - DOM manipulation & styling- `templates/spa-compatible.user.js` - Single Page Application support## Scripts Available- `scripts/generate-userscript.sh` - Generate new userscript from template- `scripts/validate-userscript.sh` - Validate script for common issues- `scripts/extract-metadata.sh` - Extract and validate metadata block- `scripts/bundle-library.sh` - Bundle external libraries into script## Reference- **Tampermonkey Documentation**: https://www.tampermonkey.net/documentation.php- **GreasyFork Best Practices**: https://greasyfork.org/help/code-rules- **GM API Reference**: https://wiki.greasespot.net/Greasemonkey_Manual:API- **UserScript Examples**: `examples/` directory

nero2465/awesome-claude-skills/tree/main/tampermonkey-developer commit 273d0cd248

Frequently asked questions

npx skillmds@latest add nero2465/tampermonkey-developer