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

# skills

> Content-addressed, versioned instructions — client.skills, including the two distinct pushes.

A skill is versioned markdown an agent loads on demand. Seven methods on your own skills, two on the platform catalogue. API detail: [Skills](/docs/api/skills).

## push

```ts theme={"system"}
client.skills.push(body: SkillContent & { slug: string }): Promise<SkillPush>
```

`POST /v1/skills` — create-or-version **by slug**. An unknown slug creates the skill; a known slug with changed `content` mints a new version; an identical push is a no-op (content-addressed).

<ResponseField name="slug" type="string" required>The skill's stable handle.</ResponseField>
<ResponseField name="content" type="string" required>The markdown body.</ResponseField>
<ResponseField name="description" type="string">One-line summary.</ResponseField>
<ResponseField name="sha256" type="string">An *integrity claim* checked against the server's own digest of `content` — never the digest of record. A mismatch is rejected with `validation_failed`, `param: "sha256"`.</ResponseField>

The reply is the version plus `id` and `slug` — which is what makes chaining into `pushVersion` work.

## pushVersion

```ts theme={"system"}
client.skills.pushVersion(ref: string, body: SkillContent): Promise<SkillPush>
```

`POST /v1/skills/{ref}/versions` — the same push addressed at a skill that **already exists**, by id or slug. Distinct from `push` on purpose: an unknown ref is a `404`, not a create, so a release pipeline pinned to a skill id cannot silently mint a second skill after a rename.

```ts theme={"system"}
const v1 = await client.skills.push({ slug: "triage", content: "# Triage\nfirst.\n" });
const v2 = await client.skills.pushVersion(v1.id, { content: "# Triage\nsecond.\n" });
```

## list

```ts theme={"system"}
client.skills.list(query?: ListQuery): Promise<Page<Skill>>
```

`GET /v1/skills`, cursor-paginated.

## get

```ts theme={"system"}
client.skills.get(slug: string): Promise<Skill>
```

`GET /v1/skills/{slug}` — by slug or id. Metadata only; the body costs a `getVersion` call.

## listVersions

```ts theme={"system"}
client.skills.listVersions(slug: string, query?: ListQuery): Promise<Page<SkillVersion>>
```

`GET /v1/skills/{slug}/versions`. Newest first. The cursor is the **version number**, not an id — versions have none of their own.

## getVersion

```ts theme={"system"}
client.skills.getVersion(slug: string, version: number): Promise<unknown>
```

`GET /v1/skills/{slug}/versions/{version}`. This is the call that returns the `content` — progressive disclosure: the body costs this second call, never every turn.

## delete

```ts theme={"system"}
client.skills.delete(slug: string): Promise<Deleted>
```

`DELETE /v1/skills/{slug}`. Removes the skill and its versions.

## catalog.list

```ts theme={"system"}
client.skills.catalog.list(query?: ListQuery & { tag?: string }): Promise<Page<SkillCatalogEntry>>
```

`GET /v1/skills/catalog` — the [platform catalogue](/docs/api/skills#the-platform-catalogue): the newest version of every published skill, alphabetical by slug, without `content`. `tag` narrows to one family (`agency`, `seo`, `media`, …) and `search` is free text over slug, name and description. The cursor is a slug. Any authenticated caller may read it, an organization or not.

### `client.skills.catalog.get(slug)`

`GET /v1/skills/catalog/{slug}` — the newest version of one slug, without `content`: what a `naive/<slug>` reference resolves to right now, and the number to pin as `naive/<slug>@N`. A slug nothing published is a `404 not_found` naming `slug`.

```ts theme={"system"}
const { data } = await client.skills.catalog.list({ tag: "seo" });
// data[0].slug === "keyword-gap-analysis" → reference it as "naive/keyword-gap-analysis"
```

## catalog.retrieve

```ts theme={"system"}
client.skills.catalog.retrieve(slug: string, version: number): Promise<SkillCatalogVersion>
```

`GET /v1/skills/catalog/{slug}/versions/{version}` — one published version **with** its `content`. `version` is the number from the list (or the one you want to pin as `naive/<slug>@N`); an unknown slug or version is a `404 not_found` naming `slug`.

```ts theme={"system"}
const latest = (await client.skills.catalog.list()).data.find((e) => e.slug === "landing-page-copy");
const body = await client.skills.catalog.retrieve("landing-page-copy", latest!.version);
console.log(body.content);
```