Skills

A skill is a reusable, versioned instruction module — a SKILL.md document — that agents load on demand. Skills are org-scoped and immutable per version: each push creates a new version identified by its content hash.

The skill object

string

Unique id (e.g. skl_01H...).

string

Unique, human-readable name within the org (e.g. refund-policy).

string | null

Short description of what the skill does.

integer

The highest version number.

string

Creation timestamp.

The skill version object

string

The skill this version belongs to (skl_…).

string

The skill’s slug.

integer

Monotonic version number.

string

SHA-256 of the SKILL.md content. Verifies integrity.

integer

Content size.

string

When this version was pushed.

Create a skill

POST /v1/skills → 201 Created for a new slug, 200 OK when the slug already exists (the push is applied as a new version of it). A skill is never created empty: the create is the first push. Both responses are the skill version object.

string

required

The SKILL.md text. Version 1 of a new slug.

string

Unique slug within the org — lowercase letters, digits and dashes. Required unless you send name.

string

The same thing spelled name. Send one of slug or name.

string

Short description. Defaults to null.

string

SHA-256 hex digest of content. Optional: the server hashes the bytes itself and refuses a digest that does not match.

curl -fsSL https://api.vetta.sh/v1/skills \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{ "slug": "refund-policy", "description": "How to process refunds.", "content": "# Refund policy\n...", "sha256": "9f86d0..." }'

{
  "id": "skl_01H8XZ...",
  "slug": "refund-policy",
  "version": 1,
  "sha256": "9f86d0...",
  "size_bytes": 1024,
  "created_at": "2026-08-20T17:00:00Z"
}

Retrieve & list

GET /v1/skills/{id}    # retrieve one
GET /v1/skills         # list (cursor-paginated)

See Pagination.

Push a new version

POST /v1/skills/{id}/versions uploads a new SKILL.md. The body is the document text, optionally with its sha256; the server rejects the request with validation_failed if the hash does not match the content. Pushing bytes identical to the current version mints nothing and answers 200.

string

required

The full SKILL.md text.

string

SHA-256 hex digest of content. Optional: the server hashes the bytes itself and refuses a digest that does not match.

string

Replace the skill’s description as part of this push.

curl -fsSL https://api.vetta.sh/v1/skills/skl_01H8XZ.../versions \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "content": "# Refund policy\nConfirm the order first.\n...", "sha256": "b1946ac9..." }'

Response

{
  "id": "skl_01H8XZ...",
  "slug": "refund-policy",
  "version": 2,
  "sha256": "b1946ac9...",
  "size_bytes": 2048,
  "created_at": "2026-08-20T18:00:00Z"
}

List versions

GET /v1/skills/{id}/versions returns version history, newest first. Cursor-paginated.

Response

{
  "data": [
    { "version": 2, "sha256": "b1946ac9...", "size_bytes": 2048, "created_at": "2026-08-20T18:00:00Z" },
    { "version": 1, "sha256": "9f86d0...", "size_bytes": 1024, "created_at": "2026-08-20T17:00:00Z" }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve one version

GET /v1/skills/{id}/versions/{n} — scope agents:read. Returns that immutable version’s metadata with its body: the skill version object plus a content string carrying the raw SKILL.md. This is the second half of progressive disclosure. The list above carries only version, sha256, size_bytes, and created_at; the text itself costs this extra call, so a runtime pays for it once when the skill is actually used rather than on every turn.

curl -fsSL https://api.vetta.sh/v1/skills/refund-policy/versions/2 \
  -H "authorization: Bearer sk_live_..."

{id} accepts a slug or an id, and {n} is the integer version. not_found (404) if either does not resolve.

Delete a skill

DELETE /v1/skills/{id} — scope agents:write. Removes the skill and its whole version history.

Agents referencing the slug — pinned (refund-policy@3) or floating (refund-policy) — fail to resolve it at session start once it is gone. Check what depends on a skill before deleting it.

Response

{ "id": "skl_01H9BC...", "object": "skill", "deleted": true }

Pin a version

An agent’s skills[] accepts two reference forms:

Reference	Resolution
`refund-policy`	Floats to the skill’s `latest_version`, resolved at session start.
`refund-policy@3`	Pinned to the immutable version `3`. Never moves, even after new pushes.

Skill versions are content-addressed and immutable, so pushing a new SKILL.md never silently changes an already-pinned agent. Use GET /v1/skills/{id}/versions to find the numbers you can pin.

Attach a skill to an agent by slug or id. An unpinned reference (refund-policy) resolves to the latest version at session start; a pinned one (refund-policy@3) is frozen.

Introduction

Core resources

Platform

Identity

The skill object

The skill version object

Create a skill

Retrieve & list

Push a new version

List versions

Retrieve one version

Delete a skill

Pin a version

​The skill object

​The skill version object

​Create a skill

​Retrieve & list

​Push a new version

​List versions

​Retrieve one version

​Delete a skill

​Pin a version

The skill object

The skill version object

Create a skill

Retrieve & list

Push a new version

List versions

Retrieve one version

Delete a skill

Pin a version