Userscript work usually breaks at the runtime and metadata boundary, not in the page logic. Choose the runtime first, declare the minimum permissions up front, then debug in the environment where the script actually runs.
When to Use
Use this skill for:
- Writing or fixing a Tampermonkey or ScriptCat userscript
- Debugging injection timing, missing permissions, CSP workarounds, or
GM_*behavior - Deciding between a portable foreground script and ScriptCat-only
@backgroundor@crontab - Adding config UI with
==UserConfig== - Packaging a ScriptCat subscription bundle
Do not use for full browser extension development or general browser automation outside userscript managers.
Runtime Selection
| Need | Choose |
|---|---|
| Page DOM or page context | Portable ==UserScript== foreground script |
| Persistent or scheduled work | ScriptCat @background or @crontab script |
| Install many scripts as one package | ScriptCat ==UserSubscribe== |
Preflight
- Confirm the manager and browser (MV3 browsers may require developer mode for ScriptCat)
- Decide page script vs background script before writing code — background scripts cannot touch the DOM
- Start with metadata:
@match,@grant,@connect,@run-at, and update URLs - Prefer portable
==UserScript==patterns — only switch to ScriptCat-only headers when needed
Quick Reference
| Intent | Default choice | Watch for |
|---|---|---|
| Page UI, DOM scraping | Portable ==UserScript== |
@match, @grant, @run-at, CSP injection |
| Cross-origin API access | GM_xmlhttpRequest with explicit @connect |
Missing hosts, cookie behavior |
| Long-running worker | ScriptCat @background |
No DOM, must return Promise for async |
| Scheduled task | ScriptCat @crontab |
Only first @crontab counts |
| User-editable settings | ==UserConfig== plus GM_getValue |
Block placement and group.key naming |
Workflow
- Choose the runtime and metadata first
- Declare the smallest permission surface that fits the task
- Implement against the runtime you chose
- Debug where the code really runs:
- Foreground scripts: page console plus manager logs
- ScriptCat background scripts: run log first, then
background.html
- Publish with the right update model
Common Mistakes
- Missing
@grantfor APIs the script actually uses - Missing
@connectfor hosts used byGM_xmlhttpRequest - Treating
@includeas a better default than@match - Using DOM APIs inside ScriptCat background or cron scripts
- Returning from a ScriptCat background script before async GM work is truly finished
- Assuming Tampermonkey and ScriptCat storage/notification/request behavior is identical
Mirrored from https://github.com/xixu-me/skills — original author: xixu-me, license: MIT. This is an unclaimed mirror. Content and ownership transfer to the author when they claim this account.