feat: add userscript skill and migrate tooling to bun

.github/workflows/markdown-fix.yml

@@ -25,17 +25,16 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v5
 
-      - name: Set up Node.js
+      - name: Set up Bun
-        uses: actions/setup-node@v5
+        uses: oven-sh/setup-bun@v2
         with:
-          node-version: "24"
+          bun-version: "1.3.11"
-          cache: npm
 
       - name: Install dependencies
-        run: npm ci
+        run: bun install --frozen-lockfile
 
       - name: Format Markdown
-        run: npm run format:md
+        run: bun run format:md
 
       - name: Detect changes
         id: changes

.github/workflows/markdown.yml

@@ -8,7 +8,7 @@ on:
       - ".prettierignore"
       - ".prettierrc.json"
       - "package.json"
-      - "package-lock.json"
+      - "bun.lock"
       - ".github/workflows/markdown.yml"
   pull_request:
     paths:
@@ -17,7 +17,7 @@ on:
       - ".prettierignore"
       - ".prettierrc.json"
       - "package.json"
-      - "package-lock.json"
+      - "bun.lock"
       - ".github/workflows/markdown.yml"
   workflow_dispatch:
 
@@ -34,14 +34,13 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v5
 
-      - name: Set up Node.js
+      - name: Set up Bun
-        uses: actions/setup-node@v5
+        uses: oven-sh/setup-bun@v2
         with:
-          node-version: "24"
+          bun-version: "1.3.11"
-          cache: npm
 
       - name: Install dependencies
-        run: npm ci
+        run: bun install --frozen-lockfile
 
       - name: Check Markdown formatting
-        run: npm run check:md
+        run: bun run check:md

AGENTS.md

@@ -11,7 +11,7 @@ This repository maintains a curated set of Agent Skills for practical engineerin
 Key technologies:
 
 - Markdown for all skill instructions and references
-- Node.js + npm for repository tooling
+- Bun for repository tooling
 - Prettier for Markdown formatting checks
 - GitHub Actions for CI formatting validation and optional formatting fixes
 
@@ -39,19 +39,19 @@ Top-level files to keep in sync when relevant:
 Install the repository tooling:
 
 ```bash
-npm ci
+bun install
 ```
 
 Check Markdown formatting:
 
 ```bash
-npm run check:md
+bun run check:md
 ```
 
 Format Markdown files in place:
 
 ```bash
-npm run format:md
+bun run format:md
 ```
 
 ## Development Workflow
@@ -74,19 +74,19 @@ There is no unit test suite in this repository today. The primary validation is
 Before finishing a change, run:
 
 ```bash
-npm run check:md
+bun run check:md
 ```
 
 If formatting fails, run:
 
 ```bash
-npm run format:md
+bun run format:md
 ```
 
 Then re-run:
 
 ```bash
-npm run check:md
+bun run check:md
 ```
 
 If you changed workflow or package metadata, make sure those files still align with the commands above:
@@ -120,7 +120,7 @@ There is no application deployment pipeline in this repository.
 
 Before opening or updating a PR:
 
-- Run `npm run check:md`.
+- Run `bun run check:md`.
 - If you added a new skill, verify its folder matches the expected layout.
 - Verify README catalog entries and links still resolve.
 - Keep changes scoped to the skill or documentation you intended to modify.

README.md

@@ -46,6 +46,7 @@ The table below lists the skills maintained in this repository.
 
 | Name                                                                                                   | Description                                                                                                                                                                    | Bundled Assets            |
 | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
+| [`develop-userscripts`](./skills/develop-userscripts/SKILL.md)                                         | Build, debug, package, and publish browser userscripts for Tampermonkey and ScriptCat, including ScriptCat background, cron, config, and subscription workflows.               | `references/`             |
 | [`github-actions-docs`](./skills/github-actions-docs/SKILL.md)                                         | Write, migrate, secure, and troubleshoot GitHub Actions workflows with official docs.                                                                                          | `references/`             |
 | [`openclaw-secure-linux-cloud`](./skills/openclaw-secure-linux-cloud/SKILL.md)                         | Securely self-host OpenClaw on cloud servers.                                                                                                                                  | `references/`             |
 | [`opensource-guide-coach`](./skills/opensource-guide-coach/SKILL.md)                                   | Start, grow, govern, fund, and sustain open source projects.                                                                                                                   | `references/`             |

