opencode-skills-notifier

An OpenCode plugin that watches GitHub repositories for new agent skills and notifies you via an in-editor toast when new skills are available to install.

Requirements

• OpenCode with plugin support
• git available in PATH

Installation

Add the plugin to ~/.config/opencode/config.json (create it if it doesn't exist):

{
  "plugin": ["opencode-skills-notifier"]
}

To pass configuration options alongside the plugin:

{
  "plugin": [
    [
      "opencode-skills-notifier",
      {
        "enabled": true,
        "repositories": ["[email protected]:your-org/your-skills-repo.git"],
        "skillsScope": "both"
      }
    ]
  ]
}

OpenCode will automatically fetch and install the package on next startup.

Configuration

| Option | Type | Default | Description | | -------------- | ------------------------------------- | -------- | ---------------------------------------------------------------------------- | | enabled | boolean | true | Master switch — set to false to disable the plugin entirely | | repositories | string[] | [] | Explicit list of Git repo URLs to monitor | | skillsScope | "global" | "project" | "both" | "both" | Where to look for locally installed skills when filtering already-known ones |

Implicit repo discovery: even without listing repos explicitly, the plugin reads the .git/config of every directory inside .agents/skills/ and checks the origin remote — so repos you've already cloned are monitored automatically.

Skills scope:

• "global" — checks ~/.agents/skills/
• "project" — checks <project>/.agents/skills/
• "both" — checks both (default)

Cache

The plugin stores state in ~/.config/opencode/skills-notifier-cache.json:

{
  "repos": {
    "[email protected]:example/my-skills.git": {
      "last_commit_hash": "abc123...",
      "known_skills": ["skill-a", "skill-b"]
    }
  },
  "notified_skills": ["skill-a", "skill-b"]
}

Delete this file to force a full re-check on the next session.

Development

# Install dependencies
bun install

# Type-check without emitting
bun run typecheck

# Watch mode (recompiles on save)
bun run dev

# Run all tests
bun test

Project layout

src/
  index.ts        Plugin entry point — registers the session.created hook
  checker.ts      Core logic: repo scanning and toast dispatch
  discovery.ts    Local repo + skills discovery from .agents/skills/
  cache.ts        Read/write ~/.config/opencode/skills-notifier-cache.json
  config.ts       Parse plugin config from PluginOptions
  types.ts        Shared TypeScript interfaces (Cache, PluginConfig)
  shell.ts        Thin re-export of Bun's $ shell helper
  *.test.ts       Unit tests (bun:test)
dist/             Compiled output (generated by tsc)

Running tests

bun test

Tests use bun:test with module mocking. Each source file has a co-located *.test.ts.

How it works

On every session start, the plugin:

1. Reads configuration from plugin options in ~/.config/opencode/opencode.json
2. Discovers repos implicitly from any locally cloned skills in .agents/skills/
3. Merges them with the explicit repositories list from config
4. For each repo, fetches the remote HEAD hash via git ls-remote and compares it to the cache
5. If the hash changed (or is new), shallow-clones the repo and reads its top-level directories as skill names
6. Filters out skills already notified or already installed locally
7. Shows a toast with the new skill names and the install command(s)
8. Persists updated hashes and notified skills to ~/.config/opencode/skills-notifier-cache.json

The check runs fire-and-forget so it never blocks session startup.

License

GPL-3.0