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

<CodeGroup>
  ```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",
  });
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash CLI theme={"system"}
  # Float to latest, and pin one skill to an exact version
  vetta agent create --name Refunder --model zai-org/GLM-5.2-FP8 \
    --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: "zai-org/GLM-5.2-FP8",
    harness: "pi",
    budget: { capUsd: 50, maxTaskUsd: 5, period: "month" },
    skills: ["refund-policy", "escalation-matrix@3"],  // float + pin
  });
  ```
</CodeGroup>

## 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 zai-org/GLM-5.2-FP8 \
  --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](/docs/concepts/agents#versioning). Skills survive session deletion — they are independent resources.

<Card title="Next: files" icon="folder" href="/docs/capabilities/files">
  Where a session's artifacts live.
</Card>