Skills

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.

SKILL.md

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

vetta skill push --slug refund-policy --file ./skills/refund-policy/SKILL.md
vetta skill versions refund-policy
vetta skill list

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.

# 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

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
});

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

CLI

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 it. Updating the array creates a new agent version. Skills survive session deletion — they are independent resources.

Next: files

Where a session’s artifacts live.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Authoring a skill

Push and version

Pinning a version

How progressive disclosure works

Attaching to an agent

Next: files

​Authoring a skill

​Push and version

​Pinning a version

​How progressive disclosure works

​Attaching to an agent

Next: files

Authoring a skill

Push and version

Pinning a version

How progressive disclosure works

Attaching to an agent