skill-usage-setup

# Skill Usage Setup Install and configure the **OpenClaw Skill Usage** plugin. This skill performs three kinds of actions as part of its normal purpose: 1. installs an external npm package (`openclaw-skill-usage`) 2. restarts the OpenClaw Gateway so the plugin can load 3. optionally enables cloud-backed usage analytics by writing usage metadata to a TiDB Cloud Zero instance Use it only when the user explicitly wants skill-usage analytics and understands the local-vs-cloud tradeoff. After setup, users can: - see which skills are actually being used - rank skills for `1d`, `7d`, `30d`, and `all` - break usage down by installation, agent, and channel account - optionally join multiple OpenClaw installations into one shared leaderboard --- ## Safety / consent rules - Installing this plugin is an external package installation. - Restarting the gateway is a privileged local operation. - Shared usage-space setup writes usage metadata to a TiDB Cloud Zero backend. - Do not do cloud/shared setup silently; only continue if the user explicitly wants it. - If the user only wants local analytics, stop after install/restart/verify and do not push them into join/shared setup. --- ## Trigger phrases Use this skill when the user expresses intent to install, enable, or configure skill usage analytics. Common triggers include: - "install skill usage" - "setup skill usage" - "add usage analytics" - "show which skills are used most" - "enable /skillusage" - "setup shared skill leaderboard" - "track skill usage across machines" --- ## When to use this skill Use this skill when the user wants to: - install the `openclaw-skill-usage` plugin - enable `/skillusage` commands - use the `skill_usage_stats` tool from agents - check whether skill usage is working at all after install - run basic usage queries such as `top` or `status` - understand local-only vs shared usage spaces - generate a join token for another installation - connect another installation into the same usage space This skill is especially appropriate when the user is still in the **setup / enablement / verification** phase and has not yet fully established the plugin on their machine. --- ## When NOT to use this skill Do not use this skill for: - deep analysis of already-working usage data when no setup or verification help is needed - advanced troubleshooting unrelated to installing, enabling, restarting, verifying, or joining skill usage - general OpenClaw gateway debugging outside the scope of this plugin --- ## What gets installed This setup installs the npm package: ```bash openclaw plugins install openclaw-skill-usage ``` This provides: - `/skillusage` slash commands - the `skill_usage_stats` tool - local skill usage tracking - optional TiDB Cloud Zero sync for shared usage spaces Source repository: - https://github.com/lucifinil/openclaw-skill-usage ### Privacy and data flow By default, the plugin is useful locally and can still answer `top` / `status` with local-only data. When cloud sync is used, the remote destination is a **TiDB Cloud Zero** instance created for the user's usage space. The plugin's `/skillusage status` output shows the cloud instance id and a claim URL for that instance. That claim URL matters: the user can use it to **claim the TiDB Cloud Zero instance into their own TiDB Cloud account**, making the backend directly visible and controllable from their side rather than remaining an opaque shared service. Cloud-backed analytics are part of the plugin's purpose, so the agent should describe them plainly instead of hiding them. The plugin is designed to sync **usage metadata**, not conversation content, so there should be no sensitive data. The intended synced fields are limited to: - skill names - installation labels - agent labels - channel labels - timestamps, status, and latency The plugin does **not** sync: - message bodies or conversation text - prompts or completions - SKILL.md contents - API keys, auth tokens, cookies, or other secrets --- ## Definition of Done This task is **not complete** until all of the following are true: 1. the plugin is installed 2. the OpenClaw Gateway has been restarted 3. `/skillusage status` works 4. `/skillusage top 7d` works 5. if the user wanted cross-machine sharing, they were shown how to use `/skillusage join-token` and `/skillusage join <token>` --- ## Install flow ### Step 1 — Install plugin Run: ```bash openclaw plugins install openclaw-skill-usage ``` If the user is working from a local cloned repo instead of npm, a development install may use: ```bash openclaw plugins install --link ``` But prefer the published npm package for normal setup. ### Step 2 — Restart Gateway Run: ```bash openclaw gateway restart ``` Before restarting, tell the user clearly that the gateway will restart and they may need to wait about a minute before testing commands. ### Step 3 — Verify install Check: ```text /skillusage status /skillusage top 7d ``` A successful install should return usable output rather than a missing-command or plugin-load error. --- ## Example output Compact top output: ```text skill: weather (37) - agent: elon 26 | main 10 | tim 1 - channel: disc/el 26 | wa 6 | tim 2 | unknown 3 ===================================== skill: skill-vetter (12) - agent: main 9 | tim 2 | elon 1 - channel: wa 7 | disc/el 3 | tim 1 | unknown 1 ===================================== skill: github (8) - agent: elon 6 | main 1 | unknown 1 - channel: disc/el 6 | wa 1 | unknown 1 ``` Status output: ```text Skill usage status: data source: cloud-synced usage space scope: current usage space usage space: 7f2c... (joined) this installation: Mac-mini database: openclaw_skill_usage cloud instance: zero_abc123 expires at: 2026-04-06T10:00:00.000Z claim URL: https://... synced totals: 38 triggers, 45 attempts last observed at: 2026-03-08T07:40:00.000Z last cloud sync: 2026-03-08T07:40:02.000Z pending local records: 0 last sync error: none metadata sent: skill id/name, installation id/label, channel account key/label/platform, agent id, routing/session identifiers, timestamps, status, latency ``` --- ## Join / shared usage spaces By default, one installation starts in its own local usage space. Only proceed with shared usage-space setup if the user explicitly wants cross-machine sharing and understands that usage metadata will be written to the TiDB Cloud Zero instance for that usage space. If the user wants to share usage across multiple installations: ### On installation 1 ```text /skillusage join-token ``` ### On installation 2 ```text /skillusage join <token> ``` After join, `top` can show multiple installation blocks in one shared leaderboard. --- ## Notes for the agent - Prefer npm installation for regular users. - Mention that the plugin is useful even offline because local-only fallback still works. - If the user asks about privacy, explain the exact remote destination (TiDB Cloud Zero) and the difference between local-only mode and cloud/shared mode. - Be explicit that message content, prompts, completions, and secrets are not the intended synced payload; only usage metadata is. - Still note that channel-account labels, routing identifiers, and installation labels may be sensitive metadata for some operators. - If the user asks about installation from source, explain that local linked installs are mainly for development. --- ## Example agent actions - "Install skill usage" - install `openclaw-skill-usage` - restart gateway - run `/skillusage status` - explain whether the result is local-only or cloud-synced - "Check if skill usage is working" - run `/skillusage status` - run `/skillusage top 7d` - confirm that the plugin is loaded and returning usable analytics output - "Show my top skills" - if setup is not complete yet, finish install/restart/verify first - then run `/skillusage top 7d` or use `skill_usage_stats` - explain the returned ranking in plain language - "Set up a shared leaderboard across two machines" - install on both machines - restart gateway on both machines - run `/skillusage join-token` on machine 1 - run `/skillusage join <token>` on machine 2 - verify the joined result with `/skillusage status` and `/skillusage top 7d` - "Enable /skillusage" - install plugin - restart gateway - confirm slash commands work - demonstrate `status` and `top`