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