# 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**. They are copied from the local checkout
(the same source as the gateway config — see "Where the config comes from" in
`mcp-config/README.md`), so no anonymous read of this repo is required. Add a
skill here, push to `main`, and it lands everywhere within the sync TTL (~1h,
or immediately on a new shell) once the checkout picks the commit up.

> 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`.