scriptcat-userscript
Write, fix and debug userscripts for ScriptCat (Tampermonkey-compatible): page scripts that run on matching sites (@match), background scripts that keep running without a page (@background) and scheduled scripts (@crontab); metadata, @grant and the GM_* / GM.* / CAT_* APIs, user config, retries. When the sctl CLI is connected, install the script into the user's ScriptCat and verify it in their real browser. Use whenever the user wants a userscript, 油猴脚本, 后台脚本, 定时脚本, a .user.js file or a ScriptCat script written, changed or debugged. Not for developing the ScriptCat extension itself, and not for managing installed scripts without changing their code (that is the sctl skill).
How do I install this agent skill?
npx skills add https://github.com/scriptscat/scriptcat --skill scriptcat-userscriptIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The scriptcat-userscript skill provides a suite of tools and instructions for the development and debugging of ScriptCat userscripts. It includes local static analysis scripts and utilizes the sctl CLI for browser-based verification and script management. The analysis confirms that identified command execution and dynamic code evaluation are standard behaviors for userscript development tools and are accompanied by appropriate safety warnings regarding sensitive information. No malicious patterns or data exfiltration behaviors were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Writing ScriptCat userscripts
ScriptCat runs Tampermonkey-style userscripts and adds two kinds of its own: background scripts and scheduled scripts, which run in the extension's background sandbox instead of a web page. Most Tampermonkey knowledge carries over; the differences below are the ones that break scripts.
Authority. The API surface is scriptcat.d.ts — in this repository src/types/scriptcat.d.ts, otherwise
https://raw.githubusercontent.com/scriptscat/scriptcat/main/src/types/scriptcat.d.ts. Working examples live in
https://github.com/scriptscat/scriptcat/tree/main/example. The developer docs at https://docs.scriptcat.org/docs/dev/
can lag behind the types; when they disagree, trust the types.
1. Pick the script type
| The script must… | Type | Key metadata |
|---|---|---|
| Change, read or automate a web page | Page script | @match / @include, @run-at |
| Keep running while the browser is open, with no page (listeners, polling, a menu in the popup) | Background script | @background |
| Run on a schedule (check-in, sync, report, periodic fetch) | Scheduled script | @crontab <expr> |
Background and scheduled scripts have no web page: no document of any site, no unsafeWindow page, no
GM_getTab/GM_saveTab. To touch a page from the background, open it with GM_openInTab and let a page
script do the DOM work, or fetch data with GM_xmlhttpRequest instead of scraping a rendered page.
2. Start from the right skeleton
These match the templates ScriptCat's own "new script" uses.
// ==UserScript==
// @name Example page script
// @namespace https://example.com/your-namespace
// @version 0.1.0
// @description What it does, in one line
// @author You
// @match https://example.com/*
// @grant none
// @noframes
// ==/UserScript==
(function () {
"use strict";
// ...
})();
// ==UserScript==
// @name Example background script
// @namespace https://example.com/your-namespace
// @version 0.1.0
// @description What it does, in one line
// @author You
// @background
// @grant GM_xmlhttpRequest
// @grant GM_notification
// ==/UserScript==
return new Promise((resolve, reject) => {
// ... resolve() when the work is really finished, reject(err) on failure
});
A scheduled script is the background skeleton with @crontab * * once * * (or another expression) in place of
@background. Background and scheduled bodies are wrapped in a function by ScriptCat, so a top-level return
is legal there.
3. Rules that break scripts when ignored
Identity and updates
@name+@namespaceidentify a script. Keep both stable once the user has installed it; changing either makes a different script. Bump@versionon every change you hand back.- A page script cannot become a background or scheduled script (or the reverse) under the same
@name+@namespace: ScriptCat rejects that install with a script type mismatch. Give a temporary script of the other type its own@name.
Permissions
- Every API needs a
@grantline (@grant GM_xmlhttpRequest, …). An ungranted API is simply undefined at runtime. GrantingGM_fooalso exposesGM.fooand vice versa — only when the names match exactly:GM.xmlHttpRequestneeds its own@grant GM.xmlHttpRequest(@grant GM_xmlhttpRequestdoes not expose it). GM_infoneeds no grant.unsafeWindowneeds no grant either, but only exists in the sandbox (any grant other thannone, or no@grantline at all);@grant unsafeWindowis harmless.@grant noneruns the script without the sandbox:windowis the page's own window, and the only API isGM_info/GM.info— no other GM API and nounsafeWindow(referencing it throws aReferenceError). Use it only for scripts that need nothing but the page.- With any other grant — and also with no
@grantline at all, unlike Tampermonkey — the script is sandboxed: itswindowis not the page's. Reach page globals (a site's own JS objects, variables it defines) throughunsafeWindow. - Declare every host you request with
@connect <host>(it also covers the host's subdomains;@connect selfcovers subdomains of the page's host; requests to exactly the page's host need nothing). For a host that is not covered,GM_xmlhttpRequestis refused ("This domain is not a part of the @connect list") as soon as the script has any@connectline, unless the user allowed that host before; only a script with no@connectat all asks the user instead.GM_downloadin native mode always asks, andGM_cookiethrows for a host outside@connect.
Page timing and SPAs
@run-at:document-start(as early as possible),document-end(DOM parsed),document-idle(the default; everything loaded),document-body(wait until<body>exists),context-menu(run when the user picks the script from the page's right-click menu). Only the first value counts, and an unknown value silently falls back to the default.- Add
@early-starttogether withdocument-startwhen the script must beat the page's own scripts, and wait forCAT_scriptLoaded()before relying on the full API. - Single-page apps change the URL without reloading, so a page script runs once and then misses later views.
Listen with
@grant window.onurlchangeandwindow.addEventListener("urlchange", e => …), and use aMutationObserverfor content that renders late. Never assume an element exists at injection time — wait for it. @noframeskeeps the script out of iframes; without it, a*://*/*match also runs inside every iframe.@inject-into contentruns in the content-script world: unaffected by the page's CSP, butunsafeWindowis then not the page'swindow. The default ispage.GM_addStyleandGM_addElementbypass the page's CSP; prefer them over creating<style>/<script>by hand. Exception: on Firefox a<script>injected withGM_addElementis still subject to the page's CSP.
Storage
GM_setValuestores JSON-like data only (no class instances). Settingundefineddeletes the key (Tampermonkey stores it instead).- Writes are asynchronous. Before
window.close()or the end of a background run,await GM.setValue(...)/await GM.setValues(...)so the write is not lost. @storageName <name>lets several scripts share one value store;GM_addValueChangeListenersees writes from the other scripts (and from other tabs) — a simple cross-script channel.
Background and scheduled scripts
- Return a
Promiseand settle it after the last asynchronous step. Once it resolves or rejects, ScriptCat treats the run as finished and later GM calls from that run are not guaranteed to work. ScriptCat wraps the body in anasyncfunction, so a body that returns nothing is marked complete as soon as its synchronous part (and any top-levelawait) finishes — pending callbacks and timers do not keep the run open. resolve(value)is logged as success,reject(err)as an error; the script list then shows the run status as error, and the message is in the log.- To retry,
reject(new CATRetryError("reason", seconds))(or aDate).CATRetryErroris undefined under@grant none; it exists with any other grant or with no@grantline. The retry queue is checked every 5 seconds, so a retry fires up to 5 seconds late; keep run time plus retry delay shorter than the cron interval so runs do not overlap. - Write exactly one
@crontabline. Every line is scheduled at runtime, but installation validates and the script list shows only the first, and one invalid extra line stops all of the script's jobs. Use 5 fields (min hour day month weekday); a 6-field form with seconds exists but is not recommended. Theonceextension limits a field's period to one run, counted when the run starts — a failed run uses up the period too, so retry failures withCATRetryError:* * once * *= at most once a day,* once * * *= at most once an hour,* once(9-17) * * *= once in each hour from 9 to 17. Full cron andoncerules: references/background.md. - Log with
GM_log(message, "debug" | "info" | "warn" | "error"): it lands in ScriptCat's log, the only place a background script's output shows up — ScriptCat's Logs page (filter by the script'snameoruuid), orsctl logs. The script list shows only the run status (running / error / stopped) and a scheduled script's next run time. Release builds do not storedebug, so log anything someone must read atinfoor above.
User configuration
- A
/* ==UserConfig== … ==/UserConfig== */YAML block after the header gives the script a settings form in ScriptCat. Read a value withGM_getValue("group.key"). Format: references/userconfig.md.
4. API lookup
references/api.md lists every GM and CAT API ScriptCat implements, with the grant name, the
cases where ScriptCat differs from Tampermonkey, and which APIs are unavailable in the background. Read it
before using an API you are unsure about, then check the exact signature in scriptcat.d.ts.
references/patterns.md has ready-made building blocks: waiting for an element, single-page-app route changes, a persistent menu switch, cross-origin requests, styles, localisation, and a background run with retry.
5. Install and verify
Writing the file is half the job; the other half is seeing it run.
First run the static check bundled with this skill (Node 18+, no dependencies; paths are relative to this skill's directory):
node scripts/check.mjs my-script.user.js # exit 1 = errors that will break the script at runtime
It reports error|warn <rule> <file>:<line> <message>: APIs used without their @grant, GM APIs or
unsafeWindow under @grant none, a page script without @match, invalid @crontab expressions, request hosts
missing from @connect, and similar. Fix every error; read each warning and fix it or say why it does not apply.
It is a static check — it cannot tell whether the script does what the user asked.
- sctl is available (
sctl statusshows ScriptCat connected): install it into the user's ScriptCat and verify it in their browser, following references/dev-loop.md. It also covers scouting the target page before you write code, iterating on a local file without an approval per change, and running background and scheduled scripts and reading their logs (sctl run/sctl logs). That loop runs inside the user's real browser, so the sctl skill's rules apply too — read it first if it is installed. - No sctl: save the code as
<name>.user.jsand tell the user to install it — drag the file onto the ScriptCat dashboard, or create a new script in ScriptCat and paste the code. Say which page to open (page script) or where to look (background: the run status in the script list, and the script's output on ScriptCat's Logs page).
Whichever path you take, report what you actually observed: "installed and the button appears on example.com" is a result; "should work" is not.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/scriptscat/scriptcat/scriptcat-userscript">View scriptcat-userscript on skillZs</a>