> ## 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](https://vetta.sh/docs/capabilities/skills.md) — 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. |
| `vetta skill catalog [slug]` | The platform's published skills; with a slug, its latest `SKILL.md`. |

## 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`](https://vetta.sh/docs/sdk/typescript#method-index) in the SDK and `POST /v1/skills/{id}/versions` in the [API reference](https://vetta.sh/docs/api/skills.md).

## 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 z-ai/glm-5.3-flash \
  --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.

A `naive/` prefix names the platform catalogue instead of your organization's skills: `naive/landing-page-copy` floats and `naive/landing-page-copy@1` pins, with the same rules. Your own `landing-page-copy` and the platform's never collide.

## catalog

The platform publishes a small catalogue of skills any agent can reference as `naive/<slug>`. Without a slug, `catalog` lists the newest version of each; `--tag` narrows it to one family (`agency`, `seo`, `media`, …) and `--search` is free text over the slug, name and description.

```bash theme={"system"}
vetta skill catalog --tag seo
```

```json theme={"system"}
{
  "object": "list",
  "data": [
    {
      "object": "skill_catalog_entry",
      "slug": "seo-content-brief",
      "version": 1,
      "name": "SEO content brief",
      "description": "Turn a target query into a brief a writer can execute: intent, audience, outline, entities, links, length.",
      "tags": ["seo", "content"],
      "content_hash": "3f1a…",
      "published_at": "2026-09-08T00:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

With a slug it prints the latest version **including its content** — the text a floating `naive/<slug>` ref hands an agent today. The `version` in the answer is the number to pin.

```bash theme={"system"}
vetta skill catalog seo-content-brief
```

| Flag | Description |
| - | - |
| `--tag` | Only skills carrying this tag. |
| `--search` | Free text over slug, name and description. |
| `--limit`, `--after` | Cursor pagination over the list. |

The same reads are [`client.skills.catalog.list()`, `client.skills.catalog.get()` and `client.skills.catalog.retrieve()`](https://vetta.sh/docs/sdk/skills) in the SDK and `GET /v1/skills/catalog` in the [API reference](https://vetta.sh/docs/api/skills.md#the-platform-catalogue).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.