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

> Persisted, versioned expertise loaded with progressive disclosure.

A skill is reusable, domain-specific expertise you attach to an agent. Skills are **persisted, versioned resources** — independent of any session, referenced from an agent's configuration, and loaded into context only as needed. Because a skill lives on the agent rather than in a single conversation, the same expertise is reused across every session and can be updated in one place.

## Authoring a skill

A skill is a `SKILL.md` file: YAML frontmatter plus a Markdown body. Skill bodies are **text, not code** — they are instructions and reference material, never executed.

```markdown SKILL.md theme={"system"}
---
name: refund-policy
description: How to evaluate and process customer refund requests within policy.
---

# Refund policy

- Refunds are allowed within 30 days of purchase.
- Orders over \$500 require a manager note in the ticket.
- Always confirm the order ID before issuing a refund.
...
```

## Push and version

Each push creates a new immutable version, content-addressed by a hash over the whole file. An agent references a skill by slug: an **unpinned** reference (`refund-policy`) resolves to the latest version at session start, while a **pinned** reference (`refund-policy@3`) is frozen to that exact version and never moves.

```bash CLI theme={"system"}
vetta skill push --slug refund-policy --file ./skills/refund-policy/SKILL.md
vetta skill versions refund-policy
vetta skill list
```

```typescript TypeScript theme={"system"}
const skill = await vetta.skills.push({
  slug: "refund-policy",
  file: "./skills/refund-policy/SKILL.md",
});
```

## Pinning a version

Because every push is immutable, you choose per reference whether a skill floats or freezes:

| Reference | Resolves to |
| - | - |
| `refund-policy` | The **latest** version, re-resolved at each session start. |
| `refund-policy@3` | Version **3**, frozen — a later push never changes it. |

Pushing a new `SKILL.md` therefore never silently changes an already-pinned agent; you bump the pin when you're ready. Use `vetta skill versions <slug>` to see the numbers you can pin to.

```bash CLI theme={"system"}
# Float to latest, and pin one skill to an exact version
vetta agent create --name Refunder --model z-ai/glm-5.3-flash \
  --skill refund-policy \
  --skill escalation-matrix@3 \
  --budget-usd 50 --max-task-usd 5 --budget-period month
```

```typescript TypeScript theme={"system"}
const agent = await vetta.agents.create({
  name: "Refunder",
  model: "z-ai/glm-5.3-flash",
  harness: "pi",
  budget: { capUsd: 50, maxTaskUsd: 5, period: "month" },
  skills: ["refund-policy", "escalation-matrix@3"],  // float + pin
});
```

## How progressive disclosure works

Skills keep the context window small by loading in two tiers:

* **Tier 1 — always on.** Every attached skill contributes its `name` and a truncated `description` to a compact index the agent always sees. The index is capped so dozens of skills cost only a few thousand characters.
* **Tier 2 — on demand.** When the agent decides a skill is relevant, it calls the built-in **`read_skill`** tool to pull the full body into context, with a provenance header identifying the exact version.

## Attaching to an agent

```bash CLI theme={"system"}
vetta agent create --name Refunder --model z-ai/glm-5.3-flash \
  --skill refund-policy --skill escalation-matrix \
  --budget-usd 50 --max-task-usd 5 --budget-period month
```

Skills are an array on the agent; each entry is a slug, optionally suffixed `@version` to [pin](#pinning-a-version) it. Updating the array creates a new [agent version](https://vetta.sh/docs/concepts/agents.md#versioning). Skills survive session deletion — they are independent resources.

> [card] [Next: files](https://vetta.sh/docs/capabilities/files.md)
>
> Where a session's artifacts live.


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