README.zh.md

@@ -45,7 +45,8 @@ npx skills add xixu-me/skills
 下表列出了此存储库中维护的 skills。
 
 | 名称                                                                                                   | 说明                                                                                                                       | 附带资源                  |
-| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| [`develop-userscripts`](./skills/develop-userscripts/SKILL.md)                                         | 为 Tampermonkey 和 ScriptCat 编写、调试、打包并发布浏览器 userscripts，包括 ScriptCat 的后台、定时、用户配置和订阅工作流。 | `references/`             |
 | [`github-actions-docs`](./skills/github-actions-docs/SKILL.md)                                         | 基于官方文档编写、迁移、加固并排查 GitHub Actions workflows。                                                              | `references/`             |
 | [`openclaw-secure-linux-cloud`](./skills/openclaw-secure-linux-cloud/SKILL.md)                         | 在云服务器上安全地自托管 OpenClaw。                                                                                        | `references/`             |
 | [`opensource-guide-coach`](./skills/opensource-guide-coach/SKILL.md)                                   | 启动、发展、治理、资助并长期维护开源项目。                                                                                 | `references/`             |

bun.lock

@@ -0,0 +1,15 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "xixu-me-skills",
+      "devDependencies": {
+        "prettier": "^3.5.3",
+      },
+    },
+  },
+  "packages": {
+    "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
+  }
+}

package-lock.json

@@ -1,29 +0,0 @@
-{
-  "name": "xixu-me-skills",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "xixu-me-skills",
-      "devDependencies": {
-        "prettier": "^3.5.3"
-      }
-    },
-    "node_modules/prettier": {
-      "version": "3.8.1",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.1.tgz",
-      "integrity": "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==",
-      "dev": true,
-      "license": "MIT",
-      "bin": {
-        "prettier": "bin/prettier.cjs"
-      },
-      "engines": {
-        "node": ">=14"
-      },
-      "funding": {
-        "url": "https://github.com/prettier/prettier?sponsor=1"
-      }
-    }
-  }
-}

package.json

