noconnorandClaude Opus 4.8
c0d67f023a
Models and MCP servers are discovered from the LiteLLM gateway at sync time
(/v1/models, and the aggregate /mcp/ endpoint). Skills have no gateway side to
query: LiteLLM's /v1/skills is a passthrough to Anthropic's Skills API, which
lists skills on an Anthropic account rather than serving skill files, and
/public/skill_hub is a marketplace catalog. So the repo is the source of truth
and the tree is fetched whole, from the repo tarball.
Deploy to ~/.config/mcp-sync/skills rather than ~/.config/opencode/skills so
the atomic replace can never delete a skill the user wrote by hand; opencode
picks the tree up via skills.paths, which expands {env:HOME} — verified — so
the shared config stays identical for every user.
Same throttle and non-fatal discipline as the config sync: a fetch that yields
no skills/ leaves the last-good tree in place instead of emptying it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
58 lines
2.0 KiB
Markdown
58 lines
2.0 KiB
Markdown
# skills — shared opencode skills
|
||
|
||
Skills every covert-gpt user gets. `mcp-config/sync.sh` deploys this directory
|
||
to `~/.config/mcp-sync/skills` on each box; the shared `opencode.gateway.json`
|
||
points opencode at it via `skills.paths`.
|
||
|
||
Unlike models and MCP servers — which are discovered from the LiteLLM gateway
|
||
at sync time — skills are plain files with nothing on the gateway to query, so
|
||
**this repo is the source of truth**. Add a skill here, push to `main`, and it
|
||
lands everywhere within the sync TTL (~1h, or immediately on a new shell).
|
||
|
||
> LiteLLM's `/v1/skills` is *not* an alternative: it is a passthrough to
|
||
> Anthropic's Skills API (`?beta=true`), which lists skills on an Anthropic
|
||
> account. It does not serve skill files to a client, and opencode cannot read
|
||
> it. `/public/skill_hub` is a marketplace catalog, also not a skill source.
|
||
|
||
## Layout
|
||
|
||
One folder per skill, each with a `SKILL.md`:
|
||
|
||
```
|
||
skills/
|
||
my-skill/
|
||
SKILL.md # required
|
||
reference.md # optional supporting files
|
||
```
|
||
|
||
`SKILL.md` needs YAML frontmatter with `name` and `description`. `name` must be
|
||
1–64 chars, lowercase alphanumeric with single-hyphen separators, and match the
|
||
folder name. `description` is 1–1024 chars and is what the model reads to decide
|
||
whether to pull the skill in — write it to say *when to use this*, not just what
|
||
it is.
|
||
|
||
```markdown
|
||
---
|
||
name: my-skill
|
||
description: Use when doing X. Covers Y and Z.
|
||
---
|
||
|
||
Body: the instructions the model follows once the skill is loaded.
|
||
```
|
||
|
||
## Don't put per-user things here
|
||
|
||
Same rule as the MCP gateway: this tree is **identical for every user**. Skills
|
||
that depend on one person's credentials, kubeconfig, or local paths belong in
|
||
that user's own `~/.config/opencode/skills/`, which sync never touches.
|
||
|
||
## Verifying
|
||
|
||
```sh
|
||
opencode debug skill # lists every skill opencode can see, with its path
|
||
```
|
||
|
||
If a skill you added here is missing, check that the sync ran (`ls
|
||
~/.config/mcp-sync/skills`) and that the folder name matches the frontmatter
|
||
`name`.
|