Skip to content

About

An OpenCode plugin to refresh Git-backed skills on demand—fetch updates, sync installed skills, and reload without restarting.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

opencode-skills-refresh

Refresh Git-backed OpenCode skills on demand: fetch updates, sync installed skills, and reload without restarting the service.

/refresh-skills           # Refresh every configured repository
/refresh-skills xskills   # Refresh only the repository named xskills

This is an OpenCode V2 plugin, tested with OpenCode 2.2.5. It includes a native server command and terminal success/error notifications. Refreshing does not ask an AI model to run shell commands or generate a response.

Install

Install directly from GitHub; no npm release is required:

opencode plugin add github:xross/opencode-skills-refresh

Alternatively, clone this repository, run npm ci --ignore-scripts, and configure the checkout directory in ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["/absolute/path/to/opencode-skills-refresh"]
}

Preserve any other plugin entries you already have. OpenCode reloads configuration automatically. Git must be installed and authenticated for the repositories you want to refresh. Local development/tests require Node.js 22.19 or newer.

Configure repositories

Create ~/.config/opencode/skills-refresh.json (or $XDG_CONFIG_HOME/opencode/skills-refresh.json):

{
  "repositories": [
    {
      "name": "xskills",
      "url": "git@github.com:xmos/xskills.git",
      "ref": "develop"
    },
    {
      "name": "team",
      "url": "https://github.com/example/team-skills.git",
      "ref": "main",
      "skills": { "exclude": ["experimental"] }
    }
  ]
}

The team repository is a placeholder: replace it with a repository you can access. Omit name to derive it from the repository basename: xmos/xskills.git becomes xskills. Names must be unique, lowercase, and contain only letters, digits, dots, hyphens or underscores. Set explicit names for repositories with the same basename. Commands accept exactly one optional name; unknown names list the available choices without changing anything.

Field Meaning
name Optional command selector; defaults to the repository basename
url HTTPS/SSH Git URL, absolute local Git repository path, or file:// Git URL
ref Required branch name, such as main or develop
skills Optional "*", { "include": ["name"] }, or { "exclude": ["name"] }
repoPath Optional checkout/cache directory
installRoot Optional directory containing this repository's installed skill links

Filters use exact installed directory names, not wildcard patterns. An empty include list deliberately uninstalls this repository's managed links.

Paths support ~; relative paths resolve against the configuration file's directory. Cache and install directories must be separate, non-overlapping directories, including across repositories. A custom installRoot must be inside an OpenCode skill source, or be added to OpenCode's skills configuration.

Defaults

For skills-refresh.json:

  • Checkouts: ~/.cache/opencode/skills-refresh/repos/<repository-id> ($XDG_CACHE_HOME is respected).
  • Installed links: <config-directory>/skills/_repos/<name>.

The first refresh clones missing repositories. Subsequent refreshes fetch the configured branch and fast-forward the checkout. A repository should contain skills/<skill-name>/SKILL.md or the legacy skill/<skill-name>/SKILL.md layout. Grouped directories are supported; skills/group/review/SKILL.md is installed as group-review. Keep skill IDs unique across repositories and other installed skills to avoid OpenCode precedence conflicts.

Existing remote-config users

If skills-refresh.json does not exist, the plugin reads the global remote-config.json used by opencode-remote-config. It derives names from URLs and preserves that plugin's existing checkout and symlink locations:

~/.cache/opencode/remote-config/repos/<repository-id>
<config-directory>/skill/_plugins/<name>

Legacy caches continue to use ~/.cache even when XDG_CACHE_HOME is set. This compatibility applies to files named remote-config.json. Only Git-backed skills are managed; agents, commands, instructions, and remote plugins are not imported. The old plugin's installMethod: "copy" and non-Git local-directory mode are not supported. Do not run two sync plugins against the same cache/install directories.

/refresh-xskills remains an alias for /refresh-skills xskills.

Use a different configuration file

Pass a file path through plugin options:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    {
      "package": "github:xross/opencode-skills-refresh",
      "options": { "configFile": "./.opencode/skills-refresh.json" }
    }
  ]
}

This configFile path resolves against the active OpenCode location, not against opencode.jsonc. Configuration is re-read for every command, so repository-list changes need no service restart.

Refresh behavior and safety

  • Refresh is manual. There is no startup fetch or periodic background polling.
  • /refresh-skills attempts each configured repository and reports each outcome. One failure does not prevent other repositories from refreshing.
  • /refresh-skills <name> never fetches or changes other repositories.
  • Successful repositories are installed before skills are reloaded once in the command's current OpenCode location. Other already-loaded locations may need /reload to observe changes.
  • Tracked/untracked local edits, local-only commits, divergent history, unexpected origins, and unexpected branches stop that repository's refresh. The plugin never resets, stashes, or force-pulls your work.
  • Only managed symlinks pointing into the corresponding skill checkout are replaced or removed. Local directories and unrelated links are preserved.
  • Fetch failures leave existing installed links untouched. An invalid/empty upstream skill tree also stops link cleanup. A checkout may already have fast-forwarded if a later installation step fails; it is not rolled back.
  • Git subprocesses have a two-minute timeout and non-interactive authentication. A shared filesystem lock prevents simultaneous updates to the same checkout.
  • On Windows, directory junctions are used instead of privilege-requiring symlinks.

Use only repositories and configuration you trust. Skills become instructions for your agent; review upstream changes before relying on newly updated guidance. Git uses your existing credentials and configuration. Do not embed tokens/passwords in repository URLs; use SSH keys or a Git credential helper.

Tags/commit pins, copied installs, and flat Markdown-only skill layouts are not supported in this initial version. Updating this plugin itself is separate from refreshing skills; use opencode plugin check / opencode plugin update for a Git-installed plugin.

Stale locks

Normally a lock is removed even when a refresh fails. If OpenCode is killed during a refresh, the error names the remaining <repoPath>.refresh-lock directory. First verify that no refresh is running in any OpenCode process, then remove only that empty lock directory with rmdir and retry. Locks are not automatically broken because that could race with a live Git operation.

Development

npm ci --ignore-scripts
npm test
npm pack --dry-run

Tests use temporary local Git repositories and never contact the network. They cover multi-repository selection, first-time clones, updates, filters, link cleanup, partial failures, local-work protection, locking, command reporting, and terminal notification routing. CI runs on Linux, macOS and Windows with Node.js 22 and 24.

License

Licensed under the MIT License.

About

An OpenCode plugin to refresh Git-backed skills on demand—fetch updates, sync installed skills, and reload without restarting.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages