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.
`vetta skill catalog [slug]`	The platform’s published skills; with a slug, its latest `SKILL.md`.

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

vetta skill catalog --tag seo

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

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() in the SDK and GET /v1/skills/catalog in the API reference.

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

catalog

version

​Commands

​push

​push-version

​Attaching to an agent

​catalog

​version

Commands

push

push-version

Attaching to an agent

catalog

version