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 directly from GitHub; no npm release is required:
opencode plugin add github:xross/opencode-skills-refreshAlternatively, clone this repository, run npm ci --ignore-scripts, and configure
the checkout directory in ~/.config/opencode/opencode.jsonc:
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.
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.
For skills-refresh.json:
- Checkouts:
~/.cache/opencode/skills-refresh/repos/<repository-id>($XDG_CACHE_HOMEis 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.
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.
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 is manual. There is no startup fetch or periodic background polling.
/refresh-skillsattempts 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
/reloadto 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.
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.
npm ci --ignore-scripts
npm test
npm pack --dry-runTests 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.
Licensed under the MIT License.
{ "$schema": "https://opencode.ai/config.json", "plugins": ["/absolute/path/to/opencode-skills-refresh"] }