opencode-skill-usage-tracker

An opencode plugin that records every skill invocation across your sessions so you can inspect which skills get used, when, and how.

What

opencode-skill-usage-tracker is an opencode plugin that passively logs skill usage. Each time a skill runs, whether triggered as a slash command or through the skill tool, it appends a JSON record to a local log file. A companion skill-log tool lets the agent query that log during a session.

Why

Once you accumulate a large library of skills, it becomes hard to know which ones you actually rely on and which sit unused. This plugin exists to make skill usage observable without changing how skills run, giving you the data to prune, prioritize, and improve your skill set over time.

Included

• Hooks both invocation paths: slash commands (command.execute.before) and the skill tool (tool.execute.before)
• Ignores built-in commands (init, review) so the log only reflects real skill activity
• Appends one JSON line per invocation with timestamp, session ID, skill name, source, and arguments
• Exposes a skill-log tool the agent can call to query recent invocations
• skill-log supports filtering by session ID and a configurable result limit
• Pure local logging to ~/.local/share/opencode/skill-usage-tracker.jsonl, no network calls

Roadmap

• Add date-range and skill-name filtering to skill-log
• Return usage counts and aggregations (most-used skills, per-session breakdown)
• Automatic log rotation to bound file size

Out of Scope

• Modifying or intercepting skill behavior, only passive observation
• Remote telemetry or exporting logs to an external service

Requirements

• opencode
• Bun runtime (the plugin reads the log via Bun.file)
• A POSIX system (Linux or macOS) with a writable ~/.local/share/opencode/ directory

Install

opencode does not load plugins directly from a Git URL. Use one of the two supported methods below. Both require the single file skill-usage-tracker.ts from this repository.

Option 1: Drop it into the plugins directory (simplest)

Files in the plugin directories are auto-loaded at startup, no config entry needed.

# Global (all projects)
cp skill-usage-tracker.ts ~/.config/opencode/plugins/

# Project-level (this project only)
cp skill-usage-tracker.ts .opencode/plugins/

opencode globs {plugin,plugins}/*.{ts,js} in these directories, so either folder name works.

Option 2: Reference it from config

Clone this repo somewhere stable, then point at the file with a relative or file:// path in your opencode.json (or opencode.jsonc). The plugin key is an array of package strings or { "package", "options" } objects:

{
  "plugin": ["./skill-usage-tracker.ts"]
}

Relative paths resolve against the config file's directory; absolute local paths are also accepted.

Note: The plugin array otherwise expects npm package names (e.g. "@my-org/custom-plugin"). This plugin is not currently published to npm, so a Git URL like https://github.com/TomzxCode/opencode-skill-usage-tracker is not a valid value and will not resolve.

Getting Started

After installing, just use your skills normally. Each invocation is logged automatically. To inspect the log, ask the agent, for example:

• "Show me the last 20 skills I used."
• "Which skills ran in session abc123?"

The skill-log tool accepts:

Argument	Type	Default	Description
limit	number	50	Maximum number of entries
session	string	-	Restrict results to a session ID

You can also read the raw JSONL file directly with any log analysis tool:

tail -n 50 ~/.local/share/opencode/skill-usage-tracker.jsonl

License

The code is licensed under the MIT license. See LICENSE.