vetta skill

Manage 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

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.

{
  "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.

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

{
  "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 in the SDK and POST /v1/skills/{id}/versions in the API reference.

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:

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.

vetta skill version parity-demo-27e5fc9d 1

{
  "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.

Getting started

Building & running

Organization

Identity

Commands

push

push-version

Attaching to an agent

version

​Commands

​push

​push-version

​Attaching to an agent

​version

Commands

push

push-version

Attaching to an agent

version