> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta skill

> Push and version skills.

Manage [skills](/docs/capabilities/skills) — persisted, versioned expertise loaded with progressive disclosure.

## Commands

| Command                            | Description                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------- |
| `vetta skill push`                 | Create or update a skill from a `SKILL.md` file (new version), **by slug**. |
| `vetta skill push-version <skill>` | Push a new version of a skill that **already exists**, by id or slug.       |
| `vetta skill list`                 | List skills in the org.                                                     |
| `vetta skill show <slug>`          | Show a skill's current version.                                             |
| `vetta skill versions <slug>`      | List version history.                                                       |
| `vetta skill version <slug> <n>`   | One version, **including its content**.                                     |
| `vetta skill rm <slug>`            | Delete a skill.                                                             |

## push

```bash theme={"system"}
vetta skill push --slug refund-policy --file ./skills/refund-policy/SKILL.md
```

Each push is content-addressed by a hash over the whole file, so an identical push is a no-op and any change creates a new immutable version.

```json theme={"system"}
{
  "slug": "refund-policy",
  "name": "refund-policy",
  "version": 3,
  "sha256": "b1946ac9...",
  "description": "How to evaluate and process customer refund requests within policy."
}
```

| Flag            | Description                                            |
| --------------- | ------------------------------------------------------ |
| `--slug`        | The skill's slug (required).                           |
| `--file`        | Path to the `SKILL.md` body. Defaults to `./SKILL.md`. |
| `--description` | Optional one-line description stored with the skill.   |

## push-version

`push` is addressed at a **slug** and creates the skill when that slug is unknown. `push-version` is addressed at a skill that **already exists** — by id or by slug — and answers `404 not_found` when it does not. A release pipeline pinned to a skill id wants this one, so a rename cannot silently mint a second skill.

```bash theme={"system"}
vetta skill push-version skl_2sm3cgp2c7yzz5vscfqyaasdfr --file ./skills/refund-policy/SKILL.md
vetta skill push-version --skill refund-policy --file ./skills/refund-policy/SKILL.md
```

```json theme={"system"}
{
  "version": 2,
  "sha256": "4b3e74d57ebbcb8a0af871b11de338f560f4db1cf42af70090b94275a6337381",
  "size_bytes": 23,
  "created_at": "2026-08-23T05:47:42.700Z",
  "id": "skl_2sm3cgp2c7yzz5vscfqyaasdfr",
  "slug": "parity-demo-d33"
}
```

| Flag      | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `--skill` | Skill id or slug. May also be given as the first positional argument. |
| `--file`  | Path to the `SKILL.md` body. Defaults to `./SKILL.md`.                |

An unknown skill is a hard error rather than a create — that is the entire difference from `push`:

```
error: not_found: no such skill: skl_does_not_exist_xxxxxxxxx (req_4dbetv5ejeyjvkyt2f3ktpay9x)
```

The same operation is [`client.skills.pushVersion`](/docs/sdk/typescript#method-index) in the SDK and `POST /v1/skills/{id}/versions` in the [API reference](/docs/api/skills).

## Attaching to an agent

Skills are referenced on the agent by slug. A **bare slug floats** to the latest version at session start; a **`slug@N` reference pins** an immutable version that never moves when someone pushes a new `SKILL.md`:

```bash theme={"system"}
vetta agent create --name Refunder --model zai-org/GLM-5.2-FP8 \
  --skill refund-policy@3 --skill escalation-matrix \
  --budget-usd 50 --max-task-usd 5 --budget-period month
```

Here `refund-policy@3` is frozen to version 3 for reproducibility, while `escalation-matrix` resolves to the latest version at session start. Use `vetta skill versions <slug>` to see the pinnable version numbers.

## version

`vetta skill versions` lists the version numbers; `vetta skill version` returns one of them in full,
and it is the only command that returns the skill's **content**. That split is deliberate — a
history listing stays small no matter how large the skills are.

```bash theme={"system"}
vetta skill version parity-demo-27e5fc9d 1
```

```json theme={"system"}
{
  "id": "skl_sn4ajzazpade2v1hj4gmkyerpe",
  "slug": "parity-demo-27e5fc9d",
  "version": 1,
  "sha256": "5f22eb6cabbfe6b898548754a4da28d7e6d4e54d53a80780088d28662fe4869f",
  "size_bytes": 14,
  "created_at": "2026-08-23T00:43:41.571Z",
  "content": "# Demo\nfirst.\n"
}
```

The `sha256` is over the content exactly as stored, so a pin of `slug@N` is reproducible: re-pushing
identical bytes is a no-op and mints no new version.