@@ -1,6 +1,7 @@
 {
   "name": "xixu-me-skills",
   "private": true,
+  "packageManager": "bun@1.3.11",
   "description": "Formatting helpers for this Agent Skills repository",
   "scripts": {
     "format:md": "prettier --write \"**/*.md\"",

skills/develop-userscripts/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: develop-userscripts
+description: Use when building, debugging, packaging, or publishing browser userscripts for Tampermonkey or ScriptCat, including GM APIs, metadata blocks, permission issues, @match/@grant/@connect setup, ScriptCat background or scheduled scripts, UserConfig blocks, or subscription workflows.
+---
+
+# Develop Userscripts
+
+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, update checks, or `GM_*` behavior
+- deciding between a portable foreground script and ScriptCat-only `@background` or `@crontab`
+- adding config UI with `==UserConfig==`
+- packaging a ScriptCat `==UserSubscribe==` bundle or preparing a CloudCat-compatible script
+
+Do not use this skill for full browser extension development or general browser automation outside userscript managers.
+
+## Runtime Selection
+
+```dot
+digraph userscript_runtime {
+    "Need page DOM or page context?" [shape=diamond];
+    "Need persistent or scheduled work?" [shape=diamond];
+    "Need to install many scripts as one package?" [shape=diamond];
+    "Portable foreground script" [shape=box];
+    "ScriptCat background or crontab script" [shape=box];
+    "ScriptCat subscription package" [shape=box];
+
+    "Need page DOM or page context?" -> "Portable foreground script" [label="yes"];
+    "Need page DOM or page context?" -> "Need persistent or scheduled work?" [label="no"];
+    "Need persistent or scheduled work?" -> "ScriptCat background or crontab script" [label="yes"];
+    "Need persistent or scheduled work?" -> "Need to install many scripts as one package?" [label="no"];
+    "Need to install many scripts as one package?" -> "ScriptCat subscription package" [label="yes"];
+    "Need to install many scripts as one package?" -> "Portable foreground script" [label="no"];
+}
+```
+
+## Preflight
+
+- Confirm the manager and browser. On Manifest V3 browsers, ScriptCat may require `Allow User Scripts` or browser developer mode before scripts run.
+- Decide page script versus background script before writing code. ScriptCat background scripts cannot touch the DOM.
+- Start with metadata, not implementation: `@match`, `@grant`, `@connect`, `@run-at`, and any update URLs.
+- Prefer portable `==UserScript==` patterns for ordinary page scripts. Only switch to ScriptCat-only headers when the requested behavior actually needs them.
+
+## Workflow
+
+1. Choose the runtime and metadata first.
+2. Declare the smallest permission surface that fits the task.
+3. Implement against the runtime you chose.
+4. Debug where the code really runs.
+   - Foreground scripts: page console plus manager logs.
+   - ScriptCat background scripts: run log first, then `background.html` for real-environment debugging.
+5. Publish with the right update model.
+   - Normal scripts: keep `@version` accurate and add `@updateURL` or `@downloadURL` only when needed.
+   - Subscription bundles: use `==UserSubscribe==`, HTTPS URLs, and subscription-level `@connect`.
+
+## Quick Reference
+
+| Intent                               | Default choice                               | Watch for                                                                 |
+| ------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------- |
+| Page UI, DOM scraping, page patching | Portable `==UserScript==`                    | `@match`, `@grant`, `@run-at`, CSP-sensitive injection                    |
+| Cross-origin API access              | `GM_xmlhttpRequest` with explicit `@connect` | Missing hosts, cookie behavior differences, user authorization            |
+| Long-running worker                  | ScriptCat `@background`                      | No DOM, must return `Promise` for async work                              |
+| Scheduled task                       | ScriptCat `@crontab`                         | Only first `@crontab` counts, prefer 5-field cron, avoid interval overlap |
+| User-editable settings               | `==UserConfig==` plus `GM_getValue`          | Block placement and `group.key` naming                                    |
+| Silent bundle install and updates    | `==UserSubscribe==`                          | HTTPS, `user.sub.js`, subscription `connect` overrides child scripts      |
+
+## Common Mistakes
+
+- Missing `@grant` for APIs the script actually uses.
+- Missing `@connect` for hosts used by `GM_xmlhttpRequest` or `GM_cookie`.
+- Treating `@include` as a better default than `@match` for ordinary host targeting.
+- Using DOM APIs inside ScriptCat background or cron scripts.
+- Returning from a ScriptCat background script before async GM work is truly finished.
+- Mixing `==UserScript==` and `==UserSubscribe==` packaging concepts.
+- Putting `==UserConfig==` in the wrong place or reading config keys without the `group.key` name.
+- Assuming Tampermonkey and ScriptCat storage, notification, or request behavior is identical.
+
+## References
+
+- [`references/metadata-and-api-map.md`](./references/metadata-and-api-map.md)
+- [`references/scriptcat-extensions.md`](./references/scriptcat-extensions.md)

skills/develop-userscripts/references/metadata-and-api-map.md

@@ -0,0 +1,97 @@
+# Metadata and API Map
+
+Distilled from the current Tampermonkey documentation and ScriptCat developer docs:
+
+- <https://www.tampermonkey.net/documentation.php>
+- <https://docs.scriptcat.org/docs/dev/api/>
+
+Use this reference to choose metadata and high-value APIs without copying the full upstream docs into the skill.
+
+## Portable Defaults
+
+- Start ordinary page scripts with `==UserScript==`, `@name`, `@namespace`, `@version`, and at least one `@match`.
+- Prefer `@match` for normal site targeting. Reach for `@include` only when you really need broader pattern matching.
+- Keep `@grant` minimal and explicit. If you use `GM_*`, list the exact APIs.
+- Add explicit `@connect` hosts for every domain touched by `GM_xmlhttpRequest` or `GM_cookie`.
+- Use `@run-at` only when timing matters. Do not add it by habit.
+- Keep update metadata simple: `@version` first, then `@updateURL`, `@downloadURL`, or `@supportURL` if the distribution model actually needs them.
+
+## Metadata Decisions
+
+| Key                                           | Use it for                      | Practical rule                                                                         |
+| --------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
+| `@match`                                      | page targeting                  | Default choice for normal host and path matching                                       |
+| `@include` / `@exclude`                       | legacy or broader pattern cases | Use sparingly when `@match` is not expressive enough                                   |
+| `@grant`                                      | privileged APIs                 | Declare only what the script uses so permissions stay readable                         |
+| `@connect`                                    | request and cookie hosts        | Prefer explicit hosts first; avoid `*` unless the use case truly requires it           |
+| `@run-at`                                     | injection timing                | Add it only when `document-start`, `document-end`, or `document-idle` changes behavior |
+| `@sandbox`                                    | Tampermonkey injection context  | Use only when page-context versus isolated-context behavior matters                    |
+| `@updateURL` / `@downloadURL` / `@supportURL` | update and support surfaces     | Keep them aligned with the actual release channel                                      |
+
+## Minimal Portable Template
+
+```javascript
+// ==UserScript==
+// @name         Example Foreground Script
+// @namespace    https://example.com/
+// @version      0.1.0
+// @match        https://app.example.com/*
+// @grant        GM_addStyle
+// @grant        GM_xmlhttpRequest
+// @connect      api.example.com
+// @run-at       document-idle
+// ==/UserScript==
+
+GM_addStyle(".userscript-ready { outline: 2px solid #0a7; }");
+
+GM_xmlhttpRequest({
+  method: "GET",
+  url: "https://api.example.com/status",
+  onload: (response) => console.log(response.responseText),
+});
+```
+
+## High-Value APIs
+
+### Storage
+
+- `GM_getValue`, `GM_setValue`, `GM_deleteValue`, and listeners are the first choice for script state.
+- In ScriptCat, `GM_setValue(name, undefined)` deletes the key instead of storing `undefined`.
+- In ScriptCat, data operations are asynchronous under the hood. If the page may close immediately after a write, prefer the `GM.*` promise form and await completion.
+
+### Menu Commands
+
+- `GM_registerMenuCommand` is useful for manual actions and diagnostics.
+- ScriptCat adds menu-specific options such as `autoClose`, `nested`, and `individual`.
+- Prefer stable IDs when you need to update or unregister the same command later.
+
+### Notifications
+
+- Use `GM_notification` for visible status, retries, or action prompts.
+- ScriptCat extends notification behavior with progress, buttons, and update or close helpers.
+- Treat those extra helpers as ScriptCat-specific, not portable Tampermonkey behavior.
+
+### Clipboard
+
+- `GM_setClipboard` is the safer default over raw page clipboard tricks.
+- ScriptCat does not support the Tampermonkey callback shape here, so write code that does not depend on it.
+
+### Tabs and Resources
+
+- `GM_openInTab` is the normal path for opening related pages.
+- In ScriptCat, prefer the `active` option and avoid old `loadInBackground` semantics unless you are explicitly matching Tampermonkey behavior.
+- `GM_getResourceText` and `GM_getResourceURL` are better than ad hoc fetches for packaged resources.
+
+### `GM_xmlhttpRequest`
+
+- Use it when same-origin fetch is blocked, cookies need manager support, or CSP interferes with ordinary requests.
+- Treat `@connect` as required design input, not an afterthought.
+- ScriptCat supports `text`, `arraybuffer`, `blob`, `json`, `document`, and `stream` response types, but documents partial feature differences and Firefox cookie caveats.
+- ScriptCat also documents support for special headers such as `user-agent`, `origin`, `referer`, `cookie`, and `host`.
+
+## Compatibility Notes
+
+- ScriptCat documents only a subset of Tampermonkey APIs and marks its extensions with `*`.
+- `GM_info.runAt` is not currently supported in ScriptCat, and `GM_info.sandboxMode` is currently only documented as `raw`.
+- Tampermonkey `@sandbox` is a high-leverage knob for page-context behavior. Do not assume ScriptCat gives you the same control surface.
+- Keep ordinary page scripts portable first. Move into ScriptCat-only runtime features only when the task needs background execution, cron, config blocks, or subscription packaging.

skills/develop-userscripts/references/scriptcat-extensions.md

@@ -0,0 +1,87 @@
+# ScriptCat Extensions
+
+Distilled from the current ScriptCat developer docs:
+
+- <https://docs.scriptcat.org/docs/dev/background/>
+- <https://docs.scriptcat.org/docs/dev/config/>
+- <https://docs.scriptcat.org/docs/dev/subscribe/>
+- <https://docs.scriptcat.org/docs/dev/cloudcat/>
+- <https://docs.scriptcat.org/docs/use/open-dev/>
+
+Use this reference when the task goes beyond a normal portable userscript.
+
+## `@background`
+
+- ScriptCat background scripts are ScriptCat-specific and run in a sandbox without DOM access.
+- Use them for persistent workers, manager-managed state, and tasks that should continue after script enablement or browser start.
+- Background logs show up in ScriptCat's run log via `GM_log`.
+
+## `@crontab`
+
+- Cron scripts are a form of background script for repeated scheduled work.
+- Only the first `@crontab` entry in a script is effective.
+- Prefer the standard 5-field cron form. ScriptCat also supports a 6-field seconds form, but its own docs discourage it.
+- ScriptCat adds `once` and `once(expr)` to prevent repeated execution inside the same time period.
+- Keep single-run time plus retry delay below the cron interval or runs can overlap.
+
+## Async Completion and `CATRetryError`
+
+- If a ScriptCat background or cron script does asynchronous work, return a `Promise`.
+- Resolve or reject only after the real work is finished. Once you settle the promise, ScriptCat considers the run complete and later GM operations may no longer take effect.
+- To request retry, reject with `new CATRetryError(message, seconds)`.
+- ScriptCat documents a minimum retry delay of 5 seconds.
+
+## Debugging Background Scripts
+
+- The editor can debug background scripts, but ScriptCat documents that value sync and registered menu commands do not behave like the real runtime there.
+- For real-environment debugging, enable browser support for userscripts first, then open the extension's `background.html` page from the extension settings.
+- On Manifest V3 browsers, ScriptCat may require `Allow User Scripts` or browser developer mode, depending on browser version and engine.
+
+## `==UserConfig==`
+
+- Place the `==UserConfig==` block after `==UserScript==`.
+- The config block uses YAML, not JavaScript object syntax.
+- ScriptCat exposes values through storage keys shaped like `group.key`, which you read with `GM_getValue`.
+
+## Minimal `==UserConfig==` Example
+
+```javascript
+// ==UserScript==
+// @name         Configurable Script
+// @namespace    https://example.com/
+// @version      0.1.0
+// @match        https://example.com/*
+// ==/UserScript==
+
+/* ==UserConfig==
+settings:
+  apiToken:
+    title: API Token
+    type: text
+    password: true
+    default: ""
+  enabled:
+    title: Enabled
+    type: checkbox
+    default: true
+==/UserConfig== */
+
+const enabled = GM_getValue("settings.enabled", true);
+```
+
+## `==UserSubscribe==`
+
+- Subscription packages must start with `==UserSubscribe==`, not `==UserScript==`.
+- ScriptCat recommends the `.user.sub.js` suffix for installation links and requires HTTPS.
+- Subscription install asks for confirmation once, then later updates are silent unless the declared `connect` permission changes.
+- A subscription can install multiple scripts through repeated `@scriptUrl` entries.
+- Subscription-level `@connect` overrides the child scripts' own `connect` metadata.
+- `@version` is the cleanest update signal. If omitted, ScriptCat falls back to content-change detection for the subscription file itself.
+
+## CloudCat Caveats
+
+- CloudCat is described as a FaaS-style path for cloud execution and is still documented as under development.
+- Uploading to cloud changes the meaning of `once` in cron expressions by collapsing it to the earliest matching time in the larger period.
+- Cloud execution only supports a reduced API set. ScriptCat currently documents `GM_xmlhttpRequest`, `GM_notification`, `GM_log`, and `GM_getValue`, with `GM_getValue` limited to exported values.
+- Use `@exportValue` and `@exportCookie` to describe which state or cookies move to the cloud runtime.
+- ScriptCat documents local export as a zip plus Node.js runner and Tencent Cloud as a hosted